From 1e06a3fb2decca65b8e0b1ee07af8fc20f1d7489 Mon Sep 17 00:00:00 2001 From: Yueh-Shun Li Date: Sun, 28 May 2023 21:55:43 +0800 Subject: [PATCH] doc: add chapter Fixed-point arguments of build helpers Add "Fixed-point arguments of build helpers" chapter in "Builde helpers" part. Co-authored-by: nicoo Co-authored-by: Silvan Mosberger Co-authored-by: Valentin Gagarin Co-authored-by: Lin Jian Co-authored-by: Philip Taron --- doc/build-helpers.md | 1 + .../fixed-point-arguments.chapter.md | 74 +++++++++++++++++++ doc/redirects.json | 12 +++ 3 files changed, 87 insertions(+) create mode 100644 doc/build-helpers/fixed-point-arguments.chapter.md diff --git a/doc/build-helpers.md b/doc/build-helpers.md index 010665484cfdaa..a9df144bacbf19 100644 --- a/doc/build-helpers.md +++ b/doc/build-helpers.md @@ -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 diff --git a/doc/build-helpers/fixed-point-arguments.chapter.md b/doc/build-helpers/fixed-point-arguments.chapter.md new file mode 100644 index 00000000000000..948473acd48b57 --- /dev/null +++ b/doc/build-helpers/fixed-point-arguments.chapter.md @@ -0,0 +1,74 @@ +# 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 [`.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: ...; }`. diff --git a/doc/redirects.json b/doc/redirects.json index 254e6ceb6fc6e3..7fd6ee6c49ac09 100644 --- a/doc/redirects.json +++ b/doc/redirects.json @@ -1,7 +1,16 @@ { + "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" + ], + "ex-build-helpers-extendMkDerivation-excludeDrvArgNames-emptying": [ + "index.html#ex-build-helpers-extendMkDerivation-excludeDrvArgNames-emptying" + ], "neovim": [ "index.html#neovim" ], @@ -38,6 +47,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" ],