Home / Docs / Specification / 30. Packages and dependencies
30.2 ita.una
-
The package. A package of edition
0.4and later is a directory withita.unaandsrc/; its modules aresrc/**/*.una, as in spec/13 §7. A directory with bothita.unaanduna.tomlis U7008 atita.una, so a package never has two manifests that could disagree. -
Grammar.
ebnfmanifest = head { section } ; head = "ita" pkg_name NEWLINE INDENT head_line { head_line } DEDENT ; head_line = "version" version_lit NEWLINE | "edition" version_lit NEWLINE | "profile" ( "app" | "systems" ) NEWLINE | "about" text_lit NEWLINE | "license" text_lit NEWLINE | "home" text_lit NEWLINE | "publish" "to" lower_ident NEWLINE ; section = sources | needs | replace | trust | labels | trusted | escapes | boundaries | contracts | run | drive | serve ; sources = "sources" NEWLINE INDENT source { source } DEDENT ; source = lower_ident text_lit NEWLINE INDENT "root" text_lit NEWLINE [ "owners" lower_ident { "," lower_ident } NEWLINE ] DEDENT ; needs = "needs" NEWLINE INDENT need { need } DEDENT ; need = pkg_name [ version_lit ] [ "as" lower_ident ] [ origin ] NEWLINE [ INDENT need_line { need_line } DEDENT ] ; pkg_name = lower_ident [ "/" lower_ident ] ; origin = "from" ( lower_ident | "path" text_lit | "workspace" ) ; need_line = "may" cap_type { "," cap_type } NEWLINE | "avoid" version_lit NEWLINE | "accept" "name" NEWLINE ; cap_type = qualified_upper "[" lower_ident { "," lower_ident } "]" ; qualified_upper = { lower_ident "." } upper_ident ; replace = "replace" NEWLINE INDENT { pkg_name version_lit "with" origin NEWLINE } DEDENT ; trust = "trust" NEWLINE INDENT { trust_line } DEDENT ; trust_line = pkg_name [ major ] [ "from" lower_ident ] "modules" module_path { "," module_path } NEWLINE [ INDENT { "may" cap_type { "," cap_type } NEWLINE } DEDENT ] ; major = int_lit | version_lit ; labels = "labels" NEWLINE INDENT { upper_ident NEWLINE } DEDENT ; trusted = "trusted" NEWLINE INDENT { module_path NEWLINE } DEDENT ; escapes = "escapes" NEWLINE INDENT "checked" "per" "module" int_lit NEWLINE DEDENT ; boundaries = "boundaries" NEWLINE INDENT { module_path NEWLINE [ INDENT { "may" cap_type { "," cap_type } NEWLINE } DEDENT ] } DEDENT ; contracts = "contracts" NEWLINE INDENT { module_path NEWLINE INDENT uses_item { uses_item } DEDENT } DEDENT ; run = "run" NEWLINE INDENT [ "entry" module_path NEWLINE ] [ "max_memory" int_lit NEWLINE ] [ "grants" NEWLINE INDENT grant { grant } DEDENT ] DEDENT ; grant = ( "console" | "clock" | "env" | "keys" text_lit | "files" text_lit file_mode { "," file_mode } | "http" text_lit [ http_method { "," http_method } ] ) NEWLINE [ INDENT limit_line { limit_line } DEDENT ] | serve_grant ; (* spec/31 §2 rule 3 *) file_mode = "read" | "write" ; http_method = "get" | "post" | "put" | "delete" ; limit_line = "at" "most" int_lit ( "per" ( "second" | "minute" | "hour" ) | "at" "once" ) NEWLINE | "waiting" "at" "most" int_lit NEWLINE ; (* spec/27 §9 *) drive = "drive" NEWLINE INDENT "module" module_path NEWLINE "ticks" int_lit NEWLINE [ "budget" int_lit NEWLINE ] DEDENT ; serve = "serve" NEWLINE INDENT "module" module_path NEWLINE [ "within" int_lit NEWLINE ] DEDENT ; -
Closed. Every section and every line has one of the forms above; anything else is U7008 at the line. The head's lines appear at most once each,
versionandeditionrequired. Each section appears at most once, in the order of the productionsection; a repeated or misplaced section is U7008. There is noforeignsection and no foreign grant, and nogitorigin: each is U7008. -
The head.
ita <name>:nameis alower_identwith no__and no trailing_, of at most 64 bytes, orowner/namewith an owner of 2 to 39 bytes by the same rule.versionis a full version,MAJOR.MINOR.PATCHwith an optional pre-release, each numeric part at most 2^31 − 1, and no build metadata.editionis0.4or a later edition the release serves. An earlier edition is U7008: that package keepsuna.toml.profileisapp, the default, orsystems(ADR 0109): asystemspackage withentrydeclaresmax_memory.aboutandlicenseare non-empty texts,homeanhttps://URL, andpublish tonamesitatyor a source name thatsourcescould declare, neverpath,gitorworkspace. A published package has nosourcessection (§15 rule 1), so the source is not checked whenita.unais read:una ita publishanduna ita yankcheck it against thesourcesof the nearest workspace whoseitaty.unalists the package as a member, after the package's own refusals and its check (§15 rule 3) and before its archive is built or anything is sent, and refuse a source no such workspace declares (U7013). Theita.unaof a published archive, read at fetch or byuna check, therefore accepts itspublish toline.
-
The sections that
una.tomlhas. Each has the meaning and the checks of spec/13 §7 and of the records it names. Every error that spec/13 §7 makes U7002 for a key ofuna.tomlis U7008 at the corresponding line ofita.una; the codes of other domains stay (U1005 and U1002 for categories, U7005 for trusted modules).labels: the categories, one per line.trusted: the trusted modules, one per line.escapes:checked per module <n>,[escape_budget] checked_per_module.boundaries(ADR 0093): a module path, then its ceiling asmaylines; nomayline is the empty ceiling.contracts(ADR 0092 rule 8): a function's qualified name, then its lockedusesclauses, one per line, each parsed by the production a header uses.run:entry, thenmax_memory, the declared memory budget in MiB from 1 to 4096 ([run] max_memory, ADR 0109 rule 4), thengrants, one grant per line, each the grant spec of spec/13 §5 it corresponds to:console,clock,env,keys "<file>",files "<path>" read, write, andhttp "<origin>" get, post; andserve "<origin>"with its item lines (spec/31 §2 rule 3), whose problems are U7008 at their lines. Paths resolve against the package root. Amax_memoryoutside that range, and asystemspackage withentryand nomax_memory(at theentryline), are U7008.- The limit lines under an
httpgrant (ADR 0117 rule 8) have the forms and the meaning of spec/27 §9:at most <n> per second,minuteorhour,at most <n> at once, andwaiting at most <n>. A line of another form or with lines below it, a count below 1 or above 2^31 − 1, a limit under a grant other thanhttp, and a kind of limit given twice are U7008 at the line, or at the count for a count out of range; a grant with such a line is not read, since without its limit it would allow more than written. The lines under aservegrant are its items (spec/31 §2 rule 3), not limit lines. Thedrivesection names the module the host drives (spec/26 §2):module,ticksand an optionalbudget, each ofticksandbudgetfrom 1 to 86,400,000 milliseconds; a missing key, a value out of range, arun entrybeside it and a module that is not in the package are U7008. Theservesection names the module of the host-driven form of a server and its optional per-request deadline (spec/31 §7, ADR 0123 rule 16):moduleand an optionalwithinfrom 1 to 86,400,000 milliseconds; a missingmodule, a value out of range, arun entryor adrivesection beside it and a module that is not in the package are U7008, and a section with such a problem is not read.
-
Canonical form.
una fmt ita.unaanduna fmt itaty.unarewrite the file in its canonical form: two spaces per level; one blank line between top-level blocks and none inside them; the head's lines in the order of the productionhead_line; one space between words, none before,,.,:,/or], none after[,.or/, and none between a capability and its[; a comment kept before the line it precedes, or two spaces after the line it ends. A line whose tokens this spacing would join into others, such as1.before2, keeps one space between every two tokens.una fmt --check ita.unareports U7001 where the file differs.una fmtof a package directory does not touchita.una, anduna fixnever editsita.una,ita.lockoritaty.una.