diff --git a/README.md b/README.md index 99dfd0e438f..29ac916d557 100644 --- a/README.md +++ b/README.md @@ -1,40 +1,53 @@ # rust-overlay *Pure and reproducible* overlay for binary distributed rust toolchains. -A better replacement for github:mozilla/nixpkgs-mozilla +A compatible but better replacement for rust overlay of [github:mozilla/nixpkgs-mozilla][mozilla]. -Hashes of toolchain components are pre-fetched (and compressed) in `manifests` directory. -So there's no need to have network access during nix evaluation (but nixpkgs-mozilla does). +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][mozilla] does). +It also works well with [Nix Flakes](https://nixos.wiki/wiki/Flakes). -Since the evaluation is now *pure*, it also means this can work well with [Nix Flakes](https://nixos.wiki/wiki/Flakes). - -- [ ] Auto-updating is TODO. +- The toolchain hashes are auto-updated daily using GitHub Actions. - Current oldest supported version is stable 1.29.0 and nightly 2018-09-13 (which is randomly chosen). -## Use as classical nix overlay - -The installaction and usage are exactly the same as nixpkgs-mozilla. -You can follow https://github.com/mozilla/nixpkgs-mozilla#rust-overlay and just replace the url to -https://github.com/oxalica/rust-overlay +## Use as a classic Nix overlay You can put the code below into your `~/.config/nixpkgs/overlays.nix`. ```nix -[ (import (builtins.fetchTarball https://github.com/oxalica/rust-overlay/archive/master.tar.gz)) ] +[ (import (builtins.fetchTarball "https://github.com/oxalica/rust-overlay/archive/master.tar.gz")) ] +``` +Then the provided attribute paths are available in nix command. +```bash +$ nix-env -iA rust-bin.stable.latest.rust # Do anything you like. ``` -Or install it into `nix-channel`: -```shell +Alternatively, you can install it into nix channels. +```bash $ 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 { overlays = [ (import ) ] }` in your nix shell environment +`import { overlays = [ (import ) ]; }` in your nix shell environment. ## Use with Nix Flakes -This repository already has flake support. So you can simply use it as input. -Here's an example of using it in nixos configuration. +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.) +```shell +$ 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) +``` + +Here's an example of using it in nixos configuration. ```nix { description = "My configuration"; @@ -52,7 +65,7 @@ Here's an example of using it in nixos configuration. ./configuration.nix # Your system configuration. ({ pkgs, ... }: { nixpkgs.overlays = [ rust-overlay.overlay ]; - environment.systemPackages = [ pkgs.latest.rustChannels.stable.rust ]; + environment.systemPackages = [ pkgs.rust-bin.stable.latest.rust ]; }) ]; }; @@ -61,31 +74,72 @@ Here's an example of using it in nixos configuration. } ``` -## Interface +## Attributes provided by the overlay -The overlay re-use many codes from nixpkgs/mozilla and the interface is **almost the same**. -It provides `latest.rustChannels.{stable,nightly}.` and `rustChannelOf`. +```nix +{ + 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"; + + stable = { + # The latest stable toolchain. + latest = { + # Aggregate all default components. (recommended) + rust = «derivation»; + # Individial components. + rustc = «derivation»; + cargo = «derivation»; + rust-std = «derivation»; + # ... other components + }; + "1.49.0" = { /* toolchain */ }; + "1.48.0" = { /* toolchain */ }; + # ... other versions. + }; -To use the latest stable or nightly rust toolchain, the easiest way is just to install -`latest.rustChannels.{stable,nightly}.rust`, which combines `rustc`, `cargo`, `rustfmt` and -all other default components. + nightly = { + # The latest nightly toolchain. + latest = { /* toolchain */ }; + "2020-12-31" = { /* toolchain */ }; + "2020-12-30" = { /* toolchain */ }; + # ... other versions. + }; -You can also pin to specific nightly toolchain using `rustChannelOf`: -```nix -(nixpkgs.rustChannelOf { date = "2020-01-01"; channel = "nightly"; }).rust -``` + # ... Some internal attributes omitted. + }; -Customize an toolchain. -```nix -nixpkgs.latest.rustChannels.stable.rust.override { - extensions = [ - "rust-src" - ]; - targets = [ - "x86_64-unknown-linux-musl" - "arm-unknown-linux-gnueabihf" - ]; + # These are for compatibility with nixpkgs-mozilla and + # provide same toolchains as `rust-bin.*`. + latest.rustChannels = /* ... */; + rustChannelOf = /* ... */; + rustChannelOfTargets = /* ... */; + rustChannels = /* ... */; } ``` -For more details, see `./rust-overlay.nix` or README of https://github.com/mozilla/nixpkgs-mozilla. +Some examples (assume `nixpkgs` had the overlay applied): + +- Latest stable rust with all default components: + `nixpkgs.rust-bin.stable.latest.rust` +- Latest nightly rust with all default components: + `nixpkgs.rust-bin.nightly.latest.rust` +- A specific version of stable rust: + `nixpkgs.rust-bin.stable."1.48.0".rust` +- A specific date of nightly rust: + `nixpkgs.rust-bin.nightly."2020-12-31".rust` +- Latest stable rust with additional component `rust-src` and extra target + `arm-unknown-linux-gnueabihf`: + + ```nix + nixpkgs.rust-bin.stable.latest.rust.override { + extensions = [ "rust-src" ]; + targets = [ "arm-unknown-linux-gnueabihf" ]; + } + ``` + +For detail about `override` , see the source code of `./rust-overlay.nix`, +or README of [nixpkgs-mozilla][mozilla]. + +[mozilla]: https://github.com/mozilla/nixpkgs-mozilla diff --git a/flake.nix b/flake.nix index a945e4a0733..c8e16cc64b3 100644 --- a/flake.nix +++ b/flake.nix @@ -1,7 +1,7 @@ { description = '' Pure and reproducible overlay for binary distributed rust toolchains. - A better replacement for github:mozilla/nixpkgs-mozilla + A compatible but better replacement for rust overlay of github:mozilla/nixpkgs-mozilla. ''; inputs = { @@ -10,7 +10,8 @@ outputs = { self, nixpkgs, flake-utils, ... }@inputs: let inherit (nixpkgs) lib; - overlay = import ./default.nix; + + overlay = import ./.; allSystems = [ "aarch64-linux" @@ -23,20 +24,32 @@ ]; in { + overlay = final: prev: overlay final prev; } // flake-utils.lib.eachSystem allSystems (system: let pkgs = import nixpkgs { inherit system; overlays = [ overlay ]; }; in rec { + # `defaultApp`, `defaultPackage` and `packages` are for human only. + # They are subject to change and **DO NOT** depend on them in your flake. + # Please use `overlay` instead. + defaultApp = { type = "app"; program = "${defaultPackage}/bin/rustc"; }; - defaultPackage = packages.rust-stable; - packages = { - rust-stable = pkgs.latest.rustChannels.stable.rust; - rust-nightly = pkgs.latest.rustChannels.nightly.rust; - }; + defaultPackage = packages.rust; + + # FIXME: We can only directly provide derivations here without nested set. + # Currently we only provide stable releases. Some nightly versions have components missing + # on some platforms, which makes `nix flake check` to be failed. + packages = + lib.mapAttrs' (version: comps: { + name = "rust-${lib.replaceStrings ["."] ["-"] version}"; + value = comps.rust; + }) pkgs.rust-bin.stable // { + rust = packages.rust-latest; + }; checks = { kind2 = (pkgs.rustChannelOf { channel = "1.48.0"; }).rust;