1 files changed, 98 insertions, 11 deletions
diff --git a/infra/libkookie/nixpkgs/doc/languages-frameworks/rust.section.md b/infra/libkookie/nixpkgs/doc/languages-frameworks/rust.section.md
index 0e1d59e1a952..0230993d3f08 100644
--- a/infra/libkookie/nixpkgs/doc/languages-frameworks/rust.section.md
+++ b/infra/libkookie/nixpkgs/doc/languages-frameworks/rust.section.md
@@ -16,9 +16,9 @@ cargo
 into the `environment.systemPackages` or bring them into
 scope with `nix-shell -p rustc cargo`.
 
-For daily builds (beta and nightly) use either rustup from
-nixpkgs or use the [Rust nightlies
-overlay](#using-the-rust-nightlies-overlay).
+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).
 
 ## Compiling Rust applications with Cargo
 
@@ -63,9 +63,52 @@ The fetcher will verify that the `Cargo.lock` file is in sync with the `src`
 attribute, and fail the build if not. It will also will compress the vendor
 directory into a tar.gz archive.
 
-### Building a crate for a different target
-
-To build your crate with a different cargo `--target` simply specify the `target` attribute:
+### Cross compilation
+
+By default, Rust packages are compiled for the host platform, just like any
+other package is.  The `--target` passed to rust tools is computed from this.
+By default, it takes the `stdenv.hostPlatform.config` and replaces components
+where they are known to differ. But there are ways to customize the argument:
+
+ - To choose a different target by name, define
+   `stdenv.hostPlatform.rustc.config` as that name (a string), and that
+   name will be used instead.
+
+   For example:
+   ```nix
+   import <nixpkgs> {
+     crossSystem = (import <nixpkgs/lib>).systems.examples.armhf-embedded // {
+       rustc.config = "thumbv7em-none-eabi";
+     };
+   }
+   ```
+   will result in:
+   ```shell
+   --target thumbv7em-none-eabi
+   ```
+
+ - To pass a completely custom target, define
+   `stdenv.hostPlatform.rustc.config` with its name, and
+   `stdenv.hostPlatform.rustc.platform` with the value.  The value will be
+   serialized to JSON in a file called
+   `${stdenv.hostPlatform.rustc.config}.json`, and the path of that file
+   will be used instead.
+
+   For example:
+   ```nix
+   import <nixpkgs> {
+     crossSystem = (import <nixpkgs/lib>).systems.examples.armhf-embedded // {
+       rustc.config = "thumb-crazy";
+       rustc.platform = { foo = ""; bar = ""; };
+     };
+   }
+   will result in:
+   ```shell
+   --target /nix/store/asdfasdfsadf-thumb-crazy.json # contains {"foo":"","bar":""}
+   ```
+
+Finally, as an ad-hoc escape hatch, a computed target (string or JSON file
+path) can be passed directly to `buildRustPackage`:
 
 ```nix
 pkgs.rustPlatform.buildRustPackage {
@@ -74,6 +117,15 @@ pkgs.rustPlatform.buildRustPackage {
 }
 ```
 
+This is useful to avoid rebuilding Rust tools, since they are actually target
+agnostic and don't need to be rebuilt. But in the future, we should always
+build the Rust tools and standard library crates separately so there is no
+reason not to take the `stdenv.hostPlatform.rustc`-modifying approach, and the
+ad-hoc escape hatch to `buildRustPackage` can be removed.
+
+Note that currently custom targets aren't compiled with `std`, so `cargo test`
+will fail. This can be ignored by adding `doCheck = false;` to your derivation.
+
 ### Running package tests
 
 When using `buildRustPackage`, the `checkPhase` is enabled by default and runs
@@ -478,8 +530,15 @@ Mozilla provides an overlay for nixpkgs to bring a nightly version of Rust into
 This overlay can _also_ be used to install recent unstable or stable versions
 of Rust, if desired.
 
-To use this overlay, clone
-[nixpkgs-mozilla](https://github.com/mozilla/nixpkgs-mozilla),
+### 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 [#sec-overlays-install](the manual on installing overlays).
+
+#### Imperative rust overlay installation
+
+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.
@@ -488,14 +547,42 @@ in the `~/.config/nixpkgs/overlays` directory.
     $ mkdir -p ~/.config/nixpkgs/overlays
     $ ln -s $(pwd)/nixpkgs-mozilla/rust-overlay.nix ~/.config/nixpkgs/overlays/rust-overlay.nix
 
-The latest version can be installed with the following command:
+### Declarative rust overlay installation
+
+Add the following to your `configuration.nix`, `home-configuration.nix`, `shell.nix`, or similar:
+
+```
+  nixpkgs = {
+    overlays = [
+      (import (builtins.fetchTarball https://github.com/mozilla/nixpkgs-mozilla/archive/master.tar.gz))
+      # Further overlays go here
+    ];
+  };
+```
+
+Note that this will fetch the latest overlay version when rebuilding your system.
+
+### Rust overlay usage
+
+The overlay contains attribute sets corresponding to different versions of the rust toolchain, such as:
+
+* `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)
+
+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.
+
+Imperatively, the latest stable version can be installed with the following command:
 
-    $ nix-env -Ai nixos.latest.rustChannels.stable.rust
+    $ nix-env -Ai nixpkgs.latest.rustChannels.stable.rust
 
 Or using the attribute with nix-shell:
 
-    $ nix-shell -p nixos.latest.rustChannels.stable.rust
+    $ nix-shell -p nixpkgs.latest.rustChannels.stable.rust
 
+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