rust-overlay

Pure and reproducible overlay for binary distributed rust toolchains. A compatible but better replacement for rust overlay of mozilla/nixpkgs-mozilla.

Hashes of toolchain components are pre-fetched (and compressed) in tree (manifests directory), so the evaluation is pure and no need to have network (but nixpkgs-mozilla does). It also works well with Nix Flakes.

The toolchain hashes are auto-updated daily using GitHub Actions.
Current oldest supported version is stable 1.29.0 and beta/nightly 2018-09-13 (which are randomly chosen).

Use as a classic Nix overlay

You can put the code below into your ~/.config/nixpkgs/overlays.nix.

[ (import (builtins.fetchTarball "https://github.com/oxalica/rust-overlay/archive/master.tar.gz")) ]

Then the provided attribute paths are available in nix command.

$ nix-env -iA rust-bin.stable.latest.default # Do anything you like.

Alternatively, you can install it into nix channels.

$ nix-channel --add https://github.com/oxalica/rust-overlay/archive/master.tar.gz rust-overlay
$ nix-channel --update

And then feel free to use it anywhere like import <nixpkgs> { overlays = [ (import <rust-overlay>) ]; } in your nix shell environment.

Use with Nix Flakes

This repository already has flake support.

NOTE: Only the output overlay is stable and preferred to be used in your flake. Other outputs like packages and defaultPackage are for human try and are subject to change.

For a quick play, just use nix shell to bring the latest stable rust toolchain into scope. (All commands below requires preview version of Nix with flake support.)

$ nix shell github:oxalica/rust-overlay
$ rustc --version
rustc 1.49.0 (e1884a8e3 2020-12-29)
$ cargo --version
cargo 1.49.0 (d00d64df9 2020-12-05)

Example: NixOS Configuration

Here's an example of using it in nixos configuration.

{
  description = "My configuration";

  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
    rust-overlay.url = "github:oxalica/rust-overlay";
  };

  outputs = { nixpkgs, rust-overlay, ... }: {
    nixosConfigurations = {
      hostname = nixpkgs.lib.nixosSystem {
        system = "x86_64-linux";
        modules = [
          ./configuration.nix # Your system configuration.
          ({ pkgs, ... }: {
            nixpkgs.overlays = [ rust-overlay.overlay ];
            environment.systemPackages = [ pkgs.rust-bin.stable.latest.default ];
          })
        ];
      };
    };
  };
}

Example: Using `devShell` and `nix develop`

Running nix develop will create a shell with the default nightly Rust toolchain installed:

{
  description = "A devShell example";

  inputs = {
    nixpkgs.url      = "github:nixos/nixpkgs/nixos-unstable";
    rust-overlay.url = "github:oxalica/rust-overlay";
    flake-utils.url  = "github:numtide/flake-utils";
  };

  outputs = { self, nixpkgs, rust-overlay, flake-utils, ... }:
    flake-utils.lib.eachDefaultSystem (system:
      let 
        overlays = [ (import rust-overlay) ];
        pkgs = import nixpkgs {
          inherit system overlays;
        };
      in
      {
        devShell = pkgs.mkShell {
          buildInputs = [
            pkgs.openssl
            pkgs.pkgconfig
            pkgs.exa
            pkgs.fd
            pkgs.rust-bin.nightly.latest.default
          ];

          shellHook = ''
            alias ls=exa
            alias find=fd
          '';
        };
      }
    );
}

Attributes provided by the overlay

{
  rust-bin = {
    # The default dist url for fetching.
    # Override it if you want to use a mirror server.
    distRoot = "https://static.rust-lang.org/dist";

    # Select a toolchain and aggregate components by rustup's `rust-toolchain` file format.
    # See: https://rust-lang.github.io/rustup/overrides.html#the-toolchain-file
    fromRustupToolchain = { channel, components ? [], targets ? [] }: «derivation»;
    # Same as `fromRustupToolchain` but read from a `rust-toolchain` file (legacy one-line string or in TOML).
    fromRustupToolchainFile = rust-toolchain-file-path: «derivation»;

    # Select the latest nightly toolchain which have specific components or profile available.
    # This helps nightly users in case of latest nightly may not contains all components they want.
    #
    # `selectLatestNightlyWith (toolchain: toolchain.default)` selects the latest nightly toolchain
    # with all `default` components (rustc, cargo, rustfmt, ...) available.
    selectLatestNightlyWith = selector: «derivation»;

    # [Experimental]
    # Custom toolchain from a specific rustc git revision.
    # This does almost the same thing as `rustup-toolchain-install-master`. (https://crates.io/crates/rustup-toolchain-install-master)
    # Parameter `components` should be an attrset with component name as key and its SRI hash as value.
    fromRustcRev = { pname ? .., rev, components, target ? .. }: «derivation»;

    stable = {
      # The latest stable toolchain.
      latest = {
        # Profiles, predefined component sets.
        # See: https://rust-lang.github.io/rustup/concepts/profiles.html
        minimal = «derivation»;  # Only `cargo`, `rustc` and `rust-std`.
        default = «derivation»;  # The default profile of `rustup`. Good for general use.
        complete = «derivation»; # Do not use it. It almost always fails.

        # Pre-aggregated package provided by upstream, the most commonly used package in `mozilla-overlay`.
        # It consists of an uncertain number of components, usually more than the `default` profile of `rustup`
        # but less than `complete` profile.
        rust = «derivation»;

        # Individial components.
        rustc = «derivation»;
        cargo = «derivation»;
        rust-std = «derivation»;
        # ... other components
      };
      "1.49.0" = { /* toolchain */ };
      "1.48.0" = { /* toolchain */ };
      # ... other versions.
    };

    beta = {
      # The latest beta toolchain.
      latest = { /* toolchain */ };
      "2021-01-01" = { /* toolchain */ };
      "2020-12-30" = { /* toolchain */ };
      # ... other versions.
    };

    nightly = {
      # The latest nightly toolchain.
      # It is preferred to use `selectLatestNightlyWith` instead of this since
      # nightly toolchain may have components (like `rustfmt` or `rls`) missing,
      # making `default` profile unusable.
      latest = { /* toolchain */ };
      "2020-12-31" = { /* toolchain */ };
      "2020-12-30" = { /* toolchain */ };
      # ... other versions.
    };

    # ... Some internal attributes omitted.
  };

  # These are for compatibility with nixpkgs-mozilla and
  # provide same toolchains as `rust-bin.*`.
  latest.rustChannels = /* ... */;
  rustChannelOf = /* ... */;
  rustChannelOfTargets = /* ... */;
  rustChannels = /* ... */;
}

Some examples (assume nixpkgs had the overlay applied):

Latest stable/beta/nightly rust with almost all components (provided the same as mozilla-overlay): nixpkgs.rust-bin.{stable,beta,nightly}.latest.rust
Latest stable/beta/nightly rust with default or minimal profile (provided the same as default behavior of rustup install). nixpkgs.rust-bin.{stable,beta,nightly}.latest.{default,minimal}

Note: default profile on nightly may not always be available due to absense of required components. You can check availability on Rustup packages availibility.
A specific version of stable rust: nixpkgs.rust-bin.stable."1.48.0".default
A specific date of beta rust: nixpkgs.rust-bin.beta."2021-01-01".default
A specific date of nightly rust: nixpkgs.rust-bin.nightly."2020-12-31".default

Latest stable rust with additional component rust-src and extra target arm-unknown-linux-gnueabihf:

nixpkgs.rust-bin.stable.latest.default.override {
  extensions = [ "rust-src" ];
  targets = [ "arm-unknown-linux-gnueabihf" ];
}

Select the latest nightly toolchain with default components and llvm-tools-preview all available. It may select toolchain earlier than rust-bin.nightly.latest due to lack of components.
```
rust-bin.selectLatestNightlyWith (toolchain: toolchain.default.override {
  extensions = [ "llvm-tools-preview" ];
})
```
If you already have a rust-toolchain file for rustup, you can simply use fromRustupToolchainFile to get the customized toolchain derivation.
```
nixpkgs.rust-bin.fromRustupToolchainFile ./rust-toolchain
```

[Experimental] Toolchain with specific rustc git revision. This is useful for development of rust components like MIRI. Note: the example below may not built since upstream CI periodly removes old artifacts.

rust-bin.fromRustcRev {
  rev = "a2cd91ceb0f156cb442d75e12dc77c3d064cdde4";
  components = {
    rustc = "sha256-x+OkPVStX00AiC3GupIdGzWluIK1BnI4ZCBbg72+ZuI=";
    rust-src = "sha256-13PpzzYtd769Xkb0QzHpNfYCOnLMWFolc9QyYq98z2k=";
  };
}

See more examples in directory examples.

For more details, see also the source code of ./rust-overlay.nix.

9.4 KiB Raw Blame History