3 files changed, 117 insertions, 0 deletions
diff --git a/doc/builders/special/fhs-environments.section.md b/doc/builders/special/fhs-environments.section.md
new file mode 100644
index 00000000000..cacad261e28
--- /dev/null
+++ b/doc/builders/special/fhs-environments.section.md
@@ -0,0 +1,49 @@
+# buildFHSUserEnv {#sec-fhs-environments}
+
+`buildFHSUserEnv` provides a way to build and run FHS-compatible lightweight sandboxes. It creates an isolated root with bound `/nix/store`, so its footprint in terms of disk space needed is quite small. This allows one 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. It uses Linux namespaces feature to create temporary lightweight environments which are destroyed after all child processes exit, without root user rights requirement. Accepted arguments are:
+
+- `name`
+        Environment name.
+- `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.
+- `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 command that would be executed inside the sandbox and passed all the command line arguments. It defaults to `bash`.
+- `profile`
+        Optional script for `/etc/profile` within the sandbox.
+
+One can create a simple environment using a `shell.nix` like that:
+
+```nix
+{ pkgs ? import <nixpkgs> {} }:
+
+(pkgs.buildFHSUserEnv {
+  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` would then drop you into a shell with these libraries and binaries available. You can use this to run closed-source applications which expect FHS structure without hassles: simply change `runScript` to the application path, e.g. `./bin/start.sh` -- relative paths are supported.
+
+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 `wrapGAppsHook`.
diff --git a/doc/builders/special/invalidateFetcherByDrvHash.section.md b/doc/builders/special/invalidateFetcherByDrvHash.section.md
new file mode 100644
index 00000000000..7c2f03a64b7
--- /dev/null
+++ b/doc/builders/special/invalidateFetcherByDrvHash.section.md
@@ -0,0 +1,31 @@
+
+## `invalidateFetcherByDrvHash` {#sec-pkgs-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:
+
+    tests.fetchgit = invalidateFetcherByDrvHash fetchgit {
+      name = "nix-source";
+      url = "https://github.com/NixOS/nix";
+      rev = "9d9dbe6ed05854e03811c361a3380e09183f4f4a";
+      sha256 = "sha256-7DszvbCNTjpzGRmpIVAWXk20P0/XTrWZ79KSOGLrUWY=";
+    };
diff --git a/doc/builders/special/mkshell.section.md b/doc/builders/special/mkshell.section.md
new file mode 100644
index 00000000000..73cc57f485b
--- /dev/null
+++ b/doc/builders/special/mkshell.section.md
@@ -0,0 +1,37 @@
+# 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
+
+* `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`.
+
+## Building the shell
+
+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.