Home / Docs / Configure a package

Offline builds

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 no registry package to put on the machine yet. Path dependencies are the dependencies usable in this release (see path dependencies).

A package of edition 0.4 builds with no network once its registry packages are on the machine. There are three ways to put them there, and each one checks every byte against ita.lock:

Why it works this way: a build that reaches the network can give a different result on a different day, or fail when a registry is down. una check, una run, una build, una test, una report, una fmt, una fix and the language server never open a connection for a package. They read the locked packages from the vendor directory or Itaoca and check each against the lock's digest, its signature by the key the lock names and its inclusion in the logged checkpoint, all offline. That the key was the owner's, valid at its log position, is checked by the registry client when the lock is resolved and when the package is fetched, bundled or unbundled, not again when it is loaded. So the same package gives the same result with or without a network, and a vendored copy that someone edited does not load.

ita.unauna
-- fails with U7010
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

vendor/ita/acme/acme+ledger-0.3.1/ita.una

una
ita acme/ledger
  version 0.3.1
  edition 0.4
  about "Ledgers"
  license "Apache-2.0"
  publish to acme

vendor/ita/acme/acme+ledger-0.3.1/src/ledger.una

una
module ledger

pub total() -> Int = 4
src/shop.unauna
module shop

pub one() -> Int = 1

The vendored copy of acme/ledger was edited after una ita vendor wrote it: its total returned 3. Its files no longer have the locked digest, and it has no provenance file beside it, so una check refuses it (U7010). Neither problem is repaired from Itaoca: a vendored copy that fails stays refused until una ita vendor writes it again from a verified copy.

Forms

text
una ita fetch [path]             copy the locked releases into Itaoca, verified
una ita vendor [path]            copy them from Itaoca into vendor/ita/
una ita verify [path]            check every copy again, in vendor/ita/ and in Itaoca
una ita bundle <file> [path]     write them, with their proofs, into one file
una ita unbundle <file> [path]   verify a bundle against the lock and fill Itaoca

Examples

On a machine that holds a mirror of the registry, fetch and vendor the locked releases, then commit vendor/ with the package:

Terminal
$ una ita fetch
fetched acme/ledger 0.3.1
$ una ita vendor
vendored acme/ledger 0.3.1
$ una ita vendor
vendor/ita is up to date

The vendor directory now holds:

text
vendor/ita/acme/acme+ledger-0.3.1/ita.una
vendor/ita/acme/acme+ledger-0.3.1/src/ledger.una
vendor/ita/acme/acme+ledger-0.3.1.provenance

A fresh checkout, on a machine whose Itaoca is empty and that has no mirror, checks and builds from it alone: una check exits with code 0.

For a machine with no network, write a bundle on the one that holds the mirror, carry the file over, and unbundle it in the package there. A second unbundle stores nothing new:

Terminal
$ una ita bundle ../shop.bundle
bundled 1 registry packages into ../shop.bundle
$ una ita unbundle ../shop.bundle
stored acme/ledger 0.3.1 in Itaoca
$ una ita unbundle ../shop.bundle
70 entries of the bundle were not used and not stored
Itaoca holds every locked registry package already

una ita verify reads every copy again. In this release it reports a package whose copies all match the lock as not yet verified, since the owner's key chain is not held beside it yet, and exits with code 1:

Diagnostic
$ una ita verify
[U7013] Error: `acme/ledger 0.3.1` is not verified: its files and provenance in vendor/ita and Itaoca match the lock, but the owner's key chain and its name map proof are not held until the registry client supplies them

Edge cases

Diagnostics

Edition

Edition 0.4 and later, a preview.

Normative source