Skip to main content
  1. All Posts/

multirust

Tools Shell

Note: multirust is not actively maintained. Migrate to rustup.rs (help).

A simple tool for managing multiple installations of the Rust
toolchain. It replaces the standard Rust toolchain with components
that dynamically choose between alternate implementations based on
context.
Features:

  • Manage multiple installations of the official Rust binaries.
  • Configure Rust toolchains per-directory.
  • Install and update from Rust release channels: nightly, beta, and
    stable.
  • Receive notifications of updates to release channels.
  • Install historical nightly toolchains from the official archives.
  • Install by specific stable version number.
  • Install additional stds for cross-compilation.
  • Install custom toolchains.
  • Isolate Cargo metadata per-installation.
  • Verify hashes of downloads.
  • Verify signatures (if GPG is available).
  • Resume partial downloads.
  • Requires only bash, curl and common unix utilities.
  • For Linux, OS X, and Windows (via MSYS2).

Migrating to rustup

If you have multirust installed and you would like to migrate to rustup.rs,
follow these steps (for Linux/Mac):

  1. First, uninstall Multirust using this command:
curl -sf https://raw.githubusercontent.com/brson/multirust/master/blastoff.sh | sh -s -- --uninstall
  1. Delete the folder ~/.multirust.
  2. If the file /usr/local/lib/rustlib/uninstall.sh still exists, the uninstallation was not successful. Run sudo /usr/local/lib/rustlib/uninstall.sh to complete it.
  3. Install rustup using the instructions at rustup.rs.

Quick installation

curl -sf https://raw.githubusercontent.com/brson/multirust/master/blastoff.sh | sh

This will build and install multirust, possibly prompting you for your
password via sudo. It will then download and install the stable
toolchain, configuring it as the default when executing rustc,
rustdoc, and cargo.

Manual build, install and configure

A manual build and install allows one to tailor multirust to meet specific needs.
The basic template is:

git clone --recursive https://github.com/brson/multirust && cd multirust
git submodule update --init
./build.sh && sudo ./install.sh

Run sudo ./install.sh --uninstall to uninstall.
Run multirust default nightly to download and install the nightly
compiler and package manager and configure it as the default.
As an example customization, to install underneath your home
directory in e.g. ~/my_stuff/bin/multirust, you could use:

./build.sh && ./install.sh --prefix=~/my_stuff/

(In this scenario, ./install.sh --prefix=~/my_stuff/ --uninstall to uninstall.)
Run ./build.sh && ./install.sh --help to see a list of available options.

Usage

To install Rust, run multirust update <toolchain>. See multirust help update for
details and to configure what this will install.
Overriding the compiler in specific directories:

mkdir beta-project && cd beta-project
multirust override beta

Now any time the toolchain is executed in the beta-project
directory or any subdirectory thereof the compiler from the beta
release channel will be used.
To pin to a specific nightly:

multirust override nightly-2014-12-18

Or a specific stable release:

multirust override 1.0.0

Information about the current override can be displayed with multirust show-override. The current override can be deleted by running
multirust remove-override from the directory where the override was
created.
Check for updates with multirust update nightly. All three release
channels can be updated at once with multirust update.
multirust run will run an arbitrary command in an environment
configured for a given toolchain, so e.g. multirust run beta cargo build will run the beta cargo, regardless of the current
override. This can also be used to e.g. open a beta shell like
multirust run beta bash.
Commands can be abbreviated by using a prefix of the intended command,
for example multirust ru (run) or multirust s-o (show-override).
In the case of an ambiguous prefix, it picks the first match using the
order of commands shown in multirust help.

Toolchain specification

multirust supports several ways to indicate the toolchain: ‘stable’,
‘beta’ and ‘nightly’ all download from the corresponding release
channel. When any of these toolchain specifiers are used multirust
will periodically notify you of available updates. All three channels
can be optionally appended with an archive date, as in
‘nightly-2014-12-18’, in which case the toolchain is downloaded from
the archive for that date (if available). Any other specifier is
considered an explicit Rust version number, as in ‘0.12.0’, or a custom
toolchain identifier, depending on context.

Cross-compilation

multirust can install additional standard libraries for
cross-compilation targets. Once you have installed a toolchain, use
the multirust list-available-targets command to show which targets
can be added, and multirust add-target to add a target.

Custom toolchains

Custom toolchains – those not distributed by The Rust Project – may be
installed from either custom-built installer or from a local directory
containing a build of Rust.
To install from an existing Rust build use either the --copy-local
or the --link-local flags to the update command. --copy-local
will copy a build of Rust to multirust’s private toolchain
installation directory; --link-local will create a toolchain that is
a symlink to a build of Rust, convenient for those who frequently
build Rust themselves:

multirust update my-rust --link-local ~/dev/rust/build/x86_64-unknown-linux-gnu/stage2

A custom-built installer can be installed with multirust update <toolchain> --installer <installer-path-or-url>, e.g. multirust update my-rust --installer rust-1.0.0-dev-x86_64-unknown-linux-gnu.tar.gz. In this case the
toolchain is installed via the specified installer and can then be
activated with multirust default my-rust.
Since the main Rust build does not produce an installer that includes
Cargo, it may be easier to install the individual rustc and cargo
installers instead of trying to produce the combined installer through
rust-packaging. For
this reason the --installer flag takes a comma-separated list of
installers, allowing custom rustc and cargo packages to be installed
with e.g.

multirust update my-rust --installer rustc-1.0.0-dev-x86_64-unknown-linux-gnu.tar.gz,cargo-nightly-x86_64-unknown-linux-gnu.tar.gz

These three options can also be supplied to the default and
override commands, in which case the toolchain is also
activated after installation.

Implementation Details

multirust installs a script called multirustproxy as all the tools
in the Rust toolchain: rustc, cargo, and rustdoc. This script
consults multirust to decide which toolchain to invoke, and decides
which tool to invoke based on the name it is called as.
multirustproxy automatically applies -C rpath to all rustc
invocations so that the resulting binaries ‘just work’ when using
dynamic linking, even though the toolchains live in various places.
It keeps Cargo’s metadata isolated per toolchain via the CARGO_HOME
environment variable.
multirust saves settings and toolchains per user in ~/.multirust.
The directory is initialized when using the multirust command to
set the default channel, or when setting an override or updating for first time.
The name of this directory can be controlled with the MULTIRUST_HOME
environment variable.

Can you trust Rust binaries?

Although multirust verifies signatures of its downloads if GPG is
available, the question of whether you can ‘trust’ Rust depends on
quite a few factors. Although I’m not prepared to give advice on this
subject, here are some of the details around how the Rust project
binaries are signed and verified. You can make your own judgments.

  • Rust binaries are produced on mostly cloud infrastructure to which
    several people have access.
  • They are signed automatically by a master bot that has access
    to a secret subkey of the Rust signing key.
  • They are uploaded to s3 using a secret key on that same bot.
  • The master bot is exposed to the Internet through an ssh tunnel via
    which it communicates…