More Toolchains

The rust tooling ecosystem is going through some changes which have made it a little tough learning what exactly is the “best” environment for maintainers and contributes of a project. I started to codify learnings in my nix config, a declarative rust environment, but I believe now some more flexibility is required.

As rust introduces new tooling, it’s generally first hidden behind the unstable -Z flags in cargo before it is stabilized. These can only be accessed by a toolchain which came from the nightly channel. This toolchain channel dimension is tricky. I originally thought it would be best to create custom composite toolchains where you mix and match components from the different channels. However, this doesn’t really fit in with the rest of the rust ecosystem tooling.

rustup, and its integration with cargo’s +<toolchain> syntax, prefers to instead bounce between toolchains on a granular, command by command basis. This is all a bit at odds with the nix style to try and package up a completely deterministic toolchain, but deferring to rustup to manage the toolchains appears to make all development easier.

Here are some scenarios which convinced me to invest more in rustup no matter the scenario.

Formatting on Nightly

The rust-bitcoin project was where I first experimented with custom composite toolchains. rust-bitcoin uses some settings which are only available in nightly at the moment.

imports_granularity = "Module"
group_imports = "StdExternalCrate"

Nightly formatting settings.

A composite toolchain for this scenario could be based on stable and replace its rustfmt component with the nightly formatter. This works fine, I assume because the formatter is fairly self-contained.

Mixing Dependency Resolvers

Another scenario I have been hacking on is trying to use cargo’s new v3 dependency resolver, the MSRV policy enforcer, while still checking that my code meets its MSRV requirement. This is extra tricky because the package.resolver/workspace.resolver setting is fairly locked down, it cannot be overwritten at runtime by an env var or cli (although I did find out how to modify its behavior later). The v3 resolver was stabilized in rust 1.84.0. One could create a composite toolchain based on its MSRV, and then replace the cargo component with a 1.84.0 version. This could theoretically get the resolving capabilities while maintaining the MSRV compiler. I haven’t actually tried this however, and am not convinced it would be as smooth as swapping out the formatter based purely on a gut feel that cargo and the compiler are closely coupled.

Maintainers and Contributors

So both these scenarios could be solved with a composite toolchain. And if you are the maintainer, sole contributor, and sole consumer of a project, you might just do it. Creating a composite toolchain looks like a pain without nix, but hey, it’s just you!

Now, as soon as one contributor shows up who doesn’t run nix (no one is perfect), it gets a little more complicated. This is where it becomes clear that composite toolchains are swimming upstream with the rust tooling ecosystem. It is much easier to get contributors to buy into rustup instead of taking the plunge into nix, and with rustup, you can now use the granular +<toolchain> syntax. Scripts can be written which enforce when and where to use certain toolchains, command by command. For example, a CI job could enforce that a nightly formatter is used while building and testing with stable.

This extreme flexibility can be a bit difficult to wrangle in for deterministic builds. For one, users can use very abstract toolchain names like stable, beta, nightly which match which ever one is installed on a system. Contributors will almost certainly use different toolchains. It doesn’t help that the nightly and stable releases are a little difficult to link. Stable is semver’d whereas nightly is by date.

What this means though is project scrips probably want to stick to specific names (e.g. 1.63.0). rustup does fail in a pretty clear manner if a toolchain is asked for which isn’t installed, so theoretically a contributor only has to feel that pain once. It would be cool if a project could declare a handful of toolchains which it uses, but I believe for now its only really possible to declare one in a rust-toolchain.toml file.

rustup had a big release in March 2025, v1.28.0 (see the changelog), which fixed up some of the annoying integration issues with rust-toolchain.toml. Now you can simply run rustup toolchain install in a project and it will install the toolchain specified by the configuration, no need to be explicit about which toolchain. But just one toolchain (for now?).

New Flake

I have updated my nix environment to use rustup by default and only create special toolchains for specific scenarios. The one below is for performance testing on an old MSRV toolchain. The thing to keep in mind is that rustup managed toolchains are outside the control of nix and are instead on a system shared spot by default (~/.rustup/). Maybe it is worth setting a project specific setting like export RUSTUP_HOME="$PWD/.rustup" to keep the toolchains separate, but not sure if worth it yet.

outputs = { self, nixpkgs, fenix }:
  let
    system = "x86_64-linux";
    pkgs = import nixpkgs {
      inherit system;
      overlays = [ fenix.overlays.default ];
    };

    # Toolchains are grabbed by their release date + channel + sha
    # (for nix purity) instead of version. I believe this is to 
    # keep a single interface between channels, and this is the 
    # only way to grab nightly versions which don't have semvers.
    # Using nightly from around the same timeframe as 1.63.0.
    base-toolchain-1-63-0-nightly = pkgs.fenix.toolchainOf {
      # A nightly close to 1.63.0 release.
      date = "2022-08-10";
      channel = "nightly";
      sha256 = "sha256-RypSW66QV4BXPd+kDcuSEInWcem5ib6J0iebZDCxypg=";
    };
  in
  {
    devShells.${system} = {
      # The rust ecosystem has three *channels* stable, beta, and nightly. When using
      # a version, e.g. 1.63, it can come from any one of these channels. But certain
      # experimental features must be used on the nightly channel, even if they
      # stabalilze later.
     
      # 1.63.0 from nightly with features for benchmarking.
      # Not including rust-analyzer, clippy, or rustfmt components
      # since not expected to code in this shell. This is equivalent
      # to the "minimal" profile.
      toolchain-1-63-0-nightly = pkgs.mkShell {
        nativeBuildInputs = with pkgs; [
          (base-toolchain-1-63-0-nightly.withComponents [
            "cargo"    # Package manager and build system
            "rust-src" # Source code for std library for IDE's
            "rustc"    # Compiler, includes std library rust-std.
          ])
          cargo-show-asm
        ];
        shellHook = ''
          echo "Using Rust 1.63.0 from nightly channel for benchmarks"
          export PS1="\[\033[01;33m\]\u@\h:\w [1.63.0]$\[\033[00m\] "
        '';
      };

      # Deferring to rust up for flexibility to switch between toolchains.
      # These toolchains are installed outside of nix's control in ~/.rustup/.
      rustup = pkgs.mkShell {
        nativeBuildInputs = with pkgs; [
          rustup
        ];
        shellHook = ''
          echo "Using rustup managed environment"
          if [ -f rust-toolchain.toml ]; then
            echo "Installing Rust toolchain specified in project..."
            # Profiles:
            # minimal  - rustc, cargo, rust-std
            # default  - adds rustfmt and clippy
            # complete - everything, not recommended since a lot of extra internals
            # Once rustup > 1.28, should just use "rustup toolchain install".
            rustup show active-toolchain || rustup toolchain install
            # Adding just rust-analyzer to avoid complete profile.
            rustup component add rust-analyzer
          fi
        '';
      };

      default = self.devShells.${system}.rustup;
    };
  };

Nix deferring to rustup to manage toolchains by default.

Here is a helpful web dashboard for component version history. Might be useful if building a complex toolchain. Also just the standard rust releases.

Lockfile Script

Back in the “mixing resolvers” scenario, a theoretical composite toolchain was proposed to replace cargo. I am in on rustup now, so not gonna do that, but there is still a hitch. The safest way to set the resolver is in the manifest Cargo.toml under the package.resolver key. This way no matter what toolchain is used by a contributor, the same resolver strategy is used. But if I set it to 3 only cargo’s > 1.84.0 will run! The rest panic since they don’t know the third strategy. This is tricky because I also want to enforce my MSRV of 1.63.0, but now I can’t run it.

After digging through the RFC and some recent updates, I did track down a way to enable the v3 resolver with an environment variable. If using the cargo > 1.84.0, CARGO_RESOLVER_INCOMPATIBLE_RUST_VERSIONS=fallback enables the MSRV checking resolver (aka v3). You can also set it to maximum for the old v2 behavior, which is also exposed as the --ignore-rust-version flag. The term “fallback” was a bit strange to me at first, but I guess the idea is that it keeps falling back on versions until it finds one which fits the MSRV.

#!/usr/bin/env bash

set -euo pipefail

strategy=${1:-"msrv"}

echo "Updating Cargo.lock using $strategy strategy"

if [ "$strategy" = "msrv" ]; then
  CARGO_RESOLVER_INCOMPATIBLE_RUST_VERSIONS=fallback cargo update --verbose
elif [ "$strategy" = "min" ]; then
  cargo +nightly-2025-04-02 update -Z direct-minimal-versions --verbose
elif [ "$strategy" = "max" ]; then
  cargo update --ignore-rust-version --verbose
else
  echo "Error: Invalid strategy '$strategy'" >&2
  exit 1
fi

Lil’ script with different dependency resolving strategies.

This script can be used to generate lockfiles for specific scenarios. MSRV is probably the most useful, check that a set of dependencies actually exists for my library’s constraints. Min and max could be helpful to gain more confidence in your library’s constraints (although there are some subtleties to min that I don’t understand yet).

The downside here is that it is still possible for a contributor to run cargo update locally and just use the default resolver for the edition (v2 if using a toolchain under 1.84.0). Maybe a guard against this could be to added some metadata marker to the custom script which CI could check for? Or maybe better to not tie a check to the checked in lockfile?

# Check code with MSRV compiler.
_test-msrv:
  # Generate a lockfile which "fallsback" to the highest dependency
  # versions which also work for the MSRV. If none fit the MSRV, then
  # the constraints take priority, the MSRV might implicitly be
  # raised. So we check the build to see if it introduces any
  # code which cannot be compiled with the MSRV. 
  CARGO_RESOLVER_INCOMPATIBLE_RUST_VERSIONS=fallback cargo update --verbose;
  # Handles creating sandboxed environments to ensure no newer binaries sneak in.
  cargo install cargo-msrv@0.18.4
  cargo msrv verify --all-features

A just recipe which contains all the logic to test an MSRV.

Somewhat surprising to me is that the v3 resolver, when used with the new MSRV-aware fallback mode, doesn’t panic if it can’t find a dependency which matches the constraints and is MSRV compliant. It prioritizes the constraints and just uses a version which isn’t compliant. So it is possible some non-MSRV code gets pulled into a library. So actually building the code is still the best way to check that its possible to use it with a certain MSRV.