pyrox.dev
1# Fixed-point arguments of build helpers {#chap-build-helpers-finalAttrs}
2
3As mentioned in the beginning of this part, `stdenv.mkDerivation` could alternatively accept a fixed-point function. The input of such function, typically named `finalAttrs`, is expected to be the final state of the attribute set.
4A build helper like this is said to accept **fixed-point arguments**.
5
6Build helpers don't always support fixed-point arguments yet, as support in [`stdenv.mkDerivation`](#mkderivation-recursive-attributes) was first included in Nixpkgs 22.05.
7
8## Defining a build helper with `lib.extendMkDerivation` {#sec-build-helper-extendMkDerivation}
9
10Developers can use the Nixpkgs library function [`lib.customisation.extendMkDerivation`](#function-library-lib.customisation.extendMkDerivation) to define a build helper supporting fixed-point arguments from an existing one with such support, with an attribute overlay similar to the one taken by [`<pkg>.overrideAttrs`](#sec-pkg-overrideAttrs).
11
12Beside overriding, `lib.extendMkDerivation` also supports `excludeDrvArgNames` to optionally exclude some arguments in the input fixed-point arguments from passing down the base build helper (specified as `constructDrv`).
13
14:::{.example #ex-build-helpers-extendMkDerivation}
15
16# Example definition of `mkLocalDerivation` extended from `stdenv.mkDerivation` with `lib.extendMkDerivation`
17
18We want to define a build helper named `mkLocalDerivation` that builds locally without using substitutes by default.
19
20Instead of taking a plain attribute set,
21
22```nix
23{
24 preferLocalBuild ? true,
25 allowSubstitute ? false,
26 specialArg ? (_: false),
27 ...
28}@args:
29
30stdenv.mkDerivation (
31 removeAttrs [
32 # Don't pass specialArg into mkDerivation.
33 "specialArg"
34 ] args
35 // {
36 # Arguments to pass
37 inherit preferLocalBuild allowSubstitute;
38 # Some expressions involving specialArg
39 greeting = if specialArg "hi" then "hi" else "hello";
40 }
41)
42```
43
44we could define with `lib.extendMkDerivation` an attribute overlay to make the result build helper also accepts the the attribute set's fixed point passing to the underlying `stdenv.mkDerivation`, named `finalAttrs` here:
45
46```nix
47lib.extendMkDerivation {
48 constructDrv = stdenv.mkDerivation;
49 excludeDrvArgNames = [
50 # Don't pass specialArg into mkDerivation.
51 "specialArg"
52 ];
53 extendDrvArgs =
54 finalAttrs:
55 {
56 preferLocalBuild ? true,
57 allowSubstitute ? false,
58 specialArg ? (_: false),
59 ...
60 }@args:
61 {
62 # Arguments to pass
63 inherit preferLocalBuild allowSubstitute;
64 # Some expressions involving specialArg
65 greeting = if specialArg "hi" then "hi" else "hello";
66 };
67}
68```
69:::
70
71If one needs to apply extra changes to the result derivation, pass the derivation transformation function to `lib.extendMkDerivation` as `lib.customisation.extendMkDerivation { transformDrv = drv: ...; }`.