Merge commit 'cfc75eec4603c06503ae750f88cf397e00796ea8'

Conflicts:
	nixpkgs/pkgs/build-support/rust/build-rust-package/default.nix

16 files changed, 223 insertions, 142 deletions

diff --git a/nixpkgs/doc/README.md b/nixpkgs/doc/README.md
index 03df6ad61138..3f9aff1a38a6 100644
--- a/nixpkgs/doc/README.md
+++ b/nixpkgs/doc/README.md
@@ -3,6 +3,7 @@
 This directory houses the sources files for the Nixpkgs manual.
 
 You can find the [rendered documentation for Nixpkgs `unstable` on nixos.org](https://nixos.org/manual/nixpkgs/unstable/).
+The rendering tool is [nixos-render-docs](../pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs), sometimes abbreviated `nrd`.
 
 [Docs for Nixpkgs stable](https://nixos.org/manual/nixpkgs/stable/) are also available.
 
diff --git a/nixpkgs/doc/builders/fetchers.chapter.md b/nixpkgs/doc/builders/fetchers.chapter.md
index 75a261db8dcd..ba7b1b190128 100644
--- a/nixpkgs/doc/builders/fetchers.chapter.md
+++ b/nixpkgs/doc/builders/fetchers.chapter.md
@@ -243,3 +243,26 @@ or
 
 ***
 ```
+## `fetchFromBittorrent` {#fetchfrombittorrent}
+
+`fetchFromBittorrent` expects two arguments. `url` which can either be a Magnet URI (Magnet Link) such as `magnet:?xt=urn:btih:dd8255ecdc7ca55fb0bbf81323d87062db1f6d1c` or an HTTP URL pointing to a `.torrent` file. It can also take a `config` argument which will craft a `settings.json` configuration file and give it to `transmission`, the underlying program that is performing the fetch. The available config options for `transmission` can be found [here](https://github.com/transmission/transmission/blob/main/docs/Editing-Configuration-Files.md#options)
+
+```
+{ fetchFromBittorrent }:
+
+fetchFromBittorrent {
+  config = { peer-limit-global = 100; };
+  url = "magnet:?xt=urn:btih:dd8255ecdc7ca55fb0bbf81323d87062db1f6d1c";
+  sha256 = "";
+}
+```
+
+### Parameters {#fetchfrombittorrent-parameters}
+
+- `url`: Magnet URI (Magnet Link) such as `magnet:?xt=urn:btih:dd8255ecdc7ca55fb0bbf81323d87062db1f6d1c` or an HTTP URL pointing to a `.torrent` file.
+
+- `backend`: Which bittorrent program to use. Default: `"transmission"`. Valid values are `"rqbit"` or `"transmission"`. These are the two most suitable torrent clients for fetching in a fixed-output derivation at the time of writing, as they can be easily exited after usage. `rqbit` is written in Rust and has a smaller closure size than `transmission`, and the performance and peer discovery properties differs between these clients, requiring experimentation to decide upon which is the best.
+
+- `config`: When using `transmission` as the `backend`, a json configuration can
+  be supplied to transmission. Refer to the [upstream documentation](https://github.com/transmission/transmission/blob/main/docs/Editing-Configuration-Files.md) for information on how to configure.
+
diff --git a/nixpkgs/doc/builders/special/darwin-builder.section.md b/nixpkgs/doc/builders/special/darwin-builder.section.md
index 13d01a0e3af8..e37fabe01a35 100644
--- a/nixpkgs/doc/builders/special/darwin-builder.section.md
+++ b/nixpkgs/doc/builders/special/darwin-builder.section.md
@@ -157,3 +157,17 @@ in the example below and rebuild.
 You may make any other changes to your VM in this attribute set. For example,
 you could enable Docker or X11 forwarding to your Darwin host.
 
+## Troubleshooting the generated configuration {#sec-darwin-builder-troubleshoot}
+
+The `linux-builder` package exposes the attributes `nixosConfig` and `nixosOptions` that allow you to inspect the generated NixOS configuration in the `nix repl`. For example:
+
+```
+$ nix repl --file ~/src/nixpkgs --argstr system aarch64-darwin
+
+nix-repl> darwin.linux-builder.nixosConfig.nix.package
+«derivation /nix/store/...-nix-2.17.0.drv»
+
+nix-repl> :p darwin.linux-builder.nixosOptions.virtualisation.memorySize.definitionsWithLocations
+[ { file = "/home/user/src/nixpkgs/nixos/modules/profiles/macos-builder.nix"; value = 3072; } ]
+
+```
diff --git a/nixpkgs/doc/hooks/mpi-check-hook.section.md b/nixpkgs/doc/hooks/mpi-check-hook.section.md
index e3fb5c40dada..586ee2cc7c2d 100644
--- a/nixpkgs/doc/hooks/mpi-check-hook.section.md
+++ b/nixpkgs/doc/hooks/mpi-check-hook.section.md
@@ -3,7 +3,7 @@
 
 This hook can be used to setup a check phase that
 requires running a MPI application. It detects the
-used present MPI implementaion type and exports
+used present MPI implementation type and exports
 the neceesary environment variables to use
 `mpirun` and `mpiexec` in a Nix sandbox.
 
diff --git a/nixpkgs/doc/languages-frameworks/dhall.section.md b/nixpkgs/doc/languages-frameworks/dhall.section.md
index 1a209dbc0680..7322a61687dd 100644
--- a/nixpkgs/doc/languages-frameworks/dhall.section.md
+++ b/nixpkgs/doc/languages-frameworks/dhall.section.md
@@ -303,11 +303,8 @@ You can use the `dhall-to-nixpkgs` command-line utility to automate
 packaging Dhall code.  For example:
 
 ```ShellSession
-$ nix-env --install --attr haskellPackages.dhall-nixpkgs
-
-$ nix-env --install --attr nix-prefetch-git  # Used by dhall-to-nixpkgs
-
-$ dhall-to-nixpkgs github https://github.com/Gabriella439/dhall-semver.git
+$ nix-shell -p haskellPackages.dhall-nixpkgs nix-prefetch-git
+[nix-shell]$ dhall-to-nixpkgs github https://github.com/Gabriella439/dhall-semver.git
 { buildDhallGitHubPackage, Prelude }:
   buildDhallGitHubPackage {
     name = "dhall-semver";
@@ -325,6 +322,10 @@ $ dhall-to-nixpkgs github https://github.com/Gabriella439/dhall-semver.git
     }
 ```
 
+:::{.note}
+`nix-prefetch-git` has to be in `$PATH` for `dhall-to-nixpkgs` to work.
+:::
+
 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:
diff --git a/nixpkgs/doc/languages-frameworks/dotnet.section.md b/nixpkgs/doc/languages-frameworks/dotnet.section.md
index 39e741618269..9ba0fef2a27b 100644
--- a/nixpkgs/doc/languages-frameworks/dotnet.section.md
+++ b/nixpkgs/doc/languages-frameworks/dotnet.section.md
@@ -161,7 +161,7 @@ in buildDotnetModule rec {
 They can be installed either as a global tool for the entire system, or as a local tool specific to project.
 
 The local installation is the easiest and works on NixOS in the same way as on other Linux distributions.
-[See dotnet documention](https://learn.microsoft.com/en-us/dotnet/core/tools/global-tools#install-a-local-tool) to learn more.
+[See dotnet documentation](https://learn.microsoft.com/en-us/dotnet/core/tools/global-tools#install-a-local-tool) to learn more.
 
 [The global installation method](https://learn.microsoft.com/en-us/dotnet/core/tools/global-tools#install-a-global-tool)
 should also work most of the time. You have to remember to update the `PATH`
diff --git a/nixpkgs/doc/languages-frameworks/haskell.section.md b/nixpkgs/doc/languages-frameworks/haskell.section.md
index 60972331840a..6b9ce32d1736 100644
--- a/nixpkgs/doc/languages-frameworks/haskell.section.md
+++ b/nixpkgs/doc/languages-frameworks/haskell.section.md
@@ -221,7 +221,7 @@ Sadly we currently don’t have tooling for this. For this you might be
 interested in the alternative [haskell.nix] framework, which, be warned, is
 completely incompatible with packages from `haskellPackages`.
 
-<!-- TODO(@maralorn) Link to package set generation docs in the contributers guide below. -->
+<!-- TODO(@maralorn) Link to package set generation docs in the contributors guide below. -->
 
 ## `haskellPackages.mkDerivation` {#haskell-mkderivation}
 
@@ -1029,7 +1029,7 @@ ugly, and we may want to deprecate them at some point. -->
 `disableCabalFlag flag drv`
 : Makes sure that the Cabal flag `flag` is disabled in Cabal's configure step.
 
-`appendBuildflags list drv`
+`appendBuildFlags list drv`
 : Adds the strings in `list` to the `buildFlags` argument for `drv`.
 
 <!-- TODO(@sternenseemann): removeConfigureFlag -->
@@ -1192,7 +1192,7 @@ with GHC), it is recommended to use overlays for Nixpkgs to change them.
 Since the interrelated parts, i.e. the package set and GHC, are connected
 via the Nixpkgs fixpoint, we need to modify them both in a way that preserves
 their connection (or else we'd have to wire it up again manually). This is
-achieved by changing GHC and the package set in seperate overlays to prevent
+achieved by changing GHC and the package set in separate overlays to prevent
 the package set from pulling in GHC from `prev`.
 
 The result is two overlays like the ones shown below. Adjustable parts are
diff --git a/nixpkgs/doc/languages-frameworks/javascript.section.md b/nixpkgs/doc/languages-frameworks/javascript.section.md
index fb1dd898c8a2..f35fd83cc594 100644
--- a/nixpkgs/doc/languages-frameworks/javascript.section.md
+++ b/nixpkgs/doc/languages-frameworks/javascript.section.md
@@ -161,6 +161,8 @@ git config --global url."https://github.com/".insteadOf git://github.com/
 
 `buildNpmPackage` allows you to package npm-based projects in Nixpkgs without the use of an auto-generated dependencies file (as used in [node2nix](#javascript-node2nix)). It works by utilizing npm's cache functionality -- creating a reproducible cache that contains the dependencies of a project, and pointing npm to it.
 
+Here's an example:
+
 ```nix
 { lib, buildNpmPackage, fetchFromGitHub }:
 
@@ -191,6 +193,8 @@ buildNpmPackage rec {
 }
 ```
 
+In the default `installPhase` set by `buildNpmPackage`, it uses `npm pack --json --dry-run` to decide what files to install in `$out/lib/node_modules/$name/`, where `$name` is the `name` string defined in the package's `package.json`. Additionally, the `bin` and `man` keys in the source's `package.json` are used to decide what binaries and manpages are supposed to be installed. If these are not defined, `npm pack` may miss some files, and no binaries will be produced.
+
 #### Arguments {#javascript-buildNpmPackage-arguments}
 
 * `npmDepsHash`: The output hash of the dependencies for this project. Can be calculated in advance with [`prefetch-npm-deps`](#javascript-buildNpmPackage-prefetch-npm-deps).
@@ -204,10 +208,11 @@ buildNpmPackage rec {
 * `npmBuildFlags`: Flags to pass to `npm run ${npmBuildScript}`.
 * `npmPackFlags`: Flags to pass to `npm pack`.
 * `npmPruneFlags`: Flags to pass to `npm prune`. Defaults to the value of `npmInstallFlags`.
+* `makeWrapperArgs`: Flags to pass to `makeWrapper`, added to executable calling the generated `.js` with `node` as an interpreter. These scripts are defined in `package.json`.
 
 #### prefetch-npm-deps {#javascript-buildNpmPackage-prefetch-npm-deps}
 
-`prefetch-npm-deps` can calculate the hash of the dependencies of an npm project ahead of time.
+`prefetch-npm-deps` is a Nixpkgs package that calculates the hash of the dependencies of an npm project ahead of time.
 
 ```console
 $ ls
@@ -217,6 +222,15 @@ $ prefetch-npm-deps package-lock.json
 sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
 ```
 
+#### fetchNpmDeps {#javascript-buildNpmPackage-fetchNpmDeps}
+
+`fetchNpmDeps` is a Nix function that requires the following mandatory arguments:
+
+- `src`: A directory / tarball with `package-lock.json` file
+- `hash`: The output hash of the node dependencies defined in `package-lock.json`.
+
+It returns a derivation with all `package-lock.json` dependencies downloaded into `$out/`, usable as an npm cache.
+
 ### corepack {#javascript-corepack}
 
 This package puts the corepack wrappers for pnpm and yarn in your PATH, and they will honor the `packageManager` setting in the `package.json`.
diff --git a/nixpkgs/doc/languages-frameworks/php.section.md b/nixpkgs/doc/languages-frameworks/php.section.md
index 2ca55aef1eff..377e3947b2a2 100644
--- a/nixpkgs/doc/languages-frameworks/php.section.md
+++ b/nixpkgs/doc/languages-frameworks/php.section.md
@@ -200,7 +200,7 @@ Internally, the helper operates in three stages:
    composer repository on the filesystem containing dependencies specified in
    `composer.json`. This process uses the function
    `php.mkComposerRepository` which in turn uses the
-   `php.composerHooks.composerRepositoryHook` hook. Internaly this function uses
+   `php.composerHooks.composerRepositoryHook` hook. Internally this function uses
    a custom
    [Composer plugin](https://github.com/nix-community/composer-local-repo-plugin) to
    generate the repository.
diff --git a/nixpkgs/doc/languages-frameworks/python.section.md b/nixpkgs/doc/languages-frameworks/python.section.md
index ca0513fbde83..40236d141d3d 100644
--- a/nixpkgs/doc/languages-frameworks/python.section.md
+++ b/nixpkgs/doc/languages-frameworks/python.section.md
@@ -32,8 +32,8 @@ Each interpreter has the following attributes:
 
 - `libPrefix`. Name of the folder in `${python}/lib/` for corresponding interpreter.
 - `interpreter`. Alias for `${python}/bin/${executable}`.
-- `buildEnv`. Function to build python interpreter environments with extra packages bundled together. See section *python.buildEnv function* for usage and documentation.
-- `withPackages`. Simpler interface to `buildEnv`. See section *python.withPackages function* for usage and documentation.
+- `buildEnv`. Function to build python interpreter environments with extra packages bundled together. See [](#python.buildenv-function) for usage and documentation.
+- `withPackages`. Simpler interface to `buildEnv`. See [](#python.withpackages-function) for usage and documentation.
 - `sitePackages`. Alias for `lib/${libPrefix}/site-packages`.
 - `executable`. Name of the interpreter executable, e.g. `python3.10`.
 - `pkgs`. Set of Python packages for that specific interpreter. The package set can be modified by overriding the interpreter and passing `packageOverrides`.
@@ -41,8 +41,8 @@ Each interpreter has the following attributes:
 ### Building packages and applications {#building-packages-and-applications}
 
 Python libraries and applications that use `setuptools` or
-`distutils` are typically built with respectively the `buildPythonPackage` and
-`buildPythonApplication` functions. These two functions also support installing a `wheel`.
+`distutils` are typically built with respectively the [`buildPythonPackage`](#buildpythonpackage-function) and
+[`buildPythonApplication`](#buildpythonapplication-function) functions. These two functions also support installing a `wheel`.
 
 All Python packages reside in `pkgs/top-level/python-packages.nix` and all
 applications elsewhere. In case a package is used as both a library and an
@@ -141,23 +141,23 @@ buildPythonPackage rec {
 
 The `buildPythonPackage` mainly does four things:
 
-* In the `buildPhase`, it calls `${python.pythonForBuild.interpreter} setup.py bdist_wheel` to
+* In the [`buildPhase`](#build-phase), it calls `${python.pythonForBuild.interpreter} setup.py bdist_wheel` to
   build a wheel binary zipfile.
-* In the `installPhase`, it installs the wheel file using `pip install *.whl`.
-* In the `postFixup` phase, the `wrapPythonPrograms` bash function is called to
+* In the [`installPhase`](#ssec-install-phase), it installs the wheel file using `pip install *.whl`.
+* In the [`postFixup`](#var-stdenv-postFixup) phase, the `wrapPythonPrograms` bash function is called to
   wrap all programs in the `$out/bin/*` directory to include `$PATH`
   environment variable and add dependent libraries to script's `sys.path`.
-* In the `installCheck` phase, `${python.interpreter} setup.py test` is run.
+* In the [`installCheck`](#ssec-installCheck-phase) phase, `${python.interpreter} setup.py test` is run.
 
-By default tests are run because `doCheck = true`. Test dependencies, like
-e.g. the test runner, should be added to `nativeCheckInputs`.
+By default tests are run because [`doCheck = true`](#var-stdenv-doCheck). Test dependencies, like
+e.g. the test runner, should be added to [`nativeCheckInputs`](#var-stdenv-nativeCheckInputs).
 
 By default `meta.platforms` is set to the same value
 as the interpreter unless overridden otherwise.
 
 ##### `buildPythonPackage` parameters {#buildpythonpackage-parameters}
 
-All parameters from `stdenv.mkDerivation` function are still supported. The
+All parameters from [`stdenv.mkDerivation`](#sec-using-stdenv) function are still supported. The
 following are specific to `buildPythonPackage`:
 
 * `catchConflicts ? true`: If `true`, abort package build if a package name
@@ -177,8 +177,8 @@ following are specific to `buildPythonPackage`:
   format. When unset, the legacy `setuptools` hooks are used for backwards
   compatibility.
 * `makeWrapperArgs ? []`: A list of strings. Arguments to be passed to
-  `makeWrapper`, which wraps generated binaries. By default, the arguments to
-  `makeWrapper` set `PATH` and `PYTHONPATH` environment variables before calling
+  [`makeWrapper`](#fun-makeWrapper), which wraps generated binaries. By default, the arguments to
+  [`makeWrapper`](#fun-makeWrapper) set `PATH` and `PYTHONPATH` environment variables before calling
   the binary. Additional arguments here can allow a developer to set environment
   variables which will be available when the binary is run. For example,
   `makeWrapperArgs = ["--set FOO BAR" "--set BAZ QUX"]`.
@@ -190,7 +190,7 @@ following are specific to `buildPythonPackage`:
 * `pipBuildFlags ? []`: A list of strings. Arguments to be passed to `pip wheel`.
 * `pypaBuildFlags ? []`: A list of strings. Arguments to be passed to `python -m build --wheel`.
 * `pythonPath ? []`: List of packages to be added into `$PYTHONPATH`. Packages
-  in `pythonPath` are not propagated (contrary to `propagatedBuildInputs`).
+  in `pythonPath` are not propagated (contrary to [`propagatedBuildInputs`](#var-stdenv-propagatedBuildInputs)).
 * `preShellHook`: Hook to execute commands before `shellHook`.
 * `postShellHook`: Hook to execute commands after `shellHook`.
 * `removeBinByteCode ? true`: Remove bytecode from `/bin`. Bytecode is only
@@ -198,7 +198,7 @@ following are specific to `buildPythonPackage`:
 * `setupPyGlobalFlags ? []`: List of flags passed to `setup.py` command.
 * `setupPyBuildFlags ? []`: List of flags passed to `setup.py build_ext` command.
 
-The `stdenv.mkDerivation` function accepts various parameters for describing
+The [`stdenv.mkDerivation`](#sec-using-stdenv) function accepts various parameters for describing
 build inputs (see "Specifying dependencies"). The following are of special
 interest for Python packages, either because these are primarily used, or
 because their behaviour is different:
@@ -208,8 +208,8 @@ because their behaviour is different:
 * `buildInputs ? []`: Build and/or run-time dependencies that need to be
   compiled for the host machine. Typically non-Python libraries which are being
   linked.
-* `nativeCheckInputs ? []`: Dependencies needed for running the `checkPhase`. These
-  are added to `nativeBuildInputs` when `doCheck = true`. Items listed in
+* `nativeCheckInputs ? []`: Dependencies needed for running the [`checkPhase`](#ssec-check-phase). These
+  are added to [`nativeBuildInputs`](#var-stdenv-nativeBuildInputs) when [`doCheck = true`](#var-stdenv-doCheck). Items listed in
   `tests_require` go here.
 * `propagatedBuildInputs ? []`: Aside from propagating dependencies,
   `buildPythonPackage` also injects code into and wraps executables with the
@@ -266,17 +266,17 @@ compilation issues, because scipy dependencies need to use the same blas impleme
 
 #### `buildPythonApplication` function {#buildpythonapplication-function}
 
-The `buildPythonApplication` function is practically the same as
-`buildPythonPackage`. The main purpose of this function is to build a Python
+The [`buildPythonApplication`](#buildpythonapplication-function) function is practically the same as
+[`buildPythonPackage`](#buildpythonpackage-function). The main purpose of this function is to build a Python
 package where one is interested only in the executables, and not importable
-modules. For that reason, when adding this package to a `python.buildEnv`, the
+modules. For that reason, when adding this package to a [`python.buildEnv`](#python.buildenv-function), the
 modules won't be made available.
 
-Another difference is that `buildPythonPackage` by default prefixes the names of
+Another difference is that [`buildPythonPackage`](#buildpythonpackage-function) by default prefixes the names of
 the packages with the version of the interpreter. Because this is irrelevant for
 applications, the prefix is omitted.
 
-When packaging a Python application with `buildPythonApplication`, it should be
+When packaging a Python application with [`buildPythonApplication`](#buildpythonapplication-function), it should be
 called with `callPackage` and passed `python` or `pythonPackages` (possibly
 specifying an interpreter version), like this:
 
@@ -329,7 +329,7 @@ package is used as both. In this case the package is added as a library to
 duplication the `toPythonApplication` can be used to convert a library to an
 application.
 
-The Nix expression shall use `buildPythonPackage` and be called from
+The Nix expression shall use [`buildPythonPackage`](#buildpythonpackage-function) and be called from
 `python-packages.nix`. A reference shall be created from `all-packages.nix` to
 the attribute in `python-packages.nix`, and the `toPythonApplication` shall be
 applied to the reference:
@@ -341,7 +341,7 @@ youtube-dl = with pythonPackages; toPythonApplication youtube-dl;
 #### `toPythonModule` function {#topythonmodule-function}
 
 In some cases, such as bindings, a package is created using
-`stdenv.mkDerivation` and added as attribute in `all-packages.nix`. The Python
+[`stdenv.mkDerivation`](#sec-using-stdenv) and added as attribute in `all-packages.nix`. The Python
 bindings should be made available from `python-packages.nix`. The
 `toPythonModule` function takes a derivation and makes certain Python-specific
 modifications.
@@ -407,9 +407,9 @@ specified packages in its path.
 
 #### `python.withPackages` function {#python.withpackages-function}
 
-The `python.withPackages` function provides a simpler interface to the `python.buildEnv` functionality.
+The [`python.withPackages`](#python.withpackages-function) function provides a simpler interface to the [`python.buildEnv`](#python.buildenv-function) functionality.
 It takes a function as an argument that is passed the set of python packages and returns the list
-of the packages to be included in the environment. Using the `withPackages` function, the previous
+of the packages to be included in the environment. Using the [`withPackages`](#python.withpackages-function) function, the previous
 example for the Pyramid Web Framework environment can be written like this:
 
 ```nix
@@ -418,7 +418,7 @@ with import <nixpkgs> {};
 python.withPackages (ps: [ ps.pyramid ])
 ```
 
-`withPackages` passes the correct package set for the specific interpreter
+[`withPackages`](#python.withpackages-function) passes the correct package set for the specific interpreter
 version as an argument to the function. In the above example, `ps` equals
 `pythonPackages`. But you can also easily switch to using python3:
 
@@ -430,7 +430,7 @@ python3.withPackages (ps: [ ps.pyramid ])
 
 Now, `ps` is set to `python3Packages`, matching the version of the interpreter.
 
-As `python.withPackages` simply uses `python.buildEnv` under the hood, it also
+As [`python.withPackages`](#python.withpackages-function) simply uses [`python.buildEnv`](#python.buildenv-function) under the hood, it also
 supports the `env` attribute. The `shell.nix` file from the previous section can
 thus be also written like this:
 
@@ -443,23 +443,22 @@ with import <nixpkgs> {};
 ])).env
 ```
 
-In contrast to `python.buildEnv`, `python.withPackages` does not support the
+In contrast to [`python.buildEnv`](#python.buildenv-function), [`python.withPackages`](#python.withpackages-function) does not support the
 more advanced options such as `ignoreCollisions = true` or `postBuild`. If you
-need them, you have to use `python.buildEnv`.
+need them, you have to use [`python.buildEnv`](#python.buildenv-function).
 
 Python 2 namespace packages may provide `__init__.py` that collide. In that case
-`python.buildEnv` should be used with `ignoreCollisions = true`.
+[`python.buildEnv`](#python.buildenv-function) should be used with `ignoreCollisions = true`.
 
 #### Setup hooks {#setup-hooks}
 
 The following are setup hooks specifically for Python packages. Most of these
-are used in `buildPythonPackage`.
+are used in [`buildPythonPackage`](#buildpythonpackage-function).
 
 - `eggUnpackhook` to move an egg to the correct folder so it can be installed
   with the `eggInstallHook`
 - `eggBuildHook` to skip building for eggs.
 - `eggInstallHook` to install eggs.
-- `flitBuildHook` to build a wheel using `flit`.
 - `pipBuildHook` to build a wheel using `pip` and PEP 517. Note a build system
   (e.g. `setuptools` or `flit`) should still be added as `nativeBuildInput`.
 - `pypaBuildHook` to build a wheel using
@@ -486,7 +485,7 @@ are used in `buildPythonPackage`.
 ### Development mode {#development-mode}
 
 Development or editable mode is supported. To develop Python packages
-`buildPythonPackage` has additional logic inside `shellPhase` to run `pip
+[`buildPythonPackage`](#buildpythonpackage-function) has additional logic inside `shellPhase` to run `pip
 install -e . --prefix $TMPDIR/`for the package.
 
 Warning: `shellPhase` is executed only if `setup.py` exists.
@@ -567,7 +566,7 @@ without impacting other applications or polluting your user environment.
 But Python libraries you would like to use for development cannot be installed,
 at least not individually, because they won't be able to find each other
 resulting in import errors. Instead, it is possible to create an environment
-with `python.buildEnv` or `python.withPackages` where the interpreter and other
+with [`python.buildEnv`](#python.buildenv-function) or [`python.withPackages`](#python.withpackages-function) where the interpreter and other
 executables are wrapped to be able to find each other and all of the modules.
 
 In the following examples we will start by creating a simple, ad-hoc environment
@@ -747,8 +746,8 @@ What's happening here?
    imports the `<nixpkgs>` function, `{}` calls it and the `with` statement
    brings all attributes of `nixpkgs` in the local scope. These attributes form
    the main package set.
-2. Then we create a Python 3.11 environment with the `withPackages` function, as before.
-3. The `withPackages` function expects us to provide a function as an argument
+2. Then we create a Python 3.11 environment with the [`withPackages`](#python.withpackages-function) function, as before.
+3. The [`withPackages`](#python.withpackages-function) function expects us to provide a function as an argument
    that takes the set of all Python packages and returns a list of packages to
    include in the environment. Here, we select the packages `numpy` and `toolz`
    from the package set.
@@ -859,7 +858,7 @@ we will look at how you can use development mode with your code.
 #### Python library packages in Nixpkgs {#python-library-packages-in-nixpkgs}
 
 With Nix all packages are built by functions. The main function in Nix for
-building Python libraries is `buildPythonPackage`. Let's see how we can build the
+building Python libraries is [`buildPythonPackage`](#buildpythonpackage-function). Let's see how we can build the
 `toolz` package.
 
 ```nix
@@ -904,13 +903,13 @@ buildPythonPackage rec {
 }
 ```
 
-What happens here? The function `buildPythonPackage` is called and as argument
+What happens here? The function [`buildPythonPackage`](#buildpythonpackage-function) is called and as argument
 it accepts a set. In this case the set is a recursive set, `rec`. One of the
 arguments is the name of the package, which consists of a basename (generally
 following the name on PyPi) and a version. Another argument, `src` specifies the
 source, which in this case is fetched from PyPI using the helper function
 `fetchPypi`. The argument `doCheck` is used to set whether tests should be run
-when building the package. Since there are no tests, we rely on `pythonImportsCheck`
+when building the package. Since there are no tests, we rely on [`pythonImportsCheck`](#using-pythonimportscheck)
 to test whether the package can be imported. Furthermore, we specify some meta
 information. The output of the function is a derivation.
 
@@ -969,7 +968,7 @@ for which Python version we want to build a package.
 So, what did we do here? Well, we took the Nix expression that we used earlier
 to build a Python environment, and said that we wanted to include our own
 version of `toolz`, named `my_toolz`. To introduce our own package in the scope
-of `withPackages` we used a `let` expression. You can see that we used
+of [`withPackages`](#python.withpackages-function) we used a `let` expression. You can see that we used
 `ps.numpy` to select numpy from the nixpkgs package set (`ps`). We did not take
 `toolz` from the Nixpkgs package set this time, but instead took our own version
 that we introduced with the `let` expression.
@@ -977,14 +976,14 @@ that we introduced with the `let` expression.
 #### Handling dependencies {#handling-dependencies}
 
 Our example, `toolz`, does not have any dependencies on other Python packages or
-system libraries. According to the manual, `buildPythonPackage` uses the
-arguments `buildInputs` and `propagatedBuildInputs` to specify dependencies. If
+system libraries. According to the manual, [`buildPythonPackage`](#buildpythonpackage-function) uses the
+arguments [`buildInputs`](#var-stdenv-buildInputs) and [`propagatedBuildInputs`](#var-stdenv-propagatedBuildInputs) to specify dependencies. If
 something is exclusively a build-time dependency, then the dependency should be
-included in `buildInputs`, but if it is (also) a runtime dependency, then it
-should be added to `propagatedBuildInputs`. Test dependencies are considered
-build-time dependencies and passed to `nativeCheckInputs`.
+included in [`buildInputs`](#var-stdenv-buildInputs), but if it is (also) a runtime dependency, then it
+should be added to [`propagatedBuildInputs`](#var-stdenv-propagatedBuildInputs). Test dependencies are considered
+build-time dependencies and passed to [`nativeCheckInputs`](#var-stdenv-nativeCheckInputs).
 
-The following example shows which arguments are given to `buildPythonPackage` in
+The following example shows which arguments are given to [`buildPythonPackage`](#buildpythonpackage-function) in
 order to build [`datashape`](https://github.com/blaze/datashape).
 
 ```nix
@@ -1038,14 +1037,14 @@ buildPythonPackage rec {
 ```
 
 We can see several runtime dependencies, `numpy`, `multipledispatch`, and
-`python-dateutil`. Furthermore, we have `nativeCheckInputs` with `pytest`.
-`pytest` is a test runner and is only used during the `checkPhase` and is
-therefore not added to `propagatedBuildInputs`.
+`python-dateutil`. Furthermore, we have [`nativeCheckInputs`](#var-stdenv-nativeCheckInputs) with `pytest`.
+`pytest` is a test runner and is only used during the [`checkPhase`](#ssec-check-phase) and is
+therefore not added to [`propagatedBuildInputs`](#var-stdenv-propagatedBuildInputs).
 
 In the previous case we had only dependencies on other Python packages to consider.
 Occasionally you have also system libraries to consider. E.g., `lxml` provides
 Python bindings to `libxml2` and `libxslt`. These libraries are only required
-when building the bindings and are therefore added as `buildInputs`.
+when building the bindings and are therefore added as [`buildInputs`](#var-stdenv-buildInputs).
 
 ```nix
 { lib
@@ -1093,7 +1092,7 @@ files of the dependencies are. This is not always the case.
 The example below shows bindings to The Fastest Fourier Transform in the West,
 commonly known as FFTW. On Nix we have separate packages of FFTW for the
 different types of floats (`"single"`, `"double"`, `"long-double"`). The
-bindings need all three types, and therefore we add all three as `buildInputs`.
+bindings need all three types, and therefore we add all three as [`buildInputs`](#var-stdenv-buildInputs).
 The bindings don't expect to find each of them in a different folder, and
 therefore we have to set `LDFLAGS` and `CFLAGS`.
 
@@ -1158,7 +1157,7 @@ buildPythonPackage rec {
 }
 ```
 
-Note also the line `doCheck = false;`, we explicitly disabled running the test-suite.
+Note also the line [`doCheck = false;`](#var-stdenv-doCheck), we explicitly disabled running the test-suite.
 
 #### Testing Python Packages {#testing-python-packages}
 
@@ -1167,10 +1166,10 @@ helps to avoid situations where the package was able to build and install,
 but is not usable at runtime. Currently, all packages will use the `test`
 command provided by the setup.py (i.e. `python setup.py test`). However,
 this is currently deprecated https://github.com/pypa/setuptools/pull/1878
-and your package should provide its own checkPhase.
+and your package should provide its own [`checkPhase`](#ssec-check-phase).
 
 ::: {.note}
-The `checkPhase` for python maps to the `installCheckPhase` on a
+The [`checkPhase`](#ssec-check-phase) for python maps to the `installCheckPhase` on a
 normal derivation. This is due to many python packages not behaving well
 to the pre-installed version of the package. Version info, and natively
 compiled extensions generally only exist in the install directory, and
@@ -1235,7 +1234,7 @@ been removed, in this case, it's recommended to use `pytestCheckHook`.
 #### Using pytestCheckHook {#using-pytestcheckhook}
 
 `pytestCheckHook` is a convenient hook which will substitute the setuptools
-`test` command for a `checkPhase` which runs `pytest`. This is also beneficial
+`test` command for a [`checkPhase`](#ssec-check-phase) which runs `pytest`. This is also beneficial
 when a package may need many items disabled to run the test suite.
 
 Using the example above, the analogous `pytestCheckHook` usage would be:
@@ -1280,14 +1279,14 @@ for example:
 ```
 
 Trying to concatenate the related strings to disable tests in a regular
-`checkPhase` would be much harder to read. This also enables us to comment on
+[`checkPhase`](#ssec-check-phase) would be much harder to read. This also enables us to comment on
 why specific tests are disabled.
 
 #### Using pythonImportsCheck {#using-pythonimportscheck}
 
 Although unit tests are highly preferred to validate correctness of a package, not
 all packages have test suites that can be run easily, and some have none at all.
-To help ensure the package still works, `pythonImportsCheck` can attempt to import
+To help ensure the package still works, [`pythonImportsCheck`](#using-pythonimportscheck) can attempt to import
 the listed modules.
 
 ```
@@ -1306,7 +1305,7 @@ roughly translates to:
   '';
 ```
 
-However, this is done in its own phase, and not dependent on whether `doCheck = true;`.
+However, this is done in its own phase, and not dependent on whether [`doCheck = true;`](#var-stdenv-doCheck).
 
 This can also be useful in verifying that the package doesn't assume commonly
 present packages (e.g. `setuptools`).
@@ -1378,11 +1377,11 @@ instead of a dev dependency).
 
 Keep in mind that while the examples above are done with `requirements.txt`,
 `pythonRelaxDepsHook` works by modifying the resulting wheel file, so it should
-work with any of the existing [hooks](#setup-hooks).
+work with any of the [existing hooks](#setup-hooks).
 
 #### Using unittestCheckHook {#using-unittestcheckhook}
 
-`unittestCheckHook` is a hook which will substitute the setuptools `test` command for a `checkPhase` which runs `python -m unittest discover`:
+`unittestCheckHook` is a hook which will substitute the setuptools `test` command for a [`checkPhase`](#ssec-check-phase) which runs `python -m unittest discover`:
 
 ```
   nativeCheckInputs = [
@@ -1452,15 +1451,15 @@ mode is also available. Let's see how you can use it.
 In the previous Nix expression the source was fetched from a url. We can also
 refer to a local source instead using `src = ./path/to/source/tree;`
 
-If we create a `shell.nix` file which calls `buildPythonPackage`, and if `src`
+If we create a `shell.nix` file which calls [`buildPythonPackage`](#buildpythonpackage-function), and if `src`
 is a local source, and if the local source has a `setup.py`, then development
 mode is activated.
 
 In the following example, we create a simple environment that has a Python 3.11
 version of our package in it, as well as its dependencies and other packages we
-like to have in the environment, all specified with `propagatedBuildInputs`.
+like to have in the environment, all specified with [`propagatedBuildInputs`](#var-stdenv-propagatedBuildInputs).
 Indeed, we can just add any package we like to have in our environment to
-`propagatedBuildInputs`.
+[`propagatedBuildInputs`](#var-stdenv-propagatedBuildInputs).
 
 ```nix
 with import <nixpkgs> {};
@@ -1494,7 +1493,7 @@ own packages. The important functions here are `import` and `callPackage`.
 
 ### Including a derivation using `callPackage` {#including-a-derivation-using-callpackage}
 
-Earlier we created a Python environment using `withPackages`, and included the
+Earlier we created a Python environment using [`withPackages`](#python.withpackages-function), and included the
 `toolz` package via a `let` expression.
 Let's split the package definition from the environment definition.
 
@@ -1533,7 +1532,7 @@ buildPythonPackage rec {
 }
 ```
 
-It takes an argument `buildPythonPackage`. We now call this function using
+It takes an argument [`buildPythonPackage`](#buildpythonpackage-function). We now call this function using
 `callPackage` in the definition of our environment
 
 ```nix
@@ -1552,10 +1551,10 @@ Packages.buildPythonPackage;
 ```
 
 Important to remember is that the Python version for which the package is made
-depends on the `python` derivation that is passed to `buildPythonPackage`. Nix
+depends on the `python` derivation that is passed to [`buildPythonPackage`](#buildpythonpackage-function). Nix
 tries to automatically pass arguments when possible, which is why generally you
 don't explicitly define which `python` derivation should be used. In the above
-example we use `buildPythonPackage` that is part of the set `python3Packages`,
+example we use [`buildPythonPackage`](#buildpythonpackage-function) that is part of the set `python3Packages`,
 and in this case the `python3` interpreter is automatically used.
 
 ## FAQ {#faq}
@@ -1698,7 +1697,7 @@ Python, guarantees the right versions of the interpreter and libraries or
 packages are available. There is therefore no need to maintain a global `site-packages`.
 
 If you want to create a Python environment for development, then the recommended
-method is to use `nix-shell`, either with or without the `python.buildEnv`
+method is to use `nix-shell`, either with or without the [`python.buildEnv`](#python.buildenv-function)
 function.
 
 ### How to consume Python modules using pip in a virtual environment like I am used to on other Operating Systems? {#how-to-consume-python-modules-using-pip-in-a-virtual-environment-like-i-am-used-to-on-other-operating-systems}
@@ -1875,7 +1874,7 @@ self: super: {
 
 ### How to override a Python package for all Python versions using extensions? {#how-to-override-a-python-package-for-all-python-versions-using-extensions}
 
-The following overlay overrides the call to `buildPythonPackage` for the
+The following overlay overrides the call to [`buildPythonPackage`](#buildpythonpackage-function) for the
 `foo` package for all interpreters by appending a Python extension to the
 `pythonPackagesExtensions` list of extensions.
 
@@ -1902,9 +1901,9 @@ configure alternatives](#sec-overlays-alternatives-blas-lapack)".
 
 In a `setup.py` or `setup.cfg` it is common to declare dependencies:
 
-* `setup_requires` corresponds to `nativeBuildInputs`
-* `install_requires` corresponds to `propagatedBuildInputs`
-* `tests_require` corresponds to `nativeCheckInputs`
+* `setup_requires` corresponds to [`nativeBuildInputs`](#var-stdenv-nativeBuildInputs)
+* `install_requires` corresponds to [`propagatedBuildInputs`](#var-stdenv-propagatedBuildInputs)
+* `tests_require` corresponds to [`nativeCheckInputs`](#var-stdenv-nativeCheckInputs)
 
 ### How to enable interpreter optimizations? {#optimizations}
 
@@ -1951,7 +1950,7 @@ collisions.
 
 ### How to contribute a Python package to nixpkgs? {#tools}
 
-Packages inside nixpkgs must use the `buildPythonPackage` or `buildPythonApplication` function directly,
+Packages inside nixpkgs must use the [`buildPythonPackage`](#buildpythonpackage-function) or [`buildPythonApplication`](#buildpythonapplication-function) function directly,
 because we can only provide security support for non-vendored dependencies.
 
 We recommend [nix-init](https://github.com/nix-community/nix-init) for creating new python packages within nixpkgs,
@@ -1965,7 +1964,7 @@ has security implications and is relevant for those using Python in a
 `nix-shell`.
 
 When the environment variable `DETERMINISTIC_BUILD` is set, all bytecode will
-have timestamp 1. The `buildPythonPackage` function sets `DETERMINISTIC_BUILD=1`
+have timestamp 1. The [`buildPythonPackage`](#buildpythonpackage-function) function sets `DETERMINISTIC_BUILD=1`
 and [PYTHONHASHSEED=0](https://docs.python.org/3.11/using/cmdline.html#envvar-PYTHONHASHSEED).
 Both are also exported in `nix-shell`.
 
@@ -1975,12 +1974,12 @@ It is recommended to test packages as part of the build process.
 Source distributions (`sdist`) often include test files, but not always.
 
 By default the command `python setup.py test` is run as part of the
-`checkPhase`, but often it is necessary to pass a custom `checkPhase`. An
+[`checkPhase`](#ssec-check-phase), but often it is necessary to pass a custom [`checkPhase`](#ssec-check-phase). An
 example of such a situation is when `py.test` is used.
 
 #### Common issues {#common-issues}
 
-* Non-working tests can often be deselected. By default `buildPythonPackage`
+* Non-working tests can often be deselected. By default [`buildPythonPackage`](#buildpythonpackage-function)
   runs `python setup.py test`. which is deprecated. Most Python modules however
   do follow the standard test protocol where the pytest runner can be used
   instead. `pytest` supports the `-k` and `--ignore` parameters to ignore test
@@ -2015,10 +2014,10 @@ example of such a situation is when `py.test` is used.
 The following rules are desired to be respected:
 
 * Python libraries are called from `python-packages.nix` and packaged with
-  `buildPythonPackage`. The expression of a library should be in
+  [`buildPythonPackage`](#buildpythonpackage-function). The expression of a library should be in
   `pkgs/development/python-modules/<name>/default.nix`.
 * Python applications live outside of `python-packages.nix` and are packaged
-  with `buildPythonApplication`.
+  with [`buildPythonApplication`](#buildpythonapplication-function).
 * Make sure libraries build for all Python interpreters.
 * By default we enable tests. Make sure the tests are found and, in the case of
   libraries, are passing for all interpreters. If certain tests fail they can be
diff --git a/nixpkgs/doc/languages-frameworks/rust.section.md b/nixpkgs/doc/languages-frameworks/rust.section.md
index 67e23cc74d4e..3bd8e1c76512 100644
--- a/nixpkgs/doc/languages-frameworks/rust.section.md
+++ b/nixpkgs/doc/languages-frameworks/rust.section.md
@@ -817,7 +817,7 @@ $ cargo test
 ## Using community maintained Rust toolchains {#using-community-maintained-rust-toolchains}
 
 ::: {.note}
-Note: The following projects cannot be used within nixpkgs since [IFD](#ssec-import-from-derivation) is disallowed.
+The following projects cannot be used within Nixpkgs since [Import From Derivation](https://nixos.org/manual/nix/unstable/language/import-from-derivation) (IFD) is disallowed in Nixpkgs.
 To package things that require Rust nightly, `RUSTC_BOOTSTRAP = true;` can sometimes be used as a hack.
 :::
 
diff --git a/nixpkgs/doc/languages-frameworks/vim.section.md b/nixpkgs/doc/languages-frameworks/vim.section.md
index bf0d663179b9..1f3727f552c8 100644
--- a/nixpkgs/doc/languages-frameworks/vim.section.md
+++ b/nixpkgs/doc/languages-frameworks/vim.section.md
@@ -134,7 +134,7 @@ If one of your favourite plugins isn't packaged, you can package it yourself:
 { config, pkgs, ... }:
 
 let
-  easygrep = pkgs.vimUtils.buildVimPluginFrom2Nix {
+  easygrep = pkgs.vimUtils.buildVimPlugin {
     name = "vim-easygrep";
     src = pkgs.fetchFromGitHub {
       owner = "dkprice";
@@ -212,9 +212,9 @@ Note: this is not possible anymore for Neovim.
 
 ## Adding new plugins to nixpkgs {#adding-new-plugins-to-nixpkgs}
 
-Nix expressions for Vim plugins are stored in [pkgs/applications/editors/vim/plugins](https://github.com/NixOS/nixpkgs/tree/master/pkgs/applications/editors/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/applications/editors/vim/plugins/update.py). This creates a [generated.nix](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/editors/vim/plugins/generated.nix) file based on the plugins listed in [vim-plugin-names](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/editors/vim/plugins/vim-plugin-names).
+Nix expressions for Vim plugins are stored in [pkgs/applications/editors/vim/plugins](https://github.com/NixOS/nixpkgs/tree/master/pkgs/applications/editors/vim/plugins). For the vast majority of plugins, Nix expressions are automatically generated by running [`nix-shell -p vimPluginsUpdater --run vim-plugins-updater`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/editors/vim/plugins/updater.nix). This creates a [generated.nix](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/editors/vim/plugins/generated.nix) file based on the plugins listed in [vim-plugin-names](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/editors/vim/plugins/vim-plugin-names).
 
-After running `./update.py`, if nvim-treesitter received an update, also run [`nvim-treesitter/update.py`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/editors/vim/plugins/update.py) to update the tree sitter grammars for `nvim-treesitter`.
+After running the updater, if nvim-treesitter received an update, also run [`nvim-treesitter/update.py`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/editors/vim/plugins/update.py) to update the tree sitter grammars for `nvim-treesitter`.
 
 Some plugins require overrides in order to function properly. Overrides are placed in [overrides.nix](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/editors/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:
 
@@ -241,7 +241,8 @@ GITHUB_API_TOKEN=my_token ./pkgs/applications/editors/vim/plugins/update.py
 Alternatively, set the number of processes to a lower count to avoid rate-limiting.
 
 ```sh
-./pkgs/applications/editors/vim/plugins/update.py --proc 1
+
+nix-shell -p vimPluginsUpdater --run 'vim-plugins-updater --proc 1'
 ```
 
 ## How to maintain an out-of-tree overlay of vim plugins ? {#vim-out-of-tree-overlays}
@@ -250,7 +251,7 @@ You can use the updater script to generate basic packages out of a custom vim
 plugin list:
 
 ```
-pkgs/applications/editors/vim/plugins/update.py -i vim-plugin-names -o generated.nix --no-commit
+nix-shell -p vimPluginsUpdater --run vim-plugins-updater -i vim-plugin-names -o generated.nix --no-commit
 ```
 
 with the contents of `vim-plugin-names` being for example:
@@ -264,7 +265,7 @@ You can then reference the generated vim plugins via:
 
 ```nix
 myVimPlugins = pkgs.vimPlugins.extend (
-  (pkgs.callPackage generated.nix {})
+  (pkgs.callPackage ./generated.nix {})
 );
 ```
 
diff --git a/nixpkgs/doc/stdenv/multiple-output.chapter.md b/nixpkgs/doc/stdenv/multiple-output.chapter.md
index c19d497ab61e..1ee063c0c2f4 100644
--- a/nixpkgs/doc/stdenv/multiple-output.chapter.md
+++ b/nixpkgs/doc/stdenv/multiple-output.chapter.md
@@ -1,7 +1,5 @@
 # Multiple-output packages {#chap-multiple-output}
 
-## Introduction {#sec-multiple-outputs-introduction}
-
 The Nix language allows a derivation to produce multiple outputs, which is similar to what is utilized by other Linux distribution packaging systems. The outputs reside in separate Nix store paths, so they can be mostly handled independently of each other, including passing to build inputs, garbage collection or binary substitution. The exception is that building from source always produces all the outputs.
 
 The main motivation is to save disk space by reducing runtime closure sizes; consequently also sizes of substituted binaries get reduced. Splitting can be used to have more granular runtime dependencies, for example the typical reduction is to split away development-only files, as those are typically not needed during runtime. As a result, closure sizes of many packages can get reduced to a half or even much less.
@@ -10,44 +8,12 @@ The main motivation is to save disk space by reducing runtime closure sizes; con
 The reduction effects could be instead achieved by building the parts in completely separate derivations. That would often additionally reduce build-time closures, but it tends to be much harder to write such derivations, as build systems typically assume all parts are being built at once. This compromise approach of single source package producing multiple binary packages is also utilized often by rpm and deb.
 :::
 
-A number of attributes can be used to work with a derivation with multiple outputs. The attribute `outputs` is a list of strings, which are the names of the outputs. For each of these names, an identically named attribute is created, corresponding to that output. The attribute `meta.outputsToInstall` is used to determine the default set of outputs to install when using the derivation name unqualified.
-
-## Installing a split package {#sec-multiple-outputs-installing}
-
-When installing a package with multiple outputs, the package’s `meta.outputsToInstall` attribute determines which outputs are actually installed. `meta.outputsToInstall` is a list whose [default installs binaries and the associated man pages](https://github.com/NixOS/nixpkgs/blob/f1680774340d5443a1409c3421ced84ac1163ba9/pkgs/stdenv/generic/make-derivation.nix#L310-L320). The following sections describe ways to install different outputs.
-
-### Selecting outputs to install via NixOS {#sec-multiple-outputs-installing-nixos}
-
-NixOS provides two ways to select the outputs to install for packages listed in `environment.systemPackages`:
-
-- The configuration option `environment.extraOutputsToInstall` is appended to each package’s `meta.outputsToInstall` attribute to determine the outputs to install. It can for example be used to install `info` documentation or debug symbols for all packages.
-
-- The outputs can be listed as packages in `environment.systemPackages`. For example, the `"out"` and `"info"` outputs for the `coreutils` package can be installed by including `coreutils` and `coreutils.info` in `environment.systemPackages`.
-
-### Selecting outputs to install via `nix-env` {#sec-multiple-outputs-installing-nix-env}
-
-`nix-env` lacks an easy way to select the outputs to install. When installing a package, `nix-env` always installs the outputs listed in `meta.outputsToInstall`, even when the user explicitly selects an output.
+A number of attributes can be used to work with a derivation with multiple outputs.
+The attribute `outputs` is a list of strings, which are the names of the outputs.
+For each of these names, an identically named attribute is created, corresponding to that output.
 
-::: {.warning}
-`nix-env` silently disregards the outputs selected by the user, and instead installs the outputs from `meta.outputsToInstall`. For example,
-
-```ShellSession
-$ nix-env -iA nixpkgs.coreutils.info
-```
-
-installs the `"out"` output (`coreutils.meta.outputsToInstall` is `[ "out" ]`) instead of the requested `"info"`.
-:::
-
-The only recourse to select an output with `nix-env` is to override the package’s `meta.outputsToInstall`, using the functions described in [](#chap-overrides). For example, the following overlay adds the `"info"` output for the `coreutils` package:
-
-```nix
-self: super:
-{
-  coreutils = super.coreutils.overrideAttrs (oldAttrs: {
-    meta = oldAttrs.meta // { outputsToInstall = oldAttrs.meta.outputsToInstall or [ "out" ] ++ [ "info" ]; };
-  });
-}
-```
+The attribute `meta.outputsToInstall` is used to determine the [default set of outputs to install](https://github.com/NixOS/nixpkgs/blob/08c3198f1c6fd89a09f8f0ea09b425028a34de3e/pkgs/stdenv/generic/check-meta.nix#L411-L426) when using the derivation name unqualified:
+`bin`, or `out`, or the first specified output; as well as `man` if that is specified.
 
 ## Using a split package {#sec-multiple-outputs-using-split-packages}
 
diff --git a/nixpkgs/doc/stdenv/stdenv.chapter.md b/nixpkgs/doc/stdenv/stdenv.chapter.md
index 15cb081a04e2..366c519751c0 100644
--- a/nixpkgs/doc/stdenv/stdenv.chapter.md
+++ b/nixpkgs/doc/stdenv/stdenv.chapter.md
@@ -991,13 +991,56 @@ Hook executed at the end of the fixup phase.
 
 If set to `true`, the standard environment will enable debug information in C/C++ builds. After installation, the debug information will be separated from the executables and stored in the output named `debug`. (This output is enabled automatically; you don’t need to set the `outputs` attribute explicitly.) To be precise, the debug information is stored in `debug/lib/debug/.build-id/XX/YYYY…`, where \<XXYYYY…\> is the \<build ID\> of the binary — a SHA-1 hash of the contents of the binary. Debuggers like GDB use the build ID to look up the separated debug information.
 
-For example, with GDB, you can add
+:::{.example #ex-gdb-debug-symbols-socat}
 
+# Enable debug symbols for use with GDB
+
+To make GDB find debug information for the `socat` package and its dependencies, you can use the following `shell.nix`:
+
+```nix
+let
+  pkgs = import ./. {
+    config = {};
+    overlays = [
+      (final: prev: {
+        ncurses = prev.ncurses.overrideAttrs { separateDebugInfo = true; };
+        readline = prev.readline.overrideAttrs { separateDebugInfo = true; };
+      })
+    ];
+  };
+
+  myDebugInfoDirs = pkgs.symlinkJoin {
+    name = "myDebugInfoDirs";
+    paths = with pkgs; [
+      glibc.debug
+      ncurses.debug
+      openssl.debug
+      readline.debug
+    ];
+  };
+in
+  pkgs.mkShell {
+
+    NIX_DEBUG_INFO_DIRS = "${pkgs.lib.getLib myDebugInfoDirs}/lib/debug";
+
+    packages = [
+      pkgs.gdb
+      pkgs.socat
+    ];
+
+    shellHook = ''
+      ${pkgs.lib.getBin pkgs.gdb}/bin/gdb ${pkgs.lib.getBin pkgs.socat}/bin/socat
+    '';
+  }
 ```
-set debug-file-directory ~/.nix-profile/lib/debug
-```
 
-to `~/.gdbinit`. GDB will then be able to find debug information installed via `nix-env -i`.
+This setup works as follows:
+- Add [`overlays`](#chap-overlays) to the package set, since debug symbols are disabled for `ncurses` and `readline` by default.
+- Create a derivation to combine all required debug symbols under one path with [`symlinkJoin`](#trivial-builder-symlinkJoin).
+- Set the environment variable `NIX_DEBUG_INFO_DIRS` in the shell. Nixpkgs patches `gdb` to use it for looking up debug symbols.
+- Run `gdb` on the `socat` binary on shell startup in the [`shellHook`](#sec-pkgs-mkShell). Here we use [`lib.getBin`](#function-library-lib.attrsets.getBin) to ensure that the correct derivation output is selected rather than the default one.
+
+:::
 
 ### The installCheck phase {#ssec-installCheck-phase}
 
@@ -1478,7 +1521,7 @@ This flag can break dynamic shared object loading. For instance, the module syst
 
 #### `bindnow` {#bindnow}
 
-Adds the `-z bindnow` linker option. During program load, all dynamic symbols are resolved, allowing for the complete GOT to be marked read-only (due to `relro`). This prevents GOT overwrite attacks. For very large applications, this can incur some performance loss during initial load while symbols are resolved, but this shouldn’t be an issue for daemons.
+Adds the `-z now` linker option. During program load, all dynamic symbols are resolved, allowing for the complete GOT to be marked read-only (due to `relro`). This prevents GOT overwrite attacks. For very large applications, this can incur some performance loss during initial load while symbols are resolved, but this shouldn’t be an issue for daemons.
 
 This flag can break dynamic shared object loading. For instance, the module systems of Xorg and PHP are incompatible with this flag. Programs incompatible with this flag often fail at runtime due to missing symbols, like:
 
diff --git a/nixpkgs/doc/using-nixpkgs.md b/nixpkgs/doc/using-nixpkgs.md
index bb222ae384fa..f850b2e83c28 100644
--- a/nixpkgs/doc/using-nixpkgs.md
+++ b/nixpkgs/doc/using-nixpkgs.md
@@ -1,6 +1,7 @@
 # Using Nixpkgs {#part-using}
 
 ```{=include=} chapters
+using/platform-support.chapter.md
 using/configuration.chapter.md
 using/overlays.chapter.md
 using/overrides.chapter.md
diff --git a/nixpkgs/doc/using/platform-support.chapter.md b/nixpkgs/doc/using/platform-support.chapter.md
new file mode 100644
index 000000000000..3f91b3d5d980
--- /dev/null
+++ b/nixpkgs/doc/using/platform-support.chapter.md
@@ -0,0 +1,18 @@
+# Platform Support {#chap-platform-support}
+
+Packages receive varying degrees of support, both in terms of maintainer attention and available computation resources for continuous integration (CI).
+
+Below is the list of the best supported platforms:
+
+- `x86_64-linux`: Highest level of support.
+- `aarch64-linux`: Well supported, with most packages building successfully in CI.
+- `aarch64-darwin`: Receives better support than `x86_64-darwin`.
+- `x86_64-darwin`: Receives some support.
+
+There are many other platforms with varying levels of support.
+The provisional platform list in [Appendix A] of [RFC046], while not up to date, can be used as guidance.
+
+A more formal definition of the platform support tiers is provided in [RFC046], but has not been fully implemented yet.
+
+[RFC046]: https://github.com/NixOS/rfcs/blob/master/rfcs/0046-platform-support-tiers.md
+[Appendix A]: https://github.com/NixOS/rfcs/blob/master/rfcs/0046-platform-support-tiers.md#appendix-a-non-normative-description-of-platforms-in-november-2019