torb install

torb install fetches every package project.lock.trb pins that is not in the cache yet, checks its tree hash before a file is written, and never changes the lock.

install is what a fresh checkout runs before its first build: it reads project.lock.trb, fetches every registry, archive: and git: package it pins that is not unpacked in the cache yet, checks each one against the tree hash the lock pins, and unpacks it. It resolves nothing and never writes the lock; installing never runs code.

Synopsis#

torb install                 The packages of the lock of the workspace around the working directory
  --offline                  No network: fail naming the first package that would have to be fetched
  --project <directory>      The project whose workspace to install

What it does#

The cache#

The cache is $TORB_CACHE, or ~/.torb/cache on Linux, macOS and FreeBSD and %LOCALAPPDATA%\torb\cache on Windows. It is content-addressed and shared by every project of the machine:

<cache>/packages/<hex of the tree hash>/    one package, unpacked, with a .complete written last
<cache>/index/<registry>/<owner>/<name>.trb the last copy of an index file from a registry on the network

Where a package is fetched from#

From the registry the lock names, as the project binds the owner: a registry on the network over HTTPS, or a file: registry, a directory of the same files. The network is curl, else wget; TORB_FETCH=curl or wget chooses one.

The mirrors of the machine's config.trb are asked first, in the order of that file, for a registry on the network. A mirror that does not have the archive, or cannot be reached, is passed over. What a mirror serves is checked against the pinned tree hash like anything else, and a refusal names the mirror. --offline contacts no mirror.

An archive: package comes from the URL its row of the lock names - a file: path relative to the workspace root, or https://... fetched the same way, without mirrors - and is checked with the same checks. One that is unpacked under its tree hash already is never fetched again; with --offline one that is not is an error saying it would have to be fetched:

$ torb install --offline
error: --offline, and acme/text is not unpacked in the cache: it would have to be fetched from https://files.acme.test/text-1.0.0.tar.gz

A git: package is fetched with the git executable on the machine (TORB_GIT names another one) at the commit its row pins - never at what its tag or branch names now - into a scratch directory under the cache, and its package files are checked like an archive's, a symbolic link refused, and installed under the pinned tree hash; a tree of another hash is refused. One already unpacked runs no git, and --offline never runs it:

$ torb install
installed acme/yaml from https://git.acme.test/yaml.git at 4f0c2b1d9e8a7f6b5c4d3e2f1a0b9c8d7e6f5a4b
1 package installed, 0 of them already in the cache

What is refused#

An archive whose tree hash is not the pinned one, a path that is absolute or climbs out of the package, a link, and an archive of more than 10 MiB or of more than 64 MiB unpacked - each before anything is written:

$ torb install --project app
error: acme/json 1.2.0: the tree hash is sha256:3f0a..., and sha256:9d41... was pinned: the archive is not the one that was published

A lock that does not match project.trb is refused with the command that fixes it; install does not resolve.

Examples#

A fresh checkout, with an empty cache:

$ torb install --project app
installed acme/json 1.2.0
1 package installed, 0 of them already in the cache
$ torb check app
2 files, no problems

project.lock.trb - what install reads.
config.trb - the mirrors an archive is fetched through.
torb update - the command that writes a lock where there is none.