add docs for makeSetupHook

This commit is contained in:
Artturin 2023-01-28 21:57:21 +02:00
parent 8f171925b3
commit 680309fc9c
3 changed files with 39 additions and 28 deletions

View file

@ -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>

View file

@ -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`

View file

@ -593,34 +593,7 @@ rec {
in linkFarm name (map mkEntryFromDrv drvs);
/*
* Make a package that just contains a setup hook with the given contents.
* This setup hook will be invoked by any package that includes this package
* as a buildInput. Optionally takes a list of substitutions that should be
* applied to the resulting script.
*
* Examples:
* # setup hook that depends on the hello package and runs ./myscript.sh
* myhellohook = makeSetupHook { propagatedBuildInputs = [ hello ]; } ./myscript.sh;
*
* # writes a Linux-exclusive setup hook where @bash@ myscript.sh is substituted for the
* # bash interpreter.
* myhellohookSub = makeSetupHook {
* name = "myscript-hook";
* propagatedBuildInputs = [ hello ];
* substitutions = { bash = "${pkgs.bash}/bin/bash"; };
* meta.platforms = lib.platforms.linux;
* } ./myscript.sh;
*
* # setup hook with a package test
* myhellohookTested = makeSetupHook {
* name = "myscript-hook";
* propagatedBuildInputs = [ hello ];
* substitutions = { bash = "${pkgs.bash}/bin/bash"; };
* meta.platforms = lib.platforms.linux;
* passthru.tests.greeting = callPackage ./test { };
* } ./myscript.sh;
*/
# docs in doc/builders/special/makesetuphook.section.md
makeSetupHook =
{ name ? lib.warn "calling makeSetupHook without passing a name is deprecated." "hook"
, deps ? [ ]