From 2204a9470bac102b7f00fdd679eeb6ed4f5eb9e2 Mon Sep 17 00:00:00 2001
From: Saehej Kang <20051028+saehejkang@users.noreply.github.com>
Date: Tue, 3 Mar 2026 08:20:06 -0800
Subject: [PATCH] [building]: add steps for using container-builder-shim
 locally (#1279)

- Update build steps for using the `container-builder-shim` locally

---------

Co-authored-by: jwhur <57657645+JaewonHur@users.noreply.github.com>
---
 BUILDING.md | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/BUILDING.md b/BUILDING.md
index c3cfb235..8f80dd11 100644
--- a/BUILDING.md
+++ b/BUILDING.md
@@ -127,6 +127,29 @@ To revert to using the Containerization dependency from your `Package.swift`:
     bin/container system start
     ```
 
+## Develop using a local copy of container-builder-shim
+
+To test changes that require the `container-builder-shim` project:
+
+1. Clone the [container-builder-shim](https://github.com/apple/container-builder-shim) repository and navigate to its directory.
+
+2. After making the necessary changes, build the custom builder image, set it as the active builder image, and remove the existing `buildkit` container so the new image will be used:
+
+```bash
+container build -t builder .
+container system property set image.builder builder:latest
+container rm -f buildkit
+```
+
+3. Run the `container` build as usual:
+
+```bash
+container build ...
+```
+
+> [!IMPORTANT]
+> If your modified builder image is broken, make sure to rebuild and correctly tag the builder image before attempting to build `container-builder-shim` again.
+
 ## Debug XPC Helpers
 
 Attach debugger to the XPC helpers using their launchd service labels: