Home / Docs / Command line

una run

Release v0.4.0

Run main of the [run] entry module.

text
una run [OPTIONS] [PATH]

Examples

sh
una run .

Run the package's main with the grants its manifest lists.

sh
una run . --grant console

Grant a capability from the command line.

Arguments

Argument What it does Default
[PATH] The package directory, or a single file .

Options

Option What it does Default
--grant <SPEC> Grant a host capability: console, clock, env, keys:<file>, files:<path>:<access>, http:<origin>[:<methods>] (edition 0.4: with ;<limit> suffixes), or, from edition 0.4, serve:<scheme>://<address>:<port> with ;<item> suffixes
--json Print machine output as JSON on stdout, and nothing else on stdout
--color <WHEN> When to use colors in human output. Values: never: Never use colors; auto: Use colors when the output is a terminal; always: Always use colors. auto
--max-depth <N> The maximum call depth 10000
--max-memory <MIB> The memory a run may hold, in MiB: 4096 by default, or the package's declared max_memory, which it may lower and never raise
--max-response <MIB> The largest HTTP response body, in MiB 16
--http-timeout <SECONDS> The total time of each HTTP request, in seconds 30
--workers <N> The threads that run tasks, from 1 to 1024; by default one per core
--task-depth <N> The depth limit of the tasks of first of and start, from 1 to --max-depth; by default 1000
--io-threads <N> The helper threads of Http, from 1 to 4096; by default 64. A run granted Http starts 2 x N + max(2, N / 4) threads for its requests before main, besides --workers and --file-threads, so a large N can pass the system's limit on a process's threads, and the run then stops with U6003
--file-threads <N> The helper threads of Files and Console, from 1 to 256; by default 4
--serve-threads <N> The threads that serve the connections of serve: grants, from 1 to 256; by default one per core. Accepted and unused by a run that does not serve
--solver-wallclock <SECONDS> Stop a solver query after this many seconds; the obligation is then unknown 60
--solver-memory <MIB> The memory limit of each solver query in MiB, from 256 to 1048576 4096
--stop-after-iterations <N> A budget of this many iterations for each for ever loop, the driver's loop included: each loop instance ends at the start of its iteration N + 1; no host stop request
--virtual-time Run on a virtual clock that starts at 0 and never waits
--cost-clock With --virtual-time: each check point (call, operation, loop iteration) moves the virtual clock by one millisecond, so time follows the run's work; the security hunt's cost-clock oracle
--deadline <SECONDS> Request a host stop after this many seconds, from 1 to 31536000
--stop-grace <SECONDS> The seconds from the first host stop request to the hard stop, from 1 to 86400 10
--trace <FILE> Write the trace to this file as a JSON array, each event as it happens

Specification

The normative rules, from spec/13 §5:

Command Meaning
una run [path] Run main of [run] entry; --grant <spec> repeated

una run [path] runs pub main() -> Unit of the entry module: [run] entry, or the module of a single file (ADR 0032). It checks the package first, at tier 1, with the grants of [run] grants and of --grant flags together as final grants, so U3012 reports before execution every uses of main that they do not grant. A package without an entry, an entry without pub main() -> Unit, a --grant value that is not a grant spec, an unreadable or invalid key file, a --max-depth, --max-memory, --max-response or --http-timeout that is not a number, a --max-memory of 0 (#185), a --max-response or --http-timeout of 0, an --http-timeout over 86400 (a day), a --max-depth whose stack cannot be allocated, and a --workers, --task-depth, --io-threads or --file-threads that is not a number or is out of its range (spec/27 §3) are usage errors (exit code 2), on una run and una test; una run also takes --serve-threads (edition 0.4 preview, spec/31 §6 rule 1), whose value out of its range or not a number is a usage error too, as is --virtual-time with a serve: grant and no --serve-script (spec/31 §6 rule 14); una run and executables take --serve-script <file> and --serve-out <file> (edition 0.4 preview, spec/31 §8 rule 6), whose usage errors are those of that rule. (Edition 0.4 preview, spec/31 §7 rules 1, 2 and 5.) For a package with a serve section, una run reports a module without pub handle(request: internal Request) -> internal Reply, or with an on_stop that is not pub on_stop() -> Unit, then a run with no serve: grant, each a usage error before any listener is bound, and otherwise runs the driver; una build reports the first and builds the driver into an executable, which reports a missing serve: grant at its start. (v0.2, ADR 0061.) The interpreter's stack is sized from --max-depth and capped at 1 GiB, and --max-memory <MiB> (default 4096) bounds the heap a run holds (spec/11 §7); una test takes both flags. Relative paths of una.toml grants resolve against the package root, and those of flags against the current directory. A Files path is relative to the grant's prefix: it is normalized lexically, its existing part is resolved through the file system, and a path that ends outside the prefix, absolute, through .. or through a link, fails with FileError.Denied, as does an operation that the grant's mode does not allow. The key file of keys:<keyfile> is a TOML table of key names to base64 keys, loaded before the run starts; the first grant that names a key wins, and an unknown name fails with KeyError.UnknownKey. (Edition 0.4 preview, ADR 0116.) When the package's ita.una has a drive section, una run runs the driver of spec/26 §2 instead of main, and a driven module without the shapes of spec/26 §2 rule 2 is a usage error. una run and executables take --stop-after-iterations <n>, an integer from 1 to 2^63 − 1, the budget of each loop instance, which ends each for ever entered, and the driver's loop, at the start of its own iteration n + 1 (spec/26 §6 rule 1); --deadline <seconds>, from 1 to 31,536,000, a host stop request after that many seconds; and --stop-grace <seconds>, from 1 to 86,400 (default 10), the time from the first host stop request to the hard stop (spec/26 §6). Another value of any of them is a usage error. A run that the hard stop cancels ends with U6007, exit code 1, with the trace of an abort; with --json, its status is aborted. una run and executables take --virtual-time, a switch with no value: the run's clock is then virtual, from 0 at the start of the run, and only the run's own waits move it, so Clock.now and the driver's ticks are the same in every run and in both engines (spec/26 §8). A value given to it, as in --virtual-time=yes, is a usage error. una test takes no such flag: time in a test is always virtual (spec/26 §8). --deadline counts seconds of the wall clock under --virtual-time too: it is a request of the host, not a time of the program. (Edition 0.4, ADR 0117 rule 10.) una run also takes --cost-clock, a switch that needs --virtual-time (a usage error, exit code 2, without it): each check point of the interpreter then moves the virtual clock by one millisecond, the cost clock of spec/27 §8 rule 6. Executables do not take it. (ADR 0117, implementation plan step 7, #973.) una run takes --trace <file>, as executables do: the trace goes to the file as a JSON array, each event as it is written, and a file that cannot be made is a usage error before the run starts (spec/27 §8). A started task that ends alone writes its line to stderr as it ends (spec/27 §7).

Help text

As una run --help prints it at v0.4.0:

text
Run `main` of the `[run] entry` module

Usage: una run [OPTIONS] [PATH]

Arguments:
  [PATH]
          The package directory, or a single file

          [default: .]

Options:
      --grant <SPEC>
          Grant a host capability: `console`, `clock`, `env`, `keys:<file>`, `files:<path>:<access>`, `http:<origin>[:<methods>]` (edition 0.4: with `;<limit>` suffixes), or, from edition 0.4, `serve:<scheme>://<address>:<port>` with `;<item>` suffixes

      --json
          Print machine output as JSON on stdout, and nothing else on stdout

      --color <WHEN>
          When to use colors in human output

          Possible values:
          - never:  Never use colors
          - auto:   Use colors when the output is a terminal
          - always: Always use colors

          [default: auto]

      --max-depth <N>
          The maximum call depth

          [default: 10000]

      --max-memory <MIB>
          The memory a run may hold, in MiB: 4096 by default, or the package's declared max_memory, which it may lower and never raise

      --max-response <MIB>
          The largest HTTP response body, in MiB (`spec/24 §4`)

          [default: 16]

      --http-timeout <SECONDS>
          The total time of each HTTP request, in seconds (`spec/24 §4`)

          [default: 30]

      --workers <N>
          The threads that run tasks, from 1 to 1024; by default one per core (ADR 0117)

      --task-depth <N>
          The depth limit of the tasks of `first of` and `start`, from 1 to --max-depth; by default 1000 (ADR 0117)

      --io-threads <N>
          The helper threads of `Http`, from 1 to 4096; by default 64 (ADR 0117). A run granted `Http` starts 2 x N + max(2, N / 4) threads for its requests before `main`, besides --workers and --file-threads, so a large N can pass the system's limit on a process's threads, and the run then stops with U6003

      --file-threads <N>
          The helper threads of `Files` and `Console`, from 1 to 256; by default 4 (ADR 0117)

      --serve-threads <N>
          The threads that serve the connections of `serve:` grants, from 1 to 256; by default one per core (ADR 0123). Accepted and unused by a run that does not serve

      --solver-wallclock <SECONDS>
          Stop a solver query after this many seconds; the obligation is then unknown

          [default: 60]

      --solver-memory <MIB>
          The memory limit of each solver query in MiB, from 256 to 1048576 (ADR 0124)

          [default: 4096]

      --stop-after-iterations <N>
          A budget of this many iterations for each `for ever` loop, the driver's loop included: each loop instance ends at the start of its iteration N + 1; no host stop request (ADR 0116)

      --virtual-time
          Run on a virtual clock that starts at 0 and never waits (ADR 0116)

      --cost-clock
          With --virtual-time: each check point (call, operation, loop iteration) moves the virtual clock by one millisecond, so time follows the run's work; the security hunt's cost-clock oracle (ADR 0117, `spec/27 §8`)

      --deadline <SECONDS>
          Request a host stop after this many seconds, from 1 to 31536000 (ADR 0116)

      --stop-grace <SECONDS>
          The seconds from the first host stop request to the hard stop, from 1 to 86400 (ADR 0116)

          [default: 10]

      --trace <FILE>
          Write the trace to this file as a JSON array, each event as it happens (ADR 0117)

      --serve-script <FILE>
          Toolchain test builds only: a shipped `una` reads and checks the file, then refuses the run as a usage error. Replace the listeners of the `serve:` grants with the connections this file describes, one JSON object per line; needs --virtual-time (ADR 0123, `spec/31 §8`)

      --serve-out <FILE>
          Toolchain test builds only, as --serve-script is. Write what each scripted connection received to this file; needs --serve-script (ADR 0123)

  -h, --help
          Print help (see a summary with '-h')
View the Markdown