toolchain

Install applications and vendor libraries from the catalog they are released to.

What it does

toolchain is the one application you download yourself. Every other application comes through it, and so does a library you want placed in a repository:

It reads one catalog, the one the product publishes its releases to, and nothing you configure points it anywhere else. An installed application’s own releases and its own update are that application’s to show and to make: ask the application, not toolchain. toolchain update, toolchain version list and toolchain version show are about toolchain itself, as they are on every application: update moves an installed application to its newest release, showing the download as it arrives and then what the release changed, and version list lists the releases there are for your machine. update --to <version> moves to one of those instead of the newest. A version older than the one installed is refused, saying both, unless you add --force, which permits moving backwards and nothing else; the version already installed changes nothing.

Concepts

A release is public or it is not offered. The catalog holds every release, and you are handed the ones chosen for clients. The newest release is the newest of those; a version you name that is not one of them is refused, with the versions that are.

An application is built per platform. A release holds one executable per platform, named <os>-<cpu>: windows-x64, linux-x64. install takes the one built for the machine it runs on and refuses, by name, a platform the release has no build for.

What is fetched is checked. The catalog records the sha256 of every file it holds. A file that is not the one recorded is refused and nothing is installed or placed.

The distribution token

The catalog answers only a request carrying the token you were issued, so set it once before installing anything:

toolchain token set

It asks for the token at a prompt that does not echo what you type, or reads it from standard input where you pipe it there. It is never taken as an argument, since a shell’s history and a process listing keep what is typed on a command line. A token is sps_pkg_ and 43 letters, digits, - or _; anything else is refused before it is kept. It is kept in a file named token in the same per-user directory installed applications are kept in, readable by your user alone, and it is never shown or logged.

Every application reads it from there: toolchain install and toolchain vendor, and each installed application’s own update and version list. toolchain token show says whether a token is set and where it is read from, without showing it, and toolchain token clear removes it.

Where no command is run to set one, as in a CI job, state it in the SOLIDPLANS_TOKEN environment variable instead. Set and not empty, it is read in place of the kept file.

A token expires. Every command that reads the catalog says so once, as a line beginning warning: on the error stream, when the token it sent expires within a fortnight, naming the date. Ask for a new one before then and set it the way the old one was set. A token that has expired or been revoked is refused as TOKEN_EXPIRED or TOKEN_REVOKED, and asking for a new one is the repair.

Installing an application

toolchain install <application>
toolchain install <application>@<major>.<minor>.<patch>

Nothing needs elevation. Everything is kept under one per-user directory – %LOCALAPPDATA%\toolchain on Windows, ~/.local/share/toolchain on Linux and macOS – which holds each installed application and one bin directory of launchers. An application is one executable file; the first time it starts it unpacks what it needs into your user’s cache directory, and every start after that reuses it. That bin directory is put on your PATH once, when toolchain itself is installed, so installing another application never touches PATH: its launcher appears in a directory your shell already looks in, and you run the application by its name.

Installing the version already installed succeeds and changes nothing. Installing while another version is installed is refused, naming both; --force installs over whatever is there.

The command answers with the version installed, the launcher it wrote and whether bin is on PATH. If it is not, add the directory it names, or run the launcher by its full path.

Vendoring a library

toolchain vendor <namespace>:<name>
toolchain vendor <namespace>:<name>@<major>.<minor>.<patch>

The library is unpacked into the directory the command is run in, at the path the library itself declares, or under lib/ by the name it is imported by where it declares none. What it depends on is placed beside it the same way. The directory needs no manifest and no configuration: this is how the first library reaches a repository that has neither.

Run again, the command takes back exactly the files it placed the time before and places the release it now resolves, so a file a newer release dropped is removed and a file of your own in the same directory is left alone. A library whose dependency the catalog does not hold is refused with the directory as it was.

Any coordinate the catalog answers for is taken. The command does not list what the catalog holds.

What a refusal means

Code Meaning
APPLICATION_NAME_INVALID, COORDINATE_INVALID What was typed does not name an application, or a library
APPLICATION_NOT_FOUND, LIBRARY_NOT_FOUND The catalog holds no public release of that name
VERSION_NOT_RELEASED It holds the name, not that version; the message lists the ones it holds
PLATFORM_NOT_BUILT No release of the application is built for this machine’s platform
APPLICATION_ALREADY_INSTALLED Another version is installed; --force installs over it
APPLICATION_IN_USE The application is running and its files could not be replaced
RELEASE_DIGEST_MISMATCH, RELEASE_DIGEST_UNRECORDED, RELEASE_FILE_MISSING The file is not what the catalog recorded, cannot be checked, or is not there
LIBRARY_PATH_OUTSIDE A library declares a path outside the directory the command was run in
STORE_FETCH_FAILED The catalog could not be reached; the message says what was tried
TOKEN_MISSING No token was sent: none is set and none is in SOLIDPLANS_TOKEN; set the one you were issued
TOKEN_UNKNOWN The catalog does not know the token sent; check it was copied whole, or ask for a new one
TOKEN_REVOKED, TOKEN_EXPIRED The token sent is no longer good; ask for a new one and set it
TOKEN_NOT_ENTITLED The token is good and does not cover what was asked for; ask whoever issued it for one that does
STORE_ACCESS_REFUSED The catalog refused the request for a reason it did not name
TOKEN_MALFORMED The token given, kept or in SOLIDPLANS_TOKEN is not shaped as one; copy it again from where it was issued
TOKEN_UNREADABLE The file the token is kept in could not be read
STORE_SETTING_NOT_HONOURED A configuration file names a store, which this build does not read; remove the field