Home / Docs / Specification / 30. Packages and dependencies

30.2 ita.una

Release v0.4.0
  1. The package. A package of edition 0.4 and later is a directory with ita.una and src/; its modules are src/**/*.una, as in spec/13 §7. A directory with both ita.una and una.toml is U7008 at ita.una, so a package never has two manifests that could disagree.

  2. Grammar.

    ebnf
    manifest     = 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 ;
  3. 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, version and edition required. Each section appears at most once, in the order of the production section; a repeated or misplaced section is U7008. There is no foreign section and no foreign grant, and no git origin: each is U7008.

  4. The head.

    • ita <name>: name is a lower_ident with no __ and no trailing _, of at most 64 bytes, or owner/name with an owner of 2 to 39 bytes by the same rule.
    • version is a full version, MAJOR.MINOR.PATCH with an optional pre-release, each numeric part at most 2^31 − 1, and no build metadata.
    • edition is 0.4 or a later edition the release serves. An earlier edition is U7008: that package keeps una.toml.
    • profile is app, the default, or systems (ADR 0109): a systems package with entry declares max_memory.
    • about and license are non-empty texts, home an https:// URL, and publish to names itaty or a source name that sources could declare, never path, git or workspace. A published package has no sources section (§15 rule 1), so the source is not checked when ita.una is read: una ita publish and una ita yank check it against the sources of the nearest workspace whose itaty.una lists 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). The ita.una of a published archive, read at fetch or by una check, therefore accepts its publish to line.
  5. The sections that una.toml has. 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 of una.toml is U7008 at the corresponding line of ita.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 as may lines; no may line is the empty ceiling.
    • contracts (ADR 0092 rule 8): a function's qualified name, then its locked uses clauses, one per line, each parsed by the production a header uses.
    • run: entry, then max_memory, the declared memory budget in MiB from 1 to 4096 ([run] max_memory, ADR 0109 rule 4), then grants, one grant per line, each the grant spec of spec/13 §5 it corresponds to: console, clock, env, keys "<file>", files "<path>" read, write, and http "<origin>" get, post; and serve "<origin>" with its item lines (spec/31 §2 rule 3), whose problems are U7008 at their lines. Paths resolve against the package root. A max_memory outside that range, and a systems package with entry and no max_memory (at the entry line), are U7008.
    • The limit lines under an http grant (ADR 0117 rule 8) have the forms and the meaning of spec/27 §9: at most <n> per second, minute or hour, at most <n> at once, and waiting 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 than http, 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 a serve grant are its items (spec/31 §2 rule 3), not limit lines. The drive section names the module the host drives (spec/26 §2): module, ticks and an optional budget, each of ticks and budget from 1 to 86,400,000 milliseconds; a missing key, a value out of range, a run entry beside it and a module that is not in the package are U7008. The serve section names the module of the host-driven form of a server and its optional per-request deadline (spec/31 §7, ADR 0123 rule 16): module and an optional within from 1 to 86,400,000 milliseconds; a missing module, a value out of range, a run entry or a drive section beside it and a module that is not in the package are U7008, and a section with such a problem is not read.
  6. Canonical form. una fmt ita.una and una fmt itaty.una rewrite 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 production head_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 as 1. before 2, keeps one space between every two tokens. una fmt --check ita.una reports U7001 where the file differs. una fmt of a package directory does not touch ita.una, and una fix never edits ita.una, ita.lock or itaty.una.