Home / Learn / 11 Packages and modules
11.3 The manifest and the lock
Page 4 of 9
11.3.1 What a manifest is
A manifest is a file that describes a package to the tools: its name, its version, which edition of the language it is written in, and how to run it. In editions 0.1 to 0.3 it is una.toml, at the root of the package (from edition 0.4 it is ita.una, chapter 19). Every command reads it before it reads any module.
una.toml is written in TOML, a common format for settings files. You need four of its rules:
- A table is a group of settings, opened by its name in brackets on a line of its own:
[package]. It runs until the next table. - A key is a setting's name, followed by
=and its value:edition = "0.2". - A value is a text in double quotes (
"store"), a whole number (0), or an array, a list of values in brackets separated by commas (["console"]). - A line that starts with
#is a comment, for people only.
11.3.2 Why the manifest is checked
A settings file that accepts anything turns a typing mistake into a setting that silently does nothing. Here a manifest means to allow each module one use of checked (chapter 7), and misspells the key:
--- a/una.toml
+++ b/una.toml
@@ -18 +18 @@
-checked_per_module = 0
+checked_per_modules = 1una check . reports:
[U7002] Error: unknown key `checked_per_modules` in [escape_budget]
╭─[ una.toml:18:1 ]
│
18 │ checked_per_modules = 1
│ ─────────┬─────────
│ ╰─────────── unknown key `checked_per_modules` in [escape_budget]
│
│ Note: run `una explain U7002` for an explanation
────╯U7002 is the code of a manifest una cannot accept, and it points at the line and the key. In a tool that ignored unknown keys, the budget would silently stay at 0, and the mistake would show up later, as an error at the first checked of some module, far from its cause. Here it shows up at the line that has it.
11.3.3 How to write una.toml
una.toml holds up to five tables in edition 0.2, and no other table or key is allowed. Edition 0.3 adds two more, [contracts] and [boundaries], which put limits on what code may do; chapter 13 covers them.
11.3.3.1 [package]: what the package is
| Key | Value |
|---|---|
name |
The package's name, a text, such as "store". |
version |
The package's own version, a text, such as "0.2.0". una checks only that it is a text that is not empty. |
edition |
The edition of Una its modules are written in: "0.1", "0.2" or "0.3" (chapter 19, Editions). Every example of this chapter uses "0.2". |
[package] is required, with all three keys.
11.3.3.2 [run]: what una run starts and grants
| Key | Value |
|---|---|
entry |
The module path of the module whose pub main una run starts. |
grants |
An array of the host capabilities the run is given, such as ["console"], besides those of a --grant flag (section 12.2). |
11.3.3.3 [labels], [trusted] and [escape_budget]
| Table and key | Value |
|---|---|
[labels] categories |
The categories that labels may name, such as ["PII"]. A label marks data, such as a customer's address, whose flow through the program Una follows (chapter 17, Information flow). |
[trusted] modules |
The modules that may declare policies, the rules that let labeled data out, each also marked trusted module in its header (chapter 17). |
[escape_budget] checked_per_module |
How many uses of checked each module may have, 0 by default (section 7.5). |
These three are optional. Without them, a package has no label categories, no trusted modules and a budget of 0.
11.3.4 A manifest, table by table
Here is a manifest that uses four of the tables, with a comment on each:
# The package: its name, its version, and the edition of the language it is written in.
[package]
name = "store"
version = "0.2.0"
edition = "0.2"
# What `una run` starts, and the host capabilities it grants, besides those of a `--grant` flag.
[run]
entry = "store.app"
grants = ["console"]
# The categories that labels may name.
[labels]
categories = ["PII"]
# How many uses of `checked` each module may have.
[escape_budget]
checked_per_module = 0The package still runs as before, with the same modules. Only una.toml changed.
11.3.5 No dependencies on other packages in una.toml
A package that una.toml describes, of edition 0.1, 0.2 or 0.3, has no way to depend on another package: una.toml has no dependency table, and a package imports only its own modules and two standard modules, std.host and std.testing. Importing anything else says so:
[U1001] Error: module `vendor.tax` is not a module of this package; the standard modules that can be imported are `std.host` and `std.testing`So everything a package runs is in its own src/, the prelude, or the host capabilities that una run grants, in [run] grants or by a --grant flag. In these editions, code from elsewhere, such as a supplier's library, is copied into src/ as modules of the package, where the checker sees all of it. Code copied in this way is called vendored code. Edition 0.3 can then put a limit on what such a module may do, as chapter 13 shows. From edition 0.4, a package describes itself in ita.una instead, and may depend on other packages in directories of its own, its path dependencies (spec/30); the packages of this chapter use una.toml.
11.3.6 verification.lock
verification.lock is the other file at the root of every package. It pins the verifier, the part of una that proves contracts (chapter 5), so that every machine gets the same answers. It is a TOML file with six keys, and no others:
| Key | What it fixes |
|---|---|
encoding_version |
How una writes its questions for the solver: "una-smt-1" |
solver and solver_version |
The solver and its exact version: "z3", "5.1.0" |
logic |
The kind of arithmetic the questions use: "QF_UFLIA" |
step_budget |
How much work the solver may do on one question before it answers "unknown" |
random_seed |
The solver's starting point, so its search runs the same way every time |
With the same sources, una.toml and lock, una check gives the same diagnostics and the same proofs on every machine. A missing or invalid lock is U7004, and a solver of another version is U5003. You rarely edit it: copy it from an existing package, and change it only to adopt a new solver, in a change of its own.
11.3.7 How the manifest is checked
- A table or a key that is not in the lists of this section is U7002, at its line.
- A value of the wrong type, such as a number where a text goes, a missing required key, and a file that is not valid TOML are U7002 too.
- A manifest error does not stop the check. The tables and keys una could read still apply, and only the wrong ones are reported. When the file is not valid TOML at all, the modules are checked with the default settings instead: no grants, no label categories, a budget of 0, and edition
0.1. So a manifest that cannot be read can bring other diagnostics with it, which go away once it is fixed. una run .also checks thatmain'susesare granted: a capability thatmainuses but neither[run] grantsnor a--grantflag grants stops the run before it starts (U3012, section 12.2).
Which to use:
| The setting… | Belongs in |
|---|---|
| Is about the whole package: its name, edition, entry or grants | una.toml |
| Is about how the verifier answers | verification.lock, copied, not edited |
| Is about one function: what it may do or how it fails | The function's header, in the module |
Limits what code may do, reviewed apart from the code, in edition 0.3 |
[contracts] or [boundaries] (chapter 13) |
11.3.8 Check yourself: a manifest
This manifest writes the version as a number:
--- a/una.toml
+++ b/una.toml
@@ -4 +4 @@
-version = "0.2.0"
+version = 2Does the package check? If not, where does una check . point?
Show the answer
It does not check:
[U7002] Error: `version` must be a string, not an integer
╭─[ una.toml:4:11 ]
│
4 │ version = 2
│ ┬
│ ╰── `version` must be a string, not an integer
│
│ Note: run `una explain U7002` for an explanation
───╯In TOML, a value without quotes is a number, and version must be a text: the mark points at the value. Write it in quotes, version = "2.0.0". The file is valid TOML, but not a valid manifest: una checks the type of each value too, not only the names of the keys.