doc/fixed-point-arguments: add an example of wrapping with transformDrv and miscelaneous fixes (#537881)

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

@@ -3,6 +3,10 @@
 `stdenv.mkDerivation` also accepts a [fixed-point function](#function-library-lib.fixedPoints.fix) instead of a plain attribute set:
 
 ```nix
+{
+  stdenv,
+  fetchurl,
+}:
 stdenv.mkDerivation (finalAttrs: {
   pname = "hello";
   version = "2.12";
@@ -23,7 +27,8 @@ See [recursive-sets](https://nix.dev/manual/nix/stable/language/syntax#recursive
 
 ## Define a build helper with `lib.extendMkDerivation` {#sec-build-helper-extendMkDerivation}
 
-Use [`lib.customisation.extendMkDerivation`](#function-library-lib.customisation.extendMkDerivation) to define a build helper with fixed-point support from an existing one. It takes an attribute overlay similar to [`<pkg>.overrideAttrs`](#sec-pkg-overrideAttrs).
+Use [`lib.customisation.extendMkDerivation`](#function-library-lib.customisation.extendMkDerivation) to define a build helper with fixed-point support from an existing one.
+Its argument `extendDrvArgs` takes an attribute overlay similar to [`<pkg>.overrideAttrs`](#sec-pkg-overrideAttrs).
 
 Besides overriding, `lib.extendMkDerivation` also supports `excludeDrvArgNames` to optionally exclude some arguments in the input fixed-point arguments from passing down to the base build helper (specified as `constructDrv`).
 
@@ -36,6 +41,10 @@ Define a build helper named `mkLocalDerivation` that builds locally without usin
 Use `lib.extendMkDerivation`:
 
 ```nix
+{
+  lib,
+  stdenv,
+}:
 lib.extendMkDerivation {
   constructDrv = stdenv.mkDerivation;
   excludeDrvArgNames = [
@@ -65,3 +74,72 @@ To apply extra changes to the result derivation, pass `transformDrv` to `lib.ext
 ```nix
 lib.customisation.extendMkDerivation { transformDrv = drv: /...; }
 ```
+
+Construct a wrapper derivation around another derivation using `transformDrv`
+
+The wrapper has access to the original arguments
+
+:::{.example #ex-build-helpers-extendMkDerivation-transformDrv-wrapper}
+
+# Define a custom build helper that downloads and builds
+
+```nix
+{
+  lib,
+  stdenvNoCC,
+  cacert,
+  configure-example,
+  download-example,
+}:
+
+lib.extendMkDerivation {
+  constructDrv = stdenvNoCC.mkDerivation;
+
+  excludeDrvArgNames = [
+    "bar"
+  ];
+
+  extendDrvArgs =
+    finalAttrs:
+    {
+      bar,
+      foo,
+      hash ? "",
+      ...
+    }@args:
+    {
+      inherit hash;
+      nativeBuildInputs = args.nativeBuildInputs or [ ] ++ [
+        cacert
+        download-example
+      ];
+      buildPhase = ''
+        runHook preBuild
+        download-example --foo="$foo" --out="$out"
+        runHook postBuild
+      '';
+      impureEnvVars = lib.fetchers.proxyImpureEnvVars;
+      outputHash = if finalAttrs.hash != "" then finalAttrs.hash else lib.fakeHash;
+      outputHashFormat = "recursive";
+      passthru = args.passthru or { } // {
+        inherit bar;
+      };
+    };
+
+  transformDrv =
+    unwrapped:
+    stdenvNoCC.mkDerivation (finalAttrs: {
+      name = finalAttrs.src.name + "-wrapped";
+      src = unwrapped;
+      nativeBuildInputs = [
+        configure-example
+      ];
+      inherit (unwrapped) bar;
+      buildPhase = ''
+        runHook preBuild
+        configure-example --bar="$bar"
+        runHook postBuild
+      '';
+    });
+}
+```

doc/redirects.json

@@ -108,6 +108,9 @@
   "ex-build-helpers-extendMkDerivation": [
     "index.html#ex-build-helpers-extendMkDerivation"
   ],
+  "ex-build-helpers-extendMkDerivation-transformDrv-wrapper": [
+    "index.html#ex-build-helpers-extendMkDerivation-transformDrv-wrapper"
+  ],
   "ex-first-package-go": [
     "index.html#ex-first-package-go"
   ],