doc/fixed-point-arguments: add an example of wrapping with transformDrv

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

@@ -74,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"
   ],