From e97de7f4af813e280e69e38bbf12e9678c06e87c Mon Sep 17 00:00:00 2001
From: Yueh-Shun Li <shamrocklee@posteo.net>
Date: Fri, 3 Jul 2026 00:06:04 +0800
Subject: [PATCH 1/3] doc/fixed-point-arguments: explicitly mention
 extendDrvArgs

---
 doc/build-helpers/fixed-point-arguments.chapter.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/doc/build-helpers/fixed-point-arguments.chapter.md b/doc/build-helpers/fixed-point-arguments.chapter.md
index 000dfe097abc..8de6636083e2 100644
--- a/doc/build-helpers/fixed-point-arguments.chapter.md
+++ b/doc/build-helpers/fixed-point-arguments.chapter.md
@@ -23,7 +23,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`).
 

From 068e58f4cbe61abe49e46d62ca82982d72a98586 Mon Sep 17 00:00:00 2001
From: Yueh-Shun Li <shamrocklee@posteo.net>
Date: Fri, 3 Jul 2026 00:29:17 +0800
Subject: [PATCH 2/3] doc/fixed-point-arguments: make examples
 callPackage-compatible

---
 doc/build-helpers/fixed-point-arguments.chapter.md | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/doc/build-helpers/fixed-point-arguments.chapter.md b/doc/build-helpers/fixed-point-arguments.chapter.md
index 8de6636083e2..190b14d52235 100644
--- a/doc/build-helpers/fixed-point-arguments.chapter.md
+++ b/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";
@@ -37,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 = [

From 1c8c1cc2a7964f879cc8b0333dd039fd4fc3f83c Mon Sep 17 00:00:00 2001
From: Yueh-Shun Li <shamrocklee@posteo.net>
Date: Fri, 3 Jul 2026 01:16:44 +0800
Subject: [PATCH 3/3] doc/fixed-point-arguments: add an example of wrapping
 with transformDrv

---
 .../fixed-point-arguments.chapter.md          | 69 +++++++++++++++++++
 doc/redirects.json                            |  3 +
 2 files changed, 72 insertions(+)

diff --git a/doc/build-helpers/fixed-point-arguments.chapter.md b/doc/build-helpers/fixed-point-arguments.chapter.md
index 190b14d52235..197aea8136d5 100644
--- a/doc/build-helpers/fixed-point-arguments.chapter.md
+++ b/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
+      '';
+    });
+}
+```
diff --git a/doc/redirects.json b/doc/redirects.json
index 1c1cb0676928..75f5c3869764 100644
--- a/doc/redirects.json
+++ b/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"
   ],