Merge branch 'nixos-unstable-small' of https://github.com/NixOS/nixpkgs

Conflicts:
	nixpkgs/nixos/modules/services/mail/rss2email.nix
	nixpkgs/pkgs/build-support/go/module.nix

23 files changed, 1130 insertions, 302 deletions

diff --git a/nixpkgs/doc/README.md b/nixpkgs/doc/README.md
index 4ed9c47aee95..1e9305d040ba 100644
--- a/nixpkgs/doc/README.md
+++ b/nixpkgs/doc/README.md
@@ -71,6 +71,11 @@ If you **omit a link text** for a link pointing to a section, the text will be s
 
 This syntax is taken from [MyST](https://myst-parser.readthedocs.io/en/latest/using/syntax.html#targets-and-cross-referencing).
 
+
+#### HTML
+
+Inlining HTML is not allowed. Parts of the documentation gets rendered to various non-HTML formats, such as man pages in the case of NixOS manual.
+
 #### Roles
 
 If you want to link to a man page, you can use `` {manpage}`nix.conf(5)` ``. The references will turn into links when a mapping exists in [`doc/manpage-urls.json`](./manpage-urls.json).
@@ -157,6 +162,9 @@ watermelon
 
 In an effort to keep the Nixpkgs manual in a consistent style, please follow the conventions below, unless they prevent you from properly documenting something.
 In that case, please open an issue about the particular documentation convention and tag it with a "needs: documentation" label.
+When needed, each convention explain why it exists, so you can make a decision whether to follow it or not based on your particular case.
+Note that these conventions are about the **structure** of the manual (and its source files), not about the content that goes in it.
+You, as the writer of documentation, are still in charge of its content.
 
 - Put each sentence in its own line.
   This makes reviews and suggestions much easier, since GitHub's review system is based on lines.
@@ -188,26 +196,153 @@ In that case, please open an issue about the particular documentation convention
   }
   ```
 
-- Use [definition lists](#definition-lists) to document function arguments, and the attributes of such arguments. For example:
+- When showing inputs/outputs of any [REPL](https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop), such as a shell or the Nix REPL, use a format as you'd see in the REPL, while trying to visually separate inputs from outputs.
+  This means that for a shell, you should use a format like the following:
+  ```shell
+  $ nix-build -A hello '<nixpkgs>' \
+    --option require-sigs false \
+    --option trusted-substituters file:///tmp/hello-cache \
+    --option substituters file:///tmp/hello-cache
+  /nix/store/zhl06z4lrfrkw5rp0hnjjfrgsclzvxpm-hello-2.12.1
+  ```
+  Note how the input is preceded by `$` on the first line and indented on subsequent lines, and how the output is provided as you'd see on the shell.
+
+  For the Nix REPL, you should use a format like the following:
+  ```shell
+  nix-repl> builtins.attrNames { a = 1; b = 2; }
+  [ "a" "b" ]
+  ```
+  Note how the input is preceded by `nix-repl>` and the output is provided as you'd see on the Nix REPL.
+
+- When documenting functions or anything that has inputs/outputs and example usage, use nested headings to clearly separate inputs, outputs, and examples.
+  Keep examples as the last nested heading, and link to the examples wherever applicable in the documentation.
+
+  The purpose of this convention is to provide a familiar structure for navigating the manual, so any reader can expect to find content related to inputs in an "inputs" heading, examples in an "examples" heading, and so on.
+  An example:
+  ```
+  ## buildImage
+
+  Some explanation about the function here.
+  Describe a particular scenario, and point to [](#ex-dockerTools-buildImage), which is an example demonstrating it.
+
+  ### Inputs
+
+  Documentation for the inputs of `buildImage`.
+  Perhaps even point to [](#ex-dockerTools-buildImage) again when talking about something specifically linked to it.
+
+  ### Passthru outputs
+
+  Documentation for any passthru outputs of `buildImage`.
+
+  ### Examples
+
+  Note that this is the last nested heading in the `buildImage` section.
+
+  :::{.example #ex-dockerTools-buildImage}
+
+  # Using `buildImage`
+
+  Example of how to use `buildImage` goes here.
+
+  :::
+  ```
+
+- Use [definition lists](#definition-lists) to document function arguments, and the attributes of such arguments as well as their [types](https://nixos.org/manual/nix/stable/language/values).
+  For example:
 
   ```markdown
   # pkgs.coolFunction
 
   Description of what `coolFunction` does.
+
+  ## Inputs
+
   `coolFunction` expects a single argument which should be an attribute set, with the following possible attributes:
 
-  `name`
+  `name` (String)
 
   : The name of the resulting image.
 
-  `tag` _optional_
+  `tag` (String; _optional_)
 
   : Tag of the generated image.
 
-    _Default value:_ the output path's hash.
-
+    _Default:_ the output path's hash.
   ```
 
+#### Examples
+
+To define a referenceable figure use the following fencing:
+
+```markdown
+:::{.example #an-attribute-set-example}
+# An attribute set example
+
+You can add text before
+
+    ```nix
+    { a = 1; b = 2;}
+    ```
+
+and after code fencing
+:::
+```
+
+Defining examples through the `example` fencing class adds them to a "List of Examples" section after the Table of Contents.
+Though this is not shown in the rendered documentation on nixos.org.
+
+#### Figures
+
+To define a referencable figure use the following fencing:
+
+```markdown
+::: {.figure #nixos-logo}
+# NixOS Logo
+![NixOS logo](./nixos_logo.png)
+:::
+```
+
+Defining figures through the `figure` fencing class adds them to a `List  of Figures` after the `Table of Contents`.
+Though this is not shown in the rendered documentation on nixos.org.
+
+#### Footnotes
+
+To add a foonote explanation, use the following syntax:
+
+```markdown
+Sometimes it's better to add context [^context] in a footnote.
+
+[^context]: This explanation will be rendered at the end of the chapter.
+```
+
+#### Inline comments
+
+Inline comments are supported with following syntax:
+
+```markdown
+<!-- This is an inline comment -->
+```
+
+The comments will not be rendered in the rendered HTML.
+
+#### Link reference definitions
+
+Links can reference a label, for example, to make the link target reusable:
+
+```markdown
+::: {.note}
+Reference links can also be used to [shorten URLs][url-id] and keep the markdown readable.
+:::
+
+[url-id]: https://github.com/NixOS/nixpkgs/blob/19d4f7dc485f74109bd66ef74231285ff797a823/doc/README.md
+```
+
+This syntax is taken from [CommonMark](https://spec.commonmark.org/0.30/#link-reference-definitions).
+
+#### Typographic replacements
+
+Typographic replacements are enabled. Check the [list of possible replacement patterns check](https://github.com/executablebooks/markdown-it-py/blob/3613e8016ecafe21709471ee0032a90a4157c2d1/markdown_it/rules_core/replacements.py#L1-L15).
+
 ## Getting help
 
 If you need documentation-specific help or reviews, ping [@NixOS/documentation-reviewers](https://github.com/orgs/nixos/teams/documentation-reviewers) on your pull request.
diff --git a/nixpkgs/doc/build-helpers/images/dockertools.section.md b/nixpkgs/doc/build-helpers/images/dockertools.section.md
index e732e0472926..9317146b8f94 100644
--- a/nixpkgs/doc/build-helpers/images/dockertools.section.md
+++ b/nixpkgs/doc/build-helpers/images/dockertools.section.md
@@ -676,6 +676,7 @@ If our package sets `includeStorePaths` to `false`, we'll end up with only the f
 dockerTools.streamLayeredImage {
   name = "hello";
   contents = [ hello ];
+  includeStorePaths = false;
 }
 ```
 
@@ -714,301 +715,855 @@ dockerTools.streamLayeredImage {
 ```
 :::
 
-## pullImage {#ssec-pkgs-dockerTools-fetchFromRegistry}
+[]{#ssec-pkgs-dockerTools-fetchFromRegistry}
+## pullImage {#ssec-pkgs-dockerTools-pullImage}
 
-This function is analogous to the `docker pull` command, in that it can be used to pull a Docker image from a Docker registry. By default [Docker Hub](https://hub.docker.com/) is used to pull images.
+This function is similar to the `docker pull` command, which means it can be used to pull a Docker image from a registry that implements the [Docker Registry HTTP API V2](https://distribution.github.io/distribution/spec/api/).
+By default, the `docker.io` registry is used.
 
-Its parameters are described in the example below:
+The image will be downloaded as an uncompressed Docker-compatible repository tarball, which is suitable for use with other `dockerTools` functions such as [`buildImage`](#ssec-pkgs-dockerTools-buildImage), [`buildLayeredImage`](#ssec-pkgs-dockerTools-buildLayeredImage), and [`streamLayeredImage`](#ssec-pkgs-dockerTools-streamLayeredImage).
+
+This function requires two different types of hashes/digests to be specified:
+
+- One of them is used to identify a unique image within the registry (see the documentation for the `imageDigest` attribute).
+- The other is used by Nix to ensure the contents of the output haven't changed (see the documentation for the `sha256` attribute).
+
+Both hashes are required because they must uniquely identify some content in two completely different systems (the Docker registry and the Nix store), but their values will not be the same.
+See [](#ex-dockerTools-pullImage-nixprefetchdocker) for a tool that can help gather these values.
+
+### Inputs {#ssec-pkgs-dockerTools-pullImage-inputs}
+
+`pullImage` expects a single argument with the following attributes:
+
+`imageName` (String)
+
+: Specifies the name of the image to be downloaded, as well as the registry endpoint.
+  By default, the `docker.io` registry is used.
+  To specify a different registry, prepend the endpoint to `imageName`, separated by a slash (`/`).
+  See [](#ex-dockerTools-pullImage-differentregistry) for how to do that.
+
+`imageDigest` (String)
+
+: Specifies the digest of the image to be downloaded.
+
+  :::{.tip}
+  **Why can't I specify a tag to pull from, and have to use a digest instead?**
+
+  Tags are often updated to point to different image contents.
+  The most common example is the `latest` tag, which is usually updated whenever a newer image version is available.
+
+  An image tag isn't enough to guarantee the contents of an image won't change, but a digest guarantees this.
+  Providing a digest helps ensure that you will still be able to build the same Nix code and get the same output even if newer versions of an image are released.
+  :::
+
+`sha256` (String)
+
+: The hash of the image after it is downloaded.
+  Internally, this is passed to the [`outputHash`](https://nixos.org/manual/nix/stable/language/advanced-attributes#adv-attr-outputHash) attribute of the resulting derivation.
+  This is needed to provide a guarantee to Nix that the contents of the image haven't changed, because Nix doesn't support the value in `imageDigest`.
+
+`finalImageName` (String; _optional_)
+
+: Specifies the name that will be used for the image after it has been downloaded.
+  This only applies after the image is downloaded, and is not used to identify the image to be downloaded in the registry.
+  Use `imageName` for that instead.
+
+  _Default value:_ the same value specified in `imageName`.
+
+`finalImageTag` (String; _optional_)
+
+: Specifies the tag that will be used for the image after it has been downloaded.
+  This only applies after the image is downloaded, and is not used to identify the image to be downloaded in the registry.
+
+  _Default value:_ `"latest"`.
+
+`os` (String; _optional_)
+
+: Specifies the operating system of the image to pull.
+  If specified, its value should follow the [OCI Image Configuration Specification](https://github.com/opencontainers/image-spec/blob/main/config.md#properties), which should still be compatible with Docker.
+  According to the linked specification, all possible values for `$GOOS` in [the Go docs](https://go.dev/doc/install/source#environment) should be valid, but will commonly be one of `darwin` or `linux`.
+
+  _Default value:_ `"linux"`.
+
+`arch` (String; _optional_)
+
+: Specifies the architecture of the image to pull.
+  If specified, its value should follow the [OCI Image Configuration Specification](https://github.com/opencontainers/image-spec/blob/main/config.md#properties), which should still be compatible with Docker.
+  According to the linked specification, all possible values for `$GOARCH` in [the Go docs](https://go.dev/doc/install/source#environment) should be valid, but will commonly be one of `386`, `amd64`, `arm`, or `arm64`.
+
+  _Default value:_ the same value from `pkgs.go.GOARCH`.
+
+`tlsVerify` (Boolean; _optional_)
+
+: Used to enable or disable HTTPS and TLS certificate verification when communicating with the chosen Docker registry.
+  Setting this to `false` will make `pullImage` connect to the registry through HTTP.
+
+  _Default value:_ `true`.
+
+`name` (String; _optional_)
+
+: The name used for the output in the Nix store path.
+
+  _Default value:_ a value derived from `finalImageName` and `finalImageTag`, with some symbols replaced.
+  It is recommended to treat the default as an opaque value.
+
+### Examples {#ssec-pkgs-dockerTools-pullImage-examples}
+
+::: {.example #ex-dockerTools-pullImage-niximage}
+# Pulling the nixos/nix Docker image from the default registry
+
+This example pulls the [`nixos/nix` image](https://hub.docker.com/r/nixos/nix) and saves it in the Nix store.
 
 ```nix
-pullImage {
+{ dockerTools }:
+dockerTools.pullImage {
   imageName = "nixos/nix";
-  imageDigest =
-    "sha256:473a2b527958665554806aea24d0131bacec46d23af09fef4598eeab331850fa";
+  imageDigest = "sha256:b8ea88f763f33dfda2317b55eeda3b1a4006692ee29e60ee54ccf6d07348c598";
   finalImageName = "nix";
-  finalImageTag = "2.11.1";
-  sha256 = "sha256-qvhj+Hlmviz+KEBVmsyPIzTB3QlVAFzwAY1zDPIBGxc=";
-  os = "linux";
-  arch = "x86_64";
+  finalImageTag = "2.19.3";
+  sha256 = "zRwlQs1FiKrvHPaf8vWOR/Tlp1C5eLn1d9pE4BZg3oA=";
 }
 ```
+:::
 
-- `imageName` specifies the name of the image to be downloaded, which can also include the registry namespace (e.g. `nixos`). This argument is required.
-
-- `imageDigest` specifies the digest of the image to be downloaded. This argument is required.
+::: {.example #ex-dockerTools-pullImage-differentregistry}
+# Pulling the nixos/nix Docker image from a specific registry
 
-- `finalImageName`, if specified, this is the name of the image to be created. Note it is never used to fetch the image since we prefer to rely on the immutable digest ID. By default it's equal to `imageName`.
+This example pulls the [`coreos/etcd` image](https://quay.io/repository/coreos/etcd) from the `quay.io` registry.
 
-- `finalImageTag`, if specified, this is the tag of the image to be created. Note it is never used to fetch the image since we prefer to rely on the immutable digest ID. By default it's `latest`.
+```nix
+{ dockerTools }:
+dockerTools.pullImage {
+  imageName = "quay.io/coreos/etcd";
+  imageDigest = "sha256:24a23053f29266fb2731ebea27f915bb0fb2ae1ea87d42d890fe4e44f2e27c5d";
+  finalImageName = "etcd";
+  finalImageTag = "v3.5.11";
+  sha256 = "Myw+85f2/EVRyMB3axECdmQ5eh9p1q77FWYKy8YpRWU=";
+}
+```
+:::
 
-- `sha256` is the checksum of the whole fetched image. This argument is required.
+::: {.example #ex-dockerTools-pullImage-nixprefetchdocker}
+# Finding the digest and hash values to use for `dockerTools.pullImage`
 
-- `os`, if specified, is the operating system of the fetched image. By default it's `linux`.
+Since [`dockerTools.pullImage`](#ssec-pkgs-dockerTools-pullImage) requires two different hashes, one can run the `nix-prefetch-docker` tool to find out the values for the hashes.
+The tool outputs some text for an attribute set which you can pass directly to `pullImage`.
 
-- `arch`, if specified, is the cpu architecture of the fetched image. By default it's `x86_64`.
+```shell
+$ nix run nixpkgs#nix-prefetch-docker -- --image-name nixos/nix --image-tag 2.19.3 --arch amd64 --os linux
+(some output removed for clarity)
+Writing manifest to image destination
+-> ImageName: nixos/nix
+-> ImageDigest: sha256:498fa2d7f2b5cb3891a4edf20f3a8f8496e70865099ba72540494cd3e2942634
+-> FinalImageName: nixos/nix
+-> FinalImageTag: latest
+-> ImagePath: /nix/store/4mxy9mn6978zkvlc670g5703nijsqc95-docker-image-nixos-nix-latest.tar
+-> ImageHash: 1q6cf2pdrasa34zz0jw7pbs6lvv52rq2aibgxccbwcagwkg2qj1q
+{
+  imageName = "nixos/nix";
+  imageDigest = "sha256:498fa2d7f2b5cb3891a4edf20f3a8f8496e70865099ba72540494cd3e2942634";
+  sha256 = "1q6cf2pdrasa34zz0jw7pbs6lvv52rq2aibgxccbwcagwkg2qj1q";
+  finalImageName = "nixos/nix";
+  finalImageTag = "latest";
+}
+```
 
-`nix-prefetch-docker` command can be used to get required image parameters:
+It is important to supply the `--arch` and `--os` arguments to `nix-prefetch-docker` to filter to a single image, in case there are multiple architectures and/or operating systems supported by the image name and tags specified.
+By default, `nix-prefetch-docker` will set `os` to `linux` and `arch` to `amd64`.
 
-```ShellSession
-$ nix run nixpkgs#nix-prefetch-docker -- --image-name mysql --image-tag 5
+Run `nix-prefetch-docker --help` for a list of all supported arguments:
+```shell
+$ nix run nixpkgs#nix-prefetch-docker -- --help
+(output removed for clarity)
 ```
+:::
+
+## exportImage {#ssec-pkgs-dockerTools-exportImage}
 
-Since a given `imageName` may transparently refer to a manifest list of images which support multiple architectures and/or operating systems, you can supply the `--os` and `--arch` arguments to specify exactly which image you want. By default it will match the OS and architecture of the host the command is run on.
+This function is similar to the `docker container export` command, which means it can be used to export an image's filesystem as an uncompressed tarball archive.
+The difference is that `docker container export` is applied to containers, but `dockerTools.exportImage` applies to Docker images.
+The resulting archive will not contain any image metadata (such as command to run with `docker container run`), only the filesystem contents.
 
-```ShellSession
-$ nix-prefetch-docker --image-name mysql --image-tag 5 --arch x86_64 --os linux
+You can use this function to import an archive in Docker with `docker image import`.
+See [](#ex-dockerTools-exportImage-importingDocker) to understand how to do that.
+
+:::{.caution}
+`exportImage` works by unpacking the given image inside a VM.
+Because of this, using this function requires the `kvm` device to be available, see [`system-features`](https://nixos.org/manual/nix/stable/command-ref/conf-file.html#conf-system-features).
+:::
+
+### Inputs {#ssec-pkgs-dockerTools-exportImage-inputs}
+
+`exportImage` expects an argument with the following attributes:
+
+`fromImage` (Attribute Set or String)
+
+: The repository tarball of the image whose filesystem will be exported.
+  It must be a valid Docker image, such as one exported by `docker image save`, or another image built with the `dockerTools` utility functions.
+
+  If `name` is not specified, `fromImage` must be an Attribute Set corresponding to a derivation, i.e. it can't be a path to a tarball.
+  If `name` is specified, `fromImage` can be either an Attribute Set corresponding to a derivation or simply a path to a tarball.
+
+  See [](#ex-dockerTools-exportImage-naming) and [](#ex-dockerTools-exportImage-fromImagePath) to understand the connection between `fromImage`, `name`, and the name used for the output of `exportImage`.
+
+`fromImageName` (String or Null; _optional_)
+
+: Used to specify the image within the repository tarball in case it contains multiple images.
+  A value of `null` means that `exportImage` will use the first image available in the repository.
+
+  :::{.note}
+  This must be used with `fromImageTag`. Using only `fromImageName` without `fromImageTag` will make `exportImage` use the first image available in the repository.
+  :::
+
+  _Default value:_ `null`.
+
+`fromImageTag` (String or Null; _optional_)
+
+: Used to specify the image within the repository tarball in case it contains multiple images.
+  A value of `null` means that `exportImage` will use the first image available in the repository.
+
+  :::{.note}
+  This must be used with `fromImageName`. Using only `fromImageTag` without `fromImageName` will make `exportImage` use the first image available in the repository
+  :::
+
+  _Default value:_ `null`.
+
+`diskSize` (Number; _optional_)
+
+: Controls the disk size (in megabytes) of the VM used to unpack the image.
+
+  _Default value:_ 1024.
+
+`name` (String; _optional_)
+
+: The name used for the output in the Nix store path.
+
+  _Default value:_ the value of `fromImage.name`.
+
+### Examples {#ssec-pkgs-dockerTools-exportImage-examples}
+
+:::{.example #ex-dockerTools-exportImage-hello}
+# Exporting a Docker image with `dockerTools.exportImage`
+
+This example first builds a layered image with [`dockerTools.buildLayeredImage`](#ssec-pkgs-dockerTools-buildLayeredImage), and then exports its filesystem with `dockerTools.exportImage`.
+
+```nix
+{ dockerTools, hello }:
+dockerTools.exportImage {
+  name = "hello";
+  fromImage = dockerTools.buildLayeredImage {
+    name = "hello";
+    contents = [ hello ];
+  };
+}
 ```
 
-Desired image name and tag can be set using `--final-image-name` and `--final-image-tag` arguments:
+When building the package above, we can see the layers of the Docker image being unpacked to produce the final output:
 
-```ShellSession
-$ nix-prefetch-docker --image-name mysql --image-tag 5 --final-image-name eu.gcr.io/my-project/mysql --final-image-tag prod
+```shell
+$ nix-build
+(some output removed for clarity)
+Unpacking base image...
+From-image name or tag wasn't set. Reading the first ID.
+Unpacking layer 5731199219418f175d1580dbca05677e69144425b2d9ecb60f416cd57ca3ca42/layer.tar
+tar: Removing leading `/' from member names
+Unpacking layer e2897bf34bb78c4a65736510204282d9f7ca258ba048c183d665bd0f3d24c5ec/layer.tar
+tar: Removing leading `/' from member names
+Unpacking layer 420aa5876dca4128cd5256da7dea0948e30ef5971712f82601718cdb0a6b4cda/layer.tar
+tar: Removing leading `/' from member names
+Unpacking layer ea5f4e620e7906c8ecbc506b5e6f46420e68d4b842c3303260d5eb621b5942e5/layer.tar
+tar: Removing leading `/' from member names
+Unpacking layer 65807b9abe8ab753fa97da8fb74a21fcd4725cc51e1b679c7973c97acd47ebcf/layer.tar
+tar: Removing leading `/' from member names
+Unpacking layer b7da2076b60ebc0ea6824ef641978332b8ac908d47b2d07ff31b9cc362245605/layer.tar
+Executing post-mount steps...
+Packing raw image...
+[    1.660036] reboot: Power down
+/nix/store/x6a5m7c6zdpqz1d8j7cnzpx9glzzvd2h-hello
 ```
 
-## exportImage {#ssec-pkgs-dockerTools-exportImage}
+The following command lists some of the contents of the output to verify that the structure of the archive is as expected:
 
-This function is analogous to the `docker export` command, in that it can be used to flatten a Docker image that contains multiple layers. It is in fact the result of the merge of all the layers of the image. As such, the result is suitable for being imported in Docker with `docker import`.
+```shell
+$ tar --exclude '*/share/*' --exclude 'nix/store/*/*' -tvf /nix/store/x6a5m7c6zdpqz1d8j7cnzpx9glzzvd2h-hello
+drwxr-xr-x root/0            0 1979-12-31 16:00 ./
+drwxr-xr-x root/0            0 1979-12-31 16:00 ./bin/
+lrwxrwxrwx root/0            0 1979-12-31 16:00 ./bin/hello -> /nix/store/h92a9jd0lhhniv2q417hpwszd4jhys7q-hello-2.12.1/bin/hello
+dr-xr-xr-x root/0            0 1979-12-31 16:00 ./nix/
+dr-xr-xr-x root/0            0 1979-12-31 16:00 ./nix/store/
+dr-xr-xr-x root/0            0 1979-12-31 16:00 ./nix/store/05zbwhz8a7i2v79r9j21pl6m6cj0xi8k-libunistring-1.1/
+dr-xr-xr-x root/0            0 1979-12-31 16:00 ./nix/store/ayg5rhjhi9ic73hqw33mjqjxwv59ndym-xgcc-13.2.0-libgcc/
+dr-xr-xr-x root/0            0 1979-12-31 16:00 ./nix/store/h92a9jd0lhhniv2q417hpwszd4jhys7q-hello-2.12.1/
+dr-xr-xr-x root/0            0 1979-12-31 16:00 ./nix/store/m59xdgkgnjbk8kk6k6vbxmqnf82mk9s0-libidn2-2.3.4/
+dr-xr-xr-x root/0            0 1979-12-31 16:00 ./nix/store/p3jshbwxiwifm1py0yq544fmdyy98j8a-glibc-2.38-27/
+drwxr-xr-x root/0            0 1979-12-31 16:00 ./share/
+```
+:::
 
-> **_NOTE:_** Using this function requires the `kvm` device to be available.
+:::{.example #ex-dockerTools-exportImage-importingDocker}
+# Importing an archive built with `dockerTools.exportImage` in Docker
 
-The parameters of `exportImage` are the following:
+We will use the same package from [](#ex-dockerTools-exportImage-hello) and import it into Docker.
 
 ```nix
-exportImage {
-  fromImage = someLayeredImage;
-  fromImageName = null;
-  fromImageTag = null;
+{ dockerTools, hello }:
+dockerTools.exportImage {
+  name = "hello";
+  fromImage = dockerTools.buildLayeredImage {
+    name = "hello";
+    contents = [ hello ];
+  };
+}
+```
+
+Building and importing it into Docker:
+
+```shell
+$ nix-build
+(output removed for clarity)
+/nix/store/x6a5m7c6zdpqz1d8j7cnzpx9glzzvd2h-hello
+$ docker image import /nix/store/x6a5m7c6zdpqz1d8j7cnzpx9glzzvd2h-hello
+sha256:1d42dba415e9b298ea0decf6497fbce954de9b4fcb2984f91e307c8fedc1f52f
+$ docker image ls
+REPOSITORY                              TAG                IMAGE ID       CREATED         SIZE
+<none>                                  <none>             1d42dba415e9   4 seconds ago   32.6MB
+```
+:::
 
-  name = someLayeredImage.name;
+:::{.example #ex-dockerTools-exportImage-naming}
+# Exploring output naming with `dockerTools.exportImage`
+
+`exportImage` does not require a `name` attribute if `fromImage` is a derivation, which means that the following works:
+
+```nix
+{ dockerTools, hello }:
+dockerTools.exportImage {
+  fromImage = dockerTools.buildLayeredImage {
+    name = "hello";
+    contents = [ hello ];
+  };
 }
 ```
 
-The parameters relative to the base image have the same synopsis as described in [buildImage](#ssec-pkgs-dockerTools-buildImage), except that `fromImage` is the only required argument in this case.
+However, since [`dockerTools.buildLayeredImage`](#ssec-pkgs-dockerTools-buildLayeredImage)'s output ends with `.tar.gz`, the output of `exportImage` will also end with `.tar.gz`, even though the archive created with `exportImage` is uncompressed:
+
+```shell
+$ nix-build
+(output removed for clarity)
+/nix/store/by3f40xvc4l6bkis74l0fj4zsy0djgkn-hello.tar.gz
+$ file /nix/store/by3f40xvc4l6bkis74l0fj4zsy0djgkn-hello.tar.gz
+/nix/store/by3f40xvc4l6bkis74l0fj4zsy0djgkn-hello.tar.gz: POSIX tar archive (GNU)
+```
+
+If the archive was actually compressed, the output of file would've mentioned that fact.
+Because of this, it may be important to set a proper `name` attribute when using `exportImage` with other functions from `dockerTools`.
+:::
 
-The `name` argument is the name of the derivation output, which defaults to `fromImage.name`.
+:::{.example #ex-dockerTools-exportImage-fromImagePath}
+# Using `dockerTools.exportImage` with a path as `fromImage`
 
-## Environment Helpers {#ssec-pkgs-dockerTools-helpers}
+It is possible to use a path as the value of the `fromImage` attribute when calling `dockerTools.exportImage`.
+However, when doing so, a `name` attribute **MUST** be specified, or you'll encounter an error when evaluating the Nix code.
 
-Some packages expect certain files to be available globally.
-When building an image from scratch (i.e. without `fromImage`), these files are missing.
-`pkgs.dockerTools` provides some helpers to set up an environment with the necessary files.
-You can include them in `copyToRoot` like this:
+For this example, we'll assume a Docker tarball image named `image.tar.gz` exists in the same directory where our package is defined:
 
 ```nix
-buildImage {
-  name = "environment-example";
-  copyToRoot = with pkgs.dockerTools; [
-    usrBinEnv
-    binSh
-    caCertificates
-    fakeNss
-  ];
+{ dockerTools }:
+dockerTools.exportImage {
+  name = "filesystem.tar";
+  fromImage = ./image.tar.gz;
 }
 ```
 
+Building this will give us the expected output:
+
+```shell
+$ nix-build
+(output removed for clarity)
+/nix/store/w13l8h3nlkg0zv56k7rj0ai0l2zlf7ss-filesystem.tar
+```
+
+If you don't specify a `name` attribute, you'll encounter an evaluation error and the package won't build.
+:::
+
+## Environment Helpers {#ssec-pkgs-dockerTools-helpers}
+
+When building Docker images with Nix, you might also want to add certain files that are expected to be available globally by the software you're packaging.
+Simple examples are the `env` utility in `/usr/bin/env`, or trusted root TLS/SSL certificates.
+Such files will most likely not be included if you're building a Docker image from scratch with Nix, and they might also not be included if you're starting from a Docker image that doesn't include them.
+The helpers in this section are packages that provide some of these commonly-needed global files.
+
+Most of these helpers are packages, which means you have to add them to the list of contents to be included in the image (this changes depending on the function you're using to build the image).
+[](#ex-dockerTools-helpers-buildImage) and [](#ex-dockerTools-helpers-buildLayeredImage) show how to include these packages on `dockerTools` functions that build an image.
+For more details on how that works, see the documentation for the function you're using.
+
 ### usrBinEnv {#sssec-pkgs-dockerTools-helpers-usrBinEnv}
 
 This provides the `env` utility at `/usr/bin/env`.
+This is currently implemented by linking to the `env` binary from the `coreutils` package, but is considered an implementation detail that could change in the future.
 
 ### binSh {#sssec-pkgs-dockerTools-helpers-binSh}
 
-This provides `bashInteractive` at `/bin/sh`.
+This provides a `/bin/sh` link to the `bash` binary from the `bashInteractive` package.
+Because of this, it supports cases such as running a command interactively in a container (for example by running `docker run -it <image_name>`).
 
 ### caCertificates {#sssec-pkgs-dockerTools-helpers-caCertificates}
 
-This sets up `/etc/ssl/certs/ca-certificates.crt`.
+This adds trusted root TLS/SSL certificates from the `cacert` package in multiple locations in an attempt to be compatible with binaries built for multiple Linux distributions.
+The locations currently used are:
 
+- `/etc/ssl/certs/ca-bundle.crt`
+- `/etc/ssl/certs/ca-certificates.crt`
+- `/etc/pki/tls/certs/ca-bundle.crt`
+
+[]{#ssec-pkgs-dockerTools-fakeNss}
 ### fakeNss {#sssec-pkgs-dockerTools-helpers-fakeNss}
 
-Provides `/etc/passwd` and `/etc/group` that contain root and nobody.
-Useful when packaging binaries that insist on using nss to look up
-username/groups (like nginx).
+This is a re-export of the `fakeNss` package from Nixpkgs.
+See [](#sec-fakeNss).
 
 ### shadowSetup {#ssec-pkgs-dockerTools-shadowSetup}
 
-This constant string is a helper for setting up the base files for managing users and groups, only if such files don't exist already. It is suitable for being used in a [`buildImage` `runAsRoot`](#ex-dockerTools-buildImage-runAsRoot) script for cases like in the example below:
+This is a string containing a script that sets up files needed for [`shadow`](https://github.com/shadow-maint/shadow) to work (using the `shadow` package from Nixpkgs), and alters `PATH` to make all its utilities available in the same script.
+It is intended to be used with other dockerTools functions in attributes that expect scripts.
+After the script in `shadowSetup` runs, you'll then be able to add more commands that make use of the utilities in `shadow`, such as adding any extra users and/or groups.
+See [](#ex-dockerTools-shadowSetup-buildImage) and [](#ex-dockerTools-shadowSetup-buildLayeredImage) to better understand how to use it.
+
+`shadowSetup` achieves a result similar to [`fakeNss`](#sssec-pkgs-dockerTools-helpers-fakeNss), but only sets up a `root` user with different values for the home directory and the shell to use, in addition to setting up files for [PAM](https://en.wikipedia.org/wiki/Linux_PAM) and a {manpage}`login.defs(5)` file.
+
+:::{.caution}
+Using both `fakeNss` and `shadowSetup` at the same time will either cause your build to break or produce unexpected results.
+Use either `fakeNss` or `shadowSetup` depending on your use case, but avoid using both.
+:::
+
+:::{.note}
+When used with [`buildLayeredImage`](#ssec-pkgs-dockerTools-buildLayeredImage) or [`streamLayeredImage`](#ssec-pkgs-dockerTools-streamLayeredImage), you will have to set the `enableFakechroot` attribute to `true`, or else the script in `shadowSetup` won't run properly.
+See [](#ex-dockerTools-shadowSetup-buildLayeredImage).
+:::
+
+### Examples {#ssec-pkgs-dockerTools-helpers-examples}
+
+:::{.example #ex-dockerTools-helpers-buildImage}
+# Using `dockerTools`'s environment helpers with `buildImage`
+
+This example adds the [`binSh`](#sssec-pkgs-dockerTools-helpers-binSh) helper to a basic Docker image built with [`dockerTools.buildImage`](#ssec-pkgs-dockerTools-buildImage).
+This helper makes it possible to enter a shell inside the container.
+This is the `buildImage` equivalent of [](#ex-dockerTools-helpers-buildLayeredImage).
 
 ```nix
-buildImage {
+{ dockerTools, hello }:
+dockerTools.buildImage {
+  name = "env-helpers";
+  tag = "latest";
+
+  copyToRoot = [
+    hello
+    dockerTools.binSh
+  ];
+```
+
+After building the image and loading it in Docker, we can create a container based on it and enter a shell inside the container.
+This is made possible by `binSh`.
+
+```shell
+$ nix-build
+(some output removed for clarity)
+/nix/store/2p0i3i04cgjlk71hsn7ll4kxaxxiv4qg-docker-image-env-helpers.tar.gz
+$ docker load -i /nix/store/2p0i3i04cgjlk71hsn7ll4kxaxxiv4qg-docker-image-env-helpers.tar.gz
+(output removed for clarity)
+$ docker run --rm -it env-helpers:latest /bin/sh
+sh-5.2# help
+GNU bash, version 5.2.21(1)-release (x86_64-pc-linux-gnu)
+(rest of output removed for clarity)
+```
+:::
+
+:::{.example #ex-dockerTools-helpers-buildLayeredImage}
+# Using `dockerTools`'s environment helpers with `buildLayeredImage`
+
+This example adds the [`binSh`](#sssec-pkgs-dockerTools-helpers-binSh) helper to a basic Docker image built with [`dockerTools.buildLayeredImage`](#ssec-pkgs-dockerTools-buildLayeredImage).
+This helper makes it possible to enter a shell inside the container.
+This is the `buildLayeredImage` equivalent of [](#ex-dockerTools-helpers-buildImage).
+
+```nix
+{ dockerTools, hello }:
+dockerTools.buildLayeredImage {
+  name = "env-helpers";
+  tag = "latest";
+
+  contents = [
+    hello
+    dockerTools.binSh
+  ];
+
+  config = {
+    Cmd = [ "/bin/hello" ];
+  };
+}
+```
+
+After building the image and loading it in Docker, we can create a container based on it and enter a shell inside the container.
+This is made possible by `binSh`.
+
+```shell
+$ nix-build
+(some output removed for clarity)
+/nix/store/rpf47f4z5b9qr4db4ach9yr4b85hjhxq-env-helpers.tar.gz
+$ docker load -i /nix/store/rpf47f4z5b9qr4db4ach9yr4b85hjhxq-env-helpers.tar.gz
+(output removed for clarity)
+$ docker run --rm -it env-helpers:latest /bin/sh
+sh-5.2# help
+GNU bash, version 5.2.21(1)-release (x86_64-pc-linux-gnu)
+(rest of output removed for clarity)
+```
+:::
+
+:::{.example #ex-dockerTools-shadowSetup-buildImage}
+# Using `dockerTools.shadowSetup` with `dockerTools.buildImage`
+
+This is an example that shows how to use `shadowSetup` with `dockerTools.buildImage`.
+Note that the extra script in `runAsRoot` uses `groupadd` and `useradd`, which are binaries provided by the `shadow` package.
+These binaries are added to the `PATH` by the `shadowSetup` script, but only for the duration of `runAsRoot`.
+
+```nix
+{ dockerTools, hello }:
+dockerTools.buildImage {
   name = "shadow-basic";
+  tag = "latest";
+
+  copyToRoot = [ hello ];
 
   runAsRoot = ''
-    #!${pkgs.runtimeShell}
-    ${pkgs.dockerTools.shadowSetup}
-    groupadd -r redis
-    useradd -r -g redis redis
+    ${dockerTools.shadowSetup}
+    groupadd -r hello
+    useradd -r -g hello hello
     mkdir /data
-    chown redis:redis /data
+    chown hello:hello /data
   '';
+
+  config = {
+    Cmd = [ "/bin/hello" ];
+    WorkingDir = "/data";
+  };
 }
 ```
+:::
 
-Creating base files like `/etc/passwd` or `/etc/login.defs` is necessary for shadow-utils to manipulate users and groups.
-
-## fakeNss {#ssec-pkgs-dockerTools-fakeNss}
-
-If your primary goal is providing a basic skeleton for user lookups to work,
-and/or a lesser privileged user, adding `pkgs.fakeNss` to
-the container image root might be the better choice than a custom script
-running `useradd` and friends.
-
-It provides a `/etc/passwd` and `/etc/group`, containing `root` and `nobody`
-users and groups.
+:::{.example #ex-dockerTools-shadowSetup-buildLayeredImage}
+# Using `dockerTools.shadowSetup` with `dockerTools.buildLayeredImage`
 
-It also provides a `/etc/nsswitch.conf`, configuring NSS host resolution to
-first check `/etc/hosts`, before checking DNS, as the default in the absence of
-a config file (`dns [!UNAVAIL=return] files`) is quite unexpected.
+It accomplishes the same thing as [](#ex-dockerTools-shadowSetup-buildImage), but using `buildLayeredImage` instead.
 
-You can pair it with `binSh`, which provides `bin/sh` as a symlink
-to `bashInteractive` (as `/bin/sh` is configured as a shell).
+Note that the extra script in `fakeRootCommands` uses `groupadd` and `useradd`, which are binaries provided by the `shadow` package.
+These binaries are added to the `PATH` by the `shadowSetup` script, but only for the duration of `fakeRootCommands`.
 
 ```nix
-buildImage {
+{ dockerTools, hello }:
+dockerTools.buildLayeredImage {
   name = "shadow-basic";
+  tag = "latest";
 
-  copyToRoot = pkgs.buildEnv {
-    name = "image-root";
-    paths = [ binSh pkgs.fakeNss ];
-    pathsToLink = [ "/bin" "/etc" "/var" ];
+  contents = [ hello ];
+
+  fakeRootCommands = ''
+    ${dockerTools.shadowSetup}
+    groupadd -r hello
+    useradd -r -g hello hello
+    mkdir /data
+    chown hello:hello /data
+  '';
+  enableFakechroot = true;
+
+  config = {
+    Cmd = [ "/bin/hello" ];
+    WorkingDir = "/data";
   };
 }
 ```
+:::
 
+[]{#ssec-pkgs-dockerTools-buildNixShellImage-arguments}
 ## buildNixShellImage {#ssec-pkgs-dockerTools-buildNixShellImage}
 
-Create a Docker image that sets up an environment similar to that of running `nix-shell` on a derivation.
-When run in Docker, this environment somewhat resembles the Nix sandbox typically used by `nix-build`, with a major difference being that access to the internet is allowed.
-It additionally also behaves like an interactive `nix-shell`, running things like `shellHook` and setting an interactive prompt.
-If the derivation is fully buildable (i.e. `nix-build` can be used on it), running `buildDerivation` inside such a Docker image will build the derivation, with all its outputs being available in the correct `/nix/store` paths, pointed to by the respective environment variables like `$out`, etc.
+`buildNixShellImage` uses [`streamNixShellImage`](#ssec-pkgs-dockerTools-streamNixShellImage) underneath to build a compressed Docker-compatible repository tarball of an image that sets up an environment similar to that of running `nix-shell` on a derivation.
+Basically, `buildNixShellImage` runs the script created by `streamNixShellImage` to save the compressed image in the Nix store.
+
+`buildNixShellImage` supports the same options as `streamNixShellImage`, see [`streamNixShellImage`](#ssec-pkgs-dockerTools-streamNixShellImage) for details.
+
+[]{#ssec-pkgs-dockerTools-buildNixShellImage-example}
+### Examples {#ssec-pkgs-dockerTools-buildNixShellImage-examples}
 
-::: {.warning}
-The behavior doesn't match `nix-shell` or `nix-build` exactly and this function is known not to work correctly for e.g. fixed-output derivations, content-addressed derivations, impure derivations and other special types of derivations.
+:::{.example #ex-dockerTools-buildNixShellImage-hello}
+# Building a Docker image with `buildNixShellImage` with the build environment for the `hello` package
+
+This example shows how to build the `hello` package inside a Docker container built with `buildNixShellImage`.
+The Docker image generated will have a name like `hello-<version>-env` and tag `latest`.
+This example is the `buildNixShellImage` equivalent of [](#ex-dockerTools-streamNixShellImage-hello).
+
+```nix
+{ dockerTools, hello }:
+dockerTools.buildNixShellImage {
+  drv = hello;
+  tag = "latest";
+}
+```
+
+The result of building this package is a `.tar.gz` file that can be loaded into Docker:
+
+```shell
+$ nix-build
+(some output removed for clarity)
+/nix/store/pkj1sgzaz31wl0pbvbg3yp5b3kxndqms-hello-2.12.1-env.tar.gz
+
+$ docker load -i /nix/store/pkj1sgzaz31wl0pbvbg3yp5b3kxndqms-hello-2.12.1-env.tar.gz
+(some output removed for clarity)
+Loaded image: hello-2.12.1-env:latest
+```
+
+After starting an interactive container, the derivation can be built by running `buildDerivation`, and the output can be executed as expected:
+
+```shell
+$ docker run -it hello-2.12.1-env:latest
+[nix-shell:~]$ buildDerivation
+Running phase: unpackPhase
+unpacking source archive /nix/store/pa10z4ngm0g83kx9mssrqzz30s84vq7k-hello-2.12.1.tar.gz
+source root is hello-2.12.1
+(some output removed for clarity)
+Running phase: fixupPhase
+shrinking RPATHs of ELF executables and libraries in /nix/store/f2vs29jibd7lwxyj35r9h87h6brgdysz-hello-2.12.1
+shrinking /nix/store/f2vs29jibd7lwxyj35r9h87h6brgdysz-hello-2.12.1/bin/hello
+checking for references to /build/ in /nix/store/f2vs29jibd7lwxyj35r9h87h6brgdysz-hello-2.12.1...
+gzipping man pages under /nix/store/f2vs29jibd7lwxyj35r9h87h6brgdysz-hello-2.12.1/share/man/
+patching script interpreter paths in /nix/store/f2vs29jibd7lwxyj35r9h87h6brgdysz-hello-2.12.1
+stripping (with command strip and flags -S -p) in  /nix/store/f2vs29jibd7lwxyj35r9h87h6brgdysz-hello-2.12.1/bin
+
+[nix-shell:~]$ $out/bin/hello
+Hello, world!
+```
 :::
 
-### Arguments {#ssec-pkgs-dockerTools-buildNixShellImage-arguments}
+## streamNixShellImage {#ssec-pkgs-dockerTools-streamNixShellImage}
+
+`streamNixShellImage` builds a **script** which, when run, will stream to stdout a Docker-compatible repository tarball of an image that sets up an environment similar to that of running `nix-shell` on a derivation.
+This means that `streamNixShellImage` does not output an image into the Nix store, but only a script that builds the image, saving on IO and disk/cache space, particularly with large images.
+See [](#ex-dockerTools-streamNixShellImage-hello) to understand how to load in Docker the image generated by this script.
+
+The environment set up by `streamNixShellImage` somewhat resembles the Nix sandbox typically used by `nix-build`, with a major difference being that access to the internet is allowed.
+It also behaves like an interactive `nix-shell`, running things like `shellHook` (see [](#ex-dockerTools-streamNixShellImage-addingShellHook)) and setting an interactive prompt.
+If the derivation is buildable (i.e. `nix-build` can be used on it), running `buildDerivation` in the container will build the derivation, with all its outputs being available in the correct `/nix/store` paths, pointed to by the respective environment variables (e.g. `$out`).
 
-`drv`
+::: {.caution}
+The environment in the image doesn't match `nix-shell` or `nix-build` exactly, and this function is known not to work correctly for fixed-output derivations, content-addressed derivations, impure derivations and other special types of derivations.
+:::
 
-: The derivation on which to base the Docker image.
+### Inputs {#ssec-pkgs-dockerTools-streamNixShellImage-inputs}
 
-    Adding packages to the Docker image is possible by e.g. extending the list of `nativeBuildInputs` of this derivation like
+`streamNixShellImage` expects one argument with the following attributes:
 
-    ```nix
-    buildNixShellImage {
-      drv = someDrv.overrideAttrs (old: {
-        nativeBuildInputs = old.nativeBuildInputs or [] ++ [
-          somethingExtra
-        ];
-      });
-      # ...
-    }
-    ```
+`drv` (Attribute Set)
 
-    Similarly, you can extend the image initialization script by extending `shellHook`
+: The derivation for which the environment in the image will be set up.
+  Adding packages to the Docker image is possible by extending the list of `nativeBuildInputs` of this derivation.
+  See [](#ex-dockerTools-streamNixShellImage-extendingBuildInputs) for how to do that.
+  Similarly, you can extend the image initialization script by extending `shellHook`.
+  [](#ex-dockerTools-streamNixShellImage-addingShellHook) shows how to do that.
 
-`name` _optional_
+`name` (String; _optional_)
 
-: The name of the resulting image.
+: The name of the generated image.
 
-    *Default:* `drv.name + "-env"`
+  _Default value:_ the value of `drv.name + "-env"`.
 
-`tag` _optional_
+`tag` (String or Null; _optional_)
 
 : Tag of the generated image.
+  If `null`, the hash of the nix derivation that builds the Docker image will be used as the tag.
 
-    *Default:* the resulting image derivation output path's hash
+  _Default value:_ `null`.
 
-`uid`/`gid` _optional_
+`uid` (Number; _optional_)
 
-: The user/group ID to run the container as. This is like a `nixbld` build user.
+: The user ID to run the container as.
+  This can be seen as a `nixbld` build user.
 
-    *Default:* 1000/1000
+  _Default value:_ 1000.
 
-`homeDirectory` _optional_
+`gid` (Number; _optional_)
+
+: The group ID to run the container as.
+  This can be seen as a `nixbld` build group.
 
-: The home directory of the user the container is running as
+  _Default value:_ 1000.
 
-    *Default:* `/build`
+`homeDirectory` (String; _optional_)
 
-`shell` _optional_
+: The home directory of the user the container is running as.
 
-: The path to the `bash` binary to use as the shell. This shell is started when running the image.
+  _Default value:_ `/build`.
 
-    *Default:* `pkgs.bashInteractive + "/bin/bash"`
+`shell` (String; _optional_)
 
-`command` _optional_
+: The path to the `bash` binary to use as the shell.
+  This shell is started when running the image.
+  This can be seen as an equivalent of the `NIX_BUILD_SHELL` [environment variable](https://nixos.org/manual/nix/stable/command-ref/nix-shell.html#environment-variables) for {manpage}`nix-shell(1)`.
 
-: Run this command in the environment of the derivation, in an interactive shell. See the `--command` option in the [`nix-shell` documentation](https://nixos.org/manual/nix/stable/command-ref/nix-shell.html?highlight=nix-shell#options).
+  _Default value:_ the `bash` binary from the `bashInteractive` package.
 
-    *Default:* (none)
+`command` (String or Null; _optional_)
 
-`run` _optional_
+: If specified, this command will be run in the environment of the derivation in an interactive shell.
+  A call to `exit` will be added after the command if it is specified, so the shell will exit after it's finished running.
+  This can be seen as an equivalent of the `--command` option in {manpage}`nix-shell(1)`.
 
-: Same as `command`, but runs the command in a non-interactive shell instead. See the `--run` option in the [`nix-shell` documentation](https://nixos.org/manual/nix/stable/command-ref/nix-shell.html?highlight=nix-shell#options).
+  _Default value:_ `null`.
 
-    *Default:* (none)
+`run` (String or Null; _optional_)
 
-### Example {#ssec-pkgs-dockerTools-buildNixShellImage-example}
+: Similar to the `command` attribute, but runs the command in a non-interactive shell instead.
+  A call to `exit` will be added after the command if it is specified, so the shell will exit after it's finished running.
+  This can be seen as an equivalent of the `--run` option in {manpage}`nix-shell(1)`.
+
+  _Default value:_ `null`.
 
-The following shows how to build the `pkgs.hello` package inside a Docker container built with `buildNixShellImage`.
+### Examples {#ssec-pkgs-dockerTools-streamNixShellImage-examples}
+
+:::{.example #ex-dockerTools-streamNixShellImage-hello}
+# Building a Docker image with `streamNixShellImage` with the build environment for the `hello` package
+
+This example shows how to build the `hello` package inside a Docker container built with `streamNixShellImage`.
+The Docker image generated will have a name like `hello-<version>-env` and tag `latest`.
+This example is the `streamNixShellImage` equivalent of [](#ex-dockerTools-buildNixShellImage-hello).
 
 ```nix
-with import <nixpkgs> {};
-dockerTools.buildNixShellImage {
+{ dockerTools, hello }:
+dockerTools.streamNixShellImage {
   drv = hello;
+  tag = "latest";
 }
 ```
 
-Build the derivation:
+The result of building this package is a script.
+Running this script and piping it into `docker load` gives you the same image that was built in [](#ex-dockerTools-buildNixShellImage-hello).
+
+```shell
+$ nix-build
+(some output removed for clarity)
+/nix/store/8vhznpz2frqazxnd8pgdvf38jscdypax-stream-hello-2.12.1-env
 
-```console
-nix-build hello.nix
+$ /nix/store/8vhznpz2frqazxnd8pgdvf38jscdypax-stream-hello-2.12.1-env | docker load
+(some output removed for clarity)
+Loaded image: hello-2.12.1-env:latest
 ```
 
-    these 8 derivations will be built:
-      /nix/store/xmw3a5ln29rdalavcxk1w3m4zb2n7kk6-nix-shell-rc.drv
-    ...
-    Creating layer 56 from paths: ['/nix/store/crpnj8ssz0va2q0p5ibv9i6k6n52gcya-stdenv-linux']
-    Creating layer 57 with customisation...
-    Adding manifests...
-    Done.
-    /nix/store/cpyn1lc897ghx0rhr2xy49jvyn52bazv-hello-2.12-env.tar.gz
+After starting an interactive container, the derivation can be built by running `buildDerivation`, and the output can be executed as expected:
 
-Load the image:
+```shell
+$ docker run -it hello-2.12.1-env:latest
+[nix-shell:~]$ buildDerivation
+Running phase: unpackPhase
+unpacking source archive /nix/store/pa10z4ngm0g83kx9mssrqzz30s84vq7k-hello-2.12.1.tar.gz
+source root is hello-2.12.1
+(some output removed for clarity)
+Running phase: fixupPhase
+shrinking RPATHs of ELF executables and libraries in /nix/store/f2vs29jibd7lwxyj35r9h87h6brgdysz-hello-2.12.1
+shrinking /nix/store/f2vs29jibd7lwxyj35r9h87h6brgdysz-hello-2.12.1/bin/hello
+checking for references to /build/ in /nix/store/f2vs29jibd7lwxyj35r9h87h6brgdysz-hello-2.12.1...
+gzipping man pages under /nix/store/f2vs29jibd7lwxyj35r9h87h6brgdysz-hello-2.12.1/share/man/
+patching script interpreter paths in /nix/store/f2vs29jibd7lwxyj35r9h87h6brgdysz-hello-2.12.1
+stripping (with command strip and flags -S -p) in  /nix/store/f2vs29jibd7lwxyj35r9h87h6brgdysz-hello-2.12.1/bin
+
+[nix-shell:~]$ $out/bin/hello
+Hello, world!
+```
+:::
+
+:::{.example #ex-dockerTools-streamNixShellImage-extendingBuildInputs}
+# Adding extra packages to a Docker image built with `streamNixShellImage`
+
+This example shows how to add extra packages to an image built with `streamNixShellImage`.
+In this case, we'll add the `cowsay` package.
+The Docker image generated will have a name like `hello-<version>-env` and tag `latest`.
+This example uses [](#ex-dockerTools-streamNixShellImage-hello) as a starting point.
 
-```console
-docker load -i result
+```nix
+{ dockerTools, cowsay, hello }:
+dockerTools.streamNixShellImage {
+  tag = "latest";
+  drv = hello.overrideAttrs (old: {
+    nativeBuildInputs = old.nativeBuildInputs or [] ++ [
+      cowsay
+    ];
+  });
+}
 ```
 
-    0d9f4c4cd109: Loading layer [==================================================>]   2.56MB/2.56MB
-    ...
-    ab1d897c0697: Loading layer [==================================================>]  10.24kB/10.24kB
-    Loaded image: hello-2.12-env:pgj9h98nal555415faa43vsydg161bdz
+The result of building this package is a script which can be run and piped into `docker load` to load the generated image.
+
+```shell
+$ nix-build
+(some output removed for clarity)
+/nix/store/h5abh0vljgzg381lna922gqknx6yc0v7-stream-hello-2.12.1-env
+
+$ /nix/store/h5abh0vljgzg381lna922gqknx6yc0v7-stream-hello-2.12.1-env | docker load
+(some output removed for clarity)
+Loaded image: hello-2.12.1-env:latest
+```
 
-Run the container:
+After starting an interactive container, we can verify the extra package is available by running `cowsay`:
 
-```console
-docker run -it hello-2.12-env:pgj9h98nal555415faa43vsydg161bdz
+```shell
+$ docker run -it hello-2.12.1-env:latest
+[nix-shell:~]$ cowsay "Hello, world!"
+ _______________
+< Hello, world! >
+ ---------------
+        \   ^__^
+         \  (oo)\_______
+            (__)\       )\/\
+                ||----w |
+                ||     ||
 ```
+:::
 
-    [nix-shell:/build]$
+:::{.example #ex-dockerTools-streamNixShellImage-addingShellHook}
+# Adding a `shellHook` to a Docker image built with `streamNixShellImage`
 
-In the running container, run the build:
+This example shows how to add a `shellHook` command to an image built with `streamNixShellImage`.
+In this case, we'll simply output the string `Hello, world!`.
+The Docker image generated will have a name like `hello-<version>-env` and tag `latest`.
+This example uses [](#ex-dockerTools-streamNixShellImage-hello) as a starting point.
 
-```console
-buildDerivation
+```nix
+{ dockerTools, hello }:
+dockerTools.streamNixShellImage {
+  tag = "latest";
+  drv = hello.overrideAttrs (old: {
+    shellHook = ''
+      ${old.shellHook or ""}
+      echo "Hello, world!"
+    '';
+  });
+}
 ```
 
-    unpacking sources
-    unpacking source archive /nix/store/8nqv6kshb3vs5q5bs2k600xpj5bkavkc-hello-2.12.tar.gz
-    ...
-    patching script interpreter paths in /nix/store/z5wwy5nagzy15gag42vv61c2agdpz2f2-hello-2.12
-    checking for references to /build/ in /nix/store/z5wwy5nagzy15gag42vv61c2agdpz2f2-hello-2.12...
+The result of building this package is a script which can be run and piped into `docker load` to load the generated image.
 
-Check the build result:
+```shell
+$ nix-build
+(some output removed for clarity)
+/nix/store/iz4dhdvgzazl5vrgyz719iwjzjy6xlx1-stream-hello-2.12.1-env
 
-```console
-$out/bin/hello
+$ /nix/store/iz4dhdvgzazl5vrgyz719iwjzjy6xlx1-stream-hello-2.12.1-env | docker load
+(some output removed for clarity)
+Loaded image: hello-2.12.1-env:latest
 ```
 
-    Hello, world!
+After starting an interactive container, we can see the result of the `shellHook`:
+
+```shell
+$ docker run -it hello-2.12.1-env:latest
+Hello, world!
+
+[nix-shell:~]$
+```
+:::
diff --git a/nixpkgs/doc/build-helpers/special.md b/nixpkgs/doc/build-helpers/special.md
index 265c2da92bf1..9da278f094dd 100644
--- a/nixpkgs/doc/build-helpers/special.md
+++ b/nixpkgs/doc/build-helpers/special.md
@@ -3,6 +3,7 @@
 This chapter describes several special build helpers.
 
 ```{=include=} sections
+special/fakenss.section.md
 special/fhs-environments.section.md
 special/makesetuphook.section.md
 special/mkshell.section.md
diff --git a/nixpkgs/doc/build-helpers/special/fakenss.section.md b/nixpkgs/doc/build-helpers/special/fakenss.section.md
new file mode 100644
index 000000000000..c890752c0653
--- /dev/null
+++ b/nixpkgs/doc/build-helpers/special/fakenss.section.md
@@ -0,0 +1,77 @@
+# fakeNss {#sec-fakeNss}
+
+Provides `/etc/passwd` and `/etc/group` files that contain `root` and `nobody`, allowing user/group lookups to work in binaries that insist on doing those.
+This might be a better choice than a custom script running `useradd` and related utilities if you only need those files to exist with some entries.
+
+`fakeNss` also provides `/etc/nsswitch.conf`, configuring NSS host resolution to first check `/etc/hosts` before checking DNS, since the default in the absence of a config file (`dns [!UNAVAIL=return] files`) is quite unexpected.
+
+It also creates an empty directory at `/var/empty` because it uses that as the home directory for the `root` and `nobody` users.
+The `/var/empty` directory can also be used as a `chroot` target to prevent file access in processes that do not need to access files, if your container runs such processes.
+
+The user entries created by `fakeNss` use the `/bin/sh` shell, which is not provided by `fakeNss` because in most cases it won't be used.
+If you need that to be available, see [`dockerTools.binSh`](#sssec-pkgs-dockerTools-helpers-binSh) or provide your own.
+
+## Inputs {#sec-fakeNss-inputs}
+
+`fakeNss` is made available in Nixpkgs as a package rather than a function, but it has two attributes that can be overridden and might be useful in particular cases.
+For more details on how overriding works, see [](#ex-fakeNss-overriding) and [](#sec-pkg-override).
+
+`extraPasswdLines` (List of Strings; _optional_)
+
+: A list of lines that will be added to `/etc/passwd`.
+  Useful if extra users need to exist in the output of `fakeNss`.
+  If `extraPasswdLines` is specified, it will **not** override the `root` and `nobody` entries created by `fakeNss`.
+  Those entries will always exist.
+
+  Lines specified here must follow the format in {manpage}`passwd(5)`.
+
+  _Default value:_ `[]`.
+
+`extraGroupLines` (List of Strings; _optional_)
+
+: A list of lines that will be added to `/etc/group`.
+  Useful if extra groups need to exist in the output of `fakeNss`.
+  If `extraGroupLines` is specified, it will **not** override the `root` and `nobody` entries created by `fakeNss`.
+  Those entries will always exist.
+
+  Lines specified here must follow the format in {manpage}`group(5)`.
+
+  _Default value:_ `[]`.
+
+## Examples {#sec-fakeNss-examples}
+
+:::{.example #ex-fakeNss-dockerTools-buildImage}
+# Using `fakeNss` with `dockerTools.buildImage`
+
+This example shows how to use `fakeNss` as-is.
+It is useful with functions in `dockerTools` to allow building Docker images that have the `/etc/passwd` and `/etc/group` files.
+This example includes the `hello` binary in the image so it can do something besides just have the extra files.
+
+```nix
+{ dockerTools, fakeNss, hello }:
+dockerTools.buildImage {
+  name = "image-with-passwd";
+  tag = "latest";
+
+  copyToRoot = [ fakeNss hello ];
+
+  config = {
+    Cmd = [ "/bin/hello" ];
+  };
+}
+```
+:::
+
+:::{.example #ex-fakeNss-overriding}
+# Using `fakeNss` with an override to add extra lines
+
+The following code uses `override` to add extra lines to `/etc/passwd` and `/etc/group` to create another user and group entry.
+
+```nix
+{ fakeNss }:
+fakeNss.override {
+  extraPasswdLines = ["newuser:x:9001:9001:new user:/var/empty:/bin/sh"];
+  extraGroupLines = ["newuser:x:9001:"];
+}
+```
+:::
diff --git a/nixpkgs/doc/build-helpers/trivial-build-helpers.chapter.md b/nixpkgs/doc/build-helpers/trivial-build-helpers.chapter.md
index 4648c7985542..384e25035060 100644
--- a/nixpkgs/doc/build-helpers/trivial-build-helpers.chapter.md
+++ b/nixpkgs/doc/build-helpers/trivial-build-helpers.chapter.md
@@ -502,9 +502,14 @@ concatScript "my-file" [ file1 file2 ]
 
 ## `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).
+`writeShellApplication` is similar to `writeShellScriptBin` and `writeScriptBin` but supports runtime dependencies with `runtimeInputs`.
+Writes an executable shell script to `/nix/store/<store path>/bin/<name>` and checks its syntax with [`shellcheck`](https://github.com/koalaman/shellcheck) and the `bash`'s `-n` option.
+Some basic Bash options are set by default (`errexit`, `nounset`, and `pipefail`), but can be overridden with `bashOptions`.
 
-For example, look at the following code:
+Extra arguments may be passed to `stdenv.mkDerivation` by setting `derivationArgs`; note that variables set in this manner will be set when the shell script is _built,_ not when it's run.
+Runtime environment variables can be set with the `runtimeEnv` argument.
+
+For example, the following shell application can refer to `curl` directly, rather than needing to write `${curl}/bin/curl`:
 
 ```nix
 writeShellApplication {
@@ -518,10 +523,6 @@ writeShellApplication {
 }
 ```
 
-Unlike with normal `writeShellScriptBin`, there is no need to manually write out `${curl}/bin/curl`, setting the PATH
-was handled by `writeShellApplication`. Moreover, the script is being checked with `shellcheck` for more strict
-validation.
-
 ## `symlinkJoin` {#trivial-builder-symlinkJoin}
 
 This can be used to put many derivations into the same directory structure. It works by creating a new derivation and adding symlinks to each of the paths listed. It expects two arguments, `name`, and `paths`. `name` is the name used in the Nix store path for the created derivation. `paths` is a list of paths that will be symlinked. These paths can be to Nix store derivations or any other subdirectory contained within.
diff --git a/nixpkgs/doc/default.nix b/nixpkgs/doc/default.nix
index 26aae9efa573..bcbc20b9f983 100644
--- a/nixpkgs/doc/default.nix
+++ b/nixpkgs/doc/default.nix
@@ -25,6 +25,7 @@ let
       { name = "gvariant"; description = "GVariant formatted string serialization functions"; }
       { name = "customisation"; description = "Functions to customise (derivation-related) functions, derivatons, or attribute sets"; }
       { name = "meta"; description = "functions for derivation metadata"; }
+      { name = "derivations"; description = "miscellaneous derivation-specific functions"; }
     ];
   };
 
diff --git a/nixpkgs/doc/doc-support/lib-function-docs.nix b/nixpkgs/doc/doc-support/lib-function-docs.nix
index 8592fafbbd15..5faa99b3e89e 100644
--- a/nixpkgs/doc/doc-support/lib-function-docs.nix
+++ b/nixpkgs/doc/doc-support/lib-function-docs.nix
@@ -29,7 +29,7 @@ stdenv.mkDerivation {
     mkdir -p "$out"
 
     cat > "$out/index.md" << 'EOF'
-    ```{=include=} sections
+    ```{=include=} sections auto-id-prefix=auto-generated
     EOF
 
     ${lib.concatMapStrings ({ name, baseName ? name, description }: ''
diff --git a/nixpkgs/doc/hooks/installShellFiles.section.md b/nixpkgs/doc/hooks/installShellFiles.section.md
index 84adea2fa30c..2567098116dd 100644
--- a/nixpkgs/doc/hooks/installShellFiles.section.md
+++ b/nixpkgs/doc/hooks/installShellFiles.section.md
@@ -2,7 +2,7 @@
 
 This hook helps with installing manpages and shell completion files. It exposes 2 shell functions `installManPage` and `installShellCompletion` that can be used from your `postInstall` hook.
 
-The `installManPage` function takes one or more paths to manpages to install. The manpages must have a section suffix, and may optionally be compressed (with `.gz` suffix). This function will place them into the correct directory.
+The `installManPage` function takes one or more paths to manpages to install. The manpages must have a section suffix, and may optionally be compressed (with `.gz` suffix). This function will place them into the correct `share/man/man<section>/` directory, in [`outputMan`](#outputman).
 
 The `installShellCompletion` function takes one or more paths to shell completion files. By default it will autodetect the shell type from the completion file extension, but you may also specify it by passing one of `--bash`, `--fish`, or `--zsh`. These flags apply to all paths listed after them (up until another shell flag is given). Each path may also have a custom installation name provided by providing a flag `--name NAME` before the path. If this flag is not provided, zsh completions will be renamed automatically such that `foobar.zsh` becomes `_foobar`. A root name may be provided for all paths using the flag `--cmd NAME`; this synthesizes the appropriate name depending on the shell (e.g. `--cmd foo` will synthesize the name `foo.bash` for bash and `_foo` for zsh). The path may also be a fifo or named fd (such as produced by `<(cmd)`), in which case the shell and name must be provided.
 
diff --git a/nixpkgs/doc/hooks/postgresql-test-hook.section.md b/nixpkgs/doc/hooks/postgresql-test-hook.section.md
index 8b37ca1e4b3e..59d7f7a644c9 100644
--- a/nixpkgs/doc/hooks/postgresql-test-hook.section.md
+++ b/nixpkgs/doc/hooks/postgresql-test-hook.section.md
@@ -45,6 +45,7 @@ Bash-only variables:
  - `postgresqlTestSetupCommands`: bash commands to run after database start, defaults to running `$postgresqlTestSetupSQL` as database administrator.
  - `postgresqlEnableTCP`: set to `1` to enable TCP listening. Flaky; not recommended.
  - `postgresqlStartCommands`: defaults to `pg_ctl start`.
+ - `postgresqlExtraSettings`: Additional configuration to add to `postgresql.conf`
 
 ## Hooks {#sec-postgresqlTestHook-hooks}
 
diff --git a/nixpkgs/doc/hooks/python.section.md b/nixpkgs/doc/hooks/python.section.md
index ecaae491e994..b7862650f167 100644
--- a/nixpkgs/doc/hooks/python.section.md
+++ b/nixpkgs/doc/hooks/python.section.md
@@ -1,3 +1,3 @@
 # Python {#setup-hook-python}
 
-Adds the `lib/${python.libPrefix}/site-packages` subdirectory of each build input to the `PYTHONPATH` environment variable.
+Adds the `python.sitePackages` subdirectory (i.e. `lib/pythonX.Y/site-packages`) of each build input to the `PYTHONPATH` environment variable.
diff --git a/nixpkgs/doc/languages-frameworks/beam.section.md b/nixpkgs/doc/languages-frameworks/beam.section.md
index 1e83d4b93c7c..992149090c63 100644
--- a/nixpkgs/doc/languages-frameworks/beam.section.md
+++ b/nixpkgs/doc/languages-frameworks/beam.section.md
@@ -216,7 +216,7 @@ in packages.mixRelease {
 Setup will require the following steps:
 
 - Move your secrets to runtime environment variables. For more information refer to the [runtime.exs docs](https://hexdocs.pm/mix/Mix.Tasks.Release.html#module-runtime-configuration). On a fresh Phoenix build that would mean that both `DATABASE_URL` and `SECRET_KEY` need to be moved to `runtime.exs`.
-- `cd assets` and `nix-shell -p node2nix --run node2nix --development` will generate a Nix expression containing your frontend dependencies
+- `cd assets` and `nix-shell -p node2nix --run "node2nix --development"` will generate a Nix expression containing your frontend dependencies
 - commit and push those changes
 - you can now `nix-build .`
 - To run the release, set the `RELEASE_TMP` environment variable to a directory that your program has write access to. It will be used to store the BEAM settings.
diff --git a/nixpkgs/doc/languages-frameworks/dart.section.md b/nixpkgs/doc/languages-frameworks/dart.section.md
index fca87fa70e4e..019765f75354 100644
--- a/nixpkgs/doc/languages-frameworks/dart.section.md
+++ b/nixpkgs/doc/languages-frameworks/dart.section.md
@@ -80,6 +80,8 @@ Do _not_ use `dart run <package_name>`, as this will attempt to download depende
 
 ### Usage with nix-shell {#ssec-dart-applications-nix-shell}
 
+#### Using dependencies from the Nix store {#ssec-dart-applications-nix-shell-deps}
+
 As `buildDartApplication` provides dependencies instead of `pub get`, Dart needs to be explicitly told where to find them.
 
 Run the following commands in the source directory to configure Dart appropriately.
@@ -101,7 +103,10 @@ See the [Dart documentation](#ssec-dart-applications) for more details on requir
 
 flutter.buildFlutterApplication {
   pname = "firmware-updater";
-  version = "unstable-2023-04-30";
+  version = "0-unstable-2023-04-30";
+
+  # To build for the Web, use the targetFlutterPlatform argument.
+  # targetFlutterPlatform = "web";
 
   src = fetchFromGitHub {
     owner = "canonical";
@@ -117,4 +122,15 @@ flutter.buildFlutterApplication {
 
 ### Usage with nix-shell {#ssec-dart-flutter-nix-shell}
 
-See the [Dart documentation](#ssec-dart-applications-nix-shell) for nix-shell instructions.
+Flutter-specific `nix-shell` usage notes are included here. See the [Dart documentation](#ssec-dart-applications-nix-shell) for general `nix-shell` instructions.
+
+#### Entering the shell {#ssec-dart-flutter-nix-shell-enter}
+
+By default, dependencies for only the `targetFlutterPlatform` are available in the
+build environment. This is useful for keeping closures small, but be problematic
+during development. It's common, for example, to build Web apps for Linux during
+development to take advantage of native features such as stateful hot reload.
+
+To enter a shell with all the usual target platforms available, use the `multiShell` attribute.
+
+e.g. `nix-shell '<nixpkgs>' -A fluffychat-web.multiShell`.
diff --git a/nixpkgs/doc/languages-frameworks/dotnet.section.md b/nixpkgs/doc/languages-frameworks/dotnet.section.md
index 978ec07cb961..7987aa41636c 100644
--- a/nixpkgs/doc/languages-frameworks/dotnet.section.md
+++ b/nixpkgs/doc/languages-frameworks/dotnet.section.md
@@ -93,7 +93,11 @@ 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` is used for specifying the dotnet project file, relative to the source root. These have `.sln` (entire solution) or `.csproj` (single project) file extensions. This can be a list of multiple projects as well. When omitted, will attempt to find and build the solution (`.sln`). If running into problems, make sure to set it to a file (or a list of files) with the `.csproj` extension - building applications as entire solutions is not fully supported by the .NET CLI.
-* `nugetDeps` takes either a path to a `deps.nix` file, or a derivation. The `deps.nix` file can be generated using the script attached to `passthru.fetch-deps`. This file can also be generated manually using `nuget-to-nix` tool, which is available in nixpkgs. If the argument is a derivation, it will be used directly and assume it has the same output as `mkNugetDeps`.
+* `nugetDeps` takes either a path to a `deps.nix` file, or a derivation. The `deps.nix` file can be generated using the script attached to `passthru.fetch-deps`. If the argument is a derivation, it will be used directly and assume it has the same output as `mkNugetDeps`.
+::: {.note}
+For more detail about managing the `deps.nix` file, see [Generating and updating NuGet dependencies](#generating-and-updating-nuget-dependencies)
+:::
+
 * `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:
@@ -144,7 +148,7 @@ in buildDotnetModule rec {
 
   projectReferences = [ referencedProject ]; # `referencedProject` must contain `nupkg` in the folder structure.
 
-  dotnet-sdk = dotnetCorePackages.sdk_6.0;
+  dotnet-sdk = dotnetCorePackages.sdk_6_0;
   dotnet-runtime = dotnetCorePackages.runtime_6_0;
 
   executables = [ "foo" ]; # This wraps "$out/lib/$pname/foo" to `$out/bin/foo`.
@@ -156,6 +160,8 @@ in buildDotnetModule rec {
 }
 ```
 
+Keep in mind that you can tag the [`@NixOS/dotnet`](https://github.com/orgs/nixos/teams/dotnet) team for help and code review.
+
 ## Dotnet global tools {#dotnet-global-tools}
 
 [.NET Global tools](https://learn.microsoft.com/en-us/dotnet/core/tools/global-tools) are a mechanism provided by the dotnet CLI to install .NET binaries from Nuget packages.
@@ -212,5 +218,43 @@ buildDotnetGlobalTool {
   };
 }
 ```
+## Generating and updating NuGet dependencies {#generating-and-updating-nuget-dependencies}
+
+First, restore the packages to the `out` directory, ensure you have cloned
+the upstream repository and you are inside it.
+
+```bash
+$ dotnet restore --packages out
+  Determining projects to restore...
+  Restored /home/lychee/Celeste64/Celeste64.csproj (in 1.21 sec).
+```
+
+Next, use `nuget-to-nix` tool provided in nixpkgs to generate a lockfile to `deps.nix` from
+the packages inside the `out` directory.
+
+```bash
+$ nuget-to-nix out > deps.nix
+```
+Which `nuget-to-nix` will generate an output similar to below
+```
+{ fetchNuGet }: [
+  (fetchNuGet { pname = "FosterFramework"; version = "0.1.15-alpha"; sha256 = "0pzsdfbsfx28xfqljcwy100xhbs6wyx0z1d5qxgmv3l60di9xkll"; })
+  (fetchNuGet { pname = "Microsoft.AspNetCore.App.Runtime.linux-x64"; version = "8.0.1"; sha256 = "1gjz379y61ag9whi78qxx09bwkwcznkx2mzypgycibxk61g11da1"; })
+  (fetchNuGet { pname = "Microsoft.NET.ILLink.Tasks"; version = "8.0.1"; sha256 = "1drbgqdcvbpisjn8mqfgba1pwb6yri80qc4mfvyczqwrcsj5k2ja"; })
+  (fetchNuGet { pname = "Microsoft.NETCore.App.Runtime.linux-x64"; version = "8.0.1"; sha256 = "1g5b30f4l8a1zjjr3b8pk9mcqxkxqwa86362f84646xaj4iw3a4d"; })
+  (fetchNuGet { pname = "SharpGLTF.Core"; version = "1.0.0-alpha0031"; sha256 = "0ln78mkhbcxqvwnf944hbgg24vbsva2jpih6q3x82d3h7rl1pkh6"; })
+  (fetchNuGet { pname = "SharpGLTF.Runtime"; version = "1.0.0-alpha0031"; sha256 = "0lvb3asi3v0n718qf9y367km7qpkb9wci38y880nqvifpzllw0jg"; })
+  (fetchNuGet { pname = "Sledge.Formats"; version = "1.2.2"; sha256 = "1y0l66m9rym0p1y4ifjlmg3j9lsmhkvbh38frh40rpvf1axn2dyh"; })
+  (fetchNuGet { pname = "Sledge.Formats.Map"; version = "1.1.5"; sha256 = "1bww60hv9xcyxpvkzz5q3ybafdxxkw6knhv97phvpkw84pd0jil6"; })
+  (fetchNuGet { pname = "System.Numerics.Vectors"; version = "4.5.0"; sha256 = "1kzrj37yzawf1b19jq0253rcs8hsq1l2q8g69d7ipnhzb0h97m59"; })
+]
+```
+
+Finally, you move the `deps.nix` file to the appropriate location to be used by `nugetDeps`, then you're all set!
+
+If you ever need to update the dependencies of a package, you instead do
+
+* `nix-build -A package.fetch-deps` to generate the update script for `package`
+* Run `./result deps.nix` to regenerate the lockfile to `deps.nix`, keep in mind if a location isn't provided, it will write to a temporary path instead
+* Finally, move the file where needed and look at its contents to confirm it has updated the dependencies.
 
-When packaging a new .NET application in nixpkgs, you can tag the [`@NixOS/dotnet`](https://github.com/orgs/nixos/teams/dotnet) team for help and code review.
diff --git a/nixpkgs/doc/languages-frameworks/emscripten.section.md b/nixpkgs/doc/languages-frameworks/emscripten.section.md
index 20d358f2e9e3..9ce48db2c2de 100644
--- a/nixpkgs/doc/languages-frameworks/emscripten.section.md
+++ b/nixpkgs/doc/languages-frameworks/emscripten.section.md
@@ -86,9 +86,9 @@ One advantage is that when `pkgs.zlib` is updated, it will automatically update
 
   postPatch = pkgs.lib.optionalString pkgs.stdenv.isDarwin ''
     substituteInPlace configure \
-      --replace '/usr/bin/libtool' 'ar' \
-      --replace 'AR="libtool"' 'AR="ar"' \
-      --replace 'ARFLAGS="-o"' 'ARFLAGS="-r"'
+      --replace-fail '/usr/bin/libtool' 'ar' \
+      --replace-fail 'AR="libtool"' 'AR="ar"' \
+      --replace-fail 'ARFLAGS="-o"' 'ARFLAGS="-r"'
   '';
 })
 ```
diff --git a/nixpkgs/doc/languages-frameworks/haskell.section.md b/nixpkgs/doc/languages-frameworks/haskell.section.md
index b0b5f5c3bb2f..bec72cb3c0d3 100644
--- a/nixpkgs/doc/languages-frameworks/haskell.section.md
+++ b/nixpkgs/doc/languages-frameworks/haskell.section.md
@@ -70,39 +70,42 @@ compilers like this:
 ```console
 $ nix-env -f '<nixpkgs>' -qaP -A haskell.compiler
 haskell.compiler.ghc810                  ghc-8.10.7
-haskell.compiler.ghc88                   ghc-8.8.4
 haskell.compiler.ghc90                   ghc-9.0.2
-haskell.compiler.ghc924                  ghc-9.2.4
 haskell.compiler.ghc925                  ghc-9.2.5
 haskell.compiler.ghc926                  ghc-9.2.6
-haskell.compiler.ghc92                   ghc-9.2.7
-haskell.compiler.ghc942                  ghc-9.4.2
-haskell.compiler.ghc943                  ghc-9.4.3
-haskell.compiler.ghc94                   ghc-9.4.4
-haskell.compiler.ghcHEAD                 ghc-9.7.20221224
-haskell.compiler.ghc8102Binary           ghc-binary-8.10.2
-haskell.compiler.ghc8102BinaryMinimal    ghc-binary-8.10.2
-haskell.compiler.ghc8107BinaryMinimal    ghc-binary-8.10.7
+haskell.compiler.ghc927                  ghc-9.2.7
+haskell.compiler.ghc92                   ghc-9.2.8
+haskell.compiler.ghc945                  ghc-9.4.5
+haskell.compiler.ghc946                  ghc-9.4.6
+haskell.compiler.ghc947                  ghc-9.4.7
+haskell.compiler.ghc94                   ghc-9.4.8
+haskell.compiler.ghc963                  ghc-9.6.3
+haskell.compiler.ghc96                   ghc-9.6.4
+haskell.compiler.ghc98                   ghc-9.8.1
+haskell.compiler.ghcHEAD                 ghc-9.9.20231121
 haskell.compiler.ghc8107Binary           ghc-binary-8.10.7
 haskell.compiler.ghc865Binary            ghc-binary-8.6.5
 haskell.compiler.ghc924Binary            ghc-binary-9.2.4
-haskell.compiler.ghc924BinaryMinimal     ghc-binary-9.2.4
-haskell.compiler.integer-simple.ghc810   ghc-integer-simple-8.10.7
 haskell.compiler.integer-simple.ghc8107  ghc-integer-simple-8.10.7
-haskell.compiler.integer-simple.ghc88    ghc-integer-simple-8.8.4
-haskell.compiler.integer-simple.ghc884   ghc-integer-simple-8.8.4
+haskell.compiler.integer-simple.ghc810   ghc-integer-simple-8.10.7
 haskell.compiler.native-bignum.ghc90     ghc-native-bignum-9.0.2
 haskell.compiler.native-bignum.ghc902    ghc-native-bignum-9.0.2
-haskell.compiler.native-bignum.ghc924    ghc-native-bignum-9.2.4
 haskell.compiler.native-bignum.ghc925    ghc-native-bignum-9.2.5
 haskell.compiler.native-bignum.ghc926    ghc-native-bignum-9.2.6
-haskell.compiler.native-bignum.ghc92     ghc-native-bignum-9.2.7
 haskell.compiler.native-bignum.ghc927    ghc-native-bignum-9.2.7
-haskell.compiler.native-bignum.ghc942    ghc-native-bignum-9.4.2
-haskell.compiler.native-bignum.ghc943    ghc-native-bignum-9.4.3
-haskell.compiler.native-bignum.ghc94     ghc-native-bignum-9.4.4
-haskell.compiler.native-bignum.ghc944    ghc-native-bignum-9.4.4
-haskell.compiler.native-bignum.ghcHEAD   ghc-native-bignum-9.7.20221224
+haskell.compiler.native-bignum.ghc92     ghc-native-bignum-9.2.8
+haskell.compiler.native-bignum.ghc928    ghc-native-bignum-9.2.8
+haskell.compiler.native-bignum.ghc945    ghc-native-bignum-9.4.5
+haskell.compiler.native-bignum.ghc946    ghc-native-bignum-9.4.6
+haskell.compiler.native-bignum.ghc947    ghc-native-bignum-9.4.7
+haskell.compiler.native-bignum.ghc94     ghc-native-bignum-9.4.8
+haskell.compiler.native-bignum.ghc948    ghc-native-bignum-9.4.8
+haskell.compiler.native-bignum.ghc963    ghc-native-bignum-9.6.3
+haskell.compiler.native-bignum.ghc96     ghc-native-bignum-9.6.4
+haskell.compiler.native-bignum.ghc964    ghc-native-bignum-9.6.4
+haskell.compiler.native-bignum.ghc98     ghc-native-bignum-9.8.1
+haskell.compiler.native-bignum.ghc981    ghc-native-bignum-9.8.1
+haskell.compiler.native-bignum.ghcHEAD   ghc-native-bignum-9.9.20231121
 haskell.compiler.ghcjs                   ghcjs-8.10.7
 ```
 
@@ -1226,10 +1229,12 @@ in
   in
 
   {
-    haskell = lib.recursiveUpdate prev.haskell {
-      compiler.${ghcName} = prev.haskell.compiler.${ghcName}.override {
-        # Unfortunately, the GHC setting is named differently for historical reasons
-        enableProfiledLibs = enableProfiling;
+    haskell = prev.haskell // {
+      compiler = prev.haskell.compiler // {
+        ${ghcName} = prev.haskell.compiler.${ghcName}.override {
+          # Unfortunately, the GHC setting is named differently for historical reasons
+          enableProfiledLibs = enableProfiling;
+        };
       };
     };
   })
@@ -1241,31 +1246,33 @@ in
   in
 
   {
-    haskell = lib.recursiveUpdate prev.haskell {
-      packages.${ghcName} = prev.haskell.packages.${ghcName}.override {
-        overrides = hfinal: hprev: {
-          mkDerivation = args: hprev.mkDerivation (args // {
-            # Since we are forcing our ideas upon mkDerivation, this change will
-            # affect every package in the package set.
-            enableLibraryProfiling = enableProfiling;
-
-            # To actually use profiling on an executable, executable profiling
-            # needs to be enabled for the executable you want to profile. You
-            # can either do this globally or…
-            enableExecutableProfiling = enableProfiling;
-          });
-
-          # …only for the package that contains an executable you want to profile.
-          # That saves on unnecessary rebuilds for packages that you only depend
-          # on for their library, but also contain executables (e.g. pandoc).
-          my-executable = haskellLib.enableExecutableProfiling hprev.my-executable;
-
-          # If you are disabling profiling to save on build time, but want to
-          # retain the ability to substitute from the binary cache. Drop the
-          # override for mkDerivation above and instead have an override like
-          # this for the specific packages you are building locally and want
-          # to make cheaper to build.
-          my-library = haskellLib.disableLibraryProfiling hprev.my-library;
+    haskell = prev.haskell // {
+      packages = prev.haskell.packages // {
+        ${ghcName} = prev.haskell.packages.${ghcName}.override {
+          overrides = hfinal: hprev: {
+            mkDerivation = args: hprev.mkDerivation (args // {
+              # Since we are forcing our ideas upon mkDerivation, this change will
+              # affect every package in the package set.
+              enableLibraryProfiling = enableProfiling;
+
+              # To actually use profiling on an executable, executable profiling
+              # needs to be enabled for the executable you want to profile. You
+              # can either do this globally or…
+              enableExecutableProfiling = enableProfiling;
+            });
+
+            # …only for the package that contains an executable you want to profile.
+            # That saves on unnecessary rebuilds for packages that you only depend
+            # on for their library, but also contain executables (e.g. pandoc).
+            my-executable = haskellLib.enableExecutableProfiling hprev.my-executable;
+
+            # If you are disabling profiling to save on build time, but want to
+            # retain the ability to substitute from the binary cache. Drop the
+            # override for mkDerivation above and instead have an override like
+            # this for the specific packages you are building locally and want
+            # to make cheaper to build.
+            my-library = haskellLib.disableLibraryProfiling hprev.my-library;
+          };
         };
       };
     };
diff --git a/nixpkgs/doc/languages-frameworks/idris2.section.md b/nixpkgs/doc/languages-frameworks/idris2.section.md
index 47bcbf46aee9..f1f0277cc609 100644
--- a/nixpkgs/doc/languages-frameworks/idris2.section.md
+++ b/nixpkgs/doc/languages-frameworks/idris2.section.md
@@ -2,7 +2,7 @@
 
 In addition to exposing the Idris2 compiler itself, Nixpkgs exposes an `idris2Packages.buildIdris` helper to make it a bit more ergonomic to build Idris2 executables or libraries.
 
-The `buildIdris` function takes a package set that defines at a minimum the `src` and `projectName` of the package to be built and any `idrisLibraries` required to build it. The `src` is the same source you're familiar with but the `projectName` must be the name of the `ipkg` file for the project (omitting the `.ipkg` extension). The `idrisLibraries` is a list of other library derivations created with `buildIdris`. You can optionally specify other derivation properties as needed but sensible defaults for `configurePhase`, `buildPhase`, and `installPhase` are provided.
+The `buildIdris` function takes an attribute set that defines at a minimum the `src` and `ipkgName` of the package to be built and any `idrisLibraries` required to build it. The `src` is the same source you're familiar with and the `ipkgName` must be the name of the `ipkg` file for the project (omitting the `.ipkg` extension). The `idrisLibraries` is a list of other library derivations created with `buildIdris`. You can optionally specify other derivation properties as needed but sensible defaults for `configurePhase`, `buildPhase`, and `installPhase` are provided.
 
 Importantly, `buildIdris` does not create a single derivation but rather an attribute set with two properties: `executable` and `library`. The `executable` property is a derivation and the `library` property is a function that will return a derivation for the library with or without source code included. Source code need not be included unless you are aiming to use IDE or LSP features that are able to jump to definitions within an editor.
 
@@ -10,7 +10,7 @@ A simple example of a fully packaged library would be the [`LSP-lib`](https://gi
 ```nix
 { fetchFromGitHub, idris2Packages }:
 let lspLibPkg = idris2Packages.buildIdris {
-  projectName = "lsp-lib";
+  ipkgName = "lsp-lib";
   src = fetchFromGitHub {
    owner = "idris-community";
    repo = "LSP-lib";
@@ -31,7 +31,7 @@ A slightly more involved example of a fully packaged executable would be the [`i
 # Assuming the previous example lives in `lsp-lib.nix`:
 let lspLib = callPackage ./lsp-lib.nix { };
     lspPkg = idris2Packages.buildIdris {
-      projectName = "idris2-lsp";
+      ipkgName = "idris2-lsp";
       src = fetchFromGitHub {
          owner = "idris-community";
          repo = "idris2-lsp";
diff --git a/nixpkgs/doc/languages-frameworks/qt.section.md b/nixpkgs/doc/languages-frameworks/qt.section.md
index 5d2850de3dca..1edceb53cfe4 100644
--- a/nixpkgs/doc/languages-frameworks/qt.section.md
+++ b/nixpkgs/doc/languages-frameworks/qt.section.md
@@ -3,72 +3,61 @@
 Writing Nix expressions for Qt libraries and applications is largely similar as for other C++ software.
 This section assumes some knowledge of the latter.
 
-The major caveat with Qt applications is that Qt uses a plugin system to load additional modules at runtime,
-from a list of well-known locations. In Nixpkgs, we patch QtCore to instead use an environment variable,
-and wrap Qt applications to set it to the right paths. This effectively makes the runtime dependencies
-pure and explicit at build-time, at the cost of introducing an extra indirection.
+The major caveat with Qt applications is that Qt uses a plugin system to load additional modules at runtime.
+In Nixpkgs, we wrap Qt applications to inject environment variables telling Qt where to discover the required plugins and QML modules.
+
+This effectively makes the runtime dependencies pure and explicit at build-time, at the cost of introducing
+an extra indirection.
 
 ## Nix expression for a Qt package (default.nix) {#qt-default-nix}
 
 ```nix
-{ stdenv, lib, qtbase, wrapQtAppsHook }:
+{ stdenv, lib, qt6, wrapQtAppsHook }:
 
 stdenv.mkDerivation {
   pname = "myapp";
   version = "1.0";
 
-  buildInputs = [ qtbase ];
-  nativeBuildInputs = [ wrapQtAppsHook ];
+  buildInputs = [ qt6.qtbase ];
+  nativeBuildInputs = [ qt6.wrapQtAppsHook ];
 }
 ```
 
-It is important to import Qt modules directly, that is: `qtbase`, `qtdeclarative`, etc. *Do not* import Qt package sets such as `qt5` because the Qt versions of dependencies may not be coherent, causing build and runtime failures.
-
-Additionally all Qt packages must include `wrapQtAppsHook` in `nativeBuildInputs`, or you must explicitly set `dontWrapQtApps`.
-
-`pkgs.callPackage` does not provide injections for `qtbase` or the like.
-Instead you want to either use `pkgs.libsForQt5.callPackage`, or `pkgs.qt6Packages.callPackage`, depending on the Qt version you want to use.
+Any Qt package should include `wrapQtAppsHook` in `nativeBuildInputs`, or explicitly set `dontWrapQtApps` to bypass generating the wrappers.
 
-For example (from [here](https://github.com/NixOS/nixpkgs/blob/2f9286912cb215969ece465147badf6d07aa43fe/pkgs/top-level/all-packages.nix#L30106))
+::: {.note}
+Graphical Linux applications should also include `qtwayland` in `buildInputs`, to ensure the Wayland platform plugin is available.
 
-```nix
-  zeal-qt5 = libsForQt5.callPackage ../data/documentation/zeal { };
-  zeal-qt6 = qt6Packages.callPackage ../data/documentation/zeal { };
-  zeal = zeal-qt5;
-```
+This may become default in the future, see [NixOS/nixpkgs#269674](https://github.com/NixOS/nixpkgs/pull/269674).
+:::
 
-## Locating runtime dependencies {#qt-runtime-dependencies}
+## Packages supporting multiple Qt versions {#qt-versions}
 
-Qt applications must be wrapped to find runtime dependencies.
-Include `wrapQtAppsHook` in `nativeBuildInputs`:
+If your package is a library that can be built with multiple Qt versions, you may want to take Qt modules as separate arguments (`qtbase`, `qtdeclarative` etc.), and invoke the package from `pkgs/top-level/qt5-packages.nix` or `pkgs/top-level/qt6-packages.nix` using the respective `callPackage` functions.
 
-```nix
-{ stdenv, wrapQtAppsHook }:
+Applications should generally be built with upstream's preferred Qt version.
 
-stdenv.mkDerivation {
-  # ...
-  nativeBuildInputs = [ wrapQtAppsHook ];
-}
-```
+## Locating additional runtime dependencies {#qt-runtime-dependencies}
 
 Add entries to `qtWrapperArgs` are to modify the wrappers created by
 `wrapQtAppsHook`:
 
 ```nix
-{ stdenv, wrapQtAppsHook }:
+{ stdenv, qt6 }:
 
 stdenv.mkDerivation {
   # ...
-  nativeBuildInputs = [ wrapQtAppsHook ];
+  nativeBuildInputs = [ qt6.wrapQtAppsHook ];
   qtWrapperArgs = [ ''--prefix PATH : /path/to/bin'' ];
 }
 ```
 
 The entries are passed as arguments to [wrapProgram](#fun-wrapProgram).
 
-Set `dontWrapQtApps` to stop applications from being wrapped automatically.
-Wrap programs manually with `wrapQtApp`, using the syntax of
-[wrapProgram](#fun-wrapProgram):
+If you need more control over the wrapping process, set `dontWrapQtApps` to disable automatic wrapper generation,
+and then create wrappers manually in `fixupPhase`, using `wrapQtApp`, which itself is a small wrapper over [wrapProgram](#fun-wrapProgram):
+
+The `makeWrapper` arguments required for Qt are also exposed in the environment as `$qtWrapperArgs`.
 
 ```nix
 { stdenv, lib, wrapQtAppsHook }:
diff --git a/nixpkgs/doc/languages-frameworks/rust.section.md b/nixpkgs/doc/languages-frameworks/rust.section.md
index a81ba1e456e8..72bade25a9fb 100644
--- a/nixpkgs/doc/languages-frameworks/rust.section.md
+++ b/nixpkgs/doc/languages-frameworks/rust.section.md
@@ -701,7 +701,7 @@ with import <nixpkgs> {};
     hello = attrs: lib.optionalAttrs (lib.versionAtLeast attrs.version "1.0")  {
       postPatch = ''
         substituteInPlace lib/zoneinfo.rs \
-          --replace "/usr/share/zoneinfo" "${tzdata}/share/zoneinfo"
+          --replace-fail "/usr/share/zoneinfo" "${tzdata}/share/zoneinfo"
       '';
     };
   };
diff --git a/nixpkgs/doc/manpage-urls.json b/nixpkgs/doc/manpage-urls.json
index d0fafa379a9f..5739a59d9420 100644
--- a/nixpkgs/doc/manpage-urls.json
+++ b/nixpkgs/doc/manpage-urls.json
@@ -314,5 +314,9 @@
   "systemd-veritysetup@.service(8)": "https://www.freedesktop.org/software/systemd/man/systemd-veritysetup@.service.html",
   "systemd-volatile-root(8)": "https://www.freedesktop.org/software/systemd/man/systemd-volatile-root.html",
   "systemd-xdg-autostart-generator(8)": "https://www.freedesktop.org/software/systemd/man/systemd-xdg-autostart-generator.html",
-  "udevadm(8)": "https://www.freedesktop.org/software/systemd/man/udevadm.html"
+  "udevadm(8)": "https://www.freedesktop.org/software/systemd/man/udevadm.html",
+  "passwd(5)": "https://man.archlinux.org/man/passwd.5",
+  "group(5)": "https://man.archlinux.org/man/group.5",
+  "login.defs(5)": "https://man.archlinux.org/man/login.defs.5",
+  "nix-shell(1)": "https://nixos.org/manual/nix/stable/command-ref/nix-shell.html"
 }
diff --git a/nixpkgs/doc/packages/linux.section.md b/nixpkgs/doc/packages/linux.section.md
index 0edf40043361..4c3b2a3b132a 100644
--- a/nixpkgs/doc/packages/linux.section.md
+++ b/nixpkgs/doc/packages/linux.section.md
@@ -12,20 +12,6 @@ Both functions have an argument `kernelPatches` which should be a list of `{name
 
 The kernel derivation created with `pkgs.buildLinux` exports an attribute `features` specifying whether optional functionality is or isn’t enabled. This is used in NixOS to implement kernel-specific behaviour.
 
-:::{.example #ex-skip-package-from-kernel-feature}
-
-# Skipping an external package because of a kernel feature
-
-For instance, if the kernel has the `iwlwifi` feature (i.e., has built-in support for Intel wireless chipsets), then NixOS doesn’t have to build the external `iwlwifi` package:
-
-```nix
-modulesTree = [kernel]
-  ++ pkgs.lib.optional (!kernel.features ? iwlwifi) kernelPackages.iwlwifi
-  ++ ...;
-```
-
-:::
-
 If you are using a kernel packaged in Nixpkgs, you can customize it by overriding its arguments. For details on how each argument affects the generated kernel, refer to [the `pkgs.buildLinux` source code](https://github.com/NixOS/nixpkgs/blob/d77bda728d5041c1294a68fb25c79e2d161f62b9/pkgs/os-specific/linux/kernel/generic.nix).
 
 :::{.example #ex-overriding-kernel-derivation}
diff --git a/nixpkgs/doc/preface.chapter.md b/nixpkgs/doc/preface.chapter.md
index 93cd1a00b4f2..e6a0905c5a95 100644
--- a/nixpkgs/doc/preface.chapter.md
+++ b/nixpkgs/doc/preface.chapter.md
@@ -27,18 +27,18 @@ With these expressions the Nix package manager can build binary packages.
 Packages, including the Nix packages collection, are distributed through
 [channels](https://nixos.org/nix/manual/#sec-channels). The collection is
 distributed for users of Nix on non-NixOS distributions through the channel
-`nixpkgs`. Users of NixOS generally use one of the `nixos-*` channels, e.g.
-`nixos-22.11`, which includes all packages and modules for the stable NixOS
+`nixpkgs-unstable`. Users of NixOS generally use one of the `nixos-*` channels,
+e.g. `nixos-22.11`, which includes all packages and modules for the stable NixOS
 22.11. Stable NixOS releases are generally only given
 security updates. More up to date packages and modules are available via the
 `nixos-unstable` channel.
 
-Both `nixos-unstable` and `nixpkgs` follow the `master` branch of the Nixpkgs
-repository, although both do lag the `master` branch by generally
+Both `nixos-unstable` and `nixpkgs-unstable` follow the `master` branch of the
+nixpkgs repository, although both do lag the `master` branch by generally
 [a couple of days](https://status.nixos.org/). Updates to a channel are
 distributed as soon as all tests for that channel pass, e.g.
 [this table](https://hydra.nixos.org/job/nixpkgs/trunk/unstable#tabs-constituents)
-shows the status of tests for the `nixpkgs` channel.
+shows the status of tests for the `nixpkgs-unstable` channel.
 
 The tests are conducted by a cluster called [Hydra](https://nixos.org/hydra/),
 which also builds binary packages from the Nix expressions in Nixpkgs for
@@ -46,5 +46,5 @@ which also builds binary packages from the Nix expressions in Nixpkgs for
 The binaries are made available via a [binary cache](https://cache.nixos.org).
 
 The current Nix expressions of the channels are available in the
-[`nixpkgs`](https://github.com/NixOS/nixpkgs) repository in branches
+[nixpkgs repository](https://github.com/NixOS/nixpkgs) in branches
 that correspond to the channel names (e.g. `nixos-22.11-small`).
diff --git a/nixpkgs/doc/stdenv/platform-notes.chapter.md b/nixpkgs/doc/stdenv/platform-notes.chapter.md
index b47f5af349b8..409c9f2e7b2e 100644
--- a/nixpkgs/doc/stdenv/platform-notes.chapter.md
+++ b/nixpkgs/doc/stdenv/platform-notes.chapter.md
@@ -54,7 +54,7 @@ Some common issues when packaging software for Darwin:
     # ...
     prePatch = ''
       substituteInPlace Makefile \
-          --replace '/usr/bin/xcrun clang' clang
+          --replace-fail '/usr/bin/xcrun clang' clang
     '';
   }
   ```
diff --git a/nixpkgs/doc/stdenv/stdenv.chapter.md b/nixpkgs/doc/stdenv/stdenv.chapter.md
index a5981d2efbe8..a948c6757c4a 100644
--- a/nixpkgs/doc/stdenv/stdenv.chapter.md
+++ b/nixpkgs/doc/stdenv/stdenv.chapter.md
@@ -230,9 +230,9 @@ stdenv.mkDerivation rec {
 
   postInstall = ''
     substituteInPlace $out/bin/solo5-virtio-mkimage \
-      --replace "/usr/lib/syslinux" "${syslinux}/share/syslinux" \
-      --replace "/usr/share/syslinux" "${syslinux}/share/syslinux" \
-      --replace "cp " "cp --no-preserve=mode "
+      --replace-fail "/usr/lib/syslinux" "${syslinux}/share/syslinux" \
+      --replace-fail "/usr/share/syslinux" "${syslinux}/share/syslinux" \
+      --replace-fail "cp " "cp --no-preserve=mode "
 
     wrapProgram $out/bin/solo5-virtio-mkimage \
       --prefix PATH : ${lib.makeBinPath [ dosfstools mtools parted syslinux ]}
@@ -1253,9 +1253,20 @@ postInstall = ''
 
 Performs string substitution on the contents of \<infile\>, writing the result to \<outfile\>. The substitutions in \<subs\> are of the following form:
 
-#### `--replace` \<s1\> \<s2\> {#fun-substitute-replace}
+#### `--replace-fail` \<s1\> \<s2\> {#fun-substitute-replace-fail}
 
 Replace every occurrence of the string \<s1\> by \<s2\>.
+Will error if no change is made.
+
+#### `--replace-warn` \<s1\> \<s2\> {#fun-substitute-replace-warn}
+
+Replace every occurrence of the string \<s1\> by \<s2\>.
+Will print a warning if no change is made.
+
+#### `--replace-quiet` \<s1\> \<s2\> {#fun-substitute-replace-quiet}
+
+Replace every occurrence of the string \<s1\> by \<s2\>.
+Will do nothing if no change can be made.
 
 #### `--subst-var` \<varName\> {#fun-substitute-subst-var}
 
@@ -1269,8 +1280,8 @@ Example:
 
 ```shell
 substitute ./foo.in ./foo.out \
-    --replace /usr/bin/bar $bar/bin/bar \
-    --replace "a string containing spaces" "some other text" \
+    --replace-fail /usr/bin/bar $bar/bin/bar \
+    --replace-fail "a string containing spaces" "some other text" \
     --subst-var someVar
 ```