push sheeet

doc/build-helpers/dev-shell-tools.chapter.md

@@ -0,0 +1,84 @@
+# Development Shell helpers {#chap-devShellTools}
+
+The `nix-shell` command has popularized the concept of transient shell environments for development or testing purposes.
+<!--
+  We should try to document the product, not its development process in the Nixpkgs reference manual,
+  but *something* needs to be said to provide context for this library.
+  This is the most future proof sentence I could come up with while Nix itself does yet make use of this.
+  Relevant is the current status of the devShell attribute "project": https://github.com/NixOS/nix/issues/7501
+  -->
+However, `nix-shell` is not the only way to create such environments, and even `nix-shell` itself can indirectly benefit from this library.
+
+This library provides a set of functions that help create such environments.
+
+## `devShellTools.valueToString` {#sec-devShellTools-valueToString}
+
+Converts Nix values to strings in the way the [`derivation` built-in function](https://nix.dev/manual/nix/2.23/language/derivations) does.
+
+:::{.example}
+## `valueToString` usage examples
+
+```nix
+devShellTools.valueToString (builtins.toFile "foo" "bar")
+# => "/nix/store/...-foo"
+```
+
+```nix
+devShellTools.valueToString false
+# => ""
+```
+
+:::
+
+## `devShellTools.unstructuredDerivationInputEnv` {#sec-devShellTools-unstructuredDerivationInputEnv}
+
+Convert a set of derivation attributes (as would be passed to [`derivation`]) to a set of environment variables that can be used in a shell script.
+This function does not support `__structuredAttrs`, but does support `passAsFile`.
+
+:::{.example}
+## `unstructuredDerivationInputEnv` usage example
+
+```nix
+devShellTools.unstructuredDerivationInputEnv {
+  drvAttrs = {
+    name = "foo";
+    buildInputs = [
+      hello
+      figlet
+    ];
+    builder = bash;
+    args = [
+      "-c"
+      "${./builder.sh}"
+    ];
+  };
+}
+# => {
+#  name = "foo";
+#  buildInputs = "/nix/store/...-hello /nix/store/...-figlet";
+#  builder = "/nix/store/...-bash";
+#}
+```
+
+Note that `args` is not included, because Nix does not added it to the builder process environment.
+
+:::
+
+## `devShellTools.derivationOutputEnv` {#sec-devShellTools-derivationOutputEnv}
+
+Takes the relevant parts of a derivation and returns a set of environment variables, that would be present in the derivation.
+
+:::{.example}
+## `derivationOutputEnv` usage example
+
+```nix
+let
+  pkg = hello;
+in
+devShellTools.derivationOutputEnv {
+  outputList = pkg.outputs;
+  outputMap = pkg;
+}
+```
+
+:::

doc/build-helpers/fixed-point-arguments.chapter.md

@@ -0,0 +1,70 @@
+# Fixed-point arguments of build helpers {#chap-build-helpers-finalAttrs}
+
+As mentioned in the beginning of this part, `stdenv.mkDerivation` could alternatively accept a fixed-point function. The input of this function, typically named `finalAttrs`, is expected to be the final state of the attribute set.  A build helper like this is said to accept **fixed-point arguments**.
+
+Build helpers don't always support fixed-point arguments yet, as support in [`stdenv.mkDerivation`](#mkderivation-recursive-attributes) was first included in Nixpkgs 22.05.
+
+## Defining a build helper with `lib.extendMkDerivation` {#sec-build-helper-extendMkDerivation}
+
+Developers can use the Nixpkgs library function [`lib.customisation.extendMkDerivation`](#function-library-lib.customisation.extendMkDerivation) to define a build helper supporting fixed-point arguments from an existing one with such support, with an attribute overlay similar to the one taken by [`<pkg>.overrideAttrs`](#sec-pkg-overrideAttrs).
+
+Besides overriding, `lib.extendMkDerivation` also supports `excludeDrvArgNames` to optionally exclude some arguments in the input fixed-point arguments from passing down the base build helper (specified as `constructDrv`).
+
+:::{.example #ex-build-helpers-extendMkDerivation}
+
+# Example definition of `mkLocalDerivation` extended from `stdenv.mkDerivation` with `lib.extendMkDerivation`
+
+We want to define a build helper named `mkLocalDerivation` that builds locally without using substitutes by default.
+
+Instead of taking a plain attribute set,
+
+```nix
+{
+  preferLocalBuild ? true,
+  allowSubstitute ? false,
+  specialArg ? (_: false),
+  ...
+}@args:
+
+stdenv.mkDerivation (
+  removeAttrs [
+    # Don't pass specialArg into mkDerivation.
+    "specialArg"
+  ] args
+  // {
+    # Arguments to pass
+    inherit preferLocalBuild allowSubstitute;
+    # Some expressions involving specialArg
+    greeting = if specialArg "hi" then "hi" else "hello";
+  }
+)
+```
+
+we could define with `lib.extendMkDerivation` an attribute overlay to make the result build helper also accept the attribute set's fixed point passing to the underlying `stdenv.mkDerivation`, named `finalAttrs` here:
+
+```nix
+lib.extendMkDerivation {
+  constructDrv = stdenv.mkDerivation;
+  excludeDrvArgNames = [
+    # Don't pass specialArg into mkDerivation.
+    "specialArg"
+  ];
+  extendDrvArgs =
+    finalAttrs:
+    {
+      preferLocalBuild ? true,
+      allowSubstitute ? false,
+      specialArg ? (_: false),
+      ...
+    }@args:
+    {
+      # Arguments to pass
+      inherit preferLocalBuild allowSubstitute;
+      # Some expressions involving specialArg
+      greeting = if specialArg "hi" then "hi" else "hello";
+    };
+}
+```
+:::
+
+If one needs to apply extra changes to the result derivation, pass the derivation transformation function to `lib.extendMkDerivation` as `lib.customisation.extendMkDerivation { transformDrv = drv: ...; }`.

doc/build-helpers/images.md

@@ -0,0 +1,12 @@
+# Images {#chap-images}
+
+This chapter describes tools for creating various types of images.
+
+```{=include=} sections
+images/appimagetools.section.md
+images/dockertools.section.md
+images/ocitools.section.md
+images/portableservice.section.md
+images/makediskimage.section.md
+images/binarycache.section.md
+```

doc/build-helpers/images/appimagetools.section.md

@@ -0,0 +1,176 @@
+# pkgs.appimageTools {#sec-pkgs-appimageTools}
+
+`pkgs.appimageTools` is a set of functions for extracting and wrapping [AppImage](https://appimage.org/) files.
+They are meant to be used if traditional packaging from source is infeasible, or if it would take too long.
+To quickly run an AppImage file, `pkgs.appimage-run` can be used as well.
+
+::: {.warning}
+The `appimageTools` API is unstable and may be subject to backwards-incompatible changes in the future.
+:::
+
+## Wrapping {#ssec-pkgs-appimageTools-wrapping}
+
+Use `wrapType2` to wrap any AppImage.
+This will create a FHS environment with many packages [expected to exist](https://github.com/AppImage/pkg2appimage/blob/master/excludelist) for the AppImage to work.
+`wrapType2` expects an argument with the `src` attribute, and either a `name` attribute or `pname` and `version` attributes.
+
+It will eventually call into [`buildFHSEnv`](#sec-fhs-environments), and any extra attributes in the argument to `wrapType2` will be passed through to it.
+This means that you can pass the `extraInstallCommands` attribute, for example, and it will have the same effect as described in [`buildFHSEnv`](#sec-fhs-environments).
+
+::: {.note}
+In the past, `appimageTools` provided both `wrapType1` and `wrapType2`, to be used depending on the type of AppImage that was being wrapped.
+However, [those were unified early 2020](https://github.com/NixOS/nixpkgs/pull/81833), meaning that both `wrapType1` and `wrapType2` have the same behaviour now.
+:::
+
+:::{.example #ex-wrapping-appimage-from-github}
+
+# Wrapping an AppImage from GitHub
+
+```nix
+{ appimageTools, fetchurl }:
+let
+  pname = "nuclear";
+  version = "0.6.30";
+
+  src = fetchurl {
+    url = "https://github.com/nukeop/nuclear/releases/download/v${version}/nuclear-v${version}.AppImage";
+    hash = "sha256-he1uGC1M/nFcKpMM9JKY4oeexJcnzV0ZRxhTjtJz6xw=";
+  };
+in
+appimageTools.wrapType2 { inherit pname version src; }
+```
+
+:::
+
+The argument passed to `wrapType2` can also contain an `extraPkgs` attribute, which allows you to include additional packages inside the FHS environment your AppImage is going to run in.
+`extraPkgs` must be a function that returns a list of packages.
+There are a few ways to learn which dependencies an application needs:
+
+  - Looking through the extracted AppImage files, reading its scripts and running `patchelf` and `ldd` on its executables.
+    This can also be done in `appimage-run`, by setting `APPIMAGE_DEBUG_EXEC=bash`.
+  - Running `strace -vfefile` on the wrapped executable, looking for libraries that can't be found.
+
+:::{.example #ex-wrapping-appimage-with-extrapkgs}
+
+# Wrapping an AppImage with extra packages
+
+```nix
+{ appimageTools, fetchurl }:
+let
+  pname = "irccloud";
+  version = "0.16.0";
+
+  src = fetchurl {
+    url = "https://github.com/irccloud/irccloud-desktop/releases/download/v${version}/IRCCloud-${version}-linux-x86_64.AppImage";
+    hash = "sha256-/hMPvYdnVB1XjKgU2v47HnVvW4+uC3rhRjbucqin4iI=";
+  };
+in
+appimageTools.wrapType2 {
+  inherit pname version src;
+  extraPkgs = pkgs: [ pkgs.at-spi2-core ];
+}
+```
+
+:::
+
+## Extracting {#ssec-pkgs-appimageTools-extracting}
+
+Use `extract` if you need to extract the contents of an AppImage.
+This is usually used in Nixpkgs to install extra files in addition to [wrapping](#ssec-pkgs-appimageTools-wrapping) the AppImage.
+`extract` expects an argument with the `src` attribute, and either a `name` attribute or `pname` and `version` attributes.
+
+::: {.note}
+In the past, `appimageTools` provided both `extractType1` and `extractType2`, to be used depending on the type of AppImage that was being extracted.
+However, [those were unified early 2020](https://github.com/NixOS/nixpkgs/pull/81572), meaning that both `extractType1` and `extractType2` have the same behaviour as `extract` now.
+:::
+
+:::{.example #ex-extracting-appimage}
+
+# Extracting an AppImage to install extra files
+
+This example was adapted from a real package in Nixpkgs to show how `extract` is usually used in combination with `wrapType2`.
+Note how `appimageContents` is used in `extraInstallCommands` to install additional files that were extracted from the AppImage.
+
+```nix
+{ appimageTools, fetchurl }:
+let
+  pname = "irccloud";
+  version = "0.16.0";
+
+  src = fetchurl {
+    url = "https://github.com/irccloud/irccloud-desktop/releases/download/v${version}/IRCCloud-${version}-linux-x86_64.AppImage";
+    hash = "sha256-/hMPvYdnVB1XjKgU2v47HnVvW4+uC3rhRjbucqin4iI=";
+  };
+
+  appimageContents = appimageTools.extract { inherit pname version src; };
+in
+appimageTools.wrapType2 {
+  inherit pname version src;
+
+  extraPkgs = pkgs: [ pkgs.at-spi2-core ];
+
+  extraInstallCommands = ''
+    mv $out/bin/irccloud-${version} $out/bin/irccloud
+    install -m 444 -D ${appimageContents}/irccloud.desktop $out/share/applications/irccloud.desktop
+    install -m 444 -D ${appimageContents}/usr/share/icons/hicolor/512x512/apps/irccloud.png \
+      $out/share/icons/hicolor/512x512/apps/irccloud.png
+    substituteInPlace $out/share/applications/irccloud.desktop \
+      --replace-fail 'Exec=AppRun' 'Exec=irccloud'
+  '';
+}
+```
+
+:::
+
+The argument passed to `extract` can also contain a `postExtract` attribute, which allows you to execute additional commands after the files are extracted from the AppImage.
+`postExtract` must be a string with commands to run.
+
+:::{.warning}
+When specifying `postExtract`, you should use `appimageTools.wrapAppImage` instead of `appimageTools.wrapType2`.
+Otherwise `wrapType2` will extract the AppImage contents without respecting the `postExtract` instructions.
+:::
+
+:::{.example #ex-extracting-appimage-with-postextract}
+
+# Extracting an AppImage to install extra files, using `postExtract`
+
+This is a rewrite of [](#ex-extracting-appimage) to use `postExtract` and `wrapAppImage`.
+
+```nix
+{ appimageTools, fetchurl }:
+let
+  pname = "irccloud";
+  version = "0.16.0";
+
+  src = fetchurl {
+    url = "https://github.com/irccloud/irccloud-desktop/releases/download/v${version}/IRCCloud-${version}-linux-x86_64.AppImage";
+    hash = "sha256-/hMPvYdnVB1XjKgU2v47HnVvW4+uC3rhRjbucqin4iI=";
+  };
+
+  appimageContents = appimageTools.extract {
+    inherit pname version src;
+    postExtract = ''
+      substituteInPlace $out/irccloud.desktop --replace-fail 'Exec=AppRun' 'Exec=irccloud'
+    '';
+  };
+in
+appimageTools.wrapAppImage {
+  inherit pname version;
+
+  src = appimageContents;
+
+  extraPkgs = pkgs: [ pkgs.at-spi2-core ];
+
+  extraInstallCommands = ''
+    mv $out/bin/irccloud-${version} $out/bin/irccloud
+    install -m 444 -D ${appimageContents}/irccloud.desktop $out/share/applications/irccloud.desktop
+    install -m 444 -D ${appimageContents}/usr/share/icons/hicolor/512x512/apps/irccloud.png \
+      $out/share/icons/hicolor/512x512/apps/irccloud.png
+  '';
+
+  # specify src archive for nix-update
+  passthru.src = src;
+}
+```
+
+:::

doc/build-helpers/images/binarycache.section.md

@@ -0,0 +1,63 @@
+# pkgs.mkBinaryCache {#sec-pkgs-binary-cache}
+
+`pkgs.mkBinaryCache` is a function for creating Nix flat-file binary caches.
+Such a cache exists as a directory on disk, and can be used as a Nix substituter by passing `--substituter file:///path/to/cache` to Nix commands.
+
+Nix packages are most commonly shared between machines using [HTTP, SSH, or S3](https://nixos.org/manual/nix/stable/package-management/sharing-packages.html), but a flat-file binary cache can still be useful in some situations.
+For example, you can copy it directly to another machine, or make it available on a network file system.
+It can also be a convenient way to make some Nix packages available inside a container via bind-mounting.
+
+`mkBinaryCache` expects an argument with the `rootPaths` attribute.
+`rootPaths` must be a list of derivations.
+The transitive closure of these derivations' outputs will be copied into the cache.
+
+## Optional arguments {#sec-pkgs-binary-cache-arguments}
+
+`compression` (`"none"` or `"xz"` or `"zstd"`; _optional_)
+
+: The compression algorithm to use.
+
+  _Default value:_ `zstd`.
+
+::: {.note}
+This function is meant for advanced use cases.
+The more idiomatic way to work with flat-file binary caches is via the [nix-copy-closure](https://nixos.org/manual/nix/stable/command-ref/nix-copy-closure.html) command.
+You may also want to consider [dockerTools](#sec-pkgs-dockerTools) for your containerization needs.
+:::
+
+[]{#sec-pkgs-binary-cache-example}
+:::{.example #ex-mkbinarycache-copying-package-closure}
+
+# Copying a package and its closure to another machine with `mkBinaryCache`
+
+The following derivation will construct a flat-file binary cache containing the closure of `hello`.
+
+```nix
+{ mkBinaryCache, hello }: mkBinaryCache { rootPaths = [ hello ]; }
+```
+
+Build the cache on a machine.
+Note that the command still builds the exact nix package above, but adds some boilerplate to build it directly from an expression.
+
+```shellSession
+$ nix-build -E 'let pkgs = import <nixpkgs> {}; in pkgs.callPackage ({ mkBinaryCache, hello }: mkBinaryCache { rootPaths = [hello]; }) {}'
+/nix/store/azf7xay5xxdnia4h9fyjiv59wsjdxl0g-binary-cache
+```
+
+Copy the resulting directory to another machine, which we'll call `host2`:
+
+```shellSession
+$ scp result host2:/tmp/hello-cache
+```
+
+At this point, the cache can be used as a substituter when building derivations on `host2`:
+
+```shellSession
+$ 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
+```
+
+:::

doc/build-helpers/images/makediskimage.section.md

@@ -0,0 +1,113 @@
+# `<nixpkgs/nixos/lib/make-disk-image.nix>` {#sec-make-disk-image}
+
+`<nixpkgs/nixos/lib/make-disk-image.nix>` is a function to create _disk images_ in multiple formats: raw, QCOW2 (QEMU), QCOW2-Compressed (compressed version), VDI (VirtualBox), VPC (VirtualPC).
+
+This function can create images in two ways:
+
+- using `cptofs` without any virtual machine to create a Nix store disk image,
+- using a virtual machine to create a full NixOS installation.
+
+When testing early-boot or lifecycle parts of NixOS such as a bootloader or multiple generations, it is necessary to opt for a full NixOS system installation.
+Whereas for many web servers, applications, it is possible to work with a Nix store only disk image and is faster to build.
+
+NixOS tests also use this function when preparing the VM. The `cptofs` method is used when `virtualisation.useBootLoader` is false (the default). Otherwise the second method is used.
+
+## Features {#sec-make-disk-image-features}
+
+For reference, read the function signature source code for documentation on arguments: <https://github.com/NixOS/nixpkgs/blob/master/nixos/lib/make-disk-image.nix>.
+Features are separated in various sections depending on if you opt for a Nix-store only image or a full NixOS image.
+
+### Common {#sec-make-disk-image-features-common}
+
+- arbitrary NixOS configuration
+- automatic or bound disk size: `diskSize` parameter, `additionalSpace` can be set when `diskSize` is `auto` to add a constant of disk space
+- multiple partition table layouts: EFI, legacy, legacy + GPT, hybrid, none through `partitionTableType` parameter
+- OVMF or EFI firmwares and variables templates can be customized
+- root filesystem `fsType` can be customized to whatever `mkfs.${fsType}` exists during operations
+- root filesystem label can be customized, defaults to `nix-store` if it's a Nix store image, otherwise `nixpkgs/nixos`
+- arbitrary code can be executed after disk image was produced with `postVM`
+- the current nixpkgs can be realized as a channel in the disk image, which will change the hash of the image when the sources are updated
+- additional store paths can be provided through `additionalPaths`
+
+### Full NixOS image {#sec-make-disk-image-features-full-image}
+
+- arbitrary contents with permissions can be placed in the target filesystem using `contents`
+- a `/etc/nixpkgs/nixos/configuration.nix` can be provided through `configFile`
+- bootloaders are supported
+- EFI variables can be mutated during image production and the result is exposed in `$out`
+- boot partition size when partition table is `efi` or `hybrid`
+
+### On bit-to-bit reproducibility {#sec-make-disk-image-features-reproducibility}
+
+Images are **NOT** deterministic, please do not hesitate to try to fix this, source of determinisms are (not exhaustive) :
+
+- bootloader installation has timestamps
+- SQLite Nix store database contains registration times
+- `/etc/shadow` is in a non-deterministic order
+
+A `deterministic` flag is available for best efforts determinism.
+
+## Usage {#sec-make-disk-image-usage}
+
+To produce a Nix-store only image:
+```nix
+let
+  pkgs = import <nixpkgs> { };
+  lib = pkgs.lib;
+  make-disk-image = import <nixpkgs/nixos/lib/make-disk-image.nix>;
+in
+make-disk-image {
+  inherit pkgs lib;
+  config = { };
+  additionalPaths = [ ];
+  format = "qcow2";
+  onlyNixStore = true;
+  partitionTableType = "none";
+  installBootLoader = false;
+  touchEFIVars = false;
+  diskSize = "auto";
+  additionalSpace = "0M"; # Defaults to 512M.
+  copyChannel = false;
+}
+```
+
+Some arguments can be left out, they are shown explicitly for the sake of the example.
+
+Building this derivation will provide a QCOW2 disk image containing only the Nix store and its registration information.
+
+To produce a NixOS installation image disk with UEFI and bootloader installed:
+```nix
+let
+  pkgs = import <nixpkgs> { };
+  lib = pkgs.lib;
+  make-disk-image = import <nixpkgs/nixos/lib/make-disk-image.nix>;
+  evalConfig = import <nixpkgs/nixos/lib/eval-config.nix>;
+in
+make-disk-image {
+  inherit pkgs lib;
+  inherit
+    (evalConfig {
+      modules = [
+        {
+          fileSystems."/" = {
+            device = "/dev/vda";
+            fsType = "ext4";
+            autoFormat = true;
+          };
+          boot.grub.device = "/dev/vda";
+        }
+      ];
+    })
+    config
+    ;
+  format = "qcow2";
+  onlyNixStore = false;
+  partitionTableType = "legacy+gpt";
+  installBootLoader = true;
+  touchEFIVars = true;
+  diskSize = "auto";
+  additionalSpace = "0M"; # Defaults to 512M.
+  copyChannel = false;
+  memSize = 2048; # Qemu VM memory size in MiB (1024*1024 bytes). Defaults to 1024M.
+}
+```

doc/build-helpers/images/ocitools.section.md

@@ -0,0 +1,106 @@
+# pkgs.ociTools {#sec-pkgs-ociTools}
+
+`pkgs.ociTools` is a set of functions for creating runtime container bundles according to the [OCI runtime specification v1.0.0](https://github.com/opencontainers/runtime-spec/blob/v1.0.0/spec.md).
+It makes no assumptions about the container runner you choose to use to run the created container.
+
+The set of functions in `pkgs.ociTools` currently does not handle the [OCI image specification](https://github.com/opencontainers/image-spec).
+
+At a high-level an OCI implementation would download an OCI Image then unpack that image into an OCI Runtime filesystem bundle.
+At this point the OCI Runtime Bundle would be run by an OCI Runtime.
+`pkgs.ociTools` provides utilities to create OCI Runtime bundles.
+
+## buildContainer {#ssec-pkgs-ociTools-buildContainer}
+
+This function creates an OCI runtime container (consisting of a `config.json` and a root filesystem directory) that runs a single command inside of it.
+The nix store of the container will contain all referenced dependencies of the given command.
+
+This function has an assumption that the container will run on POSIX platforms, and sets configurations (such as the user running the process or certain mounts) according to this assumption.
+Because of this, a container built with `buildContainer` will not work on Windows or other non-POSIX platforms without modifications to the container configuration.
+These modifications aren't supported by `buildContainer`.
+
+For `linux` platforms, `buildContainer` also configures the following namespaces (see {manpage}`unshare(1)`) to isolate the OCI container from the global namespace:
+PID, network, mount, IPC, and UTS.
+
+Note that no user namespace is created, which means that you won't be able to run the container unless you are the `root` user.
+
+### Inputs {#ssec-pkgs-ociTools-buildContainer-inputs}
+
+`buildContainer` expects an argument with the following attributes:
+
+`args` (List of String)
+
+: Specifies a set of arguments to run inside the container.
+  Any packages referenced by `args` will be made available inside the container.
+
+`mounts` (Attribute Set; _optional_)
+
+: Would specify additional mounts that the runtime must make available to the container.
+
+  :::{.warning}
+  As explained in [issue #290879](https://github.com/NixOS/nixpkgs/issues/290879), this attribute is currently ignored.
+  :::
+
+  :::{.note}
+  `buildContainer` includes a minimal set of necessary filesystems to be mounted into the container, and this set can't be changed with the `mounts` attribute.
+  :::
+
+  _Default value:_ `{}`.
+
+`readonly` (Boolean; _optional_)
+
+: If `true`, sets the container's root filesystem as read-only.
+
+  _Default value:_ `false`.
+
+`os` **DEPRECATED**
+
+: Specifies the operating system on which the container filesystem is based on.
+  If specified, its value should follow the [OCI Image Configuration Specification](https://github.com/opencontainers/image-spec/blob/main/config.md#properties).
+  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` **DEPRECATED**
+
+: Used to specify the architecture for which the binaries in the container filesystem have been compiled.
+  If specified, its value should follow the [OCI Image Configuration Specification](https://github.com/opencontainers/image-spec/blob/main/config.md#properties).
+  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:_ `x86_64`.
+
+### Examples {#ssec-pkgs-ociTools-buildContainer-examples}
+
+::: {.example #ex-ociTools-buildContainer-bash}
+# Creating an OCI runtime container that runs `bash`
+
+This example uses `ociTools.buildContainer` to create a simple container that runs `bash`.
+
+```nix
+{
+  ociTools,
+  lib,
+  bash,
+}:
+ociTools.buildContainer {
+  args = [ (lib.getExe bash) ];
+
+  readonly = false;
+}
+```
+
+As an example of how to run the container generated by this package, we'll use `runc` to start the container.
+Any other tool that supports OCI containers could be used instead.
+
+```shell
+$ nix-build
+(some output removed for clarity)
+/nix/store/7f9hgx0arvhzp2a3qphp28rxbn748l25-join
+
+$ cd /nix/store/7f9hgx0arvhzp2a3qphp28rxbn748l25-join
+$ nix-shell -p runc
+[nix-shell:/nix/store/7f9hgx0arvhzp2a3qphp28rxbn748l25-join]$ sudo runc run ocitools-example
+help
+GNU bash, version 5.2.26(1)-release (x86_64-pc-linux-gnu)
+(some output removed for clarity)
+```
+:::

doc/build-helpers/images/portableservice.section.md

@@ -0,0 +1,188 @@
+# pkgs.portableService {#sec-pkgs-portableService}
+
+`pkgs.portableService` is a function to create [Portable Services](https://systemd.io/PORTABLE_SERVICES/) in a read-only, immutable, `squashfs` raw disk image.
+This lets you use Nix to build images which can be run on many recent Linux distributions.
+
+::: {.note}
+Portable services are supported starting with systemd 239 (released on 2018-06-22).
+:::
+
+The generated image will contain the file system structure as required by the Portable Services specification, along with the packages given to `portableService` and all of their dependencies.
+When generated, the image will exist in the Nix store with the `.raw` file extension, as required by the specification.
+See [](#ex-portableService-hello) to understand how to use the output of `portableService`.
+
+## Inputs {#ssec-pkgs-portableService-inputs}
+
+`portableService` expects one argument with the following attributes:
+
+`pname` (String)
+
+: The name of the portable service.
+  The generated image will be named according to the template `$pname_$version.raw`, which is supported by the Portable Services specification.
+
+`version` (String)
+
+: The version of the portable service.
+  The generated image will be named according to the template `$pname_$version.raw`, which is supported by the Portable Services specification.
+
+`units` (List of Attribute Set)
+
+: A list of derivations for systemd unit files.
+  Each derivation must produce a single file, and must have a name that starts with the value of `pname` and ends with the suffix of the unit type (e.g. ".service", ".socket", ".timer", and so on).
+  See [](#ex-portableService-hello) to better understand this naming constraint.
+
+`description` (String or Null; _optional_)
+
+: If specified, the value is added as `PORTABLE_PRETTY_NAME` to the `/etc/os-release` file in the generated image.
+  This could be used to provide more information to anyone inspecting the image.
+
+  _Default value:_ `null`.
+
+`homepage` (String or Null; _optional_)
+
+: If specified, the value is added as `HOME_URL` to the `/etc/os-release` file in the generated image.
+  This could be used to provide more information to anyone inspecting the image.
+
+  _Default value:_ `null`.
+
+`symlinks` (List of Attribute Set; _optional_)
+
+: A list of attribute sets in the format `{object, symlink}`.
+  For each item in the list, `portableService` will create a symlink in the path specified by `symlink` (relative to the root of the image) that points to `object`.
+
+  All packages that `object` depends on and their dependencies are automatically copied into the image.
+
+  This can be used to create symlinks for applications that assume some files to exist globally (`/etc/ssl` or `/bin/bash`, for example).
+  See [](#ex-portableService-symlinks) to understand how to do that.
+
+  _Default value:_ `[]`.
+
+`contents` (List of Attribute Set; _optional_)
+
+: A list of additional derivations to be included as-is in the image.
+  These derivations will be included directly in a `/nix/store` directory inside the image.
+
+  _Default value:_ `[]`.
+
+`squashfsTools` (Attribute Set; _optional_)
+
+: Allows you to override the package that provides {manpage}`mksquashfs(1)`, which is used internally by `portableService`.
+
+  _Default value:_ `pkgs.squashfsTools`.
+
+`squash-compression` (String; _optional_)
+
+: Passed as the compression option to {manpage}`mksquashfs(1)`, which is used internally by `portableService`.
+
+  _Default value:_ `"xz -Xdict-size 100%"`.
+
+`squash-block-size` (String; _optional_)
+
+: Passed as the block size option to {manpage}`mksquashfs(1)`, which is used internally by `portableService`.
+
+  _Default value:_ `"1M"`.
+
+## Examples {#ssec-pkgs-portableService-examples}
+
+[]{#ex-pkgs-portableService}
+:::{.example #ex-portableService-hello}
+# Building a Portable Service image
+
+The following example builds a Portable Service image with the `hello` package, along with a service unit that runs it.
+
+```nix
+{
+  lib,
+  writeText,
+  portableService,
+  hello,
+}:
+let
+  hello-service = writeText "hello.service" ''
+    [Unit]
+    Description=Hello world service
+
+    [Service]
+    Type=oneshot
+    ExecStart=${lib.getExe hello}
+  '';
+in
+portableService {
+  pname = "hello";
+  inherit (hello) version;
+  units = [ hello-service ];
+}
+```
+
+After building the package, the generated image can be loaded into a system through {manpage}`portablectl(1)`:
+
+```shell
+$ nix-build
+(some output removed for clarity)
+/nix/store/8c20z1vh7z8w8dwagl8w87b45dn5k6iq-hello-img-2.12.1
+
+$ portablectl attach /nix/store/8c20z1vh7z8w8dwagl8w87b45dn5k6iq-hello-img-2.12.1/hello_2.12.1.raw
+Created directory /etc/systemd/system.attached.
+Created directory /etc/systemd/system.attached/hello.service.d.
+Written /etc/systemd/system.attached/hello.service.d/20-portable.conf.
+Created symlink /etc/systemd/system.attached/hello.service.d/10-profile.conf → /usr/lib/systemd/portable/profile/default/service.conf.
+Copied /etc/systemd/system.attached/hello.service.
+Created symlink /etc/portables/hello_2.12.1.raw → /nix/store/8c20z1vh7z8w8dwagl8w87b45dn5k6iq-hello-img-2.12.1/hello_2.12.1.raw.
+
+$ systemctl start hello
+$ journalctl -u hello
+Feb 28 22:39:16 hostname systemd[1]: Starting Hello world service...
+Feb 28 22:39:16 hostname hello[102887]: Hello, world!
+Feb 28 22:39:16 hostname systemd[1]: hello.service: Deactivated successfully.
+Feb 28 22:39:16 hostname systemd[1]: Finished Hello world service.
+
+$ portablectl detach hello_2.12.1
+Removed /etc/systemd/system.attached/hello.service.
+Removed /etc/systemd/system.attached/hello.service.d/10-profile.conf.
+Removed /etc/systemd/system.attached/hello.service.d/20-portable.conf.
+Removed /etc/systemd/system.attached/hello.service.d.
+Removed /etc/portables/hello_2.12.1.raw.
+Removed /etc/systemd/system.attached.
+```
+:::
+
+:::{.example #ex-portableService-symlinks}
+# Specifying symlinks when building a Portable Service image
+
+Some services may expect files or directories to be available globally.
+An example is a service which expects all trusted SSL certificates to exist in a specific location by default.
+
+To make things available globally, you must specify the `symlinks` attribute when using `portableService`.
+The following package builds on the package from [](#ex-portableService-hello) to make `/etc/ssl` available globally (this is only for illustrative purposes, because `hello` doesn't use `/etc/ssl`).
+
+```nix
+{
+  lib,
+  writeText,
+  portableService,
+  hello,
+  cacert,
+}:
+let
+  hello-service = writeText "hello.service" ''
+    [Unit]
+    Description=Hello world service
+
+    [Service]
+    Type=oneshot
+    ExecStart=${lib.getExe hello}
+  '';
+in
+portableService {
+  pname = "hello";
+  inherit (hello) version;
+  units = [ hello-service ];
+  symlinks = [
+    {
+      object = "${cacert}/etc/ssl";
+      symlink = "/etc/ssl";
+    }
+  ];
+}
+```
+:::

doc/build-helpers/special.md

@@ -0,0 +1,12 @@
+# Special build helpers {#chap-special}
+
+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
+special/vm-tools.section.md
+special/checkpoint-build.section.md
+```

doc/build-helpers/special/checkpoint-build.section.md

@@ -0,0 +1,41 @@
+# pkgs.checkpointBuildTools  {#sec-checkpoint-build}
+
+`pkgs.checkpointBuildTools` provides a way to build derivations incrementally. It consists of two functions to make checkpoint builds using Nix possible.
+
+For hermeticity, Nix derivations do not allow any state to be carried over between builds, making a transparent incremental build within a derivation impossible.
+
+However, we can tell Nix explicitly what the previous build state was, by representing that previous state as a derivation output. This allows the passed build state to be used for an incremental build.
+
+To change a normal derivation to a checkpoint based build, these steps must be taken:
+  ```nix
+  {
+    checkpointArtifacts = (pkgs.checkpointBuildTools.prepareCheckpointBuild pkgs.virtualbox);
+  }
+  ```
+  ```nix
+  {
+    changedVBox = pkgs.virtualbox.overrideAttrs (old: {
+      src = path/to/vbox/sources;
+    });
+  }
+  ```
+  - use `mkCheckpointBuild changedVBox checkpointArtifacts`
+  - enjoy shorter build times
+
+## Example {#sec-checkpoint-build-example}
+```nix
+{
+  pkgs ? import <nixpkgs> { },
+}:
+let
+  inherit (pkgs.checkpointBuildTools) prepareCheckpointBuild mkCheckpointBuild;
+  helloCheckpoint = prepareCheckpointBuild pkgs.hello;
+  changedHello = pkgs.hello.overrideAttrs (_: {
+    doCheck = false;
+    postPatch = ''
+      sed -i 's/Hello, world!/Hello, Nix!/g' src/hello.c
+    '';
+  });
+in
+mkCheckpointBuild changedHello helloCheckpoint
+```

doc/build-helpers/special/fakenss.section.md

@@ -0,0 +1,84 @@
+# 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:" ];
+}
+```
+:::

doc/build-helpers/special/fhs-environments.section.md

@@ -0,0 +1,69 @@
+# buildFHSEnv {#sec-fhs-environments}
+
+`buildFHSEnv` provides a way to build and run an FHS-compatible, lightweight sandbox. It creates an isolated root filesystem with the host's `/nix/store`, so its footprint in terms of disk space is quite small. This allows you to run software which is hard or unfeasible to patch for NixOS; 3rd-party source trees with FHS assumptions, games distributed as tarballs, software with integrity checking and/or external self-updated binaries for instance.
+It uses Linux' namespaces feature to create temporary lightweight environments which are destroyed after all child processes exit, without requiring elevated privileges. It works similar to containerisation technology such as Docker or FlatPak but provides no security-relevant separation from the host system.
+
+Accepted arguments are:
+
+- `name`
+        The name of the environment.
+- `pname`
+        The pname of the environment.
+- `version`
+        The version of the environment.
+- `executableName`
+        The name of the wrapper executable. Defaults to `pname` if set, or `name` otherwise.
+- `targetPkgs`
+        Packages to be installed for the main host's architecture (i.e. x86_64 on x86_64 installations). Along with libraries binaries are also installed.
+- `multiPkgs`
+        Packages to be installed for all architectures supported by a host (i.e. i686 and x86_64 on x86_64 installations). Only libraries are installed by default.
+- `multiArch`
+        Whether to install 32bit multiPkgs into the FHSEnv in 64bit environments
+- `extraBuildCommands`
+        Additional commands to be executed for finalizing the directory structure.
+- `extraBuildCommandsMulti`
+        Like `extraBuildCommands`, but executed only on multilib architectures.
+- `extraOutputsToInstall`
+        Additional derivation outputs to be linked for both target and multi-architecture packages.
+- `extraInstallCommands`
+        Additional commands to be executed for finalizing the derivation with runner script.
+- `runScript`
+        A shell command to be executed inside the sandbox. It defaults to `bash`. Command line arguments passed to the resulting wrapper are appended to this command by default.
+        This command must be escaped; i.e. `"foo app" --do-stuff --with "some file"`. See `lib.escapeShellArgs`.
+- `profile`
+        Optional script for `/etc/profile` within the sandbox.
+
+You can create a simple environment using a `shell.nix` like this:
+
+```nix
+{
+  pkgs ? import <nixpkgs> { },
+}:
+
+(pkgs.buildFHSEnv {
+  name = "simple-x11-env";
+  targetPkgs =
+    pkgs:
+    (with pkgs; [
+      udev
+      alsa-lib
+    ])
+    ++ (with pkgs.xorg; [
+      libX11
+      libXcursor
+      libXrandr
+    ]);
+  multiPkgs =
+    pkgs:
+    (with pkgs; [
+      udev
+      alsa-lib
+    ]);
+  runScript = "bash";
+}).env
+```
+
+Running `nix-shell` on it would drop you into a shell inside an FHS env where those libraries and binaries are available in FHS-compliant paths. Applications that expect an FHS structure (i.e. proprietary binaries) can run inside this environment without modification.
+You can build a wrapper by running your binary in `runScript`, e.g. `./bin/start.sh`. Relative paths work as expected.
+
+Additionally, the FHS builder links all relocated gsettings-schemas (the glib setup-hook moves them to `share/gsettings-schemas/${name}/glib-2.0/schemas`) to their standard FHS location. This means you don't need to wrap binaries with `wrapGApps*` hook.

doc/build-helpers/special/makesetuphook.section.md

@@ -0,0 +1,55 @@
+# pkgs.makeSetupHook {#sec-pkgs.makeSetupHook}
+
+`pkgs.makeSetupHook` is a build helper that produces hooks that go in to `nativeBuildInputs`
+
+## Usage {#sec-pkgs.makeSetupHook-usage}
+
+```nix
+pkgs.makeSetupHook {
+  name = "something-hook";
+  propagatedBuildInputs = [ pkgs.commandsomething ];
+  depsTargetTargetPropagated = [ pkgs.libsomething ];
+} ./script.sh
+```
+
+### setup hook that depends on the hello package and runs hello and @shell@ is substituted with path to bash {#sec-pkgs.makeSetupHook-usage-example}
+
+```nix
+pkgs.makeSetupHook
+  {
+    name = "run-hello-hook";
+    # Put dependencies here if they have hooks or necessary dependencies propagated
+    # otherwise prefer direct paths to executables.
+    propagatedBuildInputs = [
+      pkgs.hello
+      pkgs.cowsay
+    ];
+    substitutions = {
+      shell = "${pkgs.bash}/bin/bash";
+      cowsay = "${pkgs.cowsay}/bin/cowsay";
+    };
+  }
+  (
+    writeScript "run-hello-hook.sh" ''
+      #!@shell@
+      # the direct path to the executable has to be here because
+      # this will be run when the file is sourced
+      # at which point '$PATH' has not yet been populated with inputs
+      @cowsay@ cow
+
+      _printHelloHook() {
+        hello
+      }
+      preConfigureHooks+=(_printHelloHook)
+    ''
+  )
+```
+
+## Attributes {#sec-pkgs.makeSetupHook-attributes}
+
+* `name` Set the name of the hook.
+* `propagatedBuildInputs` Runtime dependencies (such as binaries) of the hook.
+* `depsTargetTargetPropagated` Non-binary dependencies.
+* `meta`
+* `passthru`
+* `substitutions` Variables for `substituteAll`

doc/build-helpers/special/mkshell.section.md

@@ -0,0 +1,46 @@
+# pkgs.mkShell {#sec-pkgs-mkShell}
+
+`pkgs.mkShell` is a specialized `stdenv.mkDerivation` that removes some
+repetition when using it with `nix-shell` (or `nix develop`).
+
+## Usage {#sec-pkgs-mkShell-usage}
+
+Here is a common usage example:
+
+```nix
+{
+  pkgs ? import <nixpkgs> { },
+}:
+pkgs.mkShell {
+  packages = [ pkgs.gnumake ];
+
+  inputsFrom = [
+    pkgs.hello
+    pkgs.gnutar
+  ];
+
+  shellHook = ''
+    export DEBUG=1
+  '';
+}
+```
+
+## Attributes {#sec-pkgs-mkShell-attributes}
+
+* `name` (default: `nix-shell`). Set the name of the derivation.
+* `packages` (default: `[]`). Add executable packages to the `nix-shell` environment.
+* `inputsFrom` (default: `[]`). Add build dependencies of the listed derivations to the `nix-shell` environment.
+* `shellHook` (default: `""`). Bash statements that are executed by `nix-shell`.
+
+... all the attributes of `stdenv.mkDerivation`.
+
+## Variants {#sec-pkgs-mkShell-variants}
+
+`pkgs.mkShellNoCC` is a variant that uses `stdenvNoCC` instead of `stdenv` as base environment. This is useful if no C compiler is needed in the shell environment.
+
+## Building the shell {#sec-pkgs-mkShell-building}
+
+This derivation output will contain a text file that contains a reference to
+all the build inputs. This is useful in CI where we want to make sure that
+every derivation, and its dependencies, build properly. Or when creating a GC
+root so that the build dependencies don't get garbage-collected.

doc/build-helpers/special/vm-tools.section.md

@@ -0,0 +1,161 @@
+# vmTools {#sec-vm-tools}
+
+A set of VM related utilities, that help in building some packages in more advanced scenarios.
+
+## `vmTools.createEmptyImage` {#vm-tools-createEmptyImage}
+
+A bash script fragment that produces a disk image at `destination`.
+
+### Attributes {#vm-tools-createEmptyImage-attributes}
+
+* `size`. The disk size, in MiB.
+* `fullName`. Name that will be written to `${destination}/nix-support/full-name`.
+* `destination` (optional, default `$out`). Where to write the image files.
+
+## `vmTools.runInLinuxVM` {#vm-tools-runInLinuxVM}
+
+Run a derivation in a Linux virtual machine (using Qemu/KVM).
+By default, there is no disk image; the root filesystem is a `tmpfs`, and the Nix store is shared with the host (via the [9P protocol](https://wiki.qemu.org/Documentation/9p#9p_Protocol)).
+Thus, any pure Nix derivation should run unmodified.
+
+If the build fails and Nix is run with the `-K/--keep-failed` option, a script `run-vm` will be left behind in the temporary build directory that allows you to boot into the VM and debug it interactively.
+
+### Attributes {#vm-tools-runInLinuxVM-attributes}
+
+* `preVM` (optional). Shell command to be evaluated *before* the VM is started (i.e., on the host).
+* `memSize` (optional, default `512`). The memory size of the VM in MiB (1024×1024 bytes).
+* `diskImage` (optional). A file system image to be attached to `/dev/sda`.
+  Note that currently we expect the image to contain a filesystem, not a full disk image with a partition table etc.
+
+### Examples {#vm-tools-runInLinuxVM-examples}
+
+Build the derivation hello inside a VM:
+```nix
+{ pkgs }: with pkgs; with vmTools; runInLinuxVM hello
+```
+
+Build inside a VM with extra memory:
+```nix
+{ pkgs }:
+with pkgs;
+with vmTools;
+runInLinuxVM (
+  hello.overrideAttrs (_: {
+    memSize = 1024;
+  })
+)
+```
+
+Use VM with a disk image (implicitly sets `diskImage`, see [`vmTools.createEmptyImage`](#vm-tools-createEmptyImage)):
+```nix
+{ pkgs }:
+with pkgs;
+with vmTools;
+runInLinuxVM (
+  hello.overrideAttrs (_: {
+    preVM = createEmptyImage {
+      size = 1024;
+      fullName = "vm-image";
+    };
+  })
+)
+```
+
+## `vmTools.extractFs` {#vm-tools-extractFs}
+
+Takes a file, such as an ISO, and extracts its contents into the store.
+
+### Attributes {#vm-tools-extractFs-attributes}
+
+* `file`. Path to the file to be extracted.
+  Note that currently we expect the image to contain a filesystem, not a full disk image with a partition table etc.
+* `fs` (optional). Filesystem of the contents of the file.
+
+### Examples {#vm-tools-extractFs-examples}
+
+Extract the contents of an ISO file:
+```nix
+{ pkgs }: with pkgs; with vmTools; extractFs { file = ./image.iso; }
+```
+
+## `vmTools.extractMTDfs` {#vm-tools-extractMTDfs}
+
+Like [](#vm-tools-extractFs), but it makes use of a [Memory Technology Device (MTD)](https://en.wikipedia.org/wiki/Memory_Technology_Device).
+
+## `vmTools.runInLinuxImage` {#vm-tools-runInLinuxImage}
+
+Like [](#vm-tools-runInLinuxVM), but instead of using `stdenv` from the Nix store, run the build using the tools provided by `/bin`, `/usr/bin`, etc. from the specified filesystem image, which typically is a filesystem containing a [FHS](https://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard)-based Linux distribution.
+
+## `vmTools.makeImageTestScript` {#vm-tools-makeImageTestScript}
+
+Generate a script that can be used to run an interactive session in the given image.
+
+### Examples {#vm-tools-makeImageTestScript-examples}
+
+Create a script for running a Fedora 27 VM:
+```nix
+{ pkgs }: with pkgs; with vmTools; makeImageTestScript diskImages.fedora27x86_64
+```
+
+Create a script for running an Ubuntu 20.04 VM:
+```nix
+{ pkgs }: with pkgs; with vmTools; makeImageTestScript diskImages.ubuntu2004x86_64
+```
+
+## `vmTools.diskImageFuns` {#vm-tools-diskImageFuns}
+
+A set of functions that build a predefined set of minimal Linux distributions images.
+
+### Images {#vm-tools-diskImageFuns-images}
+
+* Fedora
+  * `fedora26x86_64`
+  * `fedora27x86_64`
+* CentOS
+  * `centos6i386`
+  * `centos6x86_64`
+  * `centos7x86_64`
+* Ubuntu
+  * `ubuntu1404i386`
+  * `ubuntu1404x86_64`
+  * `ubuntu1604i386`
+  * `ubuntu1604x86_64`
+  * `ubuntu1804i386`
+  * `ubuntu1804x86_64`
+  * `ubuntu2004i386`
+  * `ubuntu2004x86_64`
+  * `ubuntu2204i386`
+  * `ubuntu2204x86_64`
+* Debian
+  * `debian10i386`
+  * `debian10x86_64`
+  * `debian11i386`
+  * `debian11x86_64`
+  * `debian12i386`
+  * `debian12x86_64`
+
+### Attributes {#vm-tools-diskImageFuns-attributes}
+
+* `size` (optional, defaults to `4096`). The size of the image, in MiB.
+* `extraPackages` (optional). A list names of additional packages from the distribution that should be included in the image.
+
+### Examples {#vm-tools-diskImageFuns-examples}
+
+8GiB image containing Firefox in addition to the default packages:
+```nix
+{ pkgs }:
+with pkgs;
+with vmTools;
+diskImageFuns.ubuntu2004x86_64 {
+  extraPackages = [ "firefox" ];
+  size = 8192;
+}
+```
+
+## `vmTools.diskImageExtraFuns` {#vm-tools-diskImageExtraFuns}
+
+Shorthand for `vmTools.diskImageFuns.<attr> { extraPackages = ... }`.
+
+## `vmTools.diskImages` {#vm-tools-diskImages}
+
+Shorthand for `vmTools.diskImageFuns.<attr> { }`.

doc/build-helpers/testers.chapter.md

@@ -0,0 +1,720 @@
+# Testers {#chap-testers}
+
+This chapter describes several testing builders which are available in the `testers` namespace.
+
+## `hasPkgConfigModules` {#tester-hasPkgConfigModules}
+
+<!-- Old anchor name so links still work -->
+[]{#tester-hasPkgConfigModule}
+Checks whether a package exposes a given list of `pkg-config` modules.
+If the `moduleNames` argument is omitted, `hasPkgConfigModules` will use `meta.pkgConfigModules`.
+
+:::{.example #ex-haspkgconfigmodules-defaultvalues}
+
+# Check that `pkg-config` modules are exposed using default values
+
+```nix
+{
+  passthru.tests.pkg-config = testers.hasPkgConfigModules { package = finalAttrs.finalPackage; };
+
+  meta.pkgConfigModules = [ "libfoo" ];
+}
+```
+
+:::
+
+:::{.example #ex-haspkgconfigmodules-explicitmodules}
+
+# Check that `pkg-config` modules are exposed using explicit module names
+
+```nix
+{
+  passthru.tests.pkg-config = testers.hasPkgConfigModules {
+    package = finalAttrs.finalPackage;
+    moduleNames = [ "libfoo" ];
+  };
+}
+```
+
+:::
+
+## `hasCmakeConfigModules` {#tester-hasCmakeConfigModules}
+
+Checks whether a package exposes a given list of `*config.cmake` modules.
+Note the moduleNames used in cmake find_package are case sensitive.
+
+:::{.example #ex-hascmakeconfigmodules}
+
+# Check that `*config.cmake` modules are exposed using explicit module names
+
+```nix
+{
+  passthru.tests.cmake-config = testers.hasCmakeConfigModules {
+    package = finalAttrs.finalPackage;
+    moduleNames = [ "Foo" ];
+  };
+}
+```
+
+:::
+
+## `lycheeLinkCheck` {#tester-lycheeLinkCheck}
+
+Check a packaged static site's links with the [`lychee` package](https://search.nixos.org/packages?show=lychee&type=packages&query=lychee).
+
+You may use Nix to reproducibly build static websites, such as for software documentation.
+Some packages will install documentation in their `out` or `doc` outputs, or maybe you have dedicated package where you've made your static site reproducible by running a generator, such as [Hugo](https://gohugo.io/) or [mdBook](https://rust-lang.github.io/mdBook/), in a derivation.
+
+If you have a static site that can be built with Nix, you can use `lycheeLinkCheck` to check that the hyperlinks in your site are correct, and do so as part of your Nix workflow and CI.
+
+:::{.example #ex-lycheelinkcheck}
+
+# Check hyperlinks in the `nix` documentation
+
+```nix
+testers.lycheeLinkCheck { site = nix.doc + "/share/doc/nix/manual"; }
+```
+
+:::
+
+### Return value {#tester-lycheeLinkCheck-return}
+
+This tester produces a package that does not produce useful outputs, but only succeeds if the hyperlinks in your site are correct. The build log will list the broken links.
+
+It has two modes:
+
+- Build the returned derivation; its build process will check that internal hyperlinks are correct. This runs in the sandbox, so it will not check external hyperlinks, but it is quick and reliable.
+
+- Invoke the `.online` attribute with [`nix run`](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-run) ([experimental](https://nixos.org/manual/nix/stable/contributing/experimental-features#xp-feature-nix-command)). This runs outside the sandbox, and checks that both internal and external hyperlinks are correct.
+  Example:
+
+  ```shell
+  nix run nixpkgs#lychee.tests.ok.online
+  ```
+
+### Inputs {#tester-lycheeLinkCheck-inputs}
+
+`site` (path or derivation) {#tester-lycheeLinkCheck-param-site}
+
+: The path to the files to check.
+
+`remap` (attribute set, optional) {#tester-lycheeLinkCheck-param-remap}
+
+: An attribute set where the attribute names are regular expressions.
+  The values should be strings, derivations, or path values.
+
+  In the returned check's default configuration, external URLs are only checked when you run the `.online` attribute.
+
+  By adding remappings, you can check offline that URLs to external resources are correct, by providing a stand-in from the file system.
+
+  Before checking the existence of a URL, the regular expressions are matched and replaced by their corresponding values.
+
+  Example:
+
+  ```nix
+  {
+    "https://nix\\.dev/manual/nix/[a-z0-9.-]*" = "${nix.doc}/share/doc/nix/manual";
+    "https://nixos\\.org/manual/nix/(un)?stable" =
+      "${emptyDirectory}/placeholder-to-disallow-old-nix-docs-urls";
+  }
+  ```
+
+  Store paths in the attribute values are automatically prefixed with `file://`, because lychee requires this for paths in the file system.
+  If this is a problem, or if you need to control the order in which replacements are performed, use `extraConfig.remap` instead.
+
+`extraConfig` (attribute set) {#tester-lycheeLinkCheck-param-extraConfig}
+
+: Extra configuration to pass to `lychee` in its [configuration file](https://github.com/lycheeverse/lychee/blob/master/lychee.example.toml).
+  It is automatically [translated](https://nixos.org/manual/nixos/stable/index.html#sec-settings-nix-representable) to TOML.
+
+  Example: `{ "include_verbatim" = true; }`
+
+`lychee` (derivation, optional) {#tester-lycheeLinkCheck-param-lychee}
+
+: The `lychee` package to use.
+
+## `shellcheck` {#tester-shellcheck}
+
+Run files through `shellcheck`, a static analysis tool for shell scripts, failing if there are any issues.
+
+:::{.example #ex-shellcheck}
+# Run `testers.shellcheck`
+
+A single script
+
+```nix
+testers.shellcheck {
+  name = "script";
+  src = ./script.sh;
+}
+```
+
+Multiple files
+
+```nix
+let
+  inherit (lib) fileset;
+in
+testers.shellcheck {
+  name = "nixbsd-activate";
+  src = fileset.toSource {
+    root = ./.;
+    fileset = fileset.unions [
+      ./lib.sh
+      ./nixbsd-activate
+    ];
+  };
+}
+```
+
+:::
+
+### Inputs {#tester-shellcheck-inputs}
+
+`name` (string, optional)
+: The name of the test.
+  `name` will be required at a future point because it massively improves traceability of test failures, but is kept optional for now to avoid breaking existing usages.
+  Defaults to `run-shellcheck`.
+  The name of the derivation produced by the tester is `shellcheck-${name}` when `name` is supplied.
+
+`src` (path-like)
+: The path to the shell script(s) to check.
+  This can be a single file or a directory containing shell files.
+  All files in `src` will be checked, so you may want to provide `fileset`-based source instead of a whole directory.
+
+### Return value {#tester-shellcheck-return}
+
+A derivation that runs `shellcheck` on the given script(s), producing an empty output if no issues are found.
+The build will fail if `shellcheck` finds any issues.
+
+## `shfmt` {#tester-shfmt}
+
+Run files through `shfmt`, a shell script formatter, failing if any files are reformatted.
+
+:::{.example #ex-shfmt}
+# Run `testers.shfmt`
+
+A single script
+
+```nix
+testers.shfmt {
+  name = "script";
+  src = ./script.sh;
+}
+```
+
+Multiple files
+
+```nix
+let
+  inherit (lib) fileset;
+in
+testers.shfmt {
+  name = "nixbsd";
+  src = fileset.toSource {
+    root = ./.;
+    fileset = fileset.unions [
+      ./lib.sh
+      ./nixbsd-activate
+    ];
+  };
+}
+```
+
+:::
+
+### Inputs {#tester-shfmt-inputs}
+
+`name` (string)
+: The name of the test.
+  `name` is required because it massively improves traceability of test failures.
+  The name of the derivation produced by the tester is `shfmt-${name}`.
+
+`src` (path-like)
+: The path to the shell script(s) to check.
+  This can be a single file or a directory containing shell files.
+  All files in `src` will be checked, so you may want to provide `fileset`-based source instead of a whole directory.
+
+`indent` (integer, optional)
+: The number of spaces to use for indentation.
+  Defaults to `2`.
+  A value of `0` indents with tabs.
+
+### Return value {#tester-shfmt-return}
+
+A derivation that runs `shfmt` on the given script(s), producing an empty output upon success.
+The build will fail if `shfmt` reformats anything.
+
+## `testVersion` {#tester-testVersion}
+
+Checks that the output from running a command contains the specified version string in it as a whole word.
+
+NOTE: This is a check you add to `passthru.tests` which is mainly run by OfBorg, but not in Hydra. If you want a version check failure to block the build altogether, then [`versionCheckHook`](#versioncheckhook) is the tool you're looking for (and recommended for quick builds). The motivation for adding either of these checks would be:
+
+- Catch dynamic linking errors and such and missing environment variables that should be added by wrapping.
+- Probable protection against accidentally building the wrong version, for example when using an "old" hash in a fixed-output derivation.
+
+By default, the command to be run will be inferred from the given `package` attribute:
+it will check `meta.mainProgram` first, and fall back to `pname` or `name`.
+The default argument to the command is `--version`, and the version to be checked will be inferred from the given `package` attribute as well.
+
+:::{.example #ex-testversion-hello}
+
+# Check a program version using all the default values
+
+This example will run the command `hello --version`, and then check that the version of the `hello` package is in the output of the command.
+
+```nix
+{ passthru.tests.version = testers.testVersion { package = hello; }; }
+```
+
+:::
+
+:::{.example #ex-testversion-different-commandversion}
+
+# Check the program version using a specified command and expected version string
+
+This example will run the command `leetcode -V`, and then check that `leetcode 0.4.2` is in the output of the command as a whole word (separated by whitespaces).
+This means that an output like "leetcode 0.4.21" would fail the tests, and an output like "You're running leetcode 0.4.2" would pass the tests.
+
+A common usage of the `version` attribute is to specify `version = "v${version}"`.
+
+```nix
+{
+  version = "0.4.2";
+
+  passthru.tests.version = testers.testVersion {
+    package = leetcode-cli;
+    command = "leetcode -V";
+    version = "leetcode ${version}";
+  };
+}
+```
+
+:::
+
+## `testBuildFailure` {#tester-testBuildFailure}
+
+Make sure that a build does not succeed. This is useful for testing testers.
+
+This returns a derivation with an override on the builder, with the following effects:
+
+ - Fail the build when the original builder succeeds
+ - Move `$out` to `$out/result`, if it exists (assuming `out` is the default output)
+ - Save the build log to `$out/testBuildFailure.log` (same)
+
+While `testBuildFailure` is designed to keep changes to the original builder's environment to a minimum, some small changes are inevitable:
+
+ - The file `$TMPDIR/testBuildFailure.log` is present. It should not be deleted.
+ - `stdout` and `stderr` are a pipe instead of a tty. This could be improved.
+ - One or two extra processes are present in the sandbox during the original builder's execution.
+ - The derivation and output hashes are different, but not unusual.
+ - The derivation includes a dependency on `buildPackages.bash` and `expect-failure.sh`, which is built to include a transitive dependency on `buildPackages.coreutils` and possibly more.
+   These are not added to `PATH` or any other environment variable, so they should be hard to observe.
+
+:::{.example #ex-testBuildFailure-showingenvironmentchanges}
+
+# Check that a build fails, and verify the changes made during build
+
+```nix
+runCommand "example"
+  {
+    failed = testers.testBuildFailure (
+      runCommand "fail" { } ''
+        echo ok-ish >$out
+        echo failing though
+        exit 3
+      ''
+    );
+  }
+  ''
+    grep -F 'ok-ish' $failed/result
+    grep -F 'failing though' $failed/testBuildFailure.log
+    [[ 3 = $(cat $failed/testBuildFailure.exit) ]]
+    touch $out
+  ''
+```
+
+:::
+
+## `testBuildFailure'` {#tester-testBuildFailurePrime}
+
+This tester wraps the functionality provided by [`testers.testBuildFailure`](#tester-testBuildFailure) to make writing checks easier by simplifying checking the exit code of the builder and asserting the existence of entries in the builder's log.
+Additionally, users may specify a script containing additional checks, accessing the result of applying `testers.testBuildFailure` through the variable `failed`.
+
+NOTE: This tester will produce an empty output and exit with success if none of the checks fail; there is no need to `touch "$out"` in `script`.
+
+:::{.example #ex-testBuildFailurePrime-doc-example}
+
+# Check that a build fails, and verify the changes made during build
+
+Re-using the example from [`testers.testBuildFailure`](#ex-testBuildFailure-showingenvironmentchanges), we can see how common checks are made easier and remove the need for `runCommand`:
+
+```nix
+testers.testBuildFailure' {
+  drv = runCommand "doc-example" { } ''
+    echo ok-ish >"$out"
+    echo failing though
+    exit 3
+  '';
+  expectedBuilderExitCode = 3;
+  expectedBuilderLogEntries = [ "failing though" ];
+  script = ''
+    grep --silent -F 'ok-ish' "$failed/result"
+  '';
+}
+```
+
+:::
+
+### Inputs {#tester-testBuildFailurePrime-inputs}
+
+`drv` (derivation)
+
+: The failing derivation to wrap with `testBuildFailure`.
+
+`name` (string, optional)
+
+: The name of the test.
+  When not provided, this value defaults to `testBuildFailure-${(testers.testBuildFailure drv).name}`.
+
+`expectedBuilderExitCode` (integer, optional)
+
+: The expected exit code of the builder of `drv`.
+  When not provided, this value defaults to `1`.
+
+`expectedBuilderLogEntries` (array of string-like values, optional)
+
+: A list of string-like values which must be found in the builder's log by exact match.
+  When not provided, this value defaults to `[ ]`.
+
+  NOTE: Patterns and regular expressions are not supported.
+
+`script` (string, optional)
+
+: A string containing additional checks to run.
+  When not provided, this value defaults to `""`.
+  The result of `testers.testBuildFailure drv` is available through the variable `failed`.
+  As an example, the builder's log is at `"$failed/testBuildFailure.log"`.
+
+### Return value {#tester-testBuildFailurePrime-return}
+
+The tester produces an empty output and only succeeds when the checks using `expectedBuilderExitCode`, `expectedBuilderLogEntries`, and `script` succeed.
+
+## `testEqualContents` {#tester-testEqualContents}
+
+Check that two paths have the same contents.
+
+`assertion` (string)
+
+: A message that is printed before the comparison, after `Checking:`.
+
+`expected` (path or value coercible to store path)
+
+: The path to the expected [file system object] content
+
+`actual` (value coercible to store path) <!-- path value is possible, but wrong in practice, but let's not bother readers with our predictions -->
+
+: The path to the actual file system object content to check
+
+`postFailureMessage` (string)
+
+: A message that is printed last if the file system object contents at the two paths don't match exactly.
+
+:::{.example #ex-testEqualContents-toyexample}
+
+# Check that two paths have the same contents
+
+```nix
+testers.testEqualContents {
+  assertion = "sed -e performs replacement";
+  expected = writeText "expected" ''
+    foo baz baz
+  '';
+  actual =
+    runCommand "actual"
+      {
+        # not really necessary for a package that's in stdenv
+        nativeBuildInputs = [ gnused ];
+        base = writeText "base" ''
+          foo bar baz
+        '';
+      }
+      ''
+        sed -e 's/bar/baz/g' $base >$out
+      '';
+  # if applicable
+  postFailureMessage = ''
+    The bar-baz replacer produced an unexpected result.
+    If the new behavior is acceptable and validated against the bar-baz specification, run ./adopt-new-bar-baz-result.sh to adjust this test and require the new behavior.
+  '';
+}
+```
+
+:::
+
+## `testEqualArrayOrMap` {#tester-testEqualArrayOrMap}
+
+Check that bash arrays (including associative arrays, referred to as "maps") are populated correctly.
+
+This can be used to ensure setup hooks are registered in a certain order, or to write unit tests for shell functions which transform arrays.
+
+:::{.example #ex-testEqualArrayOrMap-test-function-add-cowbell}
+
+# Test a function which appends a value to an array
+
+```nix
+testers.testEqualArrayOrMap {
+  name = "test-function-add-cowbell";
+  valuesArray = [
+    "cowbell"
+    "cowbell"
+  ];
+  expectedArray = [
+    "cowbell"
+    "cowbell"
+    "cowbell"
+  ];
+  script = ''
+    addCowbell() {
+      local -rn arrayNameRef="$1"
+      arrayNameRef+=( "cowbell" )
+    }
+
+    nixLog "appending all values in valuesArray to actualArray"
+    for value in "''${valuesArray[@]}"; do
+      actualArray+=( "$value" )
+    done
+
+    nixLog "applying addCowbell"
+    addCowbell actualArray
+  '';
+}
+```
+
+:::
+
+### Inputs {#tester-testEqualArrayOrMap-inputs}
+
+NOTE: Internally, this tester uses `__structuredAttrs` to handle marshalling between Nix expressions and shell variables.
+This imposes the restriction that arrays and "maps" have values which are string-like.
+
+NOTE: At least one of `expectedArray` and `expectedMap` must be provided.
+
+`name` (string)
+
+: The name of the test.
+
+`script` (string)
+
+: The singular task of `script` is to populate `actualArray` or `actualMap` (it may populate both).
+  To do this, `script` may access the following shell variables:
+
+  - `valuesArray` (available when `valuesArray` is provided to the tester)
+  - `valuesMap` (available when `valuesMap` is provided to the tester)
+  - `actualArray` (available when `expectedArray` is provided to the tester)
+  - `actualMap` (available when `expectedMap` is provided to the tester)
+
+  While both `expectedArray` and `expectedMap` are in scope during the execution of `script`, they *must not* be accessed or modified from within `script`.
+
+`valuesArray` (array of string-like values, optional)
+
+: An array of string-like values.
+  This array may be used within `script`.
+
+`valuesMap` (attribute set of string-like values, optional)
+
+: An attribute set of string-like values.
+  This attribute set may be used within `script`.
+
+`expectedArray` (array of string-like values, optional)
+
+: An array of string-like values.
+  This array *must not* be accessed or modified from within `script`.
+  When provided, `script` is expected to populate `actualArray`.
+
+`expectedMap` (attribute set of string-like values, optional)
+
+: An attribute set of string-like values.
+  This attribute set *must not* be accessed or modified from within `script`.
+  When provided, `script` is expected to populate `actualMap`.
+
+### Return value {#tester-testEqualArrayOrMap-return}
+
+The tester produces an empty output and only succeeds when `expectedArray` and `expectedMap` match `actualArray` and `actualMap`, respectively, when non-null.
+The build log will contain differences encountered.
+
+## `testEqualDerivation` {#tester-testEqualDerivation}
+
+Checks that two packages produce the exact same build instructions.
+
+This can be used to make sure that a certain difference of configuration, such as the presence of an overlay does not cause a cache miss.
+
+When the derivations are equal, the return value is an empty file.
+Otherwise, the build log explains the difference via `nix-diff`.
+
+:::{.example #ex-testEqualDerivation-hello}
+
+# Check that two packages produce the same derivation
+
+```nix
+testers.testEqualDerivation "The hello package must stay the same when enabling checks." hello (
+  hello.overrideAttrs (o: {
+    doCheck = true;
+  })
+)
+```
+
+:::
+
+## `invalidateFetcherByDrvHash` {#tester-invalidateFetcherByDrvHash}
+
+Use the derivation hash to invalidate the output via name, for testing.
+
+Type: `(a@{ name, ... } -> Derivation) -> a -> Derivation`
+
+Normally, fixed output derivations can and should be cached by their output hash only, but for testing we want to re-fetch everytime the fetcher changes.
+
+Changes to the fetcher become apparent in the drvPath, which is a hash of how to fetch, rather than a fixed store path.
+By inserting this hash into the name, we can make sure to re-run the fetcher every time the fetcher changes.
+
+This relies on the assumption that Nix isn't clever enough to reuse its database of local store contents to optimize fetching.
+
+You might notice that the "salted" name derives from the normal invocation, not the final derivation.
+`invalidateFetcherByDrvHash` has to invoke the fetcher function twice:
+once to get a derivation hash, and again to produce the final fixed output derivation.
+
+:::{.example #ex-invalidateFetcherByDrvHash-nix}
+
+# Prevent nix from reusing the output of a fetcher
+
+```nix
+{
+  tests.fetchgit = testers.invalidateFetcherByDrvHash fetchgit {
+    name = "nix-source";
+    url = "https://github.com/NixOS/nix";
+    rev = "9d9dbe6ed05854e03811c361a3380e09183f4f4a";
+    hash = "sha256-7DszvbCNTjpzGRmpIVAWXk20P0/XTrWZ79KSOGLrUWY=";
+  };
+}
+```
+
+:::
+
+## `runCommand` {#tester-runCommand}
+
+`runCommand :: { name, script, stdenv ? stdenvNoCC, hash ? "...", ... } -> Derivation`
+
+This is a wrapper around `pkgs.runCommandWith`, which
+- produces a fixed-output derivation, enabling the command(s) to access the network ;
+- salts the derivation's name based on its inputs, ensuring the command is re-run whenever the inputs change.
+
+It accepts the following attributes:
+- the derivation's `name` ;
+- the `script` to be executed ;
+- `stdenv`, the environment to use, defaulting to `stdenvNoCC` ;
+- the derivation's output `hash`, defaulting to the empty file's.
+  The derivation's `outputHashMode` is set by default to recursive, so the `script` can output a directory as well.
+
+All other attributes are passed through to [`mkDerivation`](#sec-using-stdenv),
+including `nativeBuildInputs` to specify dependencies available to the `script`.
+
+:::{.example #ex-tester-runCommand-nix}
+
+# Run a command with network access
+
+```nix
+testers.runCommand {
+  name = "access-the-internet";
+  script = ''
+    curl -o /dev/null https://example.com
+    touch $out
+  '';
+  nativeBuildInputs = with pkgs; [
+    cacert
+    curl
+  ];
+}
+```
+
+:::
+
+## `runNixOSTest` {#tester-runNixOSTest}
+
+A helper function that behaves exactly like the NixOS `runTest`, except it also assigns this Nixpkgs package set as the `pkgs` of the test and makes the `nixpkgs.*` options read-only.
+
+If your test is part of the Nixpkgs repository, or if you need a more general entrypoint, see ["Calling a test" in the NixOS manual](https://nixos.org/manual/nixos/stable/index.html#sec-calling-nixos-tests).
+
+:::{.example #ex-runNixOSTest-hello}
+
+# Run a NixOS test using `runNixOSTest`
+
+```nix
+pkgs.testers.runNixOSTest (
+  { lib, ... }:
+  {
+    name = "hello";
+    nodes.machine =
+      { pkgs, ... }:
+      {
+        environment.systemPackages = [ pkgs.hello ];
+      };
+    testScript = ''
+      machine.succeed("hello")
+    '';
+  }
+)
+```
+
+:::
+
+## `nixosTest` {#tester-nixosTest}
+
+Run a NixOS VM network test using this evaluation of Nixpkgs.
+
+NOTE: This function is primarily for external use. NixOS itself uses `make-test-python.nix` directly. Packages defined in Nixpkgs [reuse NixOS tests via `nixosTests`, plural](#ssec-nixos-tests-linking).
+
+It is mostly equivalent to the function `import ./make-test-python.nix` from the [NixOS manual](https://nixos.org/nixos/manual/index.html#sec-nixos-tests), except that the current application of Nixpkgs (`pkgs`) will be used, instead of letting NixOS invoke Nixpkgs anew.
+
+If a test machine needs to set NixOS options under `nixpkgs`, it must set only the `nixpkgs.pkgs` option.
+
+### Parameter {#tester-nixosTest-parameter}
+
+A [NixOS VM test network](https://nixos.org/nixos/manual/index.html#sec-nixos-tests), or path to it. Example:
+
+```nix
+{
+  name = "my-test";
+  nodes = {
+    machine1 =
+      {
+        lib,
+        pkgs,
+        nodes,
+        ...
+      }:
+      {
+        environment.systemPackages = [ pkgs.hello ];
+        services.foo.enable = true;
+      };
+    # machine2 = ...;
+  };
+  testScript = ''
+    start_all()
+    machine1.wait_for_unit("foo.service")
+    machine1.succeed("hello | foo-send")
+  '';
+}
+```
+
+### Result {#tester-nixosTest-result}
+
+A derivation that runs the VM test.
+
+Notable attributes:
+
+ * `nodes`: the evaluated NixOS configurations. Useful for debugging and exploring the configuration.
+
+ * `driverInteractive`: a script that launches an interactive Python session in the context of the `testScript`.
+
+[file system object]: https://nix.dev/manual/nix/latest/store/file-system-object

doc/build-helpers/trivial-build-helpers.chapter.md

@@ -0,0 +1,830 @@
+# Trivial build helpers {#chap-trivial-builders}
+
+Nixpkgs provides a variety of wrapper functions that help build commonly useful derivations.
+Like [`stdenv.mkDerivation`](#sec-using-stdenv), each of these build helpers creates a derivation, but the arguments passed are different (usually simpler) from those required by `stdenv.mkDerivation`.
+
+
+## `runCommandWith` {#trivial-builder-runCommandWith}
+
+The function `runCommandWith` returns a derivation built using the specified command(s), in a specified environment.
+
+It is the underlying base function of  all [`runCommand*` variants].
+The general behavior is controlled via a single attribute set passed
+as the first argument, and allows specifying `stdenv` freely.
+
+The following [`runCommand*` variants] exist: `runCommand`, `runCommandCC`, and `runCommandLocal`.
+
+[`runCommand*` variants]: #trivial-builder-runCommand
+
+### Type {#trivial-builder-runCommandWith-Type}
+
+```
+runCommandWith :: {
+  name :: name;
+  stdenv? :: Derivation;
+  runLocal? :: Bool;
+  derivationArgs? :: { ... };
+} -> String -> Derivation
+```
+
+### Inputs {#trivial-builder-runCommandWith-Inputs}
+
+`name` (String)
+:   The derivation's name, which Nix will append to the store path; see [`mkDerivation`](#sec-using-stdenv).
+
+`runLocal` (Boolean)
+:   If set to `true` this forces the derivation to be built locally, not using [substitutes] nor remote builds.
+    This is intended for very cheap commands (<1s execution time) which can be sped up by avoiding the network round-trip(s).
+    Its effect is to set [`preferLocalBuild = true`][preferLocalBuild] and [`allowSubstitutes = false`][allowSubstitutes].
+
+   ::: {.note}
+   This prevents the use of [substituters][substituter], so only set `runLocal` (or use `runCommandLocal`) when certain the user will
+   always have a builder for the `system` of the derivation. This should be true for most trivial use cases
+   (e.g., just copying some files to a different location or adding symlinks) because there the `system`
+   is usually the same as `builtins.currentSystem`.
+   :::
+
+`stdenv` (Derivation)
+:   The [standard environment](#chap-stdenv) to use, defaulting to `pkgs.stdenv`
+
+`derivationArgs` (Attribute set)
+:   Additional arguments for [`mkDerivation`](#sec-using-stdenv).
+
+`buildCommand` (String)
+:   Shell commands to run in the derivation builder.
+
+    ::: {.note}
+    You have to create a file or directory `$out` for Nix to be able to run the builder successfully.
+    :::
+
+[allowSubstitutes]: https://nix.dev/manual/nix/latest/language/advanced-attributes.html#adv-attr-allowSubstitutes
+[preferLocalBuild]: https://nix.dev/manual/nix/latest/language/advanced-attributes.html#adv-attr-preferLocalBuild
+[substituter]: https://nix.dev/manual/nix/latest/glossary#gloss-substituter
+[substitutes]: https://nix.dev/manual/nix/latest/glossary#gloss-substitute
+
+::: {.example #ex-runcommandwith}
+# Invocation of `runCommandWith`
+
+```nix
+runCommandWith
+  {
+    name = "example";
+    derivationArgs.nativeBuildInputs = [ cowsay ];
+  }
+  ''
+    cowsay > $out <<EOMOO
+    'runCommandWith' is a bit cumbersome,
+    so we have more ergonomic wrappers.
+    EOMOO
+  ''
+```
+
+:::
+
+
+## `runCommand` and `runCommandCC` {#trivial-builder-runCommand}
+
+The function `runCommand` returns a derivation built using the specified command(s), in the `stdenvNoCC` environment.
+
+`runCommandCC` is similar but uses the default compiler environment. To minimize dependencies, `runCommandCC`
+should only be used when the build command needs a C compiler.
+
+`runCommandLocal` is also similar to `runCommand`, but forces the derivation to be built locally.
+See the note on [`runCommandWith`] about `runLocal`.
+
+[`runCommandWith`]: #trivial-builder-runCommandWith
+
+### Type {#trivial-builder-runCommand-Type}
+
+```
+runCommand      :: String -> AttrSet -> String -> Derivation
+runCommandCC    :: String -> AttrSet -> String -> Derivation
+runCommandLocal :: String -> AttrSet -> String -> Derivation
+```
+
+### Input {#trivial-builder-runCommand-Input}
+
+While the type signature(s) differ from [`runCommandWith`], individual arguments with the same name will have the same type and meaning:
+
+`name` (String)
+:   The derivation's name
+
+`derivationArgs` (Attribute set)
+:   Additional parameters passed to [`mkDerivation`]
+
+`buildCommand` (String)
+:   The command(s) run to build the derivation.
+
+
+::: {.example #ex-runcommand-simple}
+# Invocation of `runCommand`
+
+```nix
+runCommand "my-example" { } ''
+  echo My example command is running
+
+  mkdir $out
+
+  echo I can write data to the Nix store > $out/message
+
+  echo I can also run basic commands like:
+
+  echo ls
+  ls
+
+  echo whoami
+  whoami
+
+  echo date
+  date
+''
+```
+:::
+
+::: {.note}
+`runCommand name derivationArgs buildCommand` is equivalent to
+```nix
+runCommandWith {
+  inherit name derivationArgs;
+  stdenv = stdenvNoCC;
+} buildCommand
+```
+
+Likewise, `runCommandCC name derivationArgs buildCommand` is equivalent to
+```nix
+runCommandWith { inherit name derivationArgs; } buildCommand
+```
+:::
+
+
+## Writing text files {#trivial-builder-text-writing}
+
+Nixpkgs provides the following functions for producing derivations which write text files or executable scripts into the Nix store.
+They are useful for creating files from Nix expression, and are all implemented as convenience wrappers around `writeTextFile`.
+
+Each of these functions will cause a derivation to be produced.
+When you coerce the result of each of these functions to a string with [string interpolation](https://nixos.org/manual/nix/stable/language/string-interpolation) or [`toString`](https://nixos.org/manual/nix/stable/language/builtins#builtins-toString), it will evaluate to the [store path](https://nixos.org/manual/nix/stable/store/store-path) of this derivation.
+
+:::: {.note}
+Some of these functions will put the resulting files within a directory inside the [derivation output](https://nixos.org/manual/nix/stable/language/derivations#attr-outputs).
+If you need to refer to the resulting files somewhere else in a Nix expression, append their path to the derivation's store path.
+
+For example, if the file destination is a directory:
+
+```nix
+{
+  my-file = writeTextFile {
+    name = "my-file";
+    text = ''
+      Contents of File
+    '';
+    destination = "/share/my-file";
+  };
+}
+```
+
+Remember to append "/share/my-file" to the resulting store path when using it elsewhere:
+
+```nix
+writeShellScript "evaluate-my-file.sh" ''
+  cat ${my-file}/share/my-file
+''
+```
+::::
+
+### `makeDesktopItem` {#trivial-builder-makeDesktopItem}
+
+Write an [XDG desktop file](https://specifications.freedesktop.org/desktop-entry-spec/1.4/) to the Nix store.
+
+This function is usually used to add desktop items to a package through the `copyDesktopItems` hook.
+
+`makeDesktopItem` adheres to version 1.4 of the specification.
+
+#### Inputs {#trivial-builder-makeDesktopItem-inputs}
+
+`makeDesktopItem` takes an attribute set that accepts most values from the [XDG specification](https://specifications.freedesktop.org/desktop-entry-spec/1.4/ar01s06.html).
+
+All recognised keys from the specification are supported with the exception of the "Hidden" field. The keys are converted into camelCase format, but correspond 1:1 to their equivalent in the specification: `genericName`, `noDisplay`, `comment`, `icon`, `onlyShowIn`, `notShowIn`, `dbusActivatable`, `tryExec`, `exec`, `path`, `terminal`, `mimeTypes`, `categories`, `implements`, `keywords`, `startupNotify`, `startupWMClass`, `url`, `prefersNonDefaultGPU`.
+
+The "Version" field is hardcoded to the version `makeDesktopItem` currently adheres to.
+
+The following fields are either required, are of a different type than in the specification, carry specific default values, or are additional fields supported by `makeDesktopItem`:
+
+`name` (String)
+
+: The name of the desktop file in the Nix store.
+
+`type` (String; _optional_)
+
+: Default value: `"Application"`
+
+`desktopName` (String)
+
+: Corresponds to the "Name" field of the specification.
+
+`actions` (List of Attribute set; _optional_)
+
+: A list of attribute sets {name, exec?, icon?}
+
+`extraConfig` (Attribute set; _optional_)
+
+: Additional key/value pairs to be added verbatim to the desktop file. Attributes need to be prefixed with 'X-'.
+
+#### Examples {#trivial-builder-makeDesktopItem-examples}
+
+::: {.example #ex-makeDesktopItem}
+# Usage 1 of `makeDesktopItem`
+
+Write a desktop file `/nix/store/<store path>/my-program.desktop` to the Nix store.
+
+```nix
+{ makeDesktopItem }:
+makeDesktopItem {
+  name = "my-program";
+  desktopName = "My Program";
+  genericName = "Video Player";
+  noDisplay = false;
+  comment = "Cool video player";
+  icon = "/path/to/icon";
+  onlyShowIn = [ "KDE" ];
+  dbusActivatable = true;
+  tryExec = "my-program";
+  exec = "my-program --someflag";
+  path = "/some/working/path";
+  terminal = false;
+  actions.example = {
+    name = "New Window";
+    exec = "my-program --new-window";
+    icon = "/some/icon";
+  };
+  mimeTypes = [ "video/mp4" ];
+  categories = [ "Utility" ];
+  implements = [ "org.my-program" ];
+  keywords = [
+    "Video"
+    "Player"
+  ];
+  startupNotify = false;
+  startupWMClass = "MyProgram";
+  prefersNonDefaultGPU = false;
+  extraConfig.X-SomeExtension = "somevalue";
+}
+```
+
+:::
+
+::: {.example #ex2-makeDesktopItem}
+# Usage 2 of `makeDesktopItem`
+
+Override the `hello` package to add a desktop item.
+
+```nix
+{
+  copyDesktopItems,
+  hello,
+  makeDesktopItem,
+}:
+
+hello.overrideAttrs {
+  nativeBuildInputs = [ copyDesktopItems ];
+
+  desktopItems = [
+    (makeDesktopItem {
+      name = "hello";
+      desktopName = "Hello";
+      exec = "hello";
+    })
+  ];
+}
+```
+
+:::
+
+### `writeTextFile` {#trivial-builder-writeTextFile}
+
+Write a text file to the Nix store.
+
+`writeTextFile` takes an attribute set with the following possible attributes:
+
+`name` (String)
+
+: Corresponds to the name used in the Nix store path identifier.
+
+`text` (String)
+
+: The contents of the file.
+
+`executable` (Bool, _optional_)
+
+: Make this file have the executable bit set.
+
+  Default: `false`
+
+`destination` (String, _optional_)
+
+: A subpath under the derivation's output path into which to put the file.
+  Subdirectories are created automatically when the derivation is realised.
+
+  By default, the store path itself will be a file containing the text contents.
+
+  Default: `""`
+
+`checkPhase` (String, _optional_)
+
+: Commands to run after generating the file.
+
+  Default: `""`
+
+`meta` (Attribute set, _optional_)
+
+: Additional metadata for the derivation.
+
+  Default: `{}`
+
+`allowSubstitutes` (Bool, _optional_)
+
+: Whether to allow substituting from a binary cache.
+  Passed through to [`allowSubstitutes`](https://nixos.org/manual/nix/stable/language/advanced-attributes#adv-attr-allowSubstitutes) of the underlying call to `derivation`.
+
+  It defaults to `false`, as running the derivation's simple `builder` executable locally is assumed to be faster than network operations.
+  Set it to true if the `checkPhase` step is expensive.
+
+  Default: `false`
+
+`preferLocalBuild` (Bool, _optional_)
+
+: Whether to prefer building locally, even if faster [remote build machines](https://nixos.org/manual/nix/stable/command-ref/conf-file#conf-substituters) are available.
+
+  Passed through to [`preferLocalBuild`](https://nixos.org/manual/nix/stable/language/advanced-attributes#adv-attr-preferLocalBuild) of the underlying call to `derivation`.
+
+  It defaults to `true` for the same reason `allowSubstitutes` defaults to `false`.
+
+  Default: `true`
+
+`derivationArgs` (Attribute set, _optional_)
+
+: Extra arguments to pass to the underlying call to `stdenv.mkDerivation`.
+
+  Default: `{}`
+
+The resulting store path will include some variation of the name, and it will be a file unless `destination` is used, in which case it will be a directory.
+
+::: {.example #ex-writeTextFile}
+# Usage 1 of `writeTextFile`
+
+Write `my-file` to `/nix/store/<store path>/some/subpath/my-cool-script`, making it executable.
+Also run a check on the resulting file in a `checkPhase`, and supply values for the less-used options.
+
+```nix
+writeTextFile {
+  name = "my-cool-script";
+  text = ''
+    #!/bin/sh
+    echo "This is my cool script!"
+  '';
+  executable = true;
+  destination = "/some/subpath/my-cool-script";
+  checkPhase = ''
+    ${pkgs.shellcheck}/bin/shellcheck $out/some/subpath/my-cool-script
+  '';
+  meta = {
+    license = pkgs.lib.licenses.cc0;
+  };
+  allowSubstitutes = true;
+  preferLocalBuild = false;
+}
+```
+:::
+
+::: {.example #ex2-writeTextFile}
+# Usage 2 of `writeTextFile`
+
+Write the string `Contents of File` to `/nix/store/<store path>`.
+See also the [](#trivial-builder-writeText) helper function.
+
+```nix
+writeTextFile {
+  name = "my-file";
+  text = ''
+    Contents of File
+  '';
+}
+```
+:::
+
+::: {.example #ex3-writeTextFile}
+# Usage 3 of `writeTextFile`
+
+Write an executable script `my-script` to `/nix/store/<store path>/bin/my-script`.
+See also the [](#trivial-builder-writeScriptBin) helper function.
+
+```nix
+writeTextFile {
+  name = "my-script";
+  text = ''
+    echo "hi"
+  '';
+  executable = true;
+  destination = "/bin/my-script";
+}
+```
+:::
+
+### `writeText` {#trivial-builder-writeText}
+
+Write a text file to the Nix store
+
+`writeText` takes the following arguments:
+a string.
+
+`name` (String)
+
+: The name used in the Nix store path.
+
+`text` (String)
+
+: The contents of the file.
+
+The store path will include the name, and it will be a file.
+
+::: {.example #ex-writeText}
+# Usage of `writeText`
+
+Write the string `Contents of File` to `/nix/store/<store path>`:
+
+```nix
+writeText "my-file" ''
+  Contents of File
+''
+```
+:::
+
+This is equivalent to:
+
+```nix
+writeTextFile {
+  name = "my-file";
+  text = ''
+    Contents of File
+  '';
+}
+```
+
+### `writeTextDir` {#trivial-builder-writeTextDir}
+
+Write a text file within a subdirectory of the Nix store.
+
+`writeTextDir` takes the following arguments:
+
+`path` (String)
+
+: The destination within the Nix store path under which to create the file.
+
+`text` (String)
+
+: The contents of the file.
+
+The store path will be a directory.
+
+::: {.example #ex-writeTextDir}
+# Usage of `writeTextDir`
+
+Write the string `Contents of File` to `/nix/store/<store path>/share/my-file`:
+
+```nix
+writeTextDir "share/my-file" ''
+  Contents of File
+''
+```
+:::
+
+This is equivalent to:
+
+```nix
+writeTextFile {
+  name = "my-file";
+  text = ''
+    Contents of File
+  '';
+  destination = "/share/my-file";
+}
+```
+
+### `writeScript` {#trivial-builder-writeScript}
+
+Write an executable script file to the Nix store.
+
+`writeScript` takes the following arguments:
+
+`name` (String)
+
+: The name used in the Nix store path.
+
+`text` (String)
+
+: The contents of the file.
+
+The created file is marked as executable.
+The store path will include the name, and it will be a file.
+
+::: {.example #ex-writeScript}
+# Usage of `writeScript`
+
+Write the string `Contents of File` to `/nix/store/<store path>` and make the file executable.
+
+```nix
+writeScript "my-file" ''
+  Contents of File
+''
+```
+
+This is equivalent to:
+
+```nix
+writeTextFile {
+  name = "my-file";
+  text = ''
+    Contents of File
+  '';
+  executable = true;
+}
+```
+:::
+
+### `writeScriptBin` {#trivial-builder-writeScriptBin}
+
+Write a script within a `bin` subdirectory of a directory in the Nix store.
+This is for consistency with the convention of software packages placing executables under `bin`.
+
+`writeScriptBin` takes the following arguments:
+
+`name` (String)
+
+: The name used in the Nix store path and within the file created under the store path.
+
+`text` (String)
+
+: The contents of the file.
+
+The created file is marked as executable.
+The file's contents will be put into `/nix/store/<store path>/bin/<name>`.
+The store path will include the name, and it will be a directory.
+
+::: {.example #ex-writeScriptBin}
+# Usage of `writeScriptBin`
+
+```nix
+writeScriptBin "my-script" ''
+  echo "hi"
+''
+```
+:::
+
+This is equivalent to:
+
+```nix
+writeTextFile {
+  name = "my-script";
+  text = ''
+    echo "hi"
+  '';
+  executable = true;
+  destination = "/bin/my-script";
+}
+```
+
+### `writeShellScript` {#trivial-builder-writeShellScript}
+
+Write a Bash script to the store.
+
+`writeShellScript` takes the following arguments:
+
+`name` (String)
+
+: The name used in the Nix store path.
+
+`text` (String)
+
+: The contents of the file.
+
+The created file is marked as executable.
+The store path will include the name, and it will be a file.
+
+This function is almost exactly like [](#trivial-builder-writeScript), except that it prepends to the file a [shebang](https://en.wikipedia.org/wiki/Shebang_%28Unix%29) line that points to the version of Bash used in Nixpkgs.
+<!-- this cannot be changed in practice, so there is no point pretending it's somehow generic -->
+
+::: {.example #ex-writeShellScript}
+# Usage of `writeShellScript`
+
+```nix
+writeShellScript "my-script" ''
+  echo "hi"
+''
+```
+:::
+
+This is equivalent to:
+
+```nix
+writeTextFile {
+  name = "my-script";
+  text = ''
+    #! ${pkgs.runtimeShell}
+    echo "hi"
+  '';
+  executable = true;
+}
+```
+
+### `writeShellScriptBin` {#trivial-builder-writeShellScriptBin}
+
+Write a Bash script to a "bin" subdirectory of a directory in the Nix store.
+
+`writeShellScriptBin` takes the following arguments:
+
+`name` (String)
+
+: The name used in the Nix store path and within the file generated under the store path.
+
+`text` (String)
+
+: The contents of the file.
+
+The file's contents will be put into `/nix/store/<store path>/bin/<name>`.
+The store path will include the name, and it will be a directory.
+
+This function is a combination of [](#trivial-builder-writeShellScript) and [](#trivial-builder-writeScriptBin).
+
+::: {.example #ex-writeShellScriptBin}
+# Usage of `writeShellScriptBin`
+
+```nix
+writeShellScriptBin "my-script" ''
+  echo "hi"
+''
+```
+:::
+
+This is equivalent to:
+
+```nix
+writeTextFile {
+  name = "my-script";
+  text = ''
+    #! ${pkgs.runtimeShell}
+    echo "hi"
+  '';
+  executable = true;
+  destination = "/bin/my-script";
+}
+```
+
+## `concatTextFile`, `concatText`, `concatScript` {#trivial-builder-concatText}
+
+These functions concatenate `files` to the Nix store in a single file. This is useful for configuration files structured in lines of text. `concatTextFile` takes an attribute set and expects two arguments, `name` and `files`. `name` corresponds to the name used in the Nix store path. `files` will be the files to be concatenated. You can also set `executable` to true to make this file have the executable bit set.
+`concatText` and`concatScript` are simple wrappers over `concatTextFile`.
+
+Here are a few examples:
+```nix
+# Writes my-file to /nix/store/<store path>
+concatTextFile
+  {
+    name = "my-file";
+    files = [
+      drv1
+      "${drv2}/path/to/file"
+    ];
+  }
+  # See also the `concatText` helper function below.
+
+  # Writes executable my-file to /nix/store/<store path>/bin/my-file
+  concatTextFile
+  {
+    name = "my-file";
+    files = [
+      drv1
+      "${drv2}/path/to/file"
+    ];
+    executable = true;
+    destination = "/bin/my-file";
+  }
+  # Writes contents of files to /nix/store/<store path>
+  concatText
+  "my-file"
+  [
+    file1
+    file2
+  ]
+
+  # Writes contents of files to /nix/store/<store path>
+  concatScript
+  "my-file"
+  [
+    file1
+    file2
+  ]
+```
+
+## `writeShellApplication` {#trivial-builder-writeShellApplication}
+
+`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`.
+
+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 {
+  name = "show-nixos-org";
+
+  runtimeInputs = [
+    curl
+    w3m
+  ];
+
+  text = ''
+    curl -s 'https://nixos.org' | w3m -dump -T text/html
+  '';
+}
+```
+
+## `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` (or alternatively `pname` and `version`) 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.
+Here is an example:
+```nix
+# adds symlinks of hello and stack to current build and prints "links added"
+symlinkJoin {
+  name = "myexample";
+  paths = [
+    pkgs.hello
+    pkgs.stack
+  ];
+  postBuild = "echo links added";
+}
+```
+This creates a derivation with a directory structure like the following:
+```
+/nix/store/sglsr5g079a5235hy29da3mq3hv8sjmm-myexample
+|-- bin
+|   |-- hello -> /nix/store/qy93dp4a3rqyn2mz63fbxjg228hffwyw-hello-2.10/bin/hello
+|   `-- stack -> /nix/store/6lzdpxshx78281vy056lbk553ijsdr44-stack-2.1.3.1/bin/stack
+`-- share
+    |-- bash-completion
+    |   `-- completions
+    |       `-- stack -> /nix/store/6lzdpxshx78281vy056lbk553ijsdr44-stack-2.1.3.1/share/bash-completion/completions/stack
+    |-- fish
+    |   `-- vendor_completions.d
+    |       `-- stack.fish -> /nix/store/6lzdpxshx78281vy056lbk553ijsdr44-stack-2.1.3.1/share/fish/vendor_completions.d/stack.fish
+...
+```
+
+## `writeClosure` {#trivial-builder-writeClosure}
+
+Given a list of [store paths](https://nixos.org/manual/nix/stable/glossary#gloss-store-path) (or string-like expressions coercible to store paths), write their collective [closure](https://nixos.org/manual/nix/stable/glossary#gloss-closure) to a text file.
+
+The result is equivalent to the output of `nix-store -q --requisites`.
+
+For example,
+
+```nix
+writeClosure [ (writeScriptBin "hi" "${hello}/bin/hello") ]
+```
+
+produces an output path `/nix/store/<hash>-runtime-deps` containing
+
+```
+/nix/store/<hash>-hello-2.10
+/nix/store/<hash>-hi
+/nix/store/<hash>-libidn2-2.3.0
+/nix/store/<hash>-libunistring-0.9.10
+/nix/store/<hash>-glibc-2.32-40
+```
+
+You can see that this includes `hi`, the original input path,
+`hello`, which is a direct reference, but also
+the other paths that are indirectly required to run `hello`.
+
+## `writeDirectReferencesToFile` {#trivial-builder-writeDirectReferencesToFile}
+
+Writes the set of references to the output file, that is, their immediate dependencies.
+
+This produces the equivalent of `nix-store -q --references`.
+
+For example,
+
+```nix
+writeDirectReferencesToFile (writeScriptBin "hi" "${hello}/bin/hello")
+```
+
+produces an output path `/nix/store/<hash>-runtime-references` containing
+
+```
+/nix/store/<hash>-hello-2.10
+```
+
+but none of `hello`'s dependencies because those are not referenced directly
+by `hi`'s output.