Home / Docs / Configure a package

Registry dependencies

What it does

In release 0.4.0 no registry is served and no command builds one or a mirror, so the commands on this page have nothing to read yet. Path dependencies are the dependencies usable in this release (see path dependencies).

A registry is a place that publishes packages for others to use. A package that needs a package from a registry names the registry in its sources section and the package in its needs section, with from and the registry's name. una ita lock then reads the registry, checks every byte it reads against the keys the package pins, and writes the release it chose into ita.lock. una ita fetch copies that release into Itaoca, the local store of packages on the machine, and checks it again. In this release a registry is read only from a mirror directory, a file:// location that holds a copy of the registry's files: there is no https:// transport, and itaty, the planned public registry, is not served (see the edge cases). From then on, una check, una run and una build read the package from Itaoca, with no network.

Why it works this way: a dependency is code that runs inside your program, so where it comes from is part of the program's meaning. Una never takes a registry's word for anything. The root line pins the digest of the registry's root metadata, the document that names the registry's keys: the log key that signs every checkpoint, and the witnesses that cosign it. Every entry the registry serves must be proven included in a checkpoint signed that way, and each release must be signed by its owner's keys, which the client replays from the owner's chain in the log, or the command fails. A mirror that serves a changed file, or a registry that changes a release it already published, is caught, never trusted.

ita.unauna
-- fails with U7011
ita shop
  version 0.1.0
  edition 0.4

sources
  acme "https://ita.acme.example"
    root "sha256:729575635bea7c1e183640271ec279aa35710c4ceb60e8427cc8accce01ddd0b"
    owners acme

needs
  acme/ledger 0.3 from acme
ita.lockuna
lock 1

solver
  encoding "una-smt-1"
  name "z3"
  version "5.1.0"
  logic "QF_UFLIA"
  steps 5000000
  seed 0

registry acme
  root "sha256:729575635bea7c1e183640271ec279aa35710c4ceb60e8427cc8accce01ddd0b"
  checkpoint 3 "sha256:1232dd034b181a3503d65fe7ddf836ed6b10d498749f2a1433fd3fed0c37f335"
  last root 1 "sha256:729575635bea7c1e183640271ec279aa35710c4ceb60e8427cc8accce01ddd0b"

package acme/ledger 0.3.1
  from acme
  digest "sha256:a897541d4792830247931c9ff223251d047c14deeb00f3b9b587a0e2703214fd"
  signed "ed25519:acme:9fa6cc6aa6f261034de0216459c23641e0a189775d6ea6f00b33ebe6a8a66998"
  logged 1
src/shop.unauna
module shop

pub one() -> Int = 1

The lock pins acme/ledger 0.3.1, but this machine has not fetched it yet: una check reports U7011 at the package's line of ita.lock, and una ita fetch is the repair.

Forms

text
sources
  <source> "https://<base URL>"
    root "sha256:<64 hexadecimal digits>"
    owners <owner>, ...

needs
  <owner>/<name> <version> [as <local>] from <source>

Where a registry is read: mirrors.una

Each source is read from its places, in order: the mirrors that Itaoca's mirrors.una lists for it, then its own URL. Itaoca is ~/.una/itaoca, or the directory the environment variable UNA_ITAOCA names. Its mirrors.una lists, under each source, one location per line:

una
mirrors
  acme
    "https://ita-mirror.example.net"
    "file:///srv/ita-mirror"

A location is an https:// URL or a file:// URL of a local directory that holds a copy of the registry's files; in this release only a file:// location is read, since there is no https transport. A mirror is trusted for nothing: what it serves is checked exactly as the registry's own copy is, and a mirror whose copy does not verify is skipped and named (U7010).

The commands

text
una ita lock                 resolve the needs and write ita.lock
una ita add acme/ledger      add a need, newest release, and lock
una ita update [<name>...]   raise needs to newer releases, and lock
una ita fetch                copy the locked releases into Itaoca, verified

Of the una ita commands, lock (with --check, for the newest checkpoint), add, update, fetch, bundle, audit and watch read a registry, from a mirror directory in this release (unbundle reads one too, for a file the bundle lacks); publish and yank stop before they read one. The commands that check, run, build and test a package (una check, una run, una build, una test, una report, una fmt, una fix and the language server) never read a registry: they read Itaoca or the vendor directory, never the network.

Examples

Adding a need from a registry, with the source already declared in sources, looks up the newest release that has waited its cooldown, writes the need and the lock, and prints the review of what changed:

Terminal
$ una ita add acme/ledger
add acme/ledger 0.3.1 (acme): digest sha256:a897541d…; may nothing; uses nothing
wrote ita.lock
wrote ita.una

The need it writes names the source:

una
needs
  acme/ledger 0.3.1 from acme

A source is chosen by the owner it serves. Asking for another one is a usage error:

Diagnostic
$ una ita add acme/ledger --from other
error: the owner of `acme/ledger` is served by the source `acme`, so the need is `from acme`, never `from other`

Fetching copies each locked release from the mirror once, checks it, and keeps it in Itaoca; a release Itaoca holds already is not read again:

Terminal
$ una ita fetch
fetched acme/ledger 0.3.1
$ una ita fetch
acme/ledger 0.3.1 is in Itaoca

Once fetched, the package's module is imported like a path dependency's, and una check, una run and una build find it in Itaoca. una ita tree looks in vendor/ita/ only, so once the package is vendored it names where each package comes from and who signed it:

una
module shop

import ledger.ledger (total)

pub sum() -> Int = total() + 1
Terminal
$ una ita vendor
vendored acme/ledger 0.3.1
$ una ita tree
shop 0.1.0
  acme/ledger 0.3.1 (acme, signed acme): may nothing (by shop); uses nothing; trust none

Edge cases

Diagnostics

Edition

Edition 0.4 and later, a preview.

Normative source