Home / Docs / Specification / 30. Packages and dependencies

30.12 Path dependencies in the program

Release v0.4.0
  1. Loading. Each need from path "<dir>" names a directory relative to the package, which holds ita.una and src/. It is read with no symbolic link followed, in it or below it; a directory that is the package itself, lies inside its src/, or is named by two needs is not read. Its ita.lock, run and sources are not read. A dependency that cannot be read is U7008 at its need.

  2. What the root accepts. A path dependency is used only when:

    • its ita.una names the package the need names (U7008 otherwise);
    • the need says accept name, since a local package carries a name a registry may hold, and no client can tell offline which owners a registry serves (U7012 otherwise);
    • its edition is the package's or earlier (U7012 otherwise);
    • and, in this release, it has no needs of its own, no labels, no trusted modules, no boundaries and no contracts, and the need's may lines name host capabilities only (U7008 at the need otherwise).

    Each of these problems is reported at the need's line in ita.una, from its first column, whichever part of the need it concerns.

    A dependency that is not used is not checked, and its modules are not importable.

  3. Modules. A dependency's module m is the module <local>.m of the program, where <local> is the need's local name: the root writes import util.text (shout). A dependency's modules import their own modules by their own paths, and the standard modules, never a module of the root (U1001). A module of the root whose first path segment is a local name is U1010. Each module's file path is checked against its own package's src/ (U1008).

  4. One program. una check checks the root's modules and every used dependency's as one program, under the root's solver pin; a diagnostic in a dependency is reported at its file, and counts as any other. una fix never edits a dependency's file, una fmt of the package formats the root's modules only, and una test runs the root's examples only.

  5. Authority. Every module of a dependency is in its package's extent, a boundary of ADR 0093 whose ceiling is the one the root writes with may lines under the need, empty without them. A call into it takes no capability by name (U3020); each is granted with with, within that ceiling (U3021), and no release may be reachable (U3024). A dependency's examples are checked as its own, with no consumer ceiling on their given lines, since they never run with the root's authority.

  6. The lock. una ita lock locks each used path dependency as package <name> <version>, from path "<dir>", its content digest (§9), and granted by <root> may <ceiling> for a non-empty ceiling. Loading checks that each path need has its locked package at the version its ita.una gives (U7009), and that every may line is within the ceiling the lock records as granted by the root (U7009 at the may line). una ita lock records a wider ceiling only with --accept-authority <package>, naming the package, so every widening is explicit and shows in the lock's diff; una fix never applies it. The digest of a path package is recorded for review and compared by una ita lock --check; loading does not compare it, since a path package is the root author's own working tree.

  7. The Core export of a program with dependencies, a later version of the Core document of spec/13 §8 that ADR 0122 rule 59 describes, is not written by this release: una core refuses it as a usage error, and this release defines no schema for it.

  8. Effective ceilings and the report. The effective ceiling of a package bounds what it can ever exercise: the least fixpoint of eff(p) = ⋃ over the packages d that need p of (ceiling_d(p) ∩ eff(d)), computed by a worklist in O((P + R) · C) for P packages, R needs and C capability operations, cycles included (ADR 0122 rule 51). The root may be granted any host capability with --grant, so eff(root) is taken as every operation, and a direct dependency's effective ceiling is the ceiling of its package extent: the one the root writes for it, or, for a package with consented trusted modules, its intersection with the trust line's (§13 rule 4); a bound never narrower than what the package can exercise. The report (spec/13 §6) holds dependencies, after handler_authority, one entry per package of the program other than the root, in name order: package, version, local, source ("path"), path, digest (the content digest of the files analysed, the bytes loaded once, or null), signed (null for a path package), replaced, edition, profile (the package's, app when its ita.una names none), granted_by (per dependent, its name, its source, null for the root, and the ceiling it writes as may), effective_ceiling, authority (the union of the uses of its functions and handlers) and trust (modules). A package with no dependencies has "dependencies": []. tcb gains registries (each registry source of the program's mounted releases with the digest of its root metadata that the lock records, §14 rule 10) and dependency_trust (§13). The human report prints one line per dependency: util 0.2.0 (path deps/util): may Console[print] (by demo); uses Console[print]; trust none.

  9. una ita tree [path] checks the program at tier 0 and prints the root's name and version, then one line per dependency, in the form of the report's human line; with --json, one una.ita/1 document with schema, command ("tree"), root, packages, the report's dependencies, and diagnostics. una ita remove <name> [path] removes the need of name from ita.una, with its indented lines, and the needs section when it empties, edited on the text as read, \r\n as \n; then resolves as una ita lock does and, only when the resolution succeeds, writes the lock and then ita.una, each through a temporary file and a rename, putting the lock back when ita.una cannot be written. A name the root does not need, or an ita.una that does not parse, is a usage error and nothing is written. Neither opens a connection.