writeReferencesToFile: docs and tests

2 files changed, 42 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.
diff --git a/pkgs/build-support/trivial-builders/test.sh b/pkgs/build-support/trivial-builders/test.sh
index eec501ae601..3e21b000815 100755
--- a/pkgs/build-support/trivial-builders/test.sh
+++ b/pkgs/build-support/trivial-builders/test.sh
@@ -38,4 +38,20 @@ testDirectReferences 'writeText "hi" "hello"'
 testDirectReferences 'writeText "hi" "hello ${hello}"'
 testDirectReferences 'writeText "hi" "hello ${hello} ${figlet}"'
 
+
+
+testClosure() {
+  expr="$1"
+  diff -U3 \
+    <(sort <$(nix-build --no-out-link --expr "with import ../../.. {}; writeReferencesToFile ($expr)")) \
+    <(nix-store -q --requisites $(nix-build --no-out-link --expr "with import ../../.. {}; ($expr)") | sort)
+}
+
+testClosure 'hello'
+testClosure 'figlet'
+testClosure 'writeText "hi" "hello"'
+testClosure 'writeText "hi" "hello ${hello}"'
+testClosure 'writeText "hi" "hello ${hello} ${figlet}"'
+
+
 echo 'OK!'