ek9_run_program

Answers with programStdout, programStderr and programExitCode after compiling one .ek9 file and running the program it declares, with string args auto-parsed into the program's typed parameters; exitedBy says whether an exit code is the program's own or the EK9 CLI's.

Category: Execution · Compare: Run (IntelliJ) / cargo run / java -jar

When to use it

'Run this program and show me its output' is one call with file:'hello.ek9' (plus programName when the file declares several programs). Pass args as strings; each is auto-parsed into the program's typed parameter.

When not to use it

Details

Stage 1 always compiles (incremental - near no-op when the cache is warm), stage 2 runs the emitted java command in its OWN process, so exitedBy says whose exit code it is: 'ek9-cli' (stage 1) or 'program' (stage 2). A program's code is its own - a returned Integer, an uncaught Exception's exitCode, a Panic's - and never means a CLI status, even when it is 3, 8 or 11. status: ok (program exited 0) / program-exited (the program exited non-zero - programExitCode, programStderr says why) / program-timed-out (killed at timeoutSeconds, exitedBy:'timeout') / compile-failed (the CLI's exit 8, compileExitCode, stage 2 skipped) / argument-mismatch (EK9's entry point refused args that do not fit the program's parameters, exit 9 or 10, exitedBy:'ek9-cli') / program-not-specified (several programs, none named - programs[] lists them) / no-programs (the file declares none - answered from the source before any compile, with the ek9_add_program route) / bad-command-combination (programName not in the file - programs[] lists what is) / no-run-command-emitted. env and workingDir apply ONLY to the program, never the compiler; there is NO sandbox - file writes, network calls and OS exits are real.

Arguments

ArgumentTypeRequiredWhat it is
argsarray of stringPositional arguments passed to the running program, as strings; the runtime parses each into the declared parameter type.
envobjectEnvironment variables for the program's process (stage 2), merged onto the inherited shell environment; a null value unsets the variable. Pass resolved values - no ${VAR} expansion is done. Never applied to the compiler (stage 1).
filestringyesThe .ek9 file declaring the program, workspace-relative (an absolute path inside the workspace is accepted).
programNamestringWhich program to run when the file declares several (the CLI's -r); a file with one program needs none.
timeoutSecondsintegerWall-clock limit before the program is killed. Default 120.
verbositystring: full | summary | noneResponse size. The default answers with status, summary, exitedBy, programStdout, programStderr and programExitCode (compileExitCode when the compile stage fails); 'full' adds the compile stage's stdout and both stages' argv, exit codes and elapsed times.
withDebugbooleanDefault false. True runs the program with the JDWP debug agent attached (the CLI's -dr) so a debugger can connect.
workingDirstringWorking directory for the program's process (stage 2). Default: the server's own cwd.

Recorded calls

Real calls, recorded against small projects and checked on every build - a changed answer fails it. 3 of the 12 recorded are shown.

Run program shape

Request

{
  "file" : "<workspace-root>/Hello.ek9",
  "timeoutSeconds" : 30
}

Response

{
  "exitedBy" : "program",
  "file" : "Hello.ek9",
  "meta" : {
    "serverMs" : "<timing>"
  },
  "programExitCode" : 0,
  "programStderr" : "",
  "programStdout" : "Hello\n",
  "programTimedOut" : false,
  "status" : "ok",
  "summary" : "program exited 0"
}

Run program returns 3

Request

{
  "file" : "<workspace-root>/Exits.ek9",
  "timeoutSeconds" : 30
}

Response

{
  "error" : {
    "kind" : "program-exited",
    "message" : "program exited 3"
  },
  "exitedBy" : "program",
  "file" : "Exits.ek9",
  "meta" : {
    "serverMs" : "<timing>"
  },
  "programExitCode" : 3,
  "programStderr" : "",
  "programStdout" : "exiting 3\n",
  "programTimedOut" : false,
  "status" : "program-exited",
  "summary" : "program exited 3 - the program's own exit code, not the EK9 CLI's"
}

Run program returns 8

Request

{
  "file" : "<workspace-root>/Exits.ek9",
  "timeoutSeconds" : 30
}

Response

{
  "error" : {
    "kind" : "program-exited",
    "message" : "program exited 8"
  },
  "exitedBy" : "program",
  "file" : "Exits.ek9",
  "meta" : {
    "serverMs" : "<timing>"
  },
  "programExitCode" : 8,
  "programStderr" : "",
  "programStdout" : "exiting 8\n",
  "programTimedOut" : false,
  "status" : "program-exited",
  "summary" : "program exited 8 - the program's own exit code, not the EK9 CLI's"
}

See also