Name: rustup.rs
Owner: rust-lang-nursery
Description: The Rust toolchain installer
Created: 2015-09-26 04:54:49.0
Updated: 2018-01-18 07:39:42.0
Pushed: 2018-01-16 10:04:57.0
Size: 9810
Language: Rust
GitHub Committers
User | Most Recent Commit | # Commits |
---|
Other Committers
User | Most Recent Commit | # Commits |
---|
| 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, including Windows.
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:
c --version
If you see something like rustc 1.19.0 (0ade33941 2017-07-17)
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
now supports generating completion scripts for Bash, Fish,
and Zsh. See rustup help completions
for full details, but the
gist is as simple as using one of the following:
sh
stup completions bash > /etc/bash_completion.d/rustup.bash-completion
sh (macOS/Homebrew)
stup completions bash > $(brew --prefix)/etc/bash_completion.d/rustup.bash-completion
sh
stup completions fish > ~/.config/fish/completions/rustup.fish
h
stup completions zsh > ~/.zfunc/_rustup
Note: you may need to restart your shell in order for the changes to take effect.
For zsh
, you must then add the following line in your ~/.zshrc
before
compinit
:
h+=~/.zfunc
rustup
allows you to customise your installation by setting the environment
variables CARGO_HOME
and RUSTUP_HOME
before running the rustup-init
executable. As mentioned in the Environment Variables section, RUSTUP_HOME
sets the root rustup folder, which is used for storing installed
toolchains and configuration options. CARGO_HOME
contains cache files used
by cargo.
Note that you will need to ensure these environment variables are always
set and that CARGO_HOME/bin
is in the $PATH
environment variable when
using the toolchain.
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, Python's pyenv, or Node's nvm.
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:
stup update
: syncing channel updates for 'stable'
: downloading component 'rustc'
: downloading component 'rust-std'
: downloading component 'rust-docs'
: downloading component 'cargo'
: installing component 'rustc'
: installing component 'rust-std'
: installing component 'rust-docs'
: installing component 'cargo'
: checking for self-updates
: downloading self-updates
able updated: rustc 1.7.0 (a5d1e7a59 2016-02-29)
This is the essence of rustup
.
Running rustup update
also checks for updates to rustup
and automatically
installs the latest version. To manually check for updates and install the
latest version of rustup
without updating installed toolchains type rustup
self update
:
stup self update
: checking for self-updates
: downloading self-updates
Rustup gives you easy access to the nightly compiler and its
experimental features. To add it just run rustup install
nightly
:
stup install nightly
: syncing channel updates for 'nightly'
: downloading toolchain manifest
: downloading component 'rustc'
: downloading component 'rust-std'
: downloading component 'rust-docs'
: downloading component 'cargo'
: installing component 'rustc'
: installing component 'rust-std'
: installing component 'rust-docs'
: installing component 'cargo'
ghtly 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
stup run nightly rustc --version
c 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
:
stup default nightly
: using existing install for 'nightly'
: default toolchain set to 'nightly'
ghtly 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:
stup update
: syncing channel updates for 'stable'
: syncing channel updates for 'nightly'
: checking for self-updates
: downloading self-updates
table unchanged: rustc 1.7.0 (a5d1e7a59 2016-02-29)
ghtly unchanged: rustc 1.9.0-nightly (02310fd31 2016-03-19)
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:
nnel>[-<date>][-<host>]
nnel> = stable|beta|nightly|<version>
e> = YYYY-MM-DD
t> = <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:
stup 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:
stup install stable-msvc
Toolchain names that don't name a channel instead can be used to name custom toolchains.
The rustup
toolchain proxies can be instructed directly to use a
specific toolchain, a convience for developers who often test
different toolchains. If the first argument to cargo
, rustc
or
other tools in the toolchain begins with +
, it will be interpreted
as a rustup toolchain name, and that toolchain will be preferred,
as in
o +beta test
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 use to a specific nightly for a directory:
up override set nightly-2014-12-18
Or a specific stable release:
up override set 1.0.0
To see the active toolchain use rustup show
. To remove the override
and use the default toolchain again, rustup override unset
.
rustup
directory overrides are a local configuration, stored in
$RUSTUP_HOME
. Some projects though find themselves 'pinned' to a
specific release of Rust and want this information reflected in their
source repository. This is most often the case for nightly-only
software that pins to a revision from the release archives.
In these cases the toolchain can be named in the project's directory
in a file called rust-toolchain
, the content of which is the name of
a single rustup
toolchain, and which is suitable to check in to
source control.
The toolchains named in this file have a more restricted form than rustup toolchains generally, and may only contain the names of the three release channels, 'stable', 'beta', 'nightly', Rust version numbers, like '1.0.0', and optionally an archive date, like 'nightly-2017-01-01'. They may not name custom toolchains, nor host-specific toolchains.
There are several ways to specify which toolchain rustup
should
execute:
cargo +beta
,RUSTUP_TOOLCHAIN
environment variable,rustup override set beta
,rust-toolchain
file,and they are prefered by rustup in that order, with the explicit
toolchain having highest precedence, and the default toolchain having
the lowest. There is one exception though: directory overrides and the
rust-toolchain
file are also preferred by their proximity to the
current directory. That is, these two override methods are discovered
by walking up the directory tree toward the filesystem root, and a
rust-toolchain
file that is closer to the current directory will be
prefered over a directory override that is further away.
To verify which toolchain is active use rustup show
.
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:
stup target add arm-linux-androideabi
: downloading component 'rust-std' for 'arm-linux-androideabi'
: installing component 'rust-std' for 'arm-linux-androideabi'
With the arm-linux-androideabi
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 assistance 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.
When targeting the MSVC ABI, Rust additionally requires 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.
By default rustup on Windows configures Rust to target the 32-bit MSVC
ABI, that is the i686-pc-windows-msvc
target triple. More
specifically, the toolchains that rustup chooses to install, unless
told otherwise through the toolchain specification, will be compiled
to run on a i686-pc-windows-msvc
host, and will target that platform
by default. When you write rustup update nightly
, rustup interprets
it as rustup update nightly-i686-pc-windows-msvc
. You can change this
behavior with rustup set default-host
or during installation.
stup set default-host x86_64-pc-windows-msvc
Since the MSVC ABI provides the best interoperation with other Windows software
it is recommended for most purposes. The GNU toolchain is always available, even
if you don't use it by default. Just install it with rustup install
:
stup install stable-gnu
You don't need to switch toolchains to support all windows targets though; a single toolchain supports all four x86 windows targets:
stup target add x86_64-pc-windows-msvc
stup target add x86_64-pc-windows-gnu
stup target add i686-pc-windows-msvc
stup target add i686-pc-windows-gnu
For convenience of developers working on Rust itself, rustup
can manage
local builds of the Rust toolchain. To teach rustup
about your build,
run:
stup 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:
stup toolchain link myrust ~/rust/build/x86_64-unknown-linux-gnu/stage2/
stup default myrust
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'.
Enterprise networks often don't have direct outside HTTP access, but enforce
the use of proxies. If you're on such a network, you can request that
rustup uses a proxy by setting its URL in the environment. In most cases,
setting https_proxy
should be sufficient. On a Unix-like system with a
shell like bash or zsh, you could use:
rt https_proxy=socks5://proxy.example.com:1080 # or http://proxy.example.com:8080
On Windows, the command would be:
https_proxy=socks5://proxy.example.com:1080
If you need a more complex setup, rustup supports the convention used by the curl program, documented in the ENVIRONMENT section of its manual page.
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
rustc +nightly foo.rs
| Shorthand way to run a nightly compiler
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 set 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
invocations. A toolchain with this name should be installed, or
invocations will fail.
RUSTUP_DIST_SERVER
(default: https://static.rust-lang.org
)
Sets the root URL for downloading static resources related to Rust.
You can change this to instead use a local mirror,
or to test the binaries from the staging directory.
RUSTUP_DIST_ROOT
(default: https://static.rust-lang.org/dist
)
Deprecated. Use RUSTUP_DIST_SERVER
instead.
RUSTUP_UPDATE_ROOT
(default https://static.rust-lang.org/rustup
)
Sets the root URL for downloading self-updates.
The primary installation method, as described at www.rustup.rs, differs by platform:
i686-pc-windows-gnu
target. In general, this is the build of rustup
one should install on Windows. Despite being built against the GNU toolchain,
the Windows build of rustup will install Rust for the MSVC toolchain if it
detects that MSVC is installed. If you prefer to install GNU toolchains or
x86_64 toolchains by default this can be modified at install time, either
interactively or with the --default-host
flag, or after installation via
rustup set default-host
.curl https://sh.rustup.rs -sSf | sh
in your
shell. This downloads and runs rustup-init.sh
, which in turn
downloads and runs the correct version of the rustup-init
executable for your platform.rustup-init
accepts arguments, which can be passed through
the shell script. Some examples:
rl https://sh.rustup.rs -sSf | sh -s -- --help
rl https://sh.rustup.rs -sSf | sh -s -- --no-modify-path
rl https://sh.rustup.rs -sSf | sh -s -- --default-toolchain nightly
rl https://sh.rustup.rs -sSf | sh -s -- --default-toolchain none
If you prefer you can directly download rustup-init
for the
platform of your choice:
?
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.
You can fetch an older version from https://static.rust-lang.org/rustup/archive/{rustup-version}/{target-triple}/rustup-init[.exe]
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 supersede 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. It is the recommended way to install Rust at www.rust-lang.org.
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.
The Rust source can be obtained by running rustup component add rust-src
.
It will be downloaded to the <toolchain root>/lib/rustlib/src/rust
directory of the current toolchain.
If rustup fails with Windows error 32, it may be due to antivirus scanning in the background. Disable antivirus scanner and try again.
Copyright Diggory Blake, the Mozilla Corporation, and rustup contributors.
Licensed under either of
at your option.
git checkout -b my-new-feature
git commit -am 'Add some feature'
git push origin my-new-feature
For developing on rustup
itself, you may want to install into a temporary
directory, with a series of commands similar to this:
rgo build
dir home
STUP_HOME=home CARGO_HOME=home target/debug/rustup-init --no-modify-path -y
You can then try out rustup
with your changes by running home/bin/rustup
, without
affecting any existing installation. Remember to keep those two environment variables
set when running your compiled rustup-init
or the toolchains it installs, but unset
when rebuilding rustup
itself.
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.