@@ -50,3 +50,50 @@ Many more commands wrap `writeTextFile` including `writeText`, `writeTextDir`, `
5050## `symlinkJoin` {#trivial-builder-symlinkJoin}
5151
5252This 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.
53+
54+## `writeReferencesToFile` {#trivial-builder-writeReferencesToFile}
55+
56+Writes the closure of transitive dependencies to a file.
57+
58+This produces the equivalent of `nix-store -q --requisites`.
59+
60+For example,
61+
62+```nix
63+writeReferencesToFile (writeScriptBin "hi" ''${hello}/bin/hello'')
64+```
65+
66+produces an output path `/nix/store/<hash>-runtime-deps` containing
67+
68+```nix
69+/nix/store/<hash>-hello-2.10
70+/nix/store/<hash>-hi
71+/nix/store/<hash>-libidn2-2.3.0
72+/nix/store/<hash>-libunistring-0.9.10
73+/nix/store/<hash>-glibc-2.32-40
74+```
75+
76+You can see that this includes `hi`, the original input path,
77+`hello`, which is a direct reference, but also
78+the other paths that are indirectly required to run `hello`.
79+
80+## `writeDirectReferencesToFile` {#trivial-builder-writeDirectReferencesToFile}
81+
82+Writes the set of references to the output file, that is, their immediate dependencies.
83+
84+This produces the equivalent of `nix-store -q --references`.
85+
86+For example,
87+
88+```nix
89+writeDirectReferencesToFile (writeScriptBin "hi" ''${hello}/bin/hello'')
90+```
91+
92+produces an output path `/nix/store/<hash>-runtime-references` containing
93+
94+```nix
95+/nix/store/<hash>-hello-2.10
96+```
97+
98+but none of `hello`'s dependencies, because those are not referenced directly
99+by `hi`'s output.