Build Status | |
---|---|
Travis | |
AppVeyor |
rustup installs The Rust Programming Language from the official release channels, enabling you to easily switch between stable, beta, and nightly compilers and keep them updated. It makes cross-compiling simpler with binary builds of the standard library for common platforms. And it runs on all platforms Rust supports, especially Windows.
WARNING: This is beta software.
- Installation
- How rustup works
- Keeping Rust up to date
- Working with nightly Rust
- Directory overrides
- Toolchain specification
- Cross-compilation
- Working with Rust on Windows
- Working with custom toolchains
- Examples
- Environment variables
- Other installation methods
- Security
- FAQ
- License
- Contributing
Follow the instructions at www.rustup.rs. If that doesn't work for you there are other installation methods.
rustup
installs rustc
, cargo
, rustup
and other standard tools
to Cargo's bin
directory. On Unix it is located at
$HOME/.cargo/bin
and on Windows at %USERPROFILE%\.cargo\bin
. This
is the same directory that cargo install
will install Rust programs
and Cargo plugins.
This directory will be in your $PATH
environment variable, which
means you can run them from the shell without further
configuration. Open a new shell and type the following:
rustc --version
If you see something like rustc 1.7.0 (a5d1e7a59 2016-02-29)
then
you are ready to Rust. If you decide Rust isn't your thing, you can
completely remove it from your system by running rustup self uninstall
.
rustup
is a toolchain multiplexer. It installs and manages many
Rust toolchains and presents them all through a single set of tools
installed to ~/.cargo/bin
. The rustc
and cargo
installed to
~/.cargo/bin
are proxies that delegate to the real
toolchain. rustup
then provides mechanisms to easily change the
active toolchain by reconfiguring the behavior of the proxies.
So when rustup
is first installed running rustc
will run the proxy
in $HOME/.cargo/bin/rustc
, which in turn will run the stable
compiler. If you later change the default toolchain to nightly with
rustup default nightly
, then that same proxy will run the nightly
compiler instead.
This is similar to Ruby's rbenv or Python's pyenv.
Rust is distributed on three different release channels: stable,
beta, and nightly. rustup
is configured to use the stable channel by
default, which represents the latest release of Rust,
and is released every six weeks.
When a new version of Rust is released, you can type rustup update
to update
to it:
$ rustup update
info: syncing channel updates for 'stable'
info: downloading component 'rustc'
info: downloading component 'rust-std'
info: downloading component 'rust-docs'
info: downloading component 'cargo'
info: installing component 'rustc'
info: installing component 'rust-std'
info: installing component 'rust-docs'
info: installing component 'cargo'
info: checking for self-updates
info: downloading self-updates
stable updated: rustc 1.7.0 (a5d1e7a59 2016-02-29)
This is the essense of rustup
.
Rustup gives you easy access to the nightly compiler and its
experimental features. To add it just run rustup install nightly
:
$ rustup install nightly
info: syncing channel updates for 'nightly'
info: downloading toolchain manifest
info: downloading component 'rustc'
info: downloading component 'rust-std'
info: downloading component 'rust-docs'
info: downloading component 'cargo'
info: installing component 'rustc'
info: installing component 'rust-std'
info: installing component 'rust-docs'
info: installing component 'cargo'
nightly installed: rustc 1.9.0-nightly (02310fd31 2016-03-19)
Now Rust nightly is installed, but not activated. To test it out you can run a command from the nightly toolchain like
$ rustup run nightly rustc --version
rustc 1.9.0-nightly (02310fd31 2016-03-19)
But more likely you want to use it for a while. To switch to nightly
globally, change the default with rustup default nightly
:
$ rustup default nightly
info: using existing install for 'nightly'
info: default toolchain set to 'nightly'
nightly unchanged: rustc 1.9.0-nightly (02310fd31 2016-03-19)
Now any time you run cargo
or rustc
you will be running the
nightly compiler.
With nightly installed any time you run rustup update
, the nightly channel
will be updated in addition to stable:
$ rustup update
info: syncing channel updates for 'stable'
info: syncing channel updates for 'nightly'
info: checking for self-updates
info: downloading self-updates
stable unchanged: rustc 1.7.0 (a5d1e7a59 2016-02-29)
nightly unchanged: rustc 1.9.0-nightly (02310fd31 2016-03-19)
Directories can be assigned their own Rust toolchain with
rustup override
. When a directory has an override then
any time rustc
or cargo
is run inside that directory,
or one of its child directories, the override toolchain
will be invoked.
To pin to a specific nightly:
rustup override add nightly-2014-12-18
Or a specific stable release:
rustup override add 1.0.0
To see the active toolchain use rustup show
. To remove the override
and use the default toolchain again, rustup override remove
.
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.
Standard release channel toolchain names have the following form:
<channel>[-<date>][-<host>]
<channel> = stable|beta|nightly|<version>
<date> = YYYY-MM-DD
<host> = <target-triple>
'channel' is either a named release channel or an explicit version number, such as "1.8.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 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 install stable-msvc
Toolchain names that don't name a channel instead can be used to name custom toolchains.
Rust supports a great number of platforms. For many of these
platforms The Rust Project publishes binary releases of the standard
library, and for some the full compiler. rustup
gives easy access
to all of them.
When you first install a toolchain, rustup
installs only the
standard library for your host platform - that is, the architecture
and operating system you are presently running. To compile to other
platforms you must install other target platforms. This is done
with the rustup target add
command. For example, to add the
Android target:
$ rustup target add arm-linux-androideabi
info: downloading component 'rust-std' for 'arm-linux-androideabi'
info: installing component 'rust-std' for 'arm-linux-androideabi'
With the arm-linux-andoideabi
target installed you can then build
for Android with Cargo by passing the --target
flag, as in cargo build --target=arm-linux-androideabi
.
Note that rustup target add
only installs the Rust standard library
for a given target. There are typically other tools necessary to
cross-compile, particularly a linker. For example, to cross compile
to Android the Android NDK must be installed. In the future, rustup
will provide assistence installing the NDK components as well.
To see a list of available targets, rustup target list
. To remove a
previously-added target, rustup target remove
.
rustup
works the same on Windows as it does on Unix, but there are
some special considerations for Rust developers on Windows. As
mentioned on the Rust download page, there are two ABIs in use
on Windows: the native (MSVC) ABI used by Visual Studio, and the GNU
ABI used by the GCC toolchain. Which version of Rust you need depends
largely on what C/C libraries you want to interoperate with: for
interop with software produced by Visual Studio use the MSVC build of
Rust; for interop with GNU software built using the MinGW/MSYS2
toolchain use the GNU build.
MSVC builds of Rust additionally require an installation of Visual Studio 2013 (or later) or the Visual C Build Tools 2015 so rustc can use its linker. For Visual Studio, make sure to check the "C tools" option. No additional software installation is necessary for basic use of the GNU build.
Rust's support for the GNU ABI is more mature, and is recommended for
typical uses, so that's what rustup
installs by default. The MSVC
toolchain is always available. To switch to it just
$ rustup default stable-msvc
For convenience of developers working on Rust itself, rustup
can manage
local builds of the Rust toolchain. To teach rustup
about your build
just run:
$ rustup toolchain link my-toolchain path/to/my/toolchain/sysroot
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,
prefering 'nightly', then 'beta' or 'stable'.
Command | Description |
---|---|
rustup default nightly |
Set the default toolchain to the latest nightly |
rustup target list |
List all available targets for the active toolchain |
rustup target add arm-linux-androideabi |
Install the Android target |
rustup target remove arm-linux-androideabi |
Remove the Android target |
rustup run nightly rustc foo.rs |
Run the nightly regardless of the active toolchain |
rustup run nightly bash |
Run a shell configured for the nightly compiler |
rustup default stable-msvc |
On Windows, use the MSVC toolchain instead of GNU |
rustup override nightly-2015-04-01 |
For the current directory, use a nightly from a specific date |
rustup toolchain link my-toolchain "C:\RustInstallation" |
Install a custom toolchain by symlinking an existing installation |
rustup show |
Show which toolchain will be used in the current directory |
-
RUSTUP_HOME
(default:~/.rustup
or%USERPROFILE%/.rustup
) Sets the root rustup folder, used for storing installed toolchains and configuration options. -
RUSTUP_TOOLCHAIN
(default: none) If set, will override the toolchain used for all rust tool nvocations. A toolchain with this name should be installed, or invocations will fail. -
RUSTUP_DIST_ROOT
(default:https://static.rust-lang.org/dist
) Sets the root URL for downloading Rust toolchains and release channel updates. You can change this to instead use a local mirror, or to test the binaries from the staging directory. -
RUSTUP_UPDATE_ROOT
(defaulthttps://static.rust-lang.org/rustup/dist
) Sets the root URL for downloading self-updates.
The primary installation method, as described at www.rustup.rs, differs by platform:
- On Windows, download and run the rustup-init.exe for the
i686-pc-windows-gnu
target. Although this build ofrustup
installs compilers targeting the GNU ABI by default, compilers targetting the MSVC ABI can be installed with e.g.rustup install stable-msvc
. - On Unix, run
curl https://sh.rustup.rs -sSf | sh
in your shell. This downloads and runs the correct version ofrustup-init
for your platform.
rustup-init
accepts arguments, which can be passed through
the shell script. Some examples:
$ curl https://sh.rustup.rs -sSf | sh -s -- --help
$ curl https://sh.rustup.rs -sSf | sh -s -- --no-modify-path
$ curl https://sh.rustup.rs -sSf | sh -s -- --default-toolchain nightly
If you prefer you can directly download rustup-init
for the
platform of your choice:
- aarch64-unknown-linux-gnu
- arm-unknown-linux-gnueabi
- arm-unknown-linux-gnueabihf
- armv7-unknown-linux-gnueabihf
- i686-apple-darwin
- i686-pc-windows-gnu
- i686-pc-windows-msvc†
- i686-unknown-linux-gnu
- x86_64-apple-darwin
- x86_64-pc-windows-gnu
- x86_64-pc-windows-msvc†
- x86_64-unknown-freebsd
- x86_64-unknown-linux-gnu
- x86_64-unknown-netbsd
†
MSVC builds of rustup
additionally require an installation of
Visual Studio 2015 or the Visual C Build Tools 2015. For
Visual Studio, make sure to check the "C tools" option. No
additional software installation is necessary for basic use of
the GNU build.
To install from source just run cargo run --release
. Note that
currently rustup only builds on nightly Rust, and that after
installation the rustup toolchains will supercede any pre-existing
toolchains by prepending ~/.cargo/bin
to the PATH
environment
variable.
rustup
is secure enough for the non-paranoid, but it still needs
work. rustup
performs all downloads over HTTPS, but does not
yet validate signatures of downloads.
Yes. rustup is an official Rust project. Once it is complete it will be the recommended way to install Rust and www.rust-lang.org will be updated to reflect that.
rustup is the successor to multirust. rustup began as multirust-rs, a rewrite of multirust from shell script to Rust, by Diggory Blake, and is now maintained by The Rust Project.
Copyright Diggory Blake, the Mozilla Corporation, and rustup contributors.
Licensed under either of
- Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
- Fork it!
- Create your feature branch:
git checkout -b my-new-feature
- Commit your changes:
git commit -am 'Add some feature'
- Push to the branch:
git push origin my-new-feature
- Submit a pull request :D
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.