Home / Learn / 11 Packages and modules

Release v0.4.0Edition 0.2

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:

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:

una.tomldiff
--- a/una.toml
+++ b/una.toml
@@ -18 +18 @@
-checked_per_module = 0
+checked_per_modules = 1

una check . reports:

Diagnostic
[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:

steps/11-manifest/una.tomltoml
# 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 = 0

The 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:

Diagnostic
[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

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:

una.tomldiff
--- a/una.toml
+++ b/una.toml
@@ -4 +4 @@
-version = "0.2.0"
+version = 2

Does the package check? If not, where does una check . point?

Show the answer

It does not check:

Diagnostic
[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.

Next:11.4 Day-to-day: the store's invoice