rustup-run

Run a command using a given Rust toolchain (see rustup help toolchain for more information)

$ rustup run [toolchain] [command]

rustup run [OPTIONS] ...

    The name of the Rust toolchain to use for executing the command. This can be a channel (e.g., stable, beta, nightly), a specific version (e.g., 1.70.0), or a custom toolchain. It can also be specified using the --toolchain option.

...
    The command to be executed, followed by any arguments or options it requires. This command will run in the environment configured by the specified toolchain.

--toolchain
    An alternative way to specify the toolchain name. This is equivalent to providing the toolchain as a positional argument.

--host
    Specifies the host triple to use when running the command (e.g., x86_64-unknown-linux-gnu).

--target
    Specifies the target triple for cross-compilation (e.g., armv7-unknown-linux-gnueabihf). This ensures that the command uses the correct toolchain components for the specified target.

--path
    Adds an additional directory to the PATH environment variable for the duration of the command's execution. This can be useful for including custom binaries or scripts.

-h, --help
    Displays a help message for the rustup-run command.

rustup-run is a subcommand of rustup, the official Rust toolchain installer and manager. Its primary purpose is to execute a given command within the context of a specific Rust toolchain. This allows developers to work with multiple Rust versions on the same system without conflicts, ensuring that a project compiles and runs against a precise Rust version (e.g., stable, beta, nightly, or a specific historical version like 1.70.0).

When rustup-run is invoked, it temporarily modifies the environment variables, most notably the PATH, to point to the binaries (like rustc, cargo, rustdoc) of the specified toolchain. This creates an isolated environment for the command, preventing it from using the globally set or default Rust toolchain, which is crucial for testing compatibility across different Rust versions, managing project-specific toolchain requirements, or utilizing experimental features only available in certain toolchains.

rustup-run is not a standalone executable; it must be invoked as a subcommand of rustup (i.e., rustup run ...).

The specified toolchain must be installed locally using rustup install for rustup-run to function correctly. If the toolchain is not found, an error will occur.

The command temporarily alters environment variables (like PATH) for the child process. These changes are isolated to the command's execution and do not affect the parent shell's environment.

rustup-run manipulates several environment variables to establish the correct execution context for the specified command:
PATH: Prepends the bin directory of the selected toolchain to the PATH, ensuring that rustc, cargo, and other Rust tools from that toolchain are found first.
RUSTUP_TOOLCHAIN: Set to the name of the toolchain currently being used by rustup-run. This can be useful for debugging or within scripts.
RUSTUP_HOME: Points to the directory where rustup stores its data (e.g., installed toolchains, configurations).
RUSTUP_DIST_SERVER: Specifies the URL of the distribution server from which rustup fetches toolchain components.

rustup-run resolves the target toolchain based on the provided argument in a specific order:
A direct toolchain name (e.g., nightly, stable, 1.70.0).
If a specific toolchain is not explicitly provided, rustup will look for a rust-toolchain.toml or rust-toolchain file in the current directory or parent directories. This file can specify the required toolchain version for the project.
If no toolchain is found through the above methods, rustup defaults to the toolchain set as the default for the user (via rustup default).

The Rust programming language has a rapid release cycle, with new stable versions released every six weeks. This necessitates a robust tool for managing different toolchain versions. rustup was created to fulfill this need, providing seamless installation, updates, and switching between various Rust toolchains.

rustup-run emerged as a critical component of rustup's functionality, enabling developers to execute commands against specific toolchains without modifying the global default. This capability became increasingly vital for projects requiring specific Rust versions, for testing code against different release channels (stable, beta, nightly), and for facilitating cross-compilation workflows. Its development has mirrored the growing complexity and versatility of the Rust ecosystem, solidifying its role as an indispensable utility for Rust developers.

rustup(1), cargo(1), rustc(1)