Home / Docs / Configure a package
ita.una
What it does
From edition 0.4, a package describes itself in ita.una, a short file at the root of the package, next to src/. It replaces una.toml, which editions 0.1 to 0.3 keep. ita.una is written in Una's own lexical syntax: two-space indentation, -- comments, words and text in double quotes. It holds no code. There are no expressions, no interpolation, no conditions and no includes, so reading it never runs anything. Its grammar is closed: every line has one of a fixed set of forms, and anything else is an error at that line (U7008).
The file starts with the head, ita <name> and its lines, then the sections the package needs, in a fixed order. The sections that una.toml had keep their meaning: labels, trusted, escapes, boundaries, contracts and run.
ita shop
version 0.1.0
edition 0.4
about "A small shop"
license "Apache-2.0"
labels
PII
run
entry shop
grants
consolemodule shop
pub main() -> Unit
uses @console: Console[print]
=
@console.print("open")Next to it, ita.lock pins the solver and every dependency (see ita.lock).
Forms
ita <name> -- or <owner>/<name>
version <MAJOR.MINOR.PATCH> -- required
edition 0.4 | 0.5 -- required
profile app | systems -- optional; app by default
about "<one line>" -- optional; required to publish
license "<SPDX expression>" -- optional; required to publish
home "<https URL>" -- optional
publish to <source> -- optional; without it the package is never published
sources | needs | replace | trust | labels | trusted | escapes | boundaries | contracts | run | drive | serve- The head's lines appear at most once each, in any order;
una fmt ita.unaputs them in the order above. - Each section appears at most once, in the order of the second line.
- A version token, such as
0.1.0or2.1, is one token here, never a number. - A text has no interpolation: write
\{for{. - The sections of
una.toml, each one per line:labels: one category per line;trusted: one module path per line;escapes:checked per module <n>;boundaries: a module path, then its ceiling asmaylines;contracts: a function's qualified name, then its lockedusesclauses, one per line;run:entry <module>,max_memory <MiB>(see[run] max_memory), andgrants, one grant per line:console,clock,env,keys "<file>",files "<path>" read, write,http "<origin>" get, post, andserve "<scheme>://<address>:<port>", with its items one per line below it, such asat most 64 at once(see Serving HTTP).
- The sections of edition
0.4:drive, withmodule <module>,ticks <milliseconds>and an optionalbudget <milliseconds>, for a program the host drives (see Driven programs);serve, withmodule <module>and an optionalwithin <milliseconds>, for a program that serves HTTP (see Serving HTTP). In this preview everywithinof aservesection is refused (U4003), since the label of a server's timing is the top label; the grant'sanswerbounds what each peer waits instead.
Examples
A version that is not MAJOR.MINOR.PATCH is U7008 at its line:
-- fails with U7008
ita shop
version 0.1
edition 0.4module shop
pub one() -> Int = 1A section that is not one of the forms, such as settings, is U7008 at its line: the grammar is closed.
-- fails with U7008
ita shop
version 0.1.0
edition 0.4
settings
color "red"module shop
pub one() -> Int = 1Edge cases
- Both manifests. A directory with both
ita.unaanduna.tomlis U7008: a package never has two manifests that could disagree. - An edition before
0.4.ita.unanaming edition0.3is U7008; that package keepsuna.toml. - Profiles.
profile systemsmakes the package asystemspackage; with arun entryit declaresmax_memory(see[package] profile). - Limits and drives. Limit lines under an
httpgrant, such asat most 10 per second, and thedrivesection are read as the grammar above gives them. A limit line under any other grant is U7008, and so is a grant with a limit line that does not read: without its limit it would allow more than it says. - Formatting.
una fmt ita.unawrites the canonical form, anduna fmt --check ita.unareports U7001.una fmtof the package does not touchita.una, anduna fixnever edits it. - Bounds.
ita.unaholds at most 1 MiB.
Diagnostics
- U7008: an invalid
ita.una: a syntax error, an unknown, repeated or misplaced line, a wrong value, or a setting this release refuses.
Edition
Edition 0.4 and later, a preview. Editions 0.1 to 0.3 are described by una.toml (see una migrate).
Normative source
- spec/30 §1: the lexical rules; spec/30 §2: the grammar and the head.
- spec/13 §7: the settings that
una.tomlandita.unashare. - Decision record: ADR 0122, for packages, dependencies and the registry.