writeReferencesToFile: docs and tests

1 files changed, 26 insertions, 0 deletions

diff --git a/doc/builders/trivial-builders.chapter.md b/doc/builders/trivial-builders.chapter.md
index 432183eaf0f..bc1317cc49c 100644
--- a/doc/builders/trivial-builders.chapter.md
+++ b/doc/builders/trivial-builders.chapter.md
@@ -51,6 +51,32 @@ Many more commands wrap `writeTextFile` including `writeText`, `writeTextDir`, `
 
 This can be used to put many derivations into the same directory structure. It works by creating a new derivation and adding symlinks to each of the paths listed. It expects two arguments, `name`, and `paths`. `name` is the name used in the Nix store path for the created derivation. `paths` is a list of paths that will be symlinked. These paths can be to Nix store derivations or any other subdirectory contained within.
 
+## `writeReferencesToFile` {#trivial-builder-writeReferencesToFile}
+
+Writes the closure of transitive dependencies to a file.
+
+This produces the equivalent of `nix-store -q --requisites`.
+
+For example,
+
+```nix
+writeReferencesToFile (writeScriptBin "hi" ''${hello}/bin/hello'')
+```
+
+produces an output path `/nix/store/<hash>-runtime-deps` containing
+
+```nix
+/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.