From 2e7d15303cd9f208ac698a0ea25c7be056e38c89 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?J=C3=B6rg=20Thalheim?= <joerg@thalheim.io>
Date: Wed, 25 Mar 2026 10:16:50 +0100
Subject: [PATCH 1/2] nixos/sd-image: add type and improve postBuildCommands
 description

The option was missing a type declaration. Use types.lines so multiple
modules can contribute commands that get merged with newlines.

While at it, document the $img shell variable so users do not have to
read the module source to discover it.
---
 nixos/modules/installer/sd-card/sd-image.nix | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/nixos/modules/installer/sd-card/sd-image.nix b/nixos/modules/installer/sd-card/sd-image.nix
index b3251f9c6e1d..223961228ba5 100644
--- a/nixos/modules/installer/sd-card/sd-image.nix
+++ b/nixos/modules/installer/sd-card/sd-image.nix
@@ -180,11 +180,16 @@ in
     };
 
     postBuildCommands = mkOption {
+      type = types.lines;
       example = literalExpression "'' dd if=\${pkgs.myBootLoader}/SPL of=$img bs=1024 seek=1 conv=notrunc ''";
       default = "";
       description = ''
-        Shell commands to run after the image is built.
-        Can be used for boards requiring to dd u-boot SPL before actual partitions.
+        Shell commands to run after the SD image has been assembled.
+
+        The path to the image is available in the {var}`img` shell
+        variable. This hook is typically used for boards that require
+        writing a bootloader (such as u-boot SPL) to a fixed offset
+        before the first partition.
       '';
     };
 

From 6fec0974dcc3a6a839e6eff42853611a7d70f3d9 Mon Sep 17 00:00:00 2001
From: Tanel Dettenborn <tanel.dettenborn@tii.ae>
Date: Wed, 25 Mar 2026 10:17:09 +0100
Subject: [PATCH 2/2] nixos/sd-image: add preBuildCommands option

Allow running shell commands after the root filesystem image has been
prepared but before the final SD image is assembled. This is useful for
adjusting the rootfs, such as resizing it to a fixed size or injecting
additional files, without having to override the entire build
derivation.

Signed-off-by: Tanel Dettenborn <tanel.dettenborn@tii.ae>
---
 nixos/modules/installer/sd-card/sd-image.nix | 29 ++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/nixos/modules/installer/sd-card/sd-image.nix b/nixos/modules/installer/sd-card/sd-image.nix
index 223961228ba5..237a96f4e3c6 100644
--- a/nixos/modules/installer/sd-card/sd-image.nix
+++ b/nixos/modules/installer/sd-card/sd-image.nix
@@ -179,6 +179,33 @@ in
       '';
     };
 
+    preBuildCommands = mkOption {
+      type = types.lines;
+      example = literalExpression ''
+        '''
+          if [ ! -w "$root_fs" ]; then
+            cp --no-preserve=mode "$root_fs" ./root-fs.img
+            root_fs=./root-fs.img
+          fi
+          resize2fs $root_fs 15G
+        '''
+      '';
+      default = "";
+      description = ''
+        Shell commands to run after the root filesystem image has been
+        prepared, but before the final SD image is assembled.
+
+        The path to the root filesystem image is available in the
+        {var}`root_fs` shell variable. This hook can be used to modify
+        the rootfs, for example to resize it or inject additional files.
+
+        Note that when {option}`sdImage.compressImage` is disabled,
+        {var}`root_fs` points to a read-only store path. To modify it,
+        first copy it to a writable location and update {var}`root_fs`
+        to point to the copy.
+      '';
+    };
+
     postBuildCommands = mkOption {
       type = types.lines;
       example = literalExpression "'' dd if=\${pkgs.myBootLoader}/SPL of=$img bs=1024 seek=1 conv=notrunc ''";
@@ -289,6 +316,8 @@ in
             zstd -d --no-progress "${config.sdImage.rootFilesystemImage}" -o $root_fs
           ''}
 
+          ${config.sdImage.preBuildCommands}
+
           # Gap in front of the first partition, in MiB
           gap=${toString config.sdImage.firmwarePartitionOffset}