Merge commit '18c84ea816348e2a098390101b92d1e39a9dbd45'

Conflicts:
	nixpkgs/nixos/modules/misc/documentation.nix
	nixpkgs/pkgs/applications/networking/browsers/firefox/packages.nix
	nixpkgs/pkgs/applications/window-managers/sway/default.nix
	nixpkgs/pkgs/build-support/rust/build-rust-package/default.nix
	nixpkgs/pkgs/development/go-modules/generic/default.nix
	nixpkgs/pkgs/development/interpreters/ruby/default.nix
	nixpkgs/pkgs/development/interpreters/ruby/patchsets.nix
	nixpkgs/pkgs/development/libraries/boehm-gc/7.6.6.nix
	nixpkgs/pkgs/development/python-modules/django-mailman3/default.nix
	nixpkgs/pkgs/servers/mail/mailman/web.nix
	nixpkgs/pkgs/top-level/aliases.nix
	nixpkgs/pkgs/top-level/all-packages.nix
	nixpkgs/pkgs/top-level/impure.nix

25 files changed, 373 insertions, 175 deletions

diff --git a/nixpkgs/doc/builders/images/dockertools.section.md b/nixpkgs/doc/builders/images/dockertools.section.md
index bfe1d17a6067..7ff4b2aeb369 100644
--- a/nixpkgs/doc/builders/images/dockertools.section.md
+++ b/nixpkgs/doc/builders/images/dockertools.section.md
@@ -151,6 +151,12 @@ Create a Docker image with many of the store paths being on their own layer to i
 
 : Shell commands to run while creating the archive for the final layer in a fakeroot environment. Unlike `extraCommands`, you can run `chown` to change the owners of the files in the archive, changing fakeroot's state instead of the real filesystem. The latter would require privileges that the build user does not have. Static binaries do not interact with the fakeroot environment. By default all files in the archive will be owned by root.
 
+`enableFakechroot` _optional_
+
+: Whether to run in `fakeRootCommands` in `fakechroot`, making programs behave as though `/` is the root of the image being created, while files in the Nix store are available as usual. This allows scripts that perform installation in `/` to work as expected. Considering that `fakechroot` is implemented via the same mechanism as `fakeroot`, the same caveats apply.
+
+    *Default:* `false`
+
 ### Behavior of `contents` in the final image {#dockerTools-buildLayeredImage-arg-contents}
 
 Each path directly listed in `contents` will have a symlink in the root of the image.
diff --git a/nixpkgs/doc/builders/packages/linux.section.md b/nixpkgs/doc/builders/packages/linux.section.md
index d8f0d0ad445f..f669c720710c 100644
--- a/nixpkgs/doc/builders/packages/linux.section.md
+++ b/nixpkgs/doc/builders/packages/linux.section.md
@@ -29,7 +29,7 @@ How to add a new (major) version of the Linux kernel to Nixpkgs:
     4.  If needed you can also run `make menuconfig`:
 
         ```ShellSession
-        $ nix-env -i ncurses
+        $ nix-env -f "<nixpkgs>" -iA ncurses
         $ export NIX_CFLAGS_LINK=-lncurses
         $ make menuconfig ARCH=arch
         ```
diff --git a/nixpkgs/doc/builders/trivial-builders.chapter.md b/nixpkgs/doc/builders/trivial-builders.chapter.md
index 46620e1b459c..c3a3572cd9f4 100644
--- a/nixpkgs/doc/builders/trivial-builders.chapter.md
+++ b/nixpkgs/doc/builders/trivial-builders.chapter.md
@@ -47,6 +47,28 @@ These functions write `text` to the Nix store. This is useful for creating scrip
 
 Many more commands wrap `writeTextFile` including `writeText`, `writeTextDir`, `writeScript`, and `writeScriptBin`. These are convenience functions over `writeTextFile`.
 
+## `writeShellApplication` {#trivial-builder-writeShellApplication}
+
+This can be used to easily produce a shell script that has some dependencies (`runtimeInputs`). It automatically sets the `PATH` of the script to contain all of the listed inputs, sets some sanity shellopts (`errexit`, `nounset`, `pipefail`), and checks the resulting script with [`shellcheck`](https://github.com/koalaman/shellcheck).
+
+For example, look at the following code:
+
+```nix
+writeShellApplication {
+  name = "show-nixos-org";
+
+  runtimeInputs = [ curl w3m ];
+
+  text = ''
+    curl -s 'https://nixos.org' | w3m -dump -T text/html
+  '';
+}
+```
+
+Unlike with normal `writeShellScriptBin`, there is no need to manually write out `${curl}/bin/curl`, setting the PATH
+was handled by `writeShellApplication`. Moreover, the script is being checked with `shellcheck` for more strict
+validation.
+
 ## `symlinkJoin` {#trivial-builder-symlinkJoin}
 
 This can be used to put many derivations into the same directory structure. It works by creating a new derivation and adding symlinks to each of the paths listed. It expects two arguments, `name`, and `paths`. `name` is the name used in the Nix store path for the created derivation. `paths` is a list of paths that will be symlinked. These paths can be to Nix store derivations or any other subdirectory contained within.
diff --git a/nixpkgs/doc/contributing/coding-conventions.chapter.md b/nixpkgs/doc/contributing/coding-conventions.chapter.md
index 7a8e7741a330..79d90c23a40f 100644
--- a/nixpkgs/doc/contributing/coding-conventions.chapter.md
+++ b/nixpkgs/doc/contributing/coding-conventions.chapter.md
@@ -181,7 +181,7 @@
   rev = "${version}";
   ```
 
-- Filling lists condionally _should_ be done with `lib.optional(s)` instead of using `if cond then [ ... ] else null` or `if cond then [ ... ] else [ ]`.
+- Building lists conditionally _should_ be done with `lib.optional(s)` instead of using `if cond then [ ... ] else null` or `if cond then [ ... ] else [ ]`.
 
   ```nix
   buildInputs = lib.optional stdenv.isDarwin iconv;
diff --git a/nixpkgs/doc/contributing/submitting-changes.chapter.md b/nixpkgs/doc/contributing/submitting-changes.chapter.md
index 221ba3006194..09ffba3dc6fc 100644
--- a/nixpkgs/doc/contributing/submitting-changes.chapter.md
+++ b/nixpkgs/doc/contributing/submitting-changes.chapter.md
@@ -43,13 +43,13 @@
   - nixpkgs:
 
     - update pkg
-      - `nix-env -i pkg-name -f <path to your local nixpkgs folder>`
+      - `nix-env -iA pkg-attribute-name -f <path to your local nixpkgs folder>`
     - add pkg
       - Make sure it’s in `pkgs/top-level/all-packages.nix`
-      - `nix-env -i pkg-name -f <path to your local nixpkgs folder>`
+      - `nix-env -iA pkg-attribute-name -f <path to your local nixpkgs folder>`
     - _If you don’t want to install pkg in you profile_.
-      - `nix-build -A pkg-attribute-name <path to your local nixpkgs folder>/default.nix` and check results in the folder `result`. It will appear in the same directory where you did `nix-build`.
-    - If you did `nix-env -i pkg-name` you can do `nix-env -e pkg-name` to uninstall it from your system.
+      - `nix-build -A pkg-attribute-name <path to your local nixpkgs folder>` and check results in the folder `result`. It will appear in the same directory where you did `nix-build`.
+    - If you installed your package with `nix-env`, you can run `nix-env -e pkg-name` where `pkg-name` is as reported by `nix-env -q` to uninstall it from your system.
 
   - NixOS and its modules:
     - You can add new module to your NixOS configuration file (usually it’s `/etc/nixos/configuration.nix`). And do `sudo nixos-rebuild test -I nixpkgs=<path to your local nixpkgs folder> --fast`.
@@ -246,11 +246,21 @@ If the branch is already in a broken state, please refrain from adding extra new
 
 ### Stable release branches {#submitting-changes-stable-release-branches}
 
-For cherry-picking a commit to a stable release branch (“backporting”), use `git cherry-pick -x <original commit>` so that the original commit id is included in the commit.
+The same staging workflow applies to stable release branches, but the main branch is called `release-*` instead of `master`.
 
-Add a reason for the backport by using `git cherry-pick -xe <original commit>` instead when it is not obvious from the original commit message. It is not needed when it's a minor version update that includes security and bug fixes but don't add new features or when the commit fixes an otherwise broken package.
+Example branch names: `release-21.11`, `staging-21.11`, `staging-next-21.11`.
 
-For backporting Pull Requests to stable branches, assign label `backport <branch>` to the original Pull Requests and automation should take care of the rest once the Pull Requests is merged.
+Most changes added to the stable release branches are cherry-picked (“backported”) from the `master` and staging branches.
+
+#### Automatically backporting a Pull Request {#submitting-changes-stable-release-branches-automatic-backports}
+
+Assign label `backport <branch>` (e.g. `backport release-21.11`) to the PR and a backport PR is automatically created after the PR is merged.
+
+#### Manually backporting changes {#submitting-changes-stable-release-branches-manual-backports}
+
+Cherry-pick changes via `git cherry-pick -x <original commit>` so that the original commit id is included in the commit message.
+
+Add a reason for the backport when it is not obvious from the original commit message. You can do this by cherry picking with `git cherry-pick -xe <original commit>`, which allows editing the commit message. This is not needed for minor version updates that include security and bug fixes but don't add new features or when the commit fixes an otherwise broken package.
 
 Here is an example of a cherry-picked commit message with good reason description:
 
diff --git a/nixpkgs/doc/functions/library/attrsets.xml b/nixpkgs/doc/functions/library/attrsets.xml
index 9d36becd496c..a30f4edf4c19 100644
--- a/nixpkgs/doc/functions/library/attrsets.xml
+++ b/nixpkgs/doc/functions/library/attrsets.xml
@@ -166,7 +166,7 @@ lib.attrsets.setAttrByPath [ "a" "b" ] 3
   <xi:include href="./locations.xml" xpointer="lib.attrsets.getAttrFromPath" />
 
   <para>
-   Like [](#function-library-lib.attrsets.attrByPath) except without a default, and it will throw if the value doesn't exist.
+   Like <xref linkend="function-library-lib.attrsets.attrByPath" /> except without a default, and it will throw if the value doesn't exist.
   </para>
 
   <variablelist>
@@ -1480,7 +1480,7 @@ lib.attrsets.zipAttrsWith
   <xi:include href="./locations.xml" xpointer="lib.attrsets.zipAttrs" />
 
   <para>
-   Merge sets of attributes and combine each attribute value in to a list. Similar to [](#function-library-lib.attrsets.zipAttrsWith) where the merge function returns a list of all values.
+   Merge sets of attributes and combine each attribute value in to a list. Similar to <xref linkend="function-library-lib.attrsets.zipAttrsWith" /> where the merge function returns a list of all values.
   </para>
 
   <variablelist>
diff --git a/nixpkgs/doc/languages-frameworks/beam.section.md b/nixpkgs/doc/languages-frameworks/beam.section.md
index fb608932dfc3..9b09d0329c5f 100644
--- a/nixpkgs/doc/languages-frameworks/beam.section.md
+++ b/nixpkgs/doc/languages-frameworks/beam.section.md
@@ -291,10 +291,10 @@ let
   # define packages to install
   basePackages = [
     git
-    # replace with beam.packages.erlang.elixir_1_11 if you need
+    # replace with beam.packages.erlang.elixir_1_13 if you need
     beam.packages.erlang.elixir
     nodejs
-    postgresql_13
+    postgresql_14
     # only used for frontend dependencies
     # you are free to use yarn2nix as well
     nodePackages.node2nix
@@ -312,10 +312,11 @@ let
     mkdir -p .nix-mix .nix-hex
     export MIX_HOME=$PWD/.nix-mix
     export HEX_HOME=$PWD/.nix-mix
+    # make hex from Nixpkgs available
+    # `mix local.hex` will install hex into MIX_HOME and should take precedence
+    export MIX_PATH="${beam.packages.erlang.hex}/lib/erlang/lib/hex/ebin"
     export PATH=$MIX_HOME/bin:$HEX_HOME/bin:$PATH
-    # TODO: not sure how to make hex available without installing it afterwards.
-    mix local.hex --if-missing
-    export LANG=en_US.UTF-8
+    export LANG=C.UTF-8
     # keep your shell history in iex
     export ERL_AFLAGS="-kernel shell_history enabled"
 
diff --git a/nixpkgs/doc/languages-frameworks/crystal.section.md b/nixpkgs/doc/languages-frameworks/crystal.section.md
index cbe31f9f0b2f..cbabba24f0c1 100644
--- a/nixpkgs/doc/languages-frameworks/crystal.section.md
+++ b/nixpkgs/doc/languages-frameworks/crystal.section.md
@@ -4,12 +4,12 @@
 
 This section uses [Mint](https://github.com/mint-lang/mint) as an example for how to build a Crystal package.
 
-If the Crystal project has any dependencies, the first step is to get a `shards.nix` file encoding those. Get a copy of the project and go to its root directory such that its `shard.lock` file is in the current directory, then run `crystal2nix` in it
-
+If the Crystal project has any dependencies, the first step is to get a `shards.nix` file encoding those. Get a copy of the project and go to its root directory such that its `shard.lock` file is in the current directory. Executable projects should usually commit the `shard.lock` file, but sometimes that's not the case, which means you need to generate it yourself. With an existing `shard.lock` file, `crystal2nix` can be run.
 ```bash
 $ git clone https://github.com/mint-lang/mint
 $ cd mint
 $ git checkout 0.5.0
+$ if [ ! -f shard.lock ]; then nix-shell -p shards --run "shards lock"; fi
 $ nix-shell -p crystal2nix --run crystal2nix
 ```
 
diff --git a/nixpkgs/doc/languages-frameworks/dhall.section.md b/nixpkgs/doc/languages-frameworks/dhall.section.md
index d1adcbf736bf..4b49908b0b0c 100644
--- a/nixpkgs/doc/languages-frameworks/dhall.section.md
+++ b/nixpkgs/doc/languages-frameworks/dhall.section.md
@@ -50,7 +50,7 @@ expression does not protect the Prelude import with a semantic integrity
 check, so the first step is to freeze the expression using `dhall freeze`,
 like this:
 
-```bash
+```ShellSession
 $ dhall freeze --inplace ./true.dhall
 ```
 
@@ -113,7 +113,7 @@ in
 
 … which we can then build using this command:
 
-```bash
+```ShellSession
 $ nix build --file ./example.nix dhallPackages.true
 ```
 
@@ -121,7 +121,7 @@ $ nix build --file ./example.nix dhallPackages.true
 
 The above package produces the following directory tree:
 
-```bash
+```ShellSession
 $ tree -a ./result
 result
 ├── .cache
@@ -135,7 +135,7 @@ result
 
 * `source.dhall` contains the result of interpreting our Dhall package:
 
-  ```bash
+  ```ShellSession
   $ cat ./result/source.dhall
   True
   ```
@@ -143,7 +143,7 @@ result
 * The `.cache` subdirectory contains one binary cache product encoding the
   same result as `source.dhall`:
 
-  ```bash
+  ```ShellSession
   $ dhall decode < ./result/.cache/dhall/122027abdeddfe8503496adeb623466caa47da5f63abd2bc6fa19f6cfcb73ecfed70
   True
   ```
@@ -151,7 +151,7 @@ result
 * `binary.dhall` contains a Dhall expression which handles fetching and decoding
   the same cache product:
 
-  ```bash
+  ```ShellSession
   $ cat ./result/binary.dhall
   missing sha256:27abdeddfe8503496adeb623466caa47da5f63abd2bc6fa19f6cfcb73ecfed70
   $ cp -r ./result/.cache .cache
@@ -168,7 +168,7 @@ to conserve disk space when they are used exclusively as dependencies.  For
 example, if we build the Prelude package it will only contain the binary
 encoding of the expression:
 
-```bash
+```ShellSession
 $ nix build --file ./example.nix dhallPackages.Prelude
 
 $ tree -a result
@@ -199,7 +199,7 @@ Dhall overlay like this:
 … and now the Prelude will contain the fully decoded result of interpreting
 the Prelude:
 
-```bash
+```ShellSession
 $ nix build --file ./example.nix dhallPackages.Prelude
 
 $ tree -a result
@@ -302,7 +302,7 @@ Additionally, `buildDhallGitHubPackage` accepts the same arguments as
 You can use the `dhall-to-nixpkgs` command-line utility to automate
 packaging Dhall code.  For example:
 
-```bash
+```ShellSession
 $ nix-env --install --attr haskellPackages.dhall-nixpkgs
 
 $ nix-env --install --attr nix-prefetch-git  # Used by dhall-to-nixpkgs
@@ -329,12 +329,12 @@ The utility takes care of automatically detecting remote imports and converting
 them to package dependencies.  You can also use the utility on local
 Dhall directories, too:
 
-```bash
+```ShellSession
 $ dhall-to-nixpkgs directory ~/proj/dhall-semver
 { buildDhallDirectoryPackage, Prelude }:
   buildDhallDirectoryPackage {
     name = "proj";
-    src = /Users/gabriel/proj/dhall-semver;
+    src = ~/proj/dhall-semver;
     file = "package.dhall";
     source = false;
     document = false;
@@ -342,6 +342,37 @@ $ dhall-to-nixpkgs directory ~/proj/dhall-semver
     }
 ```
 
+### Remote imports as fixed-output derivations {#ssec-dhall-remote-imports-as-fod}
+
+`dhall-to-nixpkgs` has the ability to fetch and build remote imports as
+fixed-output derivations by using their Dhall integrity check. This is
+sometimes easier than manually packaging all remote imports.
+
+This can be used like the following:
+
+```ShellSession
+$ dhall-to-nixpkgs directory --fixed-output-derivations ~/proj/dhall-semver
+{ buildDhallDirectoryPackage, buildDhallUrl }:
+  buildDhallDirectoryPackage {
+    name = "proj";
+    src = ~/proj/dhall-semver;
+    file = "package.dhall";
+    source = false;
+    document = false;
+    dependencies = [
+      (buildDhallUrl {
+        url = "https://prelude.dhall-lang.org/v17.0.0/package.dhall";
+        hash = "sha256-ENs8kZwl6QRoM9+Jeo/+JwHcOQ+giT2VjDQwUkvlpD4=";
+        dhallHash = "sha256:10db3c919c25e9046833df897a8ffe2701dc390fa0893d958c3430524be5a43e";
+        })
+      ];
+    }
+```
+
+Here, `dhall-semver`'s `Prelude` dependency is fetched and built with the
+`buildDhallUrl` helper function, instead of being passed in as a function
+argument.
+
 ## Overriding dependency versions {#ssec-dhall-overriding-dependency-versions}
 
 Suppose that we change our `true.dhall` example expression to depend on an older
@@ -359,7 +390,7 @@ in  Prelude.Bool.not False
 
 If we try to rebuild that expression the build will fail:
 
-```
+```ShellSession
 $ nix build --file ./example.nix dhallPackages.true
 builder for '/nix/store/0f1hla7ff1wiaqyk1r2ky4wnhnw114fi-true.drv' failed with exit code 1; last 10 log lines:
 
@@ -385,7 +416,7 @@ importing the URL.
 However, we can override the default Prelude version by using `dhall-to-nixpkgs`
 to create a Dhall package for our desired Prelude:
 
-```bash
+```ShellSession
 $ dhall-to-nixpkgs github https://github.com/dhall-lang/dhall-lang.git \
     --name Prelude \
     --directory Prelude \
@@ -396,7 +427,7 @@ $ dhall-to-nixpkgs github https://github.com/dhall-lang/dhall-lang.git \
 … and then referencing that package in our Dhall overlay, by either overriding
 the Prelude globally for all packages, like this:
 
-```bash
+```nix
   dhallOverrides = self: super: {
     true = self.callPackage ./true.nix { };
 
@@ -407,7 +438,7 @@ the Prelude globally for all packages, like this:
 … or selectively overriding the Prelude dependency for just the `true` package,
 like this:
 
-```bash
+```nix
   dhallOverrides = self: super: {
     true = self.callPackage ./true.nix {
       Prelude = self.callPackage ./Prelude.nix { };
diff --git a/nixpkgs/doc/languages-frameworks/dotnet.section.md b/nixpkgs/doc/languages-frameworks/dotnet.section.md
index 9bf96f3198a1..88e1a0b29596 100644
--- a/nixpkgs/doc/languages-frameworks/dotnet.section.md
+++ b/nixpkgs/doc/languages-frameworks/dotnet.section.md
@@ -71,30 +71,52 @@ The `dotnetCorePackages.sdk` contains both a runtime and the full sdk of a given
 
 To package Dotnet applications, you can use `buildDotnetModule`. This has similar arguments to `stdenv.mkDerivation`, with the following additions:
 
-* `projectFile` has to be used for specifying the dotnet project file relative to the source root. These usually have `.sln` or `.csproj` file extensions.
-* `nugetDeps` has to be used to specify the NuGet dependency file. Unfortunately, these cannot be deterministically fetched without a lockfile. This file should be generated using `nuget-to-nix` tool, which is available in nixpkgs.
+* `projectFile` has to be used for specifying the dotnet project file relative to the source root. These usually have `.sln` or `.csproj` file extensions. This can be an array of multiple projects as well.
+* `nugetDeps` has to be used to specify the NuGet dependency file. Unfortunately, these cannot be deterministically fetched without a lockfile. A script to fetch these is available as `passthru.fetch-deps`. This file can also be generated manually using `nuget-to-nix` tool, which is available in nixpkgs.
+* `packNupkg` is used to pack project as a `nupkg`, and installs it to `$out/share`. If set to `true`, the derivation can be used as a dependency for another dotnet project by adding it to `projectReferences`.
+* `projectReferences` can be used to resolve `ProjectReference` project items. Referenced projects can be packed with `buildDotnetModule` by setting the `packNupkg = true` attribute and passing a list of derivations to `projectReferences`. Since we are sharing referenced projects as NuGets they must be added to csproj/fsproj files as `PackageReference` as well.
+ For example, your project has a local dependency:
+ ```xml
+     <ProjectReference Include="../foo/bar.fsproj" />
+ ```
+ To enable discovery through `projectReferences` you would need to add:
+ ```xml
+     <ProjectReference Include="../foo/bar.fsproj" />
+     <PackageReference Include="bar" Version="*" Condition=" '$(ContinuousIntegrationBuild)'=='true' "/>
+  ```
 * `executables` is used to specify which executables get wrapped to `$out/bin`, relative to `$out/lib/$pname`. If this is unset, all executables generated will get installed. If you do not want to install any, set this to `[]`.
 * `runtimeDeps` is used to wrap libraries into `LD_LIBRARY_PATH`. This is how dotnet usually handles runtime dependencies.
 * `buildType` is used to change the type of build. Possible values are `Release`, `Debug`, etc. By default, this is set to `Release`.
 * `dotnet-sdk` is useful in cases where you need to change what dotnet SDK is being used.
-* `dotnet-runtime` is useful in cases where you need to change what dotnet runtime is being used.
+* `dotnet-runtime` is useful in cases where you need to change what dotnet runtime is being used. This can be either a regular dotnet runtime, or an aspnetcore.
+* `dotnet-test-sdk` is useful in cases where unit tests expect a different dotnet SDK. By default, this is set to the `dotnet-sdk` attribute.
+* `testProjectFile` is useful in cases where the regular project file does not contain the unit tests. It gets restored and build, but not installed. You may need to regenerate your nuget lockfile after setting this.
+* `disabledTests` is used to disable running specific unit tests. This gets passed as: `dotnet test --filter "FullyQualifiedName!={}"`, to ensure compatibility with all unit test frameworks.
 * `dotnetRestoreFlags` can be used to pass flags to `dotnet restore`.
 * `dotnetBuildFlags` can be used to pass flags to `dotnet build`.
+* `dotnetTestFlags` can be used to pass flags to `dotnet test`. Used only if `doCheck` is set to `true`.
 * `dotnetInstallFlags` can be used to pass flags to `dotnet install`.
+* `dotnetPackFlags` can be used to pass flags to `dotnet pack`. Used only if `packNupkg` is set to `true`.
 * `dotnetFlags` can be used to pass flags to all of the above phases.
 
+When packaging a new application, you need to fetch it's dependencies. You can set `nugetDeps` to an empty string to make the derivation temporarily evaluate, and then run `nix-build -A package.passthru.fetch-deps` to generate it's dependency fetching script. After running the script, you should have the location of the generated lockfile printed to the console. This can be copied to a stable directory. Note that if either `projectFile` or `nugetDeps` are unset, this script cannot be generated!
+
 Here is an example `default.nix`, using some of the previously discussed arguments:
 ```nix
 { lib, buildDotnetModule, dotnetCorePackages, ffmpeg }:
 
-buildDotnetModule rec {
+let
+  referencedProject = import ../../bar { ... };
+in buildDotnetModule rec {
   pname = "someDotnetApplication";
   version = "0.1";
 
   src = ./.;
 
   projectFile = "src/project.sln";
-  nugetDeps = ./deps.nix; # File generated with `nuget-to-nix path/to/src > deps.nix`.
+  nugetDeps = ./deps.nix; # File generated with `nix-build -A package.passthru.fetch-deps`.
+
+  projectReferences = [ referencedProject ]; # `referencedProject` must contain `nupkg` in the folder structure.
 
   dotnet-sdk = dotnetCorePackages.sdk_3_1;
   dotnet-runtime = dotnetCorePackages.net_5_0;
@@ -103,6 +125,8 @@ buildDotnetModule rec {
   executables = [ "foo" ]; # This wraps "$out/lib/$pname/foo" to `$out/bin/foo`.
   executables = []; # Don't install any executables.
 
+  packNupkg = true; # This packs the project as "foo-0.1.nupkg" at `$out/share`.
+
   runtimeDeps = [ ffmpeg ]; # This will wrap ffmpeg's library path into `LD_LIBRARY_PATH`.
 }
 ```
diff --git a/nixpkgs/doc/languages-frameworks/emscripten.section.md b/nixpkgs/doc/languages-frameworks/emscripten.section.md
index b3ddf0cedaea..c96f689c4c00 100644
--- a/nixpkgs/doc/languages-frameworks/emscripten.section.md
+++ b/nixpkgs/doc/languages-frameworks/emscripten.section.md
@@ -15,12 +15,12 @@ Modes of use of `emscripten`:
 
    If you want to work with `emcc`, `emconfigure` and `emmake` as you are used to from Ubuntu and similar distributions you can use these commands:
 
-    * `nix-env -i emscripten`
+    * `nix-env -f "<nixpkgs>" -iA emscripten`
     * `nix-shell -p emscripten`
 
 * **Declarative usage**:
 
-    This mode is far more power full since this makes use of `nix` for dependency management of emscripten libraries and targets by using the `mkDerivation` which is implemented by `pkgs.emscriptenStdenv` and `pkgs.buildEmscriptenPackage`. The source for the packages is in `pkgs/top-level/emscripten-packages.nix` and the abstraction behind it in `pkgs/development/em-modules/generic/default.nix`.
+    This mode is far more power full since this makes use of `nix` for dependency management of emscripten libraries and targets by using the `mkDerivation` which is implemented by `pkgs.emscriptenStdenv` and `pkgs.buildEmscriptenPackage`. The source for the packages is in `pkgs/top-level/emscripten-packages.nix` and the abstraction behind it in `pkgs/development/em-modules/generic/default.nix`. From the root of the nixpkgs repository:
     * build and install all packages:
         * `nix-env -iA emscriptenPackages`
 
diff --git a/nixpkgs/doc/languages-frameworks/gnome.section.md b/nixpkgs/doc/languages-frameworks/gnome.section.md
index 11b49f4f235a..29cb2e0e464a 100644
--- a/nixpkgs/doc/languages-frameworks/gnome.section.md
+++ b/nixpkgs/doc/languages-frameworks/gnome.section.md
@@ -92,7 +92,7 @@ For convenience, it also adds `dconf.lib` for a GIO module implementing a GSetti
 
 - []{#ssec-gnome-hooks-glib} `glib` setup hook will populate `GSETTINGS_SCHEMAS_PATH` and then `wrapGAppsHook` will prepend it to `XDG_DATA_DIRS`.
 
-- []{#ssec-gnome-hooks-gdk-pixbuf} `gdk-pixbuf` setup hook will populate `GDK_PIXBUF_MODULE_FILE` with the path to biggest `loaders.cache` file from the dependencies containing [GdkPixbuf loaders](ssec-gnome-gdk-pixbuf-loaders). This works fine when there are only two packages containing loaders (`gdk-pixbuf` and e.g. `librsvg`) – it will choose the second one, reasonably expecting that it will be bigger since it describes extra loader in addition to the default ones. But when there are more than two loader packages, this logic will break. One possible solution would be constructing a custom cache file for each package containing a program like `services/x11/gdk-pixbuf.nix` NixOS module does. `wrapGAppsHook` copies the `GDK_PIXBUF_MODULE_FILE` environment variable into the produced wrapper.
+- []{#ssec-gnome-hooks-gdk-pixbuf} `gdk-pixbuf` setup hook will populate `GDK_PIXBUF_MODULE_FILE` with the path to biggest `loaders.cache` file from the dependencies containing [GdkPixbuf loaders](#ssec-gnome-gdk-pixbuf-loaders). This works fine when there are only two packages containing loaders (`gdk-pixbuf` and e.g. `librsvg`) – it will choose the second one, reasonably expecting that it will be bigger since it describes extra loader in addition to the default ones. But when there are more than two loader packages, this logic will break. One possible solution would be constructing a custom cache file for each package containing a program like `services/x11/gdk-pixbuf.nix` NixOS module does. `wrapGAppsHook` copies the `GDK_PIXBUF_MODULE_FILE` environment variable into the produced wrapper.
 
 - []{#ssec-gnome-hooks-gtk-drop-icon-theme-cache} One of `gtk3`’s setup hooks will remove `icon-theme.cache` files from package’s icon theme directories to avoid conflicts. Icon theme packages should prevent this with `dontDropIconThemeCache = true;`.
 
diff --git a/nixpkgs/doc/languages-frameworks/go.section.md b/nixpkgs/doc/languages-frameworks/go.section.md
index 45d85f1f99ec..7cbf51c8e373 100644
--- a/nixpkgs/doc/languages-frameworks/go.section.md
+++ b/nixpkgs/doc/languages-frameworks/go.section.md
@@ -29,8 +29,6 @@ pet = buildGoModule rec {
 
   vendorSha256 = "1879j77k96684wi554rkjxydrj8g3hpp0kvxz03sd8dmwr3lh83j";
 
-  runVend = true;
-
   meta = with lib; {
     description = "Simple command-line snippet manager, written in Go";
     homepage = "https://github.com/knqyf263/pet";
diff --git a/nixpkgs/doc/languages-frameworks/idris.section.md b/nixpkgs/doc/languages-frameworks/idris.section.md
index ffdd706eb0b7..19146844cff5 100644
--- a/nixpkgs/doc/languages-frameworks/idris.section.md
+++ b/nixpkgs/doc/languages-frameworks/idris.section.md
@@ -5,10 +5,7 @@
 The easiest way to get a working idris version is to install the `idris` attribute:
 
 ```ShellSession
-$ # On NixOS
-$ nix-env -i nixos.idris
-$ # On non-NixOS
-$ nix-env -i nixpkgs.idris
+$ nix-env -f "<nixpkgs>" -iA idris
 ```
 
 This however only provides the `prelude` and `base` libraries. To install idris with additional libraries, you can use the `idrisPackages.with-packages` function, e.g. in an overlay in `~/.config/nixpkgs/overlays/my-idris.nix`:
diff --git a/nixpkgs/doc/languages-frameworks/lua.section.md b/nixpkgs/doc/languages-frameworks/lua.section.md
index 41fe0de04b4d..17b80f07d3e1 100644
--- a/nixpkgs/doc/languages-frameworks/lua.section.md
+++ b/nixpkgs/doc/languages-frameworks/lua.section.md
@@ -128,7 +128,7 @@ Let's present the luarocks way first and the manual one in a second time.
 
 ### Packaging a library on luarocks {#packaging-a-library-on-luarocks}
 
-[Luarocks.org](www.luarocks.org) is the main repository of lua packages.
+[Luarocks.org](https://luarocks.org/) is the main repository of lua packages.
 The site proposes two types of packages, the rockspec and the src.rock
 (equivalent of a [rockspec](https://github.com/luarocks/luarocks/wiki/Rockspec-format) but with the source).
 These packages can have different build types such as `cmake`, `builtin` etc .
diff --git a/nixpkgs/doc/languages-frameworks/ocaml.section.md b/nixpkgs/doc/languages-frameworks/ocaml.section.md
index 5ffc23173d6d..d266a032268c 100644
--- a/nixpkgs/doc/languages-frameworks/ocaml.section.md
+++ b/nixpkgs/doc/languages-frameworks/ocaml.section.md
@@ -1,5 +1,31 @@
 # OCaml {#sec-language-ocaml}
 
+## User guide {#sec-language-ocaml-user-guide}
+
+OCaml libraries are available in attribute sets of the form `ocaml-ng.ocamlPackages_X_XX` where X is to be replaced with the desired compiler version. For example, ocamlgraph compiled with OCaml 4.12 can be found in `ocaml-ng.ocamlPackages_4_12.ocamlgraph`. The compiler itself is also located in this set, under the name `ocaml`.
+
+If you don't care about the exact compiler version, `ocamlPackages` is a top-level alias pointing to a recent version of OCaml.
+
+OCaml applications are usually available top-level, and not inside `ocamlPackages`. Notable exceptions are build tools that must be built with the same compiler version as the compiler you intend to use like `dune` or `ocaml-lsp`.
+
+To open a shell able to build a typical OCaml project, put the dependencies in `buildInputs` and add `ocamlPackages.ocaml` and `ocamlPackages.findlib` to `nativeBuildInputs` at least.
+For example:
+```nix
+let
+ pkgs = import <nixpkgs> {};
+ # choose the ocaml version you want to use
+ ocamlPackages = pkgs.ocaml-ng.ocamlPackages_4_12;
+in
+pkgs.mkShell {
+  # build tools
+  nativeBuildInputs = with ocamlPackages; [ ocaml findlib dune_2 ocaml-lsp ];
+  # dependencies
+  buildInputs = with ocamlPackages; [ ocamlgraph ];
+}
+```
+
+## Packaging guide {#sec-language-ocaml-packaging}
+
 OCaml libraries should be installed in `$(out)/lib/ocaml/${ocaml.version}/site-lib/`. Such directories are automatically added to the `$OCAMLPATH` environment variable when building another package that depends on them or when opening a `nix-shell`.
 
 Given that most of the OCaml ecosystem is now built with dune, nixpkgs includes a convenience build support function called `buildDunePackage` that will build an OCaml package using dune, OCaml and findlib and any additional dependencies provided as `buildInputs` or `propagatedBuildInputs`.
diff --git a/nixpkgs/doc/languages-frameworks/octave.section.md b/nixpkgs/doc/languages-frameworks/octave.section.md
index ff872f4a7558..4ad2cb0d5fbf 100644
--- a/nixpkgs/doc/languages-frameworks/octave.section.md
+++ b/nixpkgs/doc/languages-frameworks/octave.section.md
@@ -24,18 +24,10 @@ You can test building an Octave package as follows:
 $ nix-build -A octavePackages.symbolic
 ```
 
-When building Octave packages with `nix-build`, the `buildOctavePackage` function adds `octave-octaveVersion` to; the start of the package's name attribute.
-
-This can be required when installing the package using `nix-env`:
-
-```ShellSession
-$ nix-env -i octave-6.2.0-symbolic
-```
-
-Although, you can also install it using the attribute name:
+To install it into your user profile, run this command from the root of the repository:
 
 ```ShellSession
-$ nix-env -i -A octavePackages.symbolic
+$ nix-env -f. -iA octavePackages.symbolic
 ```
 
 You can build Octave with packages by using the `withPackages` passed-through function.
diff --git a/nixpkgs/doc/languages-frameworks/perl.section.md b/nixpkgs/doc/languages-frameworks/perl.section.md
index c992b9d658bb..9bfd209fec5a 100644
--- a/nixpkgs/doc/languages-frameworks/perl.section.md
+++ b/nixpkgs/doc/languages-frameworks/perl.section.md
@@ -58,13 +58,7 @@ in `all-packages.nix`. You can test building a Perl package as follows:
 $ nix-build -A perlPackages.ClassC3
 ```
 
-`buildPerlPackage` adds `perl-` to the start of the name attribute, so the package above is actually called `perl-Class-C3-0.21`. So to install it, you can say:
-
-```ShellSession
-$ nix-env -i perl-Class-C3
-```
-
-(Of course you can also install using the attribute name: `nix-env -i -A perlPackages.ClassC3`.)
+To install it with `nix-env` instead: `nix-env -f. -iA perlPackages.ClassC3`.
 
 So what does `buildPerlPackage` do? It does the following:
 
@@ -135,9 +129,11 @@ This will remove the `-I` flags from the shebang line, rewrite them in the `use
 Nix expressions for Perl packages can be generated (almost) automatically from CPAN. This is done by the program `nix-generate-from-cpan`, which can be installed as follows:
 
 ```ShellSession
-$ nix-env -i nix-generate-from-cpan
+$ nix-env -f "<nixpkgs>" -iA nix-generate-from-cpan
 ```
 
+Substitute `<nixpkgs>` by the path of a nixpkgs clone to use the latest version.
+
 This program takes a Perl module name, looks it up on CPAN, fetches and unpacks the corresponding package, and prints a Nix expression on standard output. For example:
 
 ```ShellSession
diff --git a/nixpkgs/doc/languages-frameworks/python.section.md b/nixpkgs/doc/languages-frameworks/python.section.md
index cc1a7083dc25..9f9ace513c30 100644
--- a/nixpkgs/doc/languages-frameworks/python.section.md
+++ b/nixpkgs/doc/languages-frameworks/python.section.md
@@ -764,8 +764,8 @@ and in this case the `python38` interpreter is automatically used.
 
 ### Interpreters {#interpreters}
 
-Versions 2.7, 3.6, 3.7, 3.8 and 3.9 of the CPython interpreter are available as
-respectively `python27`, `python36`, `python37`, `python38` and `python39`. The
+Versions 2.7, 3.7, 3.8 and 3.9 of the CPython interpreter are available as
+respectively `python27`, `python37`, `python38` and `python39`. The
 aliases `python2` and `python3` correspond to respectively `python27` and
 `python39`. The attribute `python` maps to `python2`. The PyPy interpreters
 compatible with Python 2.7 and 3 are available as `pypy27` and `pypy3`, with
@@ -830,10 +830,11 @@ attribute set is created for each available Python interpreter. The available
 sets are
 
 * `pkgs.python27Packages`
-* `pkgs.python36Packages`
 * `pkgs.python37Packages`
 * `pkgs.python38Packages`
 * `pkgs.python39Packages`
+* `pkgs.python310Packages`
+* `pkgs.python311Packages`
 * `pkgs.pypyPackages`
 
 and the aliases
@@ -995,18 +996,18 @@ called with `callPackage` and passed `python` or `pythonPackages` (possibly
 specifying an interpreter version), like this:
 
 ```nix
-{ lib, python3Packages }:
+{ lib, python3 }:
 
-python3Packages.buildPythonApplication rec {
+python3.pkgs.buildPythonApplication rec {
   pname = "luigi";
   version = "2.7.9";
 
-  src = python3Packages.fetchPypi {
+  src = python3.pkgs.fetchPypi {
     inherit pname version;
     sha256 = "035w8gqql36zlan0xjrzz9j4lh9hs0qrsgnbyw07qs7lnkvbdv9x";
   };
 
-  propagatedBuildInputs = with python3Packages; [ tornado_4 python-daemon ];
+  propagatedBuildInputs = with python3.pkgs; [ tornado python-daemon ];
 
   meta = with lib; {
     ...
@@ -1632,3 +1633,25 @@ would be:
 ```ShellSession
 $ maintainers/scripts/update-python-libraries --target minor --commit --use-pkgs-prefix pkgs/development/python-modules/**/default.nix
 ```
+
+## CPython Update Schedule
+
+With [PEP 602](https://www.python.org/dev/peps/pep-0602/), CPython now
+follows a yearly release cadence. In nixpkgs, all supported interpreters
+are made available, but only the most recent two
+interpreters package sets are built; this is a compromise between being
+the latest interpreter, and what the majority of the Python packages support.
+
+New CPython interpreters are released in October. Generally, it takes some
+time for the majority of active Python projects to support the latest stable
+interpreter. To help ease the migration for Nixpkgs users
+between Python interpreters the schedule below will be used:
+
+| When | Event |
+| --- | --- |
+| After YY.11 Release | Bump CPython package set window. The latest and previous latest stable should now be built. |
+| After YY.05 Release | Bump default CPython interpreter to latest stable. |
+
+In practice, this means that the Python community will have had a stable interpreter
+for ~2 months before attempting to update the package set. And this will
+allow for ~7 months for Python applications to support the latest interpreter.
diff --git a/nixpkgs/doc/languages-frameworks/ruby.section.md b/nixpkgs/doc/languages-frameworks/ruby.section.md
index 36b794458cba..e29f97c566c1 100644
--- a/nixpkgs/doc/languages-frameworks/ruby.section.md
+++ b/nixpkgs/doc/languages-frameworks/ruby.section.md
@@ -8,7 +8,7 @@ In the Nixpkgs tree, Ruby packages can be found throughout, depending on what th
 
 There are two main approaches for using Ruby with gems. One is to use a specifically locked `Gemfile` for an application that has very strict dependencies. The other is to depend on the common gems, which we'll explain further down, and rely on them being updated regularly.
 
-The interpreters have common attributes, namely `gems`, and `withPackages`. So you can refer to `ruby.gems.nokogiri`, or `ruby_2_6.gems.nokogiri` to get the Nokogiri gem already compiled and ready to use.
+The interpreters have common attributes, namely `gems`, and `withPackages`. So you can refer to `ruby.gems.nokogiri`, or `ruby_2_7.gems.nokogiri` to get the Nokogiri gem already compiled and ready to use.
 
 Since not all gems have executables like `nokogiri`, it's usually more convenient to use the `withPackages` function like this: `ruby.withPackages (p: with p; [ nokogiri ])`. This will also make sure that the Ruby in your environment will be able to find the gem and it can be used in your Ruby code (for example via `ruby` or `irb` executables) via `require "nokogiri"` as usual.
 
@@ -201,6 +201,19 @@ $ nix-shell --run 'ruby -rpg -e "puts PG.library_version"'
 
 Of course for this use-case one could also use overlays since the configuration for `pg` depends on the `postgresql` alias, but for demonstration purposes this has to suffice.
 
+### Platform-specific gems
+
+Right now, bundix has some issues with pre-built, platform-specific gems: [bundix PR #68](https://github.com/nix-community/bundix/pull/68).
+Until this is solved, you can tell bundler to not use platform-specific gems and instead build them from source each time:
+- globally (will be set in `~/.config/.bundle/config`):
+```shell
+$ bundle config set force_ruby_platform true
+```
+- locally (will be set in `<project-root>/.bundle/config`):
+```shell
+$ bundle config set --local force_ruby_platform true
+```
+
 ### Adding a gem to the default gemset {#adding-a-gem-to-the-default-gemset}
 
 Now that you know how to get a working Ruby environment with Nix, it's time to go forward and start actually developing with Ruby. We will first have a look at how Ruby gems are packaged on Nix. Then, we will look at how you can use development mode with your code.
diff --git a/nixpkgs/doc/languages-frameworks/rust.section.md b/nixpkgs/doc/languages-frameworks/rust.section.md
index b2f045b11b32..56faf636df10 100644
--- a/nixpkgs/doc/languages-frameworks/rust.section.md
+++ b/nixpkgs/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}
 
@@ -186,6 +186,33 @@ added. To find the correct hash, you can first use `lib.fakeSha256` or
 `lib.fakeHash` as a stub hash. Building the package (and thus the
 vendored dependencies) will then inform you of the correct hash.
 
+### Cargo features {#cargo-features}
+
+You can disable default features using `buildNoDefaultFeatures`, and
+extra features can be added with `buildFeatures`.
+
+If you want to use different features for check phase, you can use
+`checkNoDefaultFeatures` and `checkFeatures`. They are only passed to
+`cargo test` and not `cargo build`. If left unset, they default to
+`buildNoDefaultFeatures` and `buildFeatures`.
+
+For example:
+
+```nix
+rustPlatform.buildRustPackage rec {
+  pname = "myproject";
+  version = "1.0.0";
+
+  buildNoDefaultFeatures = true;
+  buildFeatures = [ "color" "net" ];
+
+  # disable network features in tests
+  checkFeatures = [ "color" ];
+
+  # ...
+}
+```
+
 ### Cross compilation {#cross-compilation}
 
 By default, Rust packages are compiled for the host platform, just like any
@@ -237,22 +264,6 @@ where they are known to differ. But there are ways to customize the argument:
    --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 {
-  /* ... */
-  target = "x86_64-fortanix-unknown-sgx";
-}
-```
-
-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.
 
@@ -277,12 +288,12 @@ rustPlatform.buildRustPackage {
 Please note that the code will be compiled twice here: once in `release` mode
 for the `buildPhase`, and again in `debug` mode for the `checkPhase`.
 
-Test flags, e.g., `--features xxx/yyy`, can be passed to `cargo test` via the
+Test flags, e.g., `--package foo`, can be passed to `cargo test` via the
 `cargoTestFlags` attribute.
 
 Another attribute, called `checkFlags`, is used to pass arguments to the test
 binary itself, as stated
-(here)[https://doc.rust-lang.org/cargo/commands/cargo-test.html].
+[here](https://doc.rust-lang.org/cargo/commands/cargo-test.html).
 
 #### Tests relying on the structure of the `target/` directory {#tests-relying-on-the-structure-of-the-target-directory}
 
@@ -427,7 +438,7 @@ you of the correct hash.
 
 `rustPlatform` provides the following hooks to automate Cargo builds:
 
-* `cargoSetupHook`: configure Cargo to use depenencies vendored
+* `cargoSetupHook`: configure Cargo to use dependencies vendored
   through `fetchCargoTarball`. This hook uses the `cargoDeps`
   environment variable to find the vendored dependencies. If a project
   already vendors its dependencies, the variable `cargoVendorDir` can
@@ -437,18 +448,20 @@ you of the correct hash.
 * `cargoBuildHook`: use Cargo to build a crate. If the crate to be
   built is a crate in e.g. a Cargo workspace, the relative path to the
   crate to build can be set through the optional `buildAndTestSubdir`
-  environment variable. Additional Cargo build flags can be passed
-  through `cargoBuildFlags`.
+  environment variable. Features can be specified with
+  `cargoBuildNoDefaultFeatures` and `cargoBuildFeatures`. Additional
+  Cargo build flags can be passed through `cargoBuildFlags`.
 * `maturinBuildHook`: use [Maturin](https://github.com/PyO3/maturin)
   to build a Python wheel. Similar to `cargoBuildHook`, the optional
   variable `buildAndTestSubdir` can be used to build a crate in a
-  Cargo workspace. Additional maturin flags can be passed through
+  Cargo workspace. Additional Maturin flags can be passed through
   `maturinBuildFlags`.
 * `cargoCheckHook`: run tests using Cargo. The build type for checks
-  can be set using `cargoCheckType`. Additional flags can be passed to
-  the tests using `checkFlags` and `checkFlagsArray`. By default,
-  tests are run in parallel. This can be disabled by setting
-  `dontUseCargoParallelTests`.
+  can be set using `cargoCheckType`. Features can be specified with
+  `cargoCheckNoDefaultFeaatures` and `cargoCheckFeatures`. Additional
+  flags can be passed to the tests using `checkFlags` and
+  `checkFlagsArray`. By default, tests are run in parallel. This can
+  be disabled by setting `dontUseCargoParallelTests`.
 * `cargoInstallHook`: install binaries and static/shared libraries
   that were built using `cargoBuildHook`.
 
@@ -463,7 +476,7 @@ dependencies. The build itself is then performed by
 
 The following example outlines how the `tokenizers` Python package is
 built. Since the Python package is in the `source/bindings/python`
-directory of the *tokenizers* project's source archive, we use
+directory of the `tokenizers` project's source archive, we use
 `sourceRoot` to point the tooling to this directory:
 
 ```nix
@@ -688,7 +701,7 @@ Some crates require external libraries. For crates from
 `defaultCrateOverrides` package in nixpkgs itself.
 
 Starting from that file, one can add more overrides, to add features
-or build inputs by overriding the hello crate in a seperate file.
+or build inputs by overriding the hello crate in a separate file.
 
 ```nix
 with import <nixpkgs> {};
@@ -745,7 +758,7 @@ with import <nixpkgs> {};
 Actually, the overrides introduced in the previous section are more
 general. A number of other parameters can be overridden:
 
-- The version of rustc used to compile the crate:
+- The version of `rustc` used to compile the crate:
 
   ```nix
   (hello {}).override { rust = pkgs.rust; };
@@ -758,7 +771,7 @@ general. A number of other parameters can be overridden:
   (hello {}).override { release = false; };
   ```
 
-- Whether to print the commands sent to rustc when building
+- Whether to print the commands sent to `rustc` when building
   (equivalent to `--verbose` in cargo:
 
   ```nix
@@ -887,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}
-
-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.
-
-### 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).
+## Using community Rust overlays {#using-community-rust-overlays}
 
-#### Imperative rust overlay installation {#imperative-rust-overlay-installation}
+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)
 
-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.
+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.
 
-```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
-```
+Fenix is an alternative to `rustup` and can also be used as an overlay.
 
-### Declarative rust overlay installation {#declarative-rust-overlay-installation}
+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`).
 
-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'`
+
+As of writing, this prints out `rustc 1.56.0 (09c42c458 2021-10-18)`.
 
-### Rust overlay usage {#rust-overlay-usage}
+### How to use an overlay toolchain in a derivation  {#how-to-use-an-overlay-toolchain-in-a-derivation}
 
-The overlay contains attribute sets corresponding to different versions of the rust toolchain, such as:
+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"))
+  ];
+};
 
-* `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)
+rustPlatform.buildRustPackage rec {
+  pname = "ripgrep";
+  version = "12.1.1";
+  nativeBuildInputs = [
+    rust-bin.stable.latest.minimal
+  ];
 
-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.
+  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}
+
+This snippet shows how to use oxalica's Rust overlay.
+Add the following to your `configuration.nix`, `home-configuration.nix`, `shell.nix`, or similar:
 
-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.
+```nix
+{ pkgs ? import <nixpkgs> {
+    overlays = [
+      (import (builtins.fetchTarball "https://github.com/oxalica/rust-overlay/archive/master.tar.gz"))
+      # Further overlays go here
+    ];
+  };
+};
+```
 
-The overlay automatically updates itself as it uses the same source as
-[rustup](https://www.rustup.rs/).
+Note that this will fetch the latest overlay version when rebuilding your system.
diff --git a/nixpkgs/doc/languages-frameworks/vim.section.md b/nixpkgs/doc/languages-frameworks/vim.section.md
index cb5311fc95f1..4ffd6736e238 100644
--- a/nixpkgs/doc/languages-frameworks/vim.section.md
+++ b/nixpkgs/doc/languages-frameworks/vim.section.md
@@ -309,9 +309,9 @@ Sample output2:
 
 ## Adding new plugins to nixpkgs {#adding-new-plugins-to-nixpkgs}
 
-Nix expressions for Vim plugins are stored in [pkgs/misc/vim-plugins](/pkgs/misc/vim-plugins). For the vast majority of plugins, Nix expressions are automatically generated by running [`./update.py`](/pkgs/misc/vim-plugins/update.py). This creates a [generated.nix](/pkgs/misc/vim-plugins/generated.nix) file based on the plugins listed in [vim-plugin-names](/pkgs/misc/vim-plugins/vim-plugin-names). Plugins are listed in alphabetical order in `vim-plugin-names` using the format `[github username]/[repository]@[gitref]`. For example https://github.com/scrooloose/nerdtree becomes `scrooloose/nerdtree`.
+Nix expressions for Vim plugins are stored in [pkgs/misc/vim-plugins](https://github.com/NixOS/nixpkgs/tree/master/pkgs/misc/vim-plugins). For the vast majority of plugins, Nix expressions are automatically generated by running [`./update.py`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/misc/vim-plugins/update.py). This creates a [generated.nix](https://github.com/NixOS/nixpkgs/blob/master/pkgs/misc/vim-plugins/generated.nix) file based on the plugins listed in [vim-plugin-names](https://github.com/NixOS/nixpkgs/blob/master/pkgs/misc/vim-plugins/vim-plugin-names). Plugins are listed in alphabetical order in `vim-plugin-names` using the format `[github username]/[repository]@[gitref]`. For example https://github.com/scrooloose/nerdtree becomes `scrooloose/nerdtree`.
 
-Some plugins require overrides in order to function properly. Overrides are placed in [overrides.nix](/pkgs/misc/vim-plugins/overrides.nix). Overrides are most often required when a plugin requires some dependencies, or extra steps are required during the build process. For example `deoplete-fish` requires both `deoplete-nvim` and `vim-fish`, and so the following override was added:
+Some plugins require overrides in order to function properly. Overrides are placed in [overrides.nix](https://github.com/NixOS/nixpkgs/blob/master/pkgs/misc/vim-plugins/overrides.nix). Overrides are most often required when a plugin requires some dependencies, or extra steps are required during the build process. For example `deoplete-fish` requires both `deoplete-nvim` and `vim-fish`, and so the following override was added:
 
 ```nix
 deoplete-fish = super.deoplete-fish.overrideAttrs(old: {
diff --git a/nixpkgs/doc/stdenv/cross-compilation.chapter.md b/nixpkgs/doc/stdenv/cross-compilation.chapter.md
index 53522962a5c9..f6e61a1af196 100644
--- a/nixpkgs/doc/stdenv/cross-compilation.chapter.md
+++ b/nixpkgs/doc/stdenv/cross-compilation.chapter.md
@@ -158,9 +158,9 @@ One would think that `localSystem` and `crossSystem` overlap horribly with the t
 
 ### Implementation of dependencies {#ssec-cross-dependency-implementation}
 
-The categories of dependencies developed in [](#ssec-cross-dependency-categorization) are specified as lists of derivations given to `mkDerivation`, as documented in [](#ssec-stdenv-dependencies). In short, each list of dependencies for "host → target" of "foo → bar" is called `depsFooBar`, with exceptions for backwards compatibility that `depsBuildHost` is instead called `nativeBuildInputs` and `depsHostTarget` is instead called `buildInputs`. Nixpkgs is now structured so that each `depsFooBar` is automatically taken from `pkgsFooBar`. (These `pkgsFooBar`s are quite new, so there is no special case for `nativeBuildInputs` and `buildInputs`.) For example, `pkgsBuildHost.gcc` should be used at build-time, while `pkgsHostTarget.gcc` should be used at run-time.
+The categories of dependencies developed in [](#ssec-cross-dependency-categorization) are specified as lists of derivations given to `mkDerivation`, as documented in [](#ssec-stdenv-dependencies). In short, each list of dependencies for "host → target" is called `deps<host><target>` (where `host`, and `target` values are either `build`, `host`, or `target`), with exceptions for backwards compatibility that `depsBuildHost` is instead called `nativeBuildInputs` and `depsHostTarget` is instead called `buildInputs`. Nixpkgs is now structured so that each `deps<host><target>` is automatically taken from `pkgs<host><target>`. (These `pkgs<host><target>`s are quite new, so there is no special case for `nativeBuildInputs` and `buildInputs`.) For example, `pkgsBuildHost.gcc` should be used at build-time, while `pkgsHostTarget.gcc` should be used at run-time.
 
-Now, for most of Nixpkgs's history, there were no `pkgsFooBar` attributes, and most packages have not been refactored to use it explicitly. Prior to those, there were just `buildPackages`, `pkgs`, and `targetPackages`. Those are now redefined as aliases to `pkgsBuildHost`, `pkgsHostTarget`, and `pkgsTargetTarget`. It is acceptable, even recommended, to use them for libraries to show that the host platform is irrelevant.
+Now, for most of Nixpkgs's history, there were no `pkgs<host><target>` attributes, and most packages have not been refactored to use it explicitly. Prior to those, there were just `buildPackages`, `pkgs`, and `targetPackages`. Those are now redefined as aliases to `pkgsBuildHost`, `pkgsHostTarget`, and `pkgsTargetTarget`. It is acceptable, even recommended, to use them for libraries to show that the host platform is irrelevant.
 
 But before that, there was just `pkgs`, even though both `buildInputs` and `nativeBuildInputs` existed. \[Cross barely worked, and those were implemented with some hacks on `mkDerivation` to override dependencies.\] What this means is the vast majority of packages do not use any explicit package set to populate their dependencies, just using whatever `callPackage` gives them even if they do correctly sort their dependencies into the multiple lists described above. And indeed, asking that users both sort their dependencies, _and_ take them from the right attribute set, is both too onerous and redundant, so the recommended approach (for now) is to continue just categorizing by list and not using an explicit package set.
 
diff --git a/nixpkgs/doc/stdenv/stdenv.chapter.md b/nixpkgs/doc/stdenv/stdenv.chapter.md
index 02042407f6ce..6d72bd0deb4f 100644
--- a/nixpkgs/doc/stdenv/stdenv.chapter.md
+++ b/nixpkgs/doc/stdenv/stdenv.chapter.md
@@ -116,15 +116,27 @@ On Linux, `stdenv` also includes the `patchelf` utility.
 
 ## Specifying dependencies {#ssec-stdenv-dependencies}
 
-As described in the Nix manual, almost any `*.drv` store path in a derivation’s attribute set will induce a dependency on that derivation. `mkDerivation`, however, takes a few attributes intended to, between them, include all the dependencies of a package. This is done both for structure and consistency, but also so that certain other setup can take place. For example, certain dependencies need their bin directories added to the `PATH`. That is built-in, but other setup is done via a pluggable mechanism that works in conjunction with these dependency attributes. See [](#ssec-setup-hooks) for details.
+As described in the Nix manual, almost any `*.drv` store path in a derivation’s attribute set will induce a dependency on that derivation. `mkDerivation`, however, takes a few attributes intended to include all the dependencies of a package. This is done both for structure and consistency, but also so that certain other setup can take place. For example, certain dependencies need their bin directories added to the `PATH`. That is built-in, but other setup is done via a pluggable mechanism that works in conjunction with these dependency attributes. See [](#ssec-setup-hooks) for details.
 
 Dependencies can be broken down along three axes: their host and target platforms relative to the new derivation’s, and whether they are propagated. The platform distinctions are motivated by cross compilation; see [](#chap-cross) for exactly what each platform means. [^footnote-stdenv-ignored-build-platform] But even if one is not cross compiling, the platforms imply whether or not the dependency is needed at run-time or build-time, a concept that makes perfect sense outside of cross compilation. By default, the run-time/build-time distinction is just a hint for mental clarity, but with `strictDeps` set it is mostly enforced even in the native case.
 
 The extension of `PATH` with dependencies, alluded to above, proceeds according to the relative platforms alone. The process is carried out only for dependencies whose host platform matches the new derivation’s build platform i.e. dependencies which run on the platform where the new derivation will be built. [^footnote-stdenv-native-dependencies-in-path] For each dependency \<dep\> of those dependencies, `dep/bin`, if present, is added to the `PATH` environment variable.
 
-The dependency is propagated when it forces some of its other-transitive (non-immediate) downstream dependencies to also take it on as an immediate dependency. Nix itself already takes a package’s transitive dependencies into account, but this propagation ensures nixpkgs-specific infrastructure like setup hooks (mentioned above) also are run as if the propagated dependency.
+A dependency is said to be **propagated** when some of its other-transitive (non-immediate) downstream dependencies also need it as an immediate dependency.
+[^footnote-stdenv-propagated-dependencies]
 
-It is important to note that dependencies are not necessarily propagated as the same sort of dependency that they were before, but rather as the corresponding sort so that the platform rules still line up. The exact rules for dependency propagation can be given by assigning to each dependency two integers based one how its host and target platforms are offset from the depending derivation’s platforms. Those offsets are given below in the descriptions of each dependency list attribute. Algorithmically, we traverse propagated inputs, accumulating every propagated dependency’s propagated dependencies and adjusting them to account for the “shift in perspective” described by the current dependency’s platform offsets. This results in sort a transitive closure of the dependency relation, with the offsets being approximately summed when two dependency links are combined. We also prune transitive dependencies whose combined offsets go out-of-bounds, which can be viewed as a filter over that transitive closure removing dependencies that are blatantly absurd.
+It is important to note that dependencies are not necessarily propagated as the same sort of dependency that they were before, but rather as the corresponding sort so that the platform rules still line up. To determine the exact rules for dependency propagation, we start by assigning to each dependency a couple of ternary numbers (`-1` for `build`, `0` for `host`, and `1` for `target`), representing how respectively its host and target platforms are "offset" from the depending derivation’s platforms. The following table summarize the different combinations that can be obtained:
+
+| `host → target`     | attribute name      | offset   |
+| ------------------- | ------------------- | -------- |
+| `build --> build`   | `depsBuildBuild`    | `-1, -1` |
+| `build --> host`    | `nativeBuildInputs` | `-1, 0`  |
+| `build --> target`  | `depsBuildTarget`   | `-1, 1`  |
+| `host --> host`     | `depsHostHost`      | `0, 0`   |
+| `host --> target`   | `buildInputs`       | `0, 1`   |
+| `target --> target` | `depsTargetTarget`  | `1, 1`   |
+
+Algorithmically, we traverse propagated inputs, accumulating every propagated dependency’s propagated dependencies and adjusting them to account for the “shift in perspective” described by the current dependency’s platform offsets. This results is sort of a transitive closure of the dependency relation, with the offsets being approximately summed when two dependency links are combined. We also prune transitive dependencies whose combined offsets go out-of-bounds, which can be viewed as a filter over that transitive closure removing dependencies that are blatantly absurd.
 
 We can define the process precisely with [Natural Deduction](https://en.wikipedia.org/wiki/Natural_deduction) using the inference rules. This probably seems a bit obtuse, but so is the bash code that actually implements it! [^footnote-stdenv-find-inputs-location] They’re confusing in very different ways so… hopefully if something doesn’t make sense in one presentation, it will in the other!
 
@@ -179,37 +191,37 @@ Overall, the unifying theme here is that propagation shouldn’t be introducing
 
 #### `depsBuildBuild` {#var-stdenv-depsBuildBuild}
 
-A list of dependencies whose host and target platforms are the new derivation’s build platform. This means a `-1` host and `-1` target offset from the new derivation’s platforms. These are programs and libraries used at build time that produce programs and libraries also used at build time. If the dependency doesn’t care about the target platform (i.e. isn’t a compiler or similar tool), put it in `nativeBuildInputs` instead. The most common use of this `buildPackages.stdenv.cc`, the default C compiler for this role. That example crops up more than one might think in old commonly used C libraries.
+A list of dependencies whose host and target platforms are the new derivation’s build platform. These are programs and libraries used at build time that produce programs and libraries also used at build time. If the dependency doesn’t care about the target platform (i.e. isn’t a compiler or similar tool), put it in `nativeBuildInputs` instead. The most common use of this `buildPackages.stdenv.cc`, the default C compiler for this role. That example crops up more than one might think in old commonly used C libraries.
 
 Since these packages are able to be run at build-time, they are always added to the `PATH`, as described above. But since these packages are only guaranteed to be able to run then, they shouldn’t persist as run-time dependencies. This isn’t currently enforced, but could be in the future.
 
 #### `nativeBuildInputs` {#var-stdenv-nativeBuildInputs}
 
-A list of dependencies whose host platform is the new derivation’s build platform, and target platform is the new derivation’s host platform. This means a `-1` host offset and `0` target offset from the new derivation’s platforms. These are programs and libraries used at build-time that, if they are a compiler or similar tool, produce code to run at run-time—i.e. tools used to build the new derivation. If the dependency doesn’t care about the target platform (i.e. isn’t a compiler or similar tool), put it here, rather than in `depsBuildBuild` or `depsBuildTarget`. This could be called `depsBuildHost` but `nativeBuildInputs` is used for historical continuity.
+A list of dependencies whose host platform is the new derivation’s build platform, and target platform is the new derivation’s host platform. These are programs and libraries used at build-time that, if they are a compiler or similar tool, produce code to run at run-time—i.e. tools used to build the new derivation. If the dependency doesn’t care about the target platform (i.e. isn’t a compiler or similar tool), put it here, rather than in `depsBuildBuild` or `depsBuildTarget`. This could be called `depsBuildHost` but `nativeBuildInputs` is used for historical continuity.
 
 Since these packages are able to be run at build-time, they are added to the `PATH`, as described above. But since these packages are only guaranteed to be able to run then, they shouldn’t persist as run-time dependencies. This isn’t currently enforced, but could be in the future.
 
 #### `depsBuildTarget` {#var-stdenv-depsBuildTarget}
 
-A list of dependencies whose host platform is the new derivation’s build platform, and target platform is the new derivation’s target platform. This means a `-1` host offset and `1` target offset from the new derivation’s platforms. These are programs used at build time that produce code to run with code produced by the depending package. Most commonly, these are tools used to build the runtime or standard library that the currently-being-built compiler will inject into any code it compiles. In many cases, the currently-being-built-compiler is itself employed for that task, but when that compiler won’t run (i.e. its build and host platform differ) this is not possible. Other times, the compiler relies on some other tool, like binutils, that is always built separately so that the dependency is unconditional.
+A list of dependencies whose host platform is the new derivation’s build platform, and target platform is the new derivation’s target platform. These are programs used at build time that produce code to run with code produced by the depending package. Most commonly, these are tools used to build the runtime or standard library that the currently-being-built compiler will inject into any code it compiles. In many cases, the currently-being-built-compiler is itself employed for that task, but when that compiler won’t run (i.e. its build and host platform differ) this is not possible. Other times, the compiler relies on some other tool, like binutils, that is always built separately so that the dependency is unconditional.
 
-This is a somewhat confusing concept to wrap one’s head around, and for good reason. As the only dependency type where the platform offsets are not adjacent integers, it requires thinking of a bootstrapping stage *two* away from the current one. It and its use-case go hand in hand and are both considered poor form: try to not need this sort of dependency, and try to avoid building standard libraries and runtimes in the same derivation as the compiler produces code using them. Instead strive to build those like a normal library, using the newly-built compiler just as a normal library would. In short, do not use this attribute unless you are packaging a compiler and are sure it is needed.
+This is a somewhat confusing concept to wrap one’s head around, and for good reason. As the only dependency type where the platform offsets, `-1` and `1`, are not adjacent integers, it requires thinking of a bootstrapping stage *two* away from the current one. It and its use-case go hand in hand and are both considered poor form: try to not need this sort of dependency, and try to avoid building standard libraries and runtimes in the same derivation as the compiler produces code using them. Instead strive to build those like a normal library, using the newly-built compiler just as a normal library would. In short, do not use this attribute unless you are packaging a compiler and are sure it is needed.
 
 Since these packages are able to run at build time, they are added to the `PATH`, as described above. But since these packages are only guaranteed to be able to run then, they shouldn’t persist as run-time dependencies. This isn’t currently enforced, but could be in the future.
 
 #### `depsHostHost` {#var-stdenv-depsHostHost}
 
-A list of dependencies whose host and target platforms match the new derivation’s host platform. This means a `0` host offset and `0` target offset from the new derivation’s host platform. These are packages used at run-time to generate code also used at run-time. In practice, this would usually be tools used by compilers for macros or a metaprogramming system, or libraries used by the macros or metaprogramming code itself. It’s always preferable to use a `depsBuildBuild` dependency in the derivation being built over a `depsHostHost` on the tool doing the building for this purpose.
+A list of dependencies whose host and target platforms match the new derivation’s host platform. In practice, this would usually be tools used by compilers for macros or a metaprogramming system, or libraries used by the macros or metaprogramming code itself. It’s always preferable to use a `depsBuildBuild` dependency in the derivation being built over a `depsHostHost` on the tool doing the building for this purpose.
 
 #### `buildInputs` {#var-stdenv-buildInputs}
 
-A list of dependencies whose host platform and target platform match the new derivation’s. This means a `0` host offset and a `1` target offset from the new derivation’s host platform. This would be called `depsHostTarget` but for historical continuity. If the dependency doesn’t care about the target platform (i.e. isn’t a compiler or similar tool), put it here, rather than in `depsBuildBuild`.
+A list of dependencies whose host platform and target platform match the new derivation’s. This would be called `depsHostTarget` but for historical continuity. If the dependency doesn’t care about the target platform (i.e. isn’t a compiler or similar tool), put it here, rather than in `depsBuildBuild`.
 
 These are often programs and libraries used by the new derivation at *run*-time, but that isn’t always the case. For example, the machine code in a statically-linked library is only used at run-time, but the derivation containing the library is only needed at build-time. Even in the dynamic case, the library may also be needed at build-time to appease the linker.
 
 #### `depsTargetTarget` {#var-stdenv-depsTargetTarget}
 
-A list of dependencies whose host platform matches the new derivation’s target platform. This means a `1` offset from the new derivation’s platforms. These are packages that run on the target platform, e.g. the standard library or run-time deps of standard library that a compiler insists on knowing about. It’s poor form in almost all cases for a package to depend on another from a future stage \[future stage corresponding to positive offset\]. Do not use this attribute unless you are packaging a compiler and are sure it is needed.
+A list of dependencies whose host platform matches the new derivation’s target platform. These are packages that run on the target platform, e.g. the standard library or run-time deps of standard library that a compiler insists on knowing about. It’s poor form in almost all cases for a package to depend on another from a future stage \[future stage corresponding to positive offset\]. Do not use this attribute unless you are packaging a compiler and are sure it is needed.
 
 #### `depsBuildBuildPropagated` {#var-stdenv-depsBuildBuildPropagated}
 
@@ -784,7 +796,7 @@ The standard environment provides a number of useful functions.
 
 ### `makeWrapper` \<executable\> \<wrapperfile\> \<args\> {#fun-makeWrapper}
 
-Constructs a wrapper for a program with various possible arguments. For example:
+Constructs a wrapper for a program with various possible arguments. It is defined as part of 2 setup-hooks named `makeWrapper` and `makeBinaryWrapper` that implement the same bash functions. Hence, to use it you have to add `makeWrapper` to your `nativeBuildInputs`. Here's an example usage:
 
 ```bash
 # adds `FOOBAR=baz` to `$out/bin/foo`’s environment
@@ -796,9 +808,11 @@ makeWrapper $out/bin/foo $wrapperfile --set FOOBAR baz
 makeWrapper $out/bin/foo $wrapperfile --prefix PATH : ${lib.makeBinPath [ hello git ]}
 ```
 
-There’s many more kinds of arguments, they are documented in `nixpkgs/pkgs/build-support/setup-hooks/make-wrapper.sh`.
+There’s many more kinds of arguments, they are documented in `nixpkgs/pkgs/build-support/setup-hooks/make-wrapper.sh` for the `makeWrapper` implementation and in `nixpkgs/pkgs/build-support/setup-hooks/make-binary-wrapper.sh` for the `makeBinaryWrapper` implementation.
+
+`wrapProgram` is a convenience function you probably want to use most of the time, implemented by both `makeWrapper` and `makeBinaryWrapper`.
 
-`wrapProgram` is a convenience function you probably want to use most of the time.
+Using the `makeBinaryWrapper` implementation is usually preferred, as it creates a tiny _compiled_ wrapper executable, that can be used as a shebang interpreter. This is needed mostly on Darwin, where shebangs cannot point to scripts, [due to a limitation with the `execve`-syscall](https://stackoverflow.com/questions/67100831/macos-shebang-with-absolute-path-not-working). Compiled wrappers generated by `makeBinaryWrapper` can be inspected with `less <path-to-wrapper>` - by scrolling past the binary data you should be able to see the shell command that generated the executable and there see the environment variables that were injected into the wrapper.
 
 ### `substitute` \<infile\> \<outfile\> \<subs\> {#fun-substitute}
 
@@ -873,9 +887,9 @@ someVar=$(stripHash $name)
 
 ### `wrapProgram` \<executable\> \<makeWrapperArgs\> {#fun-wrapProgram}
 
-Convenience function for `makeWrapper` that automatically creates a sane wrapper file. It takes all the same arguments as `makeWrapper`, except for `--argv0`.
+Convenience function for `makeWrapper` that replaces `<\executable\>` with a wrapper that executes the original program. It takes all the same arguments as `makeWrapper`, except for `--inherit-argv0` (used by the `makeBinaryWrapper` implementation) and `--argv0` (used by both `makeWrapper` and `makeBinaryWrapper` wrapper implementations).
 
-It cannot be applied multiple times, since it will overwrite the wrapper file.
+If you will apply it multiple times, it will overwrite the wrapper file and you will end up with double wrapping, which should be avoided.
 
 ## Package setup hooks {#ssec-setup-hooks}
 
@@ -1228,6 +1242,7 @@ If the libraries lack `-fPIE`, you will get the error `recompile with -fPIE`.
 
 [^footnote-stdenv-ignored-build-platform]: The build platform is ignored because it is a mere implementation detail of the package satisfying the dependency: As a general programming principle, dependencies are always *specified* as interfaces, not concrete implementation.
 [^footnote-stdenv-native-dependencies-in-path]: Currently, this means for native builds all dependencies are put on the `PATH`. But in the future that may not be the case for sake of matching cross: the platforms would be assumed to be unique for native and cross builds alike, so only the `depsBuild*` and `nativeBuildInputs` would be added to the `PATH`.
+[^footnote-stdenv-propagated-dependencies]: Nix itself already takes a package’s transitive dependencies into account, but this propagation ensures nixpkgs-specific infrastructure like setup hooks (mentioned above) also are run as if the propagated dependency.
 [^footnote-stdenv-find-inputs-location]: The `findInputs` function, currently residing in `pkgs/stdenv/generic/setup.sh`, implements the propagation logic.
 [^footnote-stdenv-sys-lib-search-path]: It clears the `sys_lib_*search_path` variables in the Libtool script to prevent Libtool from using libraries in `/usr/lib` and such.
 [^footnote-stdenv-build-time-guessing-impurity]: Eventually these will be passed building natively as well, to improve determinism: build-time guessing, as is done today, is a risk of impurity.
diff --git a/nixpkgs/doc/using/overlays.chapter.md b/nixpkgs/doc/using/overlays.chapter.md
index d2e3b49a6aa9..df152bc14e7b 100644
--- a/nixpkgs/doc/using/overlays.chapter.md
+++ b/nixpkgs/doc/using/overlays.chapter.md
@@ -112,7 +112,7 @@ self: super:
 This overlay uses Intel's MKL library for both BLAS and LAPACK interfaces. Note that the same can be accomplished at runtime using `LD_LIBRARY_PATH` of `libblas.so.3` and `liblapack.so.3`. For instance:
 
 ```ShellSession
-$ LD_LIBRARY_PATH=$(nix-build -A mkl)/lib:$LD_LIBRARY_PATH nix-shell -p octave --run octave
+$ LD_LIBRARY_PATH=$(nix-build -A mkl)/lib${LD_LIBRARY_PATH:+:}$LD_LIBRARY_PATH nix-shell -p octave --run octave
 ```
 
 Intel MKL requires an `openmp` implementation when running with multiple processors. By default, `mkl` will use Intel's `iomp` implementation if no other is specified, but this is a runtime-only dependency and binary compatible with the LLVM implementation. To use that one instead, Intel recommends users set it with `LD_PRELOAD`. Note that `mkl` is only available on `x86_64-linux` and `x86_64-darwin`. Moreover, Hydra is not building and distributing pre-compiled binaries using it.