Contributing to rustup

1. Fork it!
2. Create your feature branch: git checkout -b my-new-feature
3. Test it: cargo test --features=test
4. Lint it!
5. Commit your changes: git commit -am 'Add some feature'
6. Push to the branch: git push origin my-new-feature
7. Submit a pull request :D

For developing on rustup itself, the easiest way is to run the development build on your current installation. This approach is best used for minor fixes or improvements. See the documentation for cargo run-rustup and RUSTUP_FORCE_ARG0 for more info.

A more formal solution involves installing rustup into a temporary directory as your dedicated test environment. To do so, you can run a series of commands similar to this:

cargo build
mkdir home
RUSTUP_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.

If you wish to install your new build to try out longer term in your home directory then you can run cargo dev-install which is an alias in .cargo/config which runs cargo run -- --no-modify-path -y to install your build into your homedir.

We use rustfmt to keep our codebase consistently formatted. Please ensure that you have correctly formatted your code (most editors will do this automatically when saving) or it may not pass the CI tests.

If you are moving, renaming or removing an existing mdBook page, please use mdBook’s output.html.redirect feature to ensure that the old URL gets redirected.

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 in the README, without any additional terms or conditions.

Linting

We use cargo clippy to ensure high-quality code and to enforce a set of best practices for Rust programming. However, not all lints provided by cargo clippy are relevant or applicable to our project. We may choose to ignore some lints if they are unstable, experimental, or specific to our project. If you are unsure about a lint, please ask us in the rustup Zulip channel.

Manual linting

When checking the codebase with clippy, it is recommended to use the following command:

$ cargo clippy --all --all-targets --all-features -- -D warnings

Please note the --all-features flag: it is used because we need to enable the test feature to make lints fully work, for which --all-features happens to be a convenient shortcut.

The test feature is required because rustup uses cargo features to conditionally compile support code for integration tests, as #[cfg(test)] is only available for unit tests.

If you encounter an issue or wish to speed up the initial analysis, you could also try activating only the test feature by replacing --all-features with --features=test.

Rust-Analyzer

To work with the codebase using rust-analyzer, you may want to configure it upfront. To do so, you can find an example configuration file in rust-analyzer.example.toml in the root of the repository. Then, you can copy it to rust-analyzer.toml and adjust the settings as needed.

You might also want to refer to the rust-analyzer manual for more details on properly setting up rust-analyzer in your IDE of choice.

If you are using rust-analyzer within VSCode, you may also add the corresponding configuration items to your project’s .vscode/settings.json¹. For example:

[cargo]
features = "all"

… will become:

"rust-analyzer.cargo.features": "all",

Checking Windows-specific code on Unix

You can lint Windows-specific code (#[cfg(windows)]) without a Windows VM with cargo clippy targeting x86_64-pc-windows-gnu.

Note: This is for linting and diagnosis only. For building distributable Windows binaries, prefer relying on our CI.

Prerequisites

You need to install the corresponding cross-compilation target first:

$ rustup target add x86_64-pc-windows-gnu

Recommended method: mingw-w64 gcc

This is the most reliable approach across all platforms. The full gcc cross-toolchain includes its own sysroot, so no manual --sysroot tuning is needed.

Install the dependencies

Lint

In most cases with mingw-w64-gcc, cargo auto-detects the cross-compiler:

$ cargo clippy --target x86_64-pc-windows-gnu

Or modify .cargo/config.windows-cross.example.toml based on sysroot matrix, then copy it as .cargo/config.windows-cross.toml.

$ cargo clippy --config .cargo/config.windows-cross.toml

If your distro does not auto-detect, set the compiler explicitly:

$ CC_x86_64_pc_windows_gnu=x86_64-w64-mingw32-gcc \
  CARGO_TARGET_X86_64_PC_WINDOWS_GNU_LINKER=x86_64-w64-mingw32-gcc \
  cargo clippy --target x86_64-pc-windows-gnu

Alternate method: clang + mingw-w64 headers

This uses a lighter install (clang + headers only instead of full gcc toolchain), but requires per-distro sysroot tuning because clang does not always auto-detect the correct MinGW header paths.

Install the dependencies

Lint

When running clippy, you may need to inform the Rust toolchain of your sysroot, which requires passing a cargo config either via a file or with environment variables.

Sysroot Matrix

Modify .cargo/config.windows-cross.example.toml based on sysroot matrix, then copy it as .cargo/config.windows-cross.toml.

$ cargo clippy --config .cargo/config.windows-cross.toml

Or, you can pass them as environment variables directly, e.g.:

$ CC_x86_64_pc_windows_gnu="clang --sysroot=/usr/x86_64-w64-mingw32" \
  CARGO_TARGET_X86_64_PC_WINDOWS_GNU_LINKER=clang \
  cargo clippy --target x86_64-pc-windows-gnu

Rust-Analyzer

It is also possible for the above setup to work with rust-analyzer. See the relevant sections in the example configuration for more information.

1. Alternatively, if you want to apply the configuration to all your Rust projects, you can add them to your global configuration at ~/.config/Code/User/settings.json instead. ↩

Coding standards

Generally we just follow good sensible Rust practices, clippy and so forth. However there are some practices we’ve agreed on that are not machine-enforced; meeting those requirements in a PR will make it easier to merge.

The following guidelines are based on that of rustls, slightly adapted to fit rustup’s situation.

Atomic commits

Our default workflow is to rebase clean commit history from a PR into the target branch, and we prefer to keep the history clean and easy to follow, blame, bisect, backport, etc.

The idea is that when bisecting, one can easily understand whether the breakage was introduced in a refactoring commit or a functional change; when backporting, it becomes much easier to keep all the mechanical changes in the backport to reduce the risk of merge conflicts, and so on.

Thus, we use atomic commits across the repo. This means that when drafting a PR, the general goal is to rewrite the history so that each commit should represent a single unit of change, ideally so “boring” that the commit message alone can be used to understand the change without having to read the code. In particular:

• Avoid mixing refactoring and functional changes in the same commit if possible
• Make mechanical changes (like renaming or moving code around) in a separate commit
• Isolate updates to Cargo.lock in their own commits

You can read more about atomic commits here.

Commit messages

Each message should in principle start with a short verbal phrase describing the change. If mentions of issues/PRs are desired, use the #1234 format instead of pasting links.

It is useful to refer to conventional commits for more detailed guidance on writing good commit messages, however strict adherence to the format is not required.

Coding style

Ordering

Top-down ordering within modules

Within a module, we prefer to order items top-down. This means that items within a module will depend on items defined below them, but not (usually) above them. The idea here is that the public API, with more internal dependencies, will be read (and changed) more often, and putting it closer to the top of the module makes it more accessible.

This can be surprising to many engineers who are used to the bottom-up ordering used in languages like Python, where items can have a run-time dependency on other items defined in the same module.

Usually const values will thus go on the bottom of the module (least complex, usually no dependencies of their own), although in larger modules it can make sense to place a const directly below the user (especially if there is a single user, or just a few co-located users).

The #[cfg(test)] mod tests {} module goes on the very bottom, if present. Other module definitions (like mod foo { .. }) can be ordered among other items as it makes sense in the context of the items imported from them. Module declarations (like mod foo;) should be ordered before other items but after imports. Imports from local modules (both declared and defined) should be kept close to the module declaration/definition.

Files that have substantial amounts of code inside inline modules should probably avoid also having much code outside of these modules.

Ordering for a given type

For a given type, we prefer to order items as follows:

1. The type definition (struct or enum)
2. The inherent impl block (that is, not a trait implementation)
3. impl blocks for traits, from most specific to least specific. The least specific would be something like a Debug or Clone impl.

Ordering associated functions within an inherent impl block

Here’s a guide to how we like to order associated functions:

0. Associated functions (that is, fn foo() {} instead of fn foo(&self) {})
1. Constructors, starting with the constructor that takes the least arguments
2. Public API that takes a &mut self
3. Public API that takes a &self
4. Private API that takes a &mut self
5. Private API that takes a &self
6. const values

Note that we usually also practice top-down ordering here; where these are in conflict, make a choice that you think makes sense. For getters and setters, the order should typically mirror the order of the fields in the type definition.

Attribute ordering

Order attributes so that documentation appears first, and the attributes with the most effect on the meaning and function of the type appear last. For example:

#![allow(unused)]
fn main() {
/// Doc comment always first
#[cfg(feature-gates)]
#[allow(lint-configuration)]
#[non_exhaustive]
#[derive(Clone, Debug)]
pub struct Foo;
}

Prefer to write derived traits in alphabetical order.

Functions

Consider avoiding short single-use functions

While single-use functions can make sense if the algorithm is sufficiently complex that it warrants an explicit name and interface, using many short single-use functions can make the code harder to follow, due to having to jump around in order to gain an understanding of what’s going on. When writing a single-use function, consider whether it needs the dedicated interface, or if it could be inlined into its caller instead.

As an exception, the introduction of a single-use function is allowed as an intermediate step in the middle of a PR, given that at the end of the PR the said function has either been reused or become reasonably complex.

Consider avoiding free-standing functions

If a function’s semantics or implementation are strongly dependent on one of its arguments, and the argument is defined in a type within the current crate, prefer using a method on the type. Similarly, if a function is taking multiple arguments that originate from the same common type in all call-sites it is a strong candidate for becoming a method on the type.

Order arguments from most specific to least specific

When writing a function, we prefer to order arguments from most specific to least specific. This means that an image_id might go before the domain, which will go before the app context. More specific arguments are more differentiating between a given function and other functions, so putting them first makes it easier to infer the context/meaning of the function (compared to starting with a number of generic context-like types).

Use impl Trait types where possible

We prefer to use impl ... for arguments and return types when there’s a single use of the type. Generic type argument bounds add a level of indirection that’s harder to read in one pass.

Avoid type elision for fully qualified function calls

We prefer to write fully qualified function calls with types included, rather than elided. For example:

#![allow(unused)]
fn main() {
// Incorrect:
<_>::default()

// Correct:
CertificateChain::default()
}

Validation

Where possible, avoid writing validate or check type functions that try to check for error conditions based on the state of a populated object. Prefer “parse, don’t validate” style and try to use the type system to make it impossible for invalid states to be represented.

Error handling

We use Result types pervasively throughout the code to signal error cases. Outside of unit/integration tests we prefer to avoid unwrap() and expect() calls unless there is a clear invariant which can be locally validated by the structure of the code. If there is such an invariant, we usually add a comment explaining how the invariant is upheld. In other cases (especially for error cases which can arise from network traffic, which could represent an attacker), we always prefer to handle errors and ultimately return an error to the network peer or close the connection.

Expressions

Avoid single-use bindings

We generally make full use of the expression-oriented nature of Rust. For example, when using iterators we prefer to use map and other combinators instead of for-loops when possible, and will often avoid variable bindings if a variable is only used once. Naming variables takes cognitive efforts, and so does tracking references to bindings in your mind. One metric we like to minimize is the number of mutable bindings in a given scope.

Remember that the overall goal is to make the code easy to understand. Combinators can help with this by eliding boilerplate (like replacing a None => None arm with a map() call), but they can also make it harder to understand the code. One example is that a combinator chain like .map().map_err() might be harder to understand than a match statement (since, in this case, both of the arms have a significant transformation).

Use early return and continue to reduce nesting

The typed nature of Rust can cause some code to end up at deeply indented levels, which we call “rightward drift”. This makes lines shorter, making the code harder to read. To avoid this, try to return early for error cases, or continue early in a loop to skip an iteration.

Hoist common expression returns

When writing a match or if expression that has arms that each share a return type (e.g. Ok(...)), hoist the commonality outside the match. This helps separate out the important differences and reduces code duplication.

#![allow(unused)]
fn main() {
// Incorrect:
match foo {
    1..10 => Ok(do_one_thing()),
    _ => Ok(do_another()),
}

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

Avoid ref in match patterns

When writing match expressions, try to avoid using ref in patterns. Prefer taking a reference on the scrutinee of the match.

Since the addition of binding modes for improved match ergonomics the ref keyword is unidiomatic and can be unfamiliar to readers.

Naming

Use concise names

We prefer concise names, especially for local variables, but prefer to expand acronyms/abbreviations that are not very well known (e.g. prefer key_usage instead of ku, anonymous instead of anon). Extremely common short-forms like url are acceptable.

Avoid adding a suffix for a variable that describes its type (provided that its type is hard to confuse with other types – for example, we do still use _id suffixes because we usually use numeric IDs for database entities). The precision/conciseness trade-off for variable names also depends on the scope of the binding.

Avoid get_ prefixes

Per the API guidelines, get_() prefixes are discouraged.

#![allow(unused)]
fn main() {
// Incorrect:
circle.get_radius()

// Correct:
circle.radius()
}

Prefer positive booleans

When creating a boolean variable, prefer giving it a positive meaning to prevent double negatives.

This rule also applies to CLI switches and environment variables.

#![allow(unused)]
fn main() {
// Incorrect:
let skip_update: bool;

// Correct:
let update: bool;

// Also correct, preferable if e.g. the `update` is already used by a function:
let should_update: bool;
}

Enum variants

When implementing or modifying an enum type, list its variants in alphabetical order. It’s acceptable to ignore this advice when matching the order imposed by an external source, e.g. a standards document.

Prefer active verbs for variant names. E.g. Allow instead of Allowed, Forbid instead of Forbidden. Avoid faux-bools like Yes and No, instead preferring variant names that are descriptive of the different states.

Don’t elide generic lifetimes

We prefer not to elide lifetimes when naming types that are generic over lifetimes. Always include a lifetime placeholder (e.g. <'_>) to avoid confusion.

Imports

In each file the imports should be grouped into at most 4 groups in the following order:

1. stdlib
2. non-repository local crates
3. repository local other crates
4. this crate

#![allow(unused)]
fn main() {
// Incorrect:
use alloc::format;
use alloc::vec::Vec;

// Correct:
use alloc::{format, vec::Vec};
}

Separate each group with a blank line, and rustfmt will sort into a canonical order. Any file that is not grouped like this can be rearranged whenever the file is touched. When you think this should be done for an existing file, please do it at the beginning of your PR in a separate commit.

We prefer to reference types and traits by an imported symbol name instead of using qualified references. Qualification paths generally add noise and are unnecessary. The one exception to this is when the symbol name is overly generic, or easily confused between different crates. In this case we prefer to import the symbol name under an alias, or if the parent module name is short, using a one-level qualified path. E.g. for a crate with a local Error type, prefer to import std::error::Error as StdError.

Exports

We prefer to export types under a single name, avoiding re-exporting types from the top-level lib.rs. The exception to this are “paved path” exports that we expect every user will need. The canonical example of such types are client::ClientConfig and server::ServerConfig. In general this sort of type is rare and most new types should be exported only from the module in which they are defined.

Misc

Numeric literals

Prefer a numeric base that fits with the domain of the value being used. E.g. use hexadecimal for protocol message literals, and octal for UNIX privileges. Use digit grouping to make larger numeric constants easy to read, e.g. use 100_000_000 instead of 100000000.

Avoid type aliases

We prefer to avoid type aliases as they obfuscate the underlying type and don’t provide additional type safety. Using the newtype idiom is one alternative when an abstraction boundary is worth the added complexity.

No direct use of process state outside rustup::process

The rustup::process module abstracts the global state that is std::env::args, std::env::vars, std::io::std* and std::env::current_dir permitting threaded tests of the CLI logic; use the relevant methods of the rustup::process::Process type rather than those APIs directly. Usually, a process: &Process variable will be available to you in the current context. For example, it could be in the form of a parameter of the current function, or a field of a Cfg instance, etc.

Writing tests

Rustup provides a number of test helpers in the rustup::test module which is conditionally enabled with the test feature.

The existing tests under tests/suite provide good examples of how to use these helpers, but you might also find it useful to look at the documentation for particular APIs in the rustup::test module.

For example, for more information regarding end-to-end tests with the .expect() APIs (e.g. how to generate/update the snapshots), please refer to the documentation of the Assert type.

Clippy lints

At the time of writing, rustup’s CI pipeline runs clippy on both Windows and Linux, but contributors to particularly OS-specific code should also make sure that their clippy checking is done on that particular platform, as OS-conditional code is a common source of unused imports and other small lints, which can build up over time.

Writing platform-specific code

If you are on Unix and would like to develop Windows-specific code (#[cfg(windows)]), you can check and lint your code locally before pushing the code and leaving the rest to our CI as long as the relevant test cases are in place.

In the rare case where you would like to test Windows-specific behavior yourself, you can use one of Microsoft’s developer VM images.

For developing Unix-specific code (#[cfg(unix)]) on Windows, it is recommended to use WSL2 for a full Linux environment.

Version numbers

If you ever see a released version of rustup which has :: in its version string then something went wrong with the CI and that needs to be addressed.

We use git-testament to construct our version strings. This records, as a struct, details of the git commit, tag description, and also an indication of modifications to the working tree present when the binary was compiled.

During normal development you may get information from invoking rustup --version which looks like rustup-init 1.18.3+15 (a54051502 2019-05-26) or even rustup-init 1.18.3+15 (a54051502 2019-05-26) dirty 1 modification.

The first part is always the binary name as per clap’s normal operation. The version number is a combination of the most recent tag in the git repo, and the number of commits since that tag. The parenthesised information is, naturally, the SHA of the most recent commit and the date of that commit. If the indication of a dirty tree is present, the number of changes is indicated. This combines adds, deletes, modifies, and unknown entries.

You can request further information of a rustup binary with the rustup dump-testament hidden command. It produces output of the form:

$ rustup dump-testament
Rustup version renders as: 1.18.3+15 (a54051502 2019-05-26) dirty 1 modification
Current crate version: 1.18.3
Built from branch: kinnison/version-strings
Commit info: 1.18.3+15 (a54051502 2019-05-26)
Modified: CONTRIBUTING.md

This can be handy when you are testing development versions on your PC and cannot remember exactly which version you had installed, or if you have given a development copy (or instruction to build such) to a user, and wish to have them confirm exactly what they are using.

Finally, we tell git-testament that we trust the stable branch to carry releases. If the build is being performed when not on the stable branch, and the tag and CARGO_PKG_VERSION differ, then the short version string will include both, in the form rustup-init 1.18.3 :: 1.18.2+99 (a54051502 2019-05-26) which indicates the crate version before the rest of the commit. On the other hand, if the build was on the stable branch then regardless of the tag information, providing the commit was clean, the version is always replaced by the crate version. The dump-testament hidden command can reveal the truth however.

Making a release

In rustup, there are two possible release “modes”: the beta release and the official release. The main difference between the two is that they use different values for the RUSTUP_UPDATE_ROOT environment variable:

• A beta release is deployed on https://dev-static.rust-lang.org/rustup.
• An official release is deployed on https://static.rust-lang.org/rustup.

By switching between those two values, rustup effectively provides two “self update channels”, making beta testing possible with rustup self update.

Currently, rustup does one beta release followed by one official release for each version number in the increasing order. In other words, we don’t release any 1.28.x once the 1.29.0 beta release is out, and the latter is followed by the 1.29.0 stable release, and so on.

Bumping the version number

The version number is registered in the Cargo.toml file of the project.

The general principle for version numbers is that we always increment the minor number unless:

• A major incompatibility has been introduced in this release: increment the major number instead.
• This release is a hotfix because the last one had a defect: increment the patch number instead.

Minor version bumps

NOTE: Rustup hasn’t been doing major version bumps since a long time ago, but if we ever do, the procedure for it should be similar to that of a minor one.

A minor version bump should be performed immediately after the latest X.Y.0 (e.g. 1.29.0) beta release, and to do so, the following steps should be taken:

• In the main branch, note the current minor version number X.Y (e.g. 1.29) and create a new branch from main named release/X.Y (e.g. release/1.29). This will be the active backport branch from now on.
• In a separate PR targeting main:
  • Bump the minor version number in Cargo.toml (e.g. to 1.30.0).
  • Run cargo build and review Cargo.lock changes.

Patch version bumps

A patch version bump should be performed immediately after any latest release other than X.Y.0 betas if the backport branch release/X.Y is still considered active (i.e. it is expected to cut new patch releases from the branch):

• In a separate PR targeting that backport branch:
  • Bump the patch version number in Cargo.toml (e.g. to 1.29.1).
  • Run cargo build and review Cargo.lock changes.

Maintaining the backport branch

When the backport branch release/X.Y is active, you are expected to backport to it any relevant non-breaking changes one would like to see in new patch releases. This includes, but is not limited to:

• Bug fixes.
• Patch-compatible documentation improvements.
• Minor features if they are not expected to cause any breakage.
• CI adjustments if relevant to the active backport branch.

The backport PRs should bear the backport label and target the active backport branch in a rebased, commit-preserving manner.

It is OK to backport multiple original PRs at once as long as the conflict resolution is straightforward (we would expect this to be the case for the most part otherwise it would be against the point of patch releases in the first place).

The backport branches already have similar CI setup like that of main, but the full CI must be manually triggered rather than scheduled. To do so, you can use the GitHub CLI under the project directory:

$ gh workflow run ci.yaml --ref release/X.Y

Cutting a new release

Before making a release, ensure that rustup-init.sh is behaving correctly, and that you’re satisfied that nothing in the ecosystem is breaking because of the update. A useful set of things to check includes verifying that real-world toolchains install okay, and that rust-analyzer isn’t broken by the release. While it’s not our responsibility if they depend on non-stable APIs, we should behave well if we can.

The next step is to check whether you are cutting a beta or an official release, and determine which $BRANCH you should be working on:

• main for X.Y.0 beta releases.
• release/X.Y for any other X.Y.* release.

Producing the final release artifacts is a bit involved because of the way rustup is distributed. Below is a list of things to be done in order to cut a new [b]eta release or an official [r]elease:

1. [b/r] Make sure that the desired version number for the new release $VER_NUM already exists in $BRANCH’s Cargo.toml file. Then in a new PR targeting $BRANCH:
   1. Update CHANGELOG.md accordingly if necessary.
   2. Update rustup-init.sh so that:
      • The version number matches $VER_NUM.
      • The commit shasum matches the latest commit on $BRANCH.
   3. Update the test snapshot of rustup-init.sh --help. At the moment of writing, this is done by running:

      $ SNAPSHOTS=overwrite cargo test --features=test -- cli_rustup_init_ui
      

2. [b/r] After merging the PR made in the previous step:
   1. Pull the latest remote $BRANCH changes to the local $BRANCH.
   2. Hard-reset the local stable to $BRANCH’s tip.
   3. Double-check that the current local stable is indeed what is expected for the next release (version number, commit history, etc.).
   4. Force-push the local stable to the remote stable.
3. [b/r] While you wait for green CI on stable, double-check the functionality of rustup-init.sh and rustup-init just in case.
4. [b/r] Ensure all of CI is green on the stable branch. Once it is, check through a representative proportion of the builds looking for the reported version statements to ensure that we definitely built something cleanly which reports as the right version number when run --version.
5. [b] Make a new PR to the Inside Rust Blog adding a new “Call for Testing” announcement post.
6. [r] Make a new PR to the Rust Blog adding a new release announcement post.
7. [b/r] Ping someone in the release team to perform the actual release. They can find instructions in ci/sync-dist.py.

   Note: Some manual testing occurs here, so hopefully they’ll catch anything egregious in which case abort the change and roll back.

8. [b] Once the beta release has happened, post a new topic named “Seeking beta testers for rustup $VER_NUM” on the Internals Forum to point to the blog post made previously.
9. [r] Once the official release has happened, prepare and push a tag on the latest stable commit.
   • git tag -as $VER_NUM -m $VER_NUM (optionally without -s if not GPG signing the tag)
   • git push origin $VER_NUM
10. [b/r] Immediately perform the corresponding version bump for the next release as described in the previous sections.

Developer tips and tricks

cargo run-rustup

This is the easiest way to build rustup from source and test it against your current rustup installation. Compared to cargo run which executes rustup-init, cargo run-rustup runs rustup directly.

For example, if you want to run rustup show, you may execute:

> cargo run-rustup -- show

RUSTUP_FORCE_ARG0

Sometimes, you may want to test how rustup behaves when it’s invoked with an executable name different from rustup-init and rustup, such as rustc or cargo when testing the proxy mode. In this case, RUSTUP_FORCE_ARG0 can be used to force rustup into thinking it’s being invoked with the given name. Similar to cargo run-rustup, it directly runs on your existing rustup installation.

For example, if you want to run rustc --version, you may execute:

> cargo run --config env.RUSTUP_FORCE_ARG0=\'rustc\' -- --version

This command passes the RUSTUP_FORCE_ARG0 environment variable to the rustup-init binary without influencing the cargo run command itself, which is very important since cargo could also be a rustup proxy.

In fact, cargo run-rustup is simply implemented as an alias of cargo run --config env.RUSTUP_FORCE_ARG0=\'rustup\'.

RUSTUP_BACKTRACK_LIMIT

If it’s necessary to alter the backtracking limit from the default of half a release cycle for some reason, you can set the RUSTUP_BACKTRACK_LIMIT environment variable. If this is unparsable as an i32 or if it’s absent then the default of 21 days (half a cycle) is used. If it parses and is less than 1, it is clamped to 1 at minimum.

This is not meant for use by users, but can be suggested in diagnosing an issue should one arise with the backtrack limits.

RUSTUP_MAX_RETRIES

When downloading a file, rustup will retry the download a number of times. The default is 3 times, but if this variable is set to a valid usize then it is the max retry count. A value of 0 means no retries, thus the default of 3 will mean a download is tried a total of four times before failing out.

RUSTUP_BACKTRACE

By default while running tests, we unset some environment variables that will break our testing (like RUSTUP_TOOLCHAIN, SHELL, ZDOTDIR, RUST_BACKTRACE). But if you want to debug locally, you may need backtrace. RUSTUP_BACKTRACE is used like RUST_BACKTRACE to enable backtraces of failed tests.

NOTE: This is a backtrace for the test, not for any subprocess invocation of rustup process running in the test

$ RUSTUP_BACKTRACE=1 cargo test --release --test cli-v1 -- remove_toolchain_then_add_again
    Finished release [optimized] target(s) in 0.38s
     Running target\release\deps\cli_v1-1f29f824792f6dc1.exe

running 1 test
test remove_toolchain_then_add_again ... FAILED

failures:

---- remove_toolchain_then_add_again stdout ----
thread 'remove_toolchain_then_add_again' panicked at 'called `Result::unwrap()` on an `Err` value: Os { code: 1142, kind: Other, message: "An attempt was made to create more links on a file than the file system supports." }', src\libcore\result.rs:999:5
stack backtrace:
   0: backtrace::backtrace::trace_unsynchronized
             at C:\Users\appveyor\.cargo\registry\src\github.com-1ecc6299db9ec823\backtrace-0.3.29\src\backtrace\mod.rs:66
   1: std::sys_common::backtrace::_print
             at /rustc/de02101e6d949c4a9040211e9ce8c488a997497e\/src\libstd\sys_common\backtrace.rs:47
   2: std::sys_common::backtrace::print
             at /rustc/de02101e6d949c4a9040211e9ce8c488a997497e\/src\libstd\sys_common\backtrace.rs:36
   3: std::panicking::default_hook::{{closure}}
             at /rustc/de02101e6d949c4a9040211e9ce8c488a997497e\/src\libstd\panicking.rs:198
   4: std::panicking::default_hook
             at /rustc/de02101e6d949c4a9040211e9ce8c488a997497e\/src\libstd\panicking.rs:209
   5: std::panicking::rust_panic_with_hook
             at /rustc/de02101e6d949c4a9040211e9ce8c488a997497e\/src\libstd\panicking.rs:475
   6: std::panicking::continue_panic_fmt
             at /rustc/de02101e6d949c4a9040211e9ce8c488a997497e\/src\libstd\panicking.rs:382
   7: std::panicking::rust_begin_panic
             at /rustc/de02101e6d949c4a9040211e9ce8c488a997497e\/src\libstd\panicking.rs:309
   8: core::panicking::panic_fmt
             at /rustc/de02101e6d949c4a9040211e9ce8c488a997497e\/src\libcore\panicking.rs:85
   9: core::result::unwrap_failed
  10: cli_v1::mock::clitools::test
  11: alloc::boxed::{{impl}}::call_once<(),FnOnce<()>>
             at /rustc/de02101e6d949c4a9040211e9ce8c488a997497e\src\liballoc\boxed.rs:746
  12: panic_unwind::__rust_maybe_catch_panic
             at /rustc/de02101e6d949c4a9040211e9ce8c488a997497e\/src\libpanic_unwind\lib.rs:82
  13: std::panicking::try
             at /rustc/de02101e6d949c4a9040211e9ce8c488a997497e\src\libstd\panicking.rs:273
  14: std::panic::catch_unwind
             at /rustc/de02101e6d949c4a9040211e9ce8c488a997497e\src\libstd\panic.rs:388
  15: test::run_test::run_test_inner::{{closure}}
             at /rustc/de02101e6d949c4a9040211e9ce8c488a997497e\/src\libtest\lib.rs:1466
note: Some details are omitted, run with `RUST_BACKTRACE=full` for a verbose backtrace.


failures:
    remove_toolchain_then_add_again

test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 26 filtered out

error: test failed, to rerun pass '--test cli-v1'

Tracing

Similar to other tools in the Rust ecosystem like rustc and cargo, rustup also provides observability/logging features via the tracing crate.

The verbosity of logs is controlled via the RUSTUP_LOG environment variable using tracing_subscriber’s directive syntax.

Console-based tracing

A tracing_subscriber that prints log lines directly to stderr is directly available in the prebuilt version of rustup since v1.28.0.

For historical reasons, if RUSTUP_LOG is not set, this subscriber will print the log lines in a format that mimics the “legacy” stderr output in older versions of rustup:

> rustup default stable
info: using existing install for 'stable-aarch64-apple-darwin'
info: default toolchain set to 'stable-aarch64-apple-darwin'

  stable-aarch64-apple-darwin unchanged - rustc 1.79.0 (129f3b996 2024-06-10)

However, once RUSTUP_LOG is set to any value, rustup’s “custom logging mode” will be activated, and tracing_subscriber’s builtin output format will be used instead:

> RUSTUP_LOG=trace rustup default stable
2024-06-16T12:08:48.732894Z  INFO rustup::cli::common: using existing install for 'stable-aarch64-apple-darwin'
2024-06-16T12:08:48.739232Z  INFO rustup::cli::common: default toolchain set to 'stable-aarch64-apple-darwin'

  stable-aarch64-apple-darwin unchanged - rustc 1.79.0 (129f3b996 2024-06-10)

Please note that since RUSTUP_LOG=trace essentially accepts log lines from all possible sources, you might sometimes see log lines coming from rustup’s dependencies, such as hyper_util in the following example:

> RUSTUP_LOG=trace rustup update
[..]
2024-06-16T12:12:45.569428Z TRACE hyper_util::client::legacy::client: http1 handshake complete, spawning background dispatcher task
2024-06-16T12:12:45.648682Z TRACE hyper_util::client::legacy::pool: pool dropped, dropping pooled (("https", static.rust-lang.org))

   stable-aarch64-apple-darwin unchanged - rustc 1.79.0 (129f3b996 2024-06-10)
  nightly-aarch64-apple-darwin unchanged - rustc 1.81.0-nightly (3cf924b93 2024-06-15)

2024-06-16T12:12:45.693350Z  INFO rustup::cli::rustup_mode: cleaning up downloads & tmp directories

It is also possible to limit the sources of the log lines and the desired max level for each source. For example, set RUSTUP_LOG=rustup=DEBUG to receive log lines only from rustup itself with a max verbosity of DEBUG.

Opentelemetry tracing

The feature otel can be used when building rustup to turn on Opentelemetry tracing with an OLTP GRPC exporter.

This can be very useful for diagnosing performance or correctness issues in more complicated scenarios.

The normal OTLP environment variables can be used to customise its behaviour, but often the simplest thing is to just run a Jaeger docker container on the same host:

docker run -d --name jaeger   -e COLLECTOR_ZIPKIN_HOST_PORT=:9411   -e COLLECTOR_OTLP_ENABLED=true   -p 6831:6831/udp   -p 6832:6832/udp   -p 5778:5778   -p 16686:16686   -p 4317:4317   -p 4318:4318   -p 14250:14250   -p 14268:14268   -p 14269:14269   -p 9411:9411   jaegertracing/all-in-one:latest

Then build rustup-init with tracing:

cargo build --features=otel

Run the operation you want to analyze. For example, we can now run rustup show with tracing:

RUSTUP_FORCE_ARG0="rustup" ./target/debug/rustup-init show

And look in Jaeger for a trace.

Tracing can also be used in tests to get a trace of the operations taken during the test. To use this feature, build the project with --features=otel,test.

Adding instrumentation

Instrumenting a currently uninstrumented function is mostly simply done like so:

#![allow(unused)]
fn main() {
#[tracing::instrument(level = "trace", err(level = "trace"), skip_all)]
}

Sometimes you might want to instrument a function only when the otel feature is enabled. In this case, you will need to use conditional compilation with cfg_attr:

#![allow(unused)]
fn main() {
#[cfg_attr(feature="otel", tracing::instrument(level = "trace", err(level = "trace"), skip_all))]
}

skip_all is not required, but some core structs don’t implement Debug yet, and others have a lot of output in Debug: tracing adds some overheads, so keeping spans lightweight can help avoid frequency bias in the results - where parameters with large debug in frequently called functions show up as much slower than they are.

Some good general heuristics:

• Do instrument slow blocking functions
• Do instrument functions with many callers or that call many different things, as these tend to help figure the puzzle of what-is-happening
• Default to not instrumenting thin shim functions (or at least, only instrument them temporarily while figuring out the shape of a problem)
• Be way of debug build timing - release optimisations make a huge difference, though debug is a lot faster to iterate on. If something isn’t a problem in release don’t pay it too much heed in debug.