14 files changed, 220 insertions, 48 deletions

diff --git a/doc/builders/images/dockertools.section.md b/doc/builders/images/dockertools.section.md
index bfe1d17a606..7ff4b2aeb36 100644
--- a/doc/builders/images/dockertools.section.md
+++ b/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/doc/builders/trivial-builders.chapter.md b/doc/builders/trivial-builders.chapter.md
index 46620e1b459..c3a3572cd9f 100644
--- a/doc/builders/trivial-builders.chapter.md
+++ b/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/doc/functions/library/attrsets.xml b/doc/functions/library/attrsets.xml
index 9d36becd496..a30f4edf4c1 100644
--- a/doc/functions/library/attrsets.xml
+++ b/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/doc/languages-frameworks/beam.section.md b/doc/languages-frameworks/beam.section.md
index fb608932dfc..9b09d0329c5 100644
--- a/doc/languages-frameworks/beam.section.md
+++ b/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/doc/languages-frameworks/dhall.section.md b/doc/languages-frameworks/dhall.section.md
index d1adcbf736b..4b49908b0b0 100644
--- a/doc/languages-frameworks/dhall.section.md
+++ b/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/doc/languages-frameworks/dotnet.section.md b/doc/languages-frameworks/dotnet.section.md
index f2a5efd05db..159347008e8 100644
--- a/doc/languages-frameworks/dotnet.section.md
+++ b/doc/languages-frameworks/dotnet.section.md
@@ -71,8 +71,19 @@ 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`.
@@ -83,22 +94,29 @@ To package Dotnet applications, you can use `buildDotnetModule`. This has simila
 * `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`.
+* `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;
@@ -107,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/doc/languages-frameworks/gnome.section.md b/doc/languages-frameworks/gnome.section.md
index 11b49f4f235..29cb2e0e464 100644
--- a/doc/languages-frameworks/gnome.section.md
+++ b/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/doc/languages-frameworks/lua.section.md b/doc/languages-frameworks/lua.section.md
index 41fe0de04b4..17b80f07d3e 100644
--- a/doc/languages-frameworks/lua.section.md
+++ b/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/doc/languages-frameworks/ocaml.section.md b/doc/languages-frameworks/ocaml.section.md
index 5ffc23173d6..d266a032268 100644
--- a/doc/languages-frameworks/ocaml.section.md
+++ b/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/doc/languages-frameworks/python.section.md b/doc/languages-frameworks/python.section.md
index 53466921887..4d70409a20c 100644
--- a/doc/languages-frameworks/python.section.md
+++ b/doc/languages-frameworks/python.section.md
@@ -995,18 +995,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 +1632,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/doc/languages-frameworks/ruby.section.md b/doc/languages-frameworks/ruby.section.md
index 5e2f72ed61e..e29f97c566c 100644
--- a/doc/languages-frameworks/ruby.section.md
+++ b/doc/languages-frameworks/ruby.section.md
@@ -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/doc/languages-frameworks/rust.section.md b/doc/languages-frameworks/rust.section.md
index e7e804b9963..56faf636df1 100644
--- a/doc/languages-frameworks/rust.section.md
+++ b/doc/languages-frameworks/rust.section.md
@@ -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
@@ -261,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}
 
@@ -421,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
   `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`.
 
diff --git a/doc/languages-frameworks/vim.section.md b/doc/languages-frameworks/vim.section.md
index cb5311fc95f..4ffd6736e23 100644
--- a/doc/languages-frameworks/vim.section.md
+++ b/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/doc/stdenv/stdenv.chapter.md b/doc/stdenv/stdenv.chapter.md
index c108fffd1b0..6d72bd0deb4 100644
--- a/doc/stdenv/stdenv.chapter.md
+++ b/doc/stdenv/stdenv.chapter.md
@@ -796,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
@@ -808,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.
+`wrapProgram` is a convenience function you probably want to use most of the time, implemented by both `makeWrapper` and `makeBinaryWrapper`.
+
+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}
 
@@ -885,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}