add docs for makeSetupHook

2 files changed, 38 insertions, 0 deletions

diff --git a/doc/builders/special.xml b/doc/builders/special.xml
index 525eb71abfe7e..c971134819818 100644
--- a/doc/builders/special.xml
+++ b/doc/builders/special.xml
@@ -6,6 +6,7 @@
   This chapter describes several special builders.
  </para>
  <xi:include href="special/fhs-environments.section.xml" />
+ <xi:include href="special/makesetuphook.section.xml" />
  <xi:include href="special/mkshell.section.xml" />
  <xi:include href="special/darwin-builder.section.xml" />
 </chapter>
diff --git a/doc/builders/special/makesetuphook.section.md b/doc/builders/special/makesetuphook.section.md
new file mode 100644
index 0000000000000..90d75c5491cff
--- /dev/null
+++ b/doc/builders/special/makesetuphook.section.md
@@ -0,0 +1,37 @@
+# pkgs.makeSetupHook {#sec-pkgs.makeSetupHook}
+
+`pkgs.makeSetupHook` is a builder 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
+
+```nix
+pkgs.makeSetupHook {
+    name = "run-hello-hook";
+    propagatedBuildInputs = [ pkgs.hello ];
+    substitutions = { shell = "${pkgs.bash}/bin/bash"; };
+    passthru.tests.greeting = callPackage ./test { };
+    meta.platforms = lib.platforms.linux;
+} (writeScript "run-hello-hook.sh" ''
+    #!@shell@
+    hello
+'')
+```
+
+## 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`