Toolchains
Many rustup
commands deal with toolchains, a single installation of the
Rust compiler. rustup
supports multiple types of toolchains. The most basic
track the official release channels: stable, beta and nightly; but
rustup
can also install toolchains from the official archives, for alternate
host platforms, and from local builds.
Toolchain specification
Standard release channel toolchain names have the following form:
<channel>[-<date>][-<host>]
<channel> = stable|beta|nightly|<versioned>[-<prerelease>]
<versioned> = <major.minor>|<major.minor.patch>
<prerelease> = beta[.<number>]
<date> = YYYY-MM-DD
<host> = <target-triple>
‘channel’ is a named release channel, a major and minor version number such as
1.42
, or a fully specified version number, such as 1.42.0
. Channel names
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.
Finally, the host may be specified as a target triple. This is most useful for installing a 32-bit compiler on a 64-bit platform, or for installing the MSVC-based toolchain on Windows. For example:
$ rustup toolchain install stable-x86_64-pc-windows-msvc
For convenience, elements of the target triple that are omitted will be inferred, so the above could be written:
$ rustup toolchain install stable-msvc
Toolchain names that don’t name a channel instead can be used to name custom toolchains.
Custom toolchains
For convenience of developers working on Rust itself, rustup
can manage
local builds of the Rust toolchain. To teach rustup
about your build, run:
$ rustup toolchain link my-toolchain path/to/my/toolchain/sysroot
For example, on Ubuntu you might clone rust-lang/rust
into ~/rust
, build
it, and then run:
$ rustup toolchain link my-toolchain ~/rust/build/x86_64-unknown-linux-gnu/stage2/
$ rustup default my-toolchain
Now you can name my-toolchain
as any other rustup
toolchain. Create a
rustup
toolchain for each of your rust-lang/rust
workspaces and test them
easily with rustup run my-toolchain rustc
.
Because the rust-lang/rust
tree does not include Cargo, when cargo
is
invoked for a custom toolchain and it is not available, rustup
will attempt
to use cargo
from one of the release channels, preferring ‘nightly’, then
‘beta’ or ‘stable’.