Toolchains: pep-install

pep-install installs Pepper toolchains side by side and picks the default one, the way rustup and nvm do. pepper install runs it with the same arguments:

pepper install list               # the installed toolchains, marking the default and the one in use here
pepper install list --available   # the releases with an archive for this machine
pepper install add 0.3            # installs the newest 0.3.x; the default stays as it is
pepper install use 0.3.0          # makes it the default
pepper install update             # installs the newest release and makes it the default
pepper install add --force 0.3.0  # installs 0.3.0 again, replacing it
pepper install remove 0.2.1
pepper install which              # the toolchain this folder uses, why, and its pep-build
pepper install setup              # sets this machine up: installs, sets the default and the PATH, checks
pepper install uninstall          # removes the home and its PATH changes

pep-install <command> [arguments]

A toolchain is one release of the compiler, its runtime and the tools (pep-build, pep-fmt, pep-test, …). The pepper command that pep-install sits beside runs the tools of the toolchain a folder uses: the one pepper +<version> names, else PEPPER_TOOLCHAIN’s, else the one the project’s pep.toml pins with toolchain = "0.3", else the default (see Toolchains).

Options and commands

A <version> is exact (0.3.0), or a prefix (0.3, 0) for the newest release, or installed toolchain, that starts so, or latest for the newest. A prerelease such as 0.4.0-dev, the build of main that each merge replaces, is picked only by naming it exactly; prefixes, latest and update leave prereleases out. Only releases are installed; there is no nightly channel.

The exit status is 0 on success, 1 when a command fails, and 2 for a mistake on the command line.

Where toolchains go

The Pepper home holds them:

~/.pepper/bin/pepper                 the entry point
~/.pepper/bin/pep-install
~/.pepper/toolchains/0.3.0/bin/      a toolchain's pep-build, pep-fmt, ...
~/.pepper/toolchains/0.3.0/runtime/  and its runtime
~/.pepper/default-toolchain          the default toolchain's version

The install scripts set up the home by running setup (see Setting a machine up): it installs the newest release this way and puts its pepper and pep-install in bin.

update replaces the home’s pepper and pep-install with the new toolchain’s when they differ. Each is written beside the old one and renamed into place, the old one first moved aside to <name>.old; on Windows, where a running program cannot be removed, that .old file is removed by the next update.

add --force and update --force install a toolchain that is already installed again, the way a fresh one is: downloaded, checked and unpacked beside its folder. The old folder is then moved aside, the new one put in its place and the old one removed, so no stale files remain, and a failed download or unpack leaves the old toolchain as it was. On Windows a toolchain one of whose programs is running (a pep-lsp the editor started, say) cannot be moved, and the install fails, leaving it in place.

The home is the folder above the running pep-install when that is a home (it has a toolchains folder), else PEPPER_HOME, else %LOCALAPPDATA%\pepper on Windows and ~/.pepper elsewhere.

Setting a machine up

setup is what the install scripts run, from the installer archive each release carries (pepper-install-<version>-<target>.tar.gz, .zip on Windows, holding only pep-install). It does what add and use do, then:

• puts the toolchain’s pepper and pep-install in the home’s bin, as update does;
• unless that folder is on the PATH already or --no-modify-path is given, adds it: on Windows to the user’s PATH, elsewhere with a line in ~/.profile, and in ~/.bashrc, ~/.bash_profile and ~/.zshrc when they exist (~/.zshrc also when the shell is zsh), and in fish’s conf.d/pepper.fish when fish is installed. Each line follows a # Added by the Pepper installer comment;
• unless --no-prerequisites is given, checks for what linking a program needs and offers to install what is missing, asking on the terminal first unless --yes is given: Xcode’s command line tools on macOS, the Visual Studio Build Tools’ C++ workload on Windows (with winget), and clang when the check program’s build finds none (apt, dnf, yum, pacman or zypper on Linux, through sudo when not root; winget or Scoop on Windows). It notes when OpenSSL 3, which the tls module loads, is missing, and on macOS offers brew install openssl@3;
• builds and runs a small program with the home’s pepper, from an empty folder, and fails when it cannot.

A toolchain from before side-by-side toolchains, which has no pepper to put in bin, cannot be set up. An archive named for no release (a dev build, pepper-dev-<target>) is installed under the version its pep-build reports.

uninstall removes the home, refusing a folder that holds neither toolchains nor bin/pep-build, and the PATH lines setup added for that home’s bin.

More toolchain folders

Toolchains are also found in the folders PEPPER_TOOLCHAIN_PATH lists, separated as PATH separates them (; on Windows, : elsewhere), and for pep-install in each --path folder, which come first. Each is laid out as the home’s toolchains folder is, a folder per toolchain named by its version:

/opt/pepper/0.3.0/bin/pep-build
/opt/pepper/0.3.0/runtime/

PEPPER_TOOLCHAIN_PATH=/opt/pepper pepper +0.3.0 build main.pep
pepper install --path /opt/pepper use 0.3.0

The home’s own toolchains folder is searched first, so a toolchain there wins over one of the same version elsewhere. list marks a toolchain found elsewhere with its folder; use, which and pepper +<version> take it as they take one in the home, and add and update count it as installed (--force installs into the home all the same). remove removes only toolchains in the home: a toolchain in another folder is left to whoever put it there. A project’s pep.toml cannot add folders, since where toolchains are differs from one machine to the next.

Editors

The VS Code extension runs the language server of the toolchain the workspace uses, as pepper install which reports it, and offers to install Pepper, the toolchain the workspace needs, or a newer default when they are missing or old; see pep-lsp.

Downloads

add and update find this machine’s archive (linux-x64, macos-arm64, macos-x64 or windows-x64) among the GitHub releases, as the install scripts do, download it and check it against its .sha256. The archive is unpacked beside the toolchain’s folder first, so a download that fails or does not match its checksum leaves nothing behind.