Commit bbdf8601 authored by Yueh-Shun Li's avatar Yueh-Shun Li
Browse files

doc: add chapter Fixed-point arguments of build helpers 



Add "Fixed-point arguments of build helpers" chapter in "Builde helpers" part.

Co-authored-by: default avatarnicoo <nicoo@mur.at>
Co-authored-by: default avatarSilvan Mosberger <github@infinisil.com>
Co-authored-by: default avatarValentin Gagarin <valentin.gagarin@tweag.io>
Co-authored-by: default avatarLin Jian <me@linj.tech>
Co-authored-by: default avatarPhilip Taron <philip.taron@gmail.com>
parent 2439ead7

doc/build-helpers.md

+1 −0
Original line number Diff line number Diff line
@@ -17,6 +17,7 @@ There is no uniform interface for build helpers. 
[Language- or framework-specific build helpers](#chap-language-support) usually follow the style of `stdenv.mkDerivation`, which accepts an attribute set or a fixed-point function taking an attribute set.



```{=include=} chapters

build-helpers/fixed-point-arguments.chapter.md

build-helpers/fetchers.chapter.md

build-helpers/trivial-build-helpers.chapter.md

build-helpers/testers.chapter.md

doc/build-helpers/fixed-point-arguments.chapter.md

0 → 100644
+74 −0
Original line number Diff line number Diff line 
# Fixed-point arguments of build helpers {#chap-build-helpers-finalAttrs}



As 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.

A build helper like this is said to accept **fixed-point arguments**.



Build helpers don't always support fixed-point arguments yet, as support in [`stdenv.mkDerivation`](#mkderivation-recursive-attributes) was first included in Nixpkgs 22.05.



## Defining a build helper with `lib.extendMkDerivation` {#sec-build-helper-extendMkDerivation}



Developers 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).



Beside overriding, `lib.extendMkDerivation` also supports `excludeDrvArgNames` to optionally exclude some arguments in the input fixed-point argumnts from passing down the base build helper (specified as `constructDrv`).



:::{.example #ex-build-helpers-extendMkDerivation}



# Example definition of `mkLocalDerivation` extended from `stdenv.mkDerivation` with `lib.extendMkDerivation`



We want to define a build helper named `mkLocalDerivation` that builds locally without using substitutes by default.



Instead of taking a plain attribute set,



```nix

{

  preferLocalBuild ? true,

  allowSubstitute ? false,

  specialArg ? (_: false),

  ...

}@args:



stdenv.mkDerivation (

  removeAttrs [

    # Don't pass specialArg into mkDerivation.

    "specialArg"

  ] args

  // {

    # Arguments to pass

    inherit preferLocalBuild allowSubstitute;

    # Some expressions involving specialArg

    greeting = if specialArg "hi" then "hi" else "hello";

  }

)

```



we 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:



```nix

lib.extendMkDerivation {

  constructDrv = stdenv.mkDerivation;

  excludeDrvArgNames = [

    # Don't pass specialArg into mkDerivation.

    "specialArg"

  ];

  extendDrvArgs =

    finalAttrs:

    {

      preferLocalBuild ? true,

      allowSubstitute ? false,

      specialArg ? (_: false),

      ...

    }@args:

    {

      # Arguments to pass

      inherit

        preferLocalBuild

        allowSubstitute

        ;

      # Some expressions involving specialArg

      greeting = if specialArg "hi" then "hi" else "hello";

    };

}

```

:::



If one needs to apply extra changes to the result derivation, pass the derivation transformation function to `lib.extendMkDerivation` as `lib.customisation.extendMkDerivation { transformDrv = drv: ...; }`.

doc/redirects.json

+9 −0
Original line number Diff line number Diff line 
{

  "chap-build-helpers-finalAttrs": [

    "index.html#chap-build-helpers-finalAttrs"

  ],

  "chap-release-notes": [

    "release-notes.html#chap-release-notes"

  ],

  "ex-build-helpers-extendMkDerivation": [

    "index.html#ex-build-helpers-extendMkDerivation"

  ],

  "neovim": [

    "index.html#neovim"

  ],
@@ -38,6 +44,9 @@ 
  "sec-allow-insecure": [

    "index.html#sec-allow-insecure"

  ],

  "sec-build-helper-extendMkDerivation": [

    "index.html#sec-build-helper-extendMkDerivation"

  ],

  "sec-modify-via-packageOverrides": [

    "index.html#sec-modify-via-packageOverrides"

  ],