Home / Docs / Command line
una run
Run main of the [run] entry module.
una run [OPTIONS] [PATH]Examples
una run .Run the package's main with the grants its manifest lists.
una run . --grant consoleGrant 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:
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')