rustup Documentation

rustup is the official toolchain installer for the Rust Programming Language. It allows you to:

• Install Rust from official release channels.
• Switch between stable, beta, and nightly compilers.
• Keep toolchains updated.
• Simplify cross-compilation using binary builds of the standard library for common platforms.
• Run on all platforms supported by Rust.

Rustup manages the Rust toolchain using several key abstractions:

• Channels: Groups of toolchains (e.g., stable, beta, nightly).
• Toolchains: Specific installations of the Rust compiler and associated tools.
• Components: Individual pieces of a toolchain, such as rust-docs or rust-analyzer.
• Profiles: Sets of components that are installed together (e.g., default, minimal).
• Proxies: The rustc and cargo commands provided by rustup that proxy calls to the active toolchain.

Rust is released through three primary channels managed by rustup:

• stable: The most reliable channel, with releases every 6 weeks.
• beta: The version that will become the next stable release.
• nightly: Updated every night and contains experimental features.

rustup allows you to install, update, and switch between these channels or specific versions (e.g., 1.45.2 or nightly-2020-07-27).

Rustup is the official toolchain installer for the Rust Programming Language. It allows you to install and manage multiple Rust toolchains (stable, beta, and nightly), switch between them easily, and manage cross-compilation by providing binary builds of the standard library for common platforms. It is compatible with all platforms supported by Rust, including Windows.

For detailed instructions on installation and usage, refer to The Rustup book.

rustup acts as a toolchain multiplexer. It installs multiple Rust toolchains and manages them through a single set of tools located in ~/.cargo/bin.

Key mechanism:

• The rustc and cargo executables in ~/.cargo/bin are proxies.
• These proxies delegate commands to the actual toolchain currently set as active.
• You can change which toolchain the proxies point to by reconfiguring the default toolchain (e.g., using rustup default <channel>).

Advanced management of your Rust environment can be achieved through:

• Basic usage: Standard commands for managing toolchains.
• Overrides: Setting specific toolchains for specific directories.
• Cross-compilation: Configuring rustup for targeting different architectures.
• Environment variables: Using system variables to control rustup behavior.
• Configuration: Modifying rustup's internal settings.
• Network proxies: Configuring proxy settings for toolchain downloads.

To keep code readable and reduce nesting:

• Avoid single-use bindings: Use iterator combinators (like .map()) instead of for loops and avoid naming variables that are only used once.
• Reduce nesting: Use early return for error cases or early continue in loops to avoid "rightward drift."
• Hoist common returns: When match or if arms share a return type (e.g., Ok(...)), hoist the wrapper outside the expression.
• Avoid ref in match patterns: Use binding modes by taking a reference on the scrutinee instead of using the ref keyword.

// Incorrect:
match foo {
    1..10 => Ok(do_one_thing()),
    _ => Ok(do_another()),
}

// Correct:
Ok(match foo {
    1..10 => do_one_thing(),
    _ => do_another(),
})

Rust on Windows uses one of two ABIs. Your choice depends on the C/C++ libraries you need to interoperate with:

• MSVC ABI: Use this for interop with software produced by Visual Studio. This is the default for rustup on Windows. Note: This requires an installation of Visual Studio so rustc can use its linker and libraries.
• GNU ABI: Use this for interop with GNU software built using the MinGW/MSYS2 toolchain. While no additional software is strictly required for basic use, many library crates require a full MSYS2 installation with MinGW to compile successfully.

When developing rustup, use cargo run-rustup to build the project from source and run it directly against your current rustup installation. This differs from cargo run, which executes rustup-init.

For example, to run rustup show using your local build, use:

> cargo run-rustup -- show

To add an optional component to a toolchain that is already installed, use the rustup component add command.

rustup component add rust-docs