18.5 Running, testing and building
Page 6 of 11
18.5.1 What running, testing and building are
una can execute a package in three ways:
- Running executes
main.una run .does it inside una itself, which reads the checked program and carries it out step by step. A program that executes another program this way is an interpreter. - Testing executes every
exampleof the package (chapter 14), each on its own, and compares the results with what the examples expect. - Building turns the package into a native executable: a file of instructions for the machine's processor, which runs on its own, without una. Turning code into such a file is compiling, and a program that does it is a compiler.
18.5.2 Why three commands
Each answers its own need. While you write, una run . shows what the program does right away. Before a change is done, una test . checks the numbers against values a person worked out. To ship, una build . gives an executable that the store's machines run without una installed.
18.5.3 How to write them
18.5.3.1 una run . and --grant
una run . runs main of the module that [run] entry names, with the grants of [run] grants (chapter 12). una run --grant <spec> . adds a grant for one run, such as --grant clock, on top of those of una.toml.
18.5.3.2 una test .
una test . runs every example and prints one line for each, then a count:
$ una test .
example discount "30 percent off a lamp" ... ok
example discount "a typed percent above 90 is OutOfRange" ... ok
2 examples: 2 passed, 0 failed18.5.3.3 una build .
una build . compiles the package into a native executable, after the same checks:
una build .$ una build .
built target/una/discount18.5.3.4 With --json
With --json, una run . prints the run as one document: the status, the lines printed, the failure if any, and the trace of the run, the list of every operation it performed. This is a different thing from una trace, which follows a requirement to the code:
$ una --json run .
{"schema":"una.run/1","tier":1,"status":"ok","output":["LAMP-01 1393, DESK-02 11000"],"failure":null,"diagnostics":[],"trace":[{"seq":1,"instance":"host:Console","capability":"Console","op":"print","args":{"line":"\"LAMP-01 1393, DESK-02 11000\""},"outcome":{"kind":"ok","value":"unit"}}]}The trace is what the program asked of the outside world, in order, with the arguments and the outcome of each operation. una --json test . gives each example its outcome, its result and its own trace:
$ una --json test .
{"schema":"una.test/1","tier":1,"redacted":false,"diagnostics":[],"examples":[{"module":"discount","name":"30 percent off a lamp","outcome":"pass","reason":null,"expectation":null,"result":{"kind":"ok","value":"1393"},"trace":[]},{"module":"discount","name":"a typed percent above 90 is OutOfRange","outcome":"pass","reason":null,"expectation":null,"result":{"kind":"fail","variant":"OutOfRange","value":"OutOfRange(95)"},"trace":[]}],"passed":2,"failed":0}18.5.4 Every command checks first
una run, una test and una build check the package first, at tier 1, and run nothing when the check reports an error. On the package with the wrong word, the run is rejected: nothing ran, output and trace are empty, and diagnostics holds the reason:
$ una --json run .
{"schema":"una.run/1","tier":1,"status":"rejected","output":[],"failure":null,"diagnostics":[{"schema":"una.diagnostic/1","code":"U5001","severity":"error","domain":"verification","message":"postcondition of `sale_price` is refuted","primary":{"file":"src/discount.una","start":{"line":24,"col":29},"end":{"line":24,"col":34}},"related":[{"file":"src/discount.una","start":{"line":20,"col":11},"end":{"line":20,"col":25},"message":"ensures clause"}],"obligation":{"id":"ob-8a05af02a5f7","kind":"postcondition","goal":"result >= cost","status":"refuted"},"counterexample":{"bindings":[{"name":"cost","value":1},{"name":"off","value":0},{"name":"price","value":0},{"name":"result","value":0}]},"repairs":[{"rank":1,"escape_cost":0,"description":"add a guard or an arm so that the failing path returns a value for which `result >= cost` holds","edit":null},{"rank":2,"escape_cost":0,"description":"adjust the `ensures` clause","edit":null}],"explain":"una explain U5001"}],"trace":[]}So a program that runs, or an executable that exists, is always one that checked.
18.5.5 How running, testing and building behave
- The status of a run.
okfor a run that returned,failedwhenmainfailed with its error kind,abortedwhen the run was stopped, by a limit (chapter 16 shows one) or another runtime error, andrejectedwhen the checks failed and nothing ran. - The examples run alone. Each example gets only the handlers its
givenlines install, so an example never reaches the console or a real service by accident. - The executable.
una build .writes it under the package, attarget/una/<name>, with<name>from[package] name. It runsmainwith the grants ofuna.tomlbuilt in, takes further--grantflags, and prints whatuna run .prints. Linking is the last step of a build: it joins the compiled code with the runtime library, the code that every Una executable shares. On a Mac,unalinks with a linker built into it and needs no other program. On Linux, it links through the system's C compiler,cc(gcc or clang, with the C library's development files), which must be on the path, the list of directories where the terminal looks for programs. It builds for the machine it runs on.
18.5.6 Exit codes
Every command of una ends with an exit code, the number the terminal receives when the command ends (What a tool is), and one of four:
| Code | Meaning |
|---|---|
| 0 | Success: no error, every obligation proven, every example passed |
| 1 | The output holds at least one error with a code, an obligation that is not proven, or a failed example |
| 2 | A usage error: the command line itself is wrong, such as an unknown flag or a path with no package; it is printed on stderr, without a code |
| 3 | An internal error of una itself, U8001 |
So una check . exits with 0 when the package checks, and with 1 when it reports a problem. una run . exits with 1 when the run is not ok, and una test . with 1 when an example fails. Another program that runs una for you, such as a release script or a code editor, tells success from failure by this number, without reading the text. The exit code does not depend on --json: the document and the text say the same thing.
18.5.7 Choosing a command
The table matches each question of this chapter to the command that answers it:
Which to use:
| You want to… | Use |
|---|---|
| Know whether the package is right, fast, while you type | una check --tier 0 ., or an editor with una lsp |
| Know whether it is right, proofs included | una check . |
| Apply the repairs that are exact | una fix --dry-run ., then una fix . |
| See what was proven, and for which requirement | una obligations ., una trace <requirement> |
| See what a function promises, inferred clauses included | una contract <module.function> |
| Review what a package may do and trusts | una report . |
| Run it, test it, ship it | una run ., una test ., una build . |
18.5.8 Check yourself: an example with the wrong number
Someone worked out 30 percent off 19.90 by hand and wrote 13.90:
--- a/src/discount.una
+++ b/src/discount.una
@@ -46,3 +46,3 @@
do sale_price(1990, cost: 1200, off: 30)
- expect result == 1393
+ expect result == 1390
Does una check . accept the package? What does una test . print?
Show the answer
una check . accepts it: an example's do line must check, but whether its expectation holds is decided by running it. una test . runs it and reports the failure, with the line, the expectation and the value the code gave:
$ una test .
example discount "30 percent off a lamp" ... FAILED
src/discount.una:47: expect result == 1390
it is false, with `result` = `1393`
example discount "a typed percent above 90 is OutOfRange" ... ok
2 examples: 1 passed, 1 failedThe code computes 1393, which is right: 1990 - 1990 * 30 / 100 is 1990 - 597. The example was wrong, so the fix is in the example. A failed example says that the code and the person disagree; reading the value tells you which one is wrong.