Tweak flake outputs and README

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.
+Hashes of toolchain components are pre-fetched (and compressed) in tree (`manifests` directory),
-So there's no need to have network access during nix evaluation (but nixpkgs-mozilla does).
+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).
+- The toolchain hashes are auto-updated daily using GitHub Actions.
-
-- [ ] Auto-updating is TODO.
 - Current oldest supported version is stable 1.29.0 and nightly 2018-09-13
   (which is randomly chosen).
 
-## Use as classical nix overlay
+## Use as a classic 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
 
 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`:
+Alternatively, you can install it into nix channels.
-```shell
+```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 <nixpkgs> { overlays = [ (import <rust-overlay>) ] }` in your nix shell environment
+`import <nixpkgs> { overlays = [ (import <rust-overlay>) ]; }` in your nix shell environment.
 
 ## Use with Nix Flakes
 
-This repository already has flake support. So you can simply use it as input.
+This repository already has flake support.
-Here's an example of using it in nixos configuration.
 
+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**.
+```nix
-It provides `latest.rustChannels.{stable,nightly}.<toolchain-component>` and `rustChannelOf`.
+{
+  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
+    nightly = {
-`latest.rustChannels.{stable,nightly}.rust`, which combines `rustc`, `cargo`, `rustfmt` and
+      # The latest nightly toolchain.
-all other default components.
+      latest = { /* toolchain */ };
+      "2020-12-31" = { /* toolchain */ };
+      "2020-12-30" = { /* toolchain */ };
+      # ... other versions.
+    };
 
-You can also pin to specific nightly toolchain using `rustChannelOf`:
+    # ... Some internal attributes omitted.
-```nix
+  };
-(nixpkgs.rustChannelOf { date = "2020-01-01"; channel = "nightly"; }).rust
-```
 
-Customize an toolchain.
+  # These are for compatibility with nixpkgs-mozilla and
-```nix
+  # provide same toolchains as `rust-bin.*`.
-nixpkgs.latest.rustChannels.stable.rust.override {
+  latest.rustChannels = /* ... */;
-  extensions = [
+  rustChannelOf = /* ... */;
-    "rust-src"
+  rustChannelOfTargets = /* ... */;
-  ];
+  rustChannels = /* ... */;
-  targets = [
-    "x86_64-unknown-linux-musl"
-    "arm-unknown-linux-gnueabihf"
-  ];
 }
 ```
 
-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

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;
+    defaultPackage = packages.rust;
-    packages = {
+
-      rust-stable = pkgs.latest.rustChannels.stable.rust;
+    # FIXME: We can only directly provide derivations here without nested set.
-      rust-nightly = pkgs.latest.rustChannels.nightly.rust;
+    # 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;