Merge staging-next into staging

1 files changed, 82 insertions, 51 deletions

diff --git a/doc/languages-frameworks/rust.section.md b/doc/languages-frameworks/rust.section.md
index 19369a5d3f1..e6ba26c4487 100644
--- a/doc/languages-frameworks/rust.section.md
+++ b/doc/languages-frameworks/rust.section.md
@@ -13,7 +13,7 @@ into your `configuration.nix` or bring them into scope with `nix-shell -p rustc
 
 For other versions such as daily builds (beta and nightly),
 use either `rustup` from nixpkgs (which will manage the rust installation in your home directory),
-or use Mozilla's [Rust nightlies overlay](#using-the-rust-nightlies-overlay).
+or use a community maintained [Rust overlay](#using-community-rust-overlays).
 
 ## Compiling Rust applications with Cargo {#compiling-rust-applications-with-cargo}
 
@@ -900,76 +900,107 @@ rustc 1.26.0-nightly (188e693b3 2018-03-26)
 
 To see that you are using nightly.
 
-## Using the Rust nightlies overlay {#using-the-rust-nightlies-overlay}
+## Using community Rust overlays {#using-community-rust-overlays}
 
-Mozilla provides an overlay for nixpkgs to bring a nightly version of Rust into scope.
-This overlay can _also_ be used to install recent unstable or stable versions
-of Rust, if desired.
+There are two community maintained approaches to Rust toolchain management:
+- [oxalica's Rust overlay](https://github.com/oxalica/rust-overlay)
+- [fenix](https://github.com/nix-community/fenix)
 
-### Rust overlay installation {#rust-overlay-installation}
-
-You can use this overlay by either changing your local nixpkgs configuration,
-or by adding the overlay declaratively in a nix expression,  e.g. in `configuration.nix`.
-For more information see [the manual on installing overlays](#sec-overlays-install).
-
-#### Imperative rust overlay installation {#imperative-rust-overlay-installation}
+Oxalica's overlay allows you to select a particular Rust version and components.
+See [their documentation](https://github.com/oxalica/rust-overlay#rust-overlay) for more
+detailed usage.
 
-Clone [nixpkgs-mozilla](https://github.com/mozilla/nixpkgs-mozilla),
-and create a symbolic link to the file
-[rust-overlay.nix](https://github.com/mozilla/nixpkgs-mozilla/blob/master/rust-overlay.nix)
-in the `~/.config/nixpkgs/overlays` directory.
+Fenix is an alternative to `rustup` and can also be used as an overlay.
 
-```ShellSession
-$ git clone https://github.com/mozilla/nixpkgs-mozilla.git
-$ mkdir -p ~/.config/nixpkgs/overlays
-$ ln -s $(pwd)/nixpkgs-mozilla/rust-overlay.nix ~/.config/nixpkgs/overlays/rust-overlay.nix
-```
+Both Oxalica's overlay and fenix better integrate with nix and cache optimizations.
+Because of this and ergonomics, either of those community projects
+should be preferred to the Mozilla's Rust overlay (nixpkgs-mozilla).
 
-### Declarative rust overlay installation {#declarative-rust-overlay-installation}
-
-Add the following to your `configuration.nix`, `home-configuration.nix`, `shell.nix`, or similar:
+### How to select a specific rustc and toolchain version {#how-to-select-a-specific-rustc-and-toolchain-version}
 
+You can consume the oxalica overlay and use it to grab a specific Rust toolchain version.
+Here is an example `shell.nix` showing how to grab the current stable toolchain:
 ```nix
 { pkgs ? import <nixpkgs> {
     overlays = [
-      (import (builtins.fetchTarball https://github.com/mozilla/nixpkgs-mozilla/archive/master.tar.gz))
-      # Further overlays go here
+      (import (fetchTarball "https://github.com/oxalica/rust-overlay/archive/master.tar.gz"))
     ];
-  };
-};
+  }
+}:
+pkgs.mkShell {
+  nativeBuildInputs = with pkgs; [
+    pkg-config
+    rust-bin.stable.latest.minimal
+  ];
+}
 ```
 
-Note that this will fetch the latest overlay version when rebuilding your system.
+You can try this out by:
+1. Saving that to `shell.nix`
+2. Executing `nix-shell --pure --command 'rustc --version'`
 
-### Rust overlay usage {#rust-overlay-usage}
+As of writing, this prints out `rustc 1.56.0 (09c42c458 2021-10-18)`.
 
-The overlay contains attribute sets corresponding to different versions of the rust toolchain, such as:
+### How to use an overlay toolchain in a derivation  {#how-to-use-an-overlay-toolchain-in-a-derivation}
 
-* `latest.rustChannels.stable`
-* `latest.rustChannels.nightly`
-* a function `rustChannelOf`, called as `(rustChannelOf { date = "2018-04-11"; channel = "nightly"; })`, or...
-* `(nixpkgs.rustChannelOf { rustToolchain = ./rust-toolchain; })` if you have a local `rust-toolchain` file (see https://github.com/mozilla/nixpkgs-mozilla#using-in-nix-expressions for an example)
+You can also use an overlay's Rust toolchain with `buildRustPackage`.
+The below snippet demonstrates invoking `buildRustPackage` with an oxalica overlay selected Rust toolchain:
+```nix
+with import <nixpkgs> {
+  overlays = [
+    (import (fetchTarball "https://github.com/oxalica/rust-overlay/archive/master.tar.gz"))
+  ];
+};
 
-Each of these contain packages such as `rust`, which contains your usual rust development tools with the respective toolchain chosen.
-For example, you might want to add `latest.rustChannels.stable.rust` to the list of packages in your configuration.
+rustPlatform.buildRustPackage rec {
+  pname = "ripgrep";
+  version = "12.1.1";
+  nativeBuildInputs = [
+    rust-bin.stable.latest.minimal
+  ];
+
+  src = fetchFromGitHub {
+    owner = "BurntSushi";
+    repo = "ripgrep";
+    rev = version;
+    sha256 = "1hqps7l5qrjh9f914r5i6kmcz6f1yb951nv4lby0cjnp5l253kps";
+  };
 
-Imperatively, the latest stable version can be installed with the following command:
+  cargoSha256 = "03wf9r2csi6jpa7v5sw5lpxkrk4wfzwmzx7k3991q3bdjzcwnnwp";
 
-```ShellSession
-$ nix-env -Ai nixpkgs.latest.rustChannels.stable.rust
+  meta = with lib; {
+    description = "A fast line-oriented regex search tool, similar to ag and ack";
+    homepage = "https://github.com/BurntSushi/ripgrep";
+    license = licenses.unlicense;
+    maintainers = [ maintainers.tailhook ];
+  };
+}
 ```
 
-Or using the attribute with nix-shell:
+Follow the below steps to try that snippet.
+1. create a new directory
+1. save the above snippet as `default.nix` in that directory
+1. cd into that directory and run `nix-build`
 
-```ShellSession
-$ nix-shell -p nixpkgs.latest.rustChannels.stable.rust
-```
+### Rust overlay installation {#rust-overlay-installation}
+
+You can use this overlay by either changing your local nixpkgs configuration,
+or by adding the overlay declaratively in a nix expression,  e.g. in `configuration.nix`.
+For more information see [the manual on installing overlays](#sec-overlays-install).
+
+### Declarative Rust overlay installation {#declarative-rust-overlay-installation}
 
-Substitute the `nixpkgs` prefix with `nixos` on NixOS.
-To install the beta or nightly channel, "stable" should be substituted by
-"nightly" or "beta", or
-use the function provided by this overlay to pull a version based on a
-build date.
+This snippet shows how to use oxalica's Rust overlay.
+Add the following to your `configuration.nix`, `home-configuration.nix`, `shell.nix`, or similar:
 
-The overlay automatically updates itself as it uses the same source as
-[rustup](https://www.rustup.rs/).
+```nix
+{ pkgs ? import <nixpkgs> {
+    overlays = [
+      (import (builtins.fetchTarball "https://github.com/oxalica/rust-overlay/archive/master.tar.gz"))
+      # Further overlays go here
+    ];
+  };
+};
+```
+
+Note that this will fetch the latest overlay version when rebuilding your system.