From d7a6d04353b97e02464fc2eed8f997af535385f7 Mon Sep 17 00:00:00 2001
From: Robin De Schepper <robin.deschepper93@gmail.com>
Date: Tue, 19 Sep 2023 11:57:03 +0200
Subject: [PATCH 1/3] feature: `CIBW_DEBUG_KEEP_CONTAINER` option. debug
 container after build

---
 cibuildwheel/oci_container.py | 16 +++++++++-------
 docs/options.md               | 32 ++++++++++++++++++++++++++++++++
 2 files changed, 41 insertions(+), 7 deletions(-)

diff --git a/cibuildwheel/oci_container.py b/cibuildwheel/oci_container.py
index 1e1a19a8..e2430144 100644
--- a/cibuildwheel/oci_container.py
+++ b/cibuildwheel/oci_container.py
@@ -17,7 +17,7 @@ from types import TracebackType
 from typing import IO, Dict, Literal
 
 from .typing import PathOrStr, PopenBytes
-from .util import CIProvider, detect_ci_provider, parse_key_value_string
+from .util import CIProvider, detect_ci_provider, parse_key_value_string, strtobool
 
 ContainerEngineName = Literal["docker", "podman"]
 
@@ -178,12 +178,14 @@ class OCIContainer:
 
         assert isinstance(self.name, str)
 
-        subprocess.run(
-            [self.engine.name, "rm", "--force", "-v", self.name],
-            stdout=subprocess.DEVNULL,
-            check=False,
-        )
-        self.name = None
+        keep_container = strtobool(os.environ.get("CIBW_DEBUG_KEEP_CONTAINER", ""))
+        if not keep_container:
+            subprocess.run(
+                [self.engine.name, "rm", "--force", "-v", self.name],
+                stdout=subprocess.DEVNULL,
+                check=False,
+            )
+            self.name = None
 
     def copy_into(self, from_path: Path, to_path: PurePath) -> None:
         # `docker cp` causes 'no space left on device' error when
diff --git a/docs/options.md b/docs/options.md
index 078c907d..f44e0b75 100644
--- a/docs/options.md
+++ b/docs/options.md
@@ -1426,6 +1426,38 @@ This option is not supported in the overrides section in `pyproject.toml`.
     test-skip = "*-macosx_arm64 *-macosx_universal2:arm64"
     ```
 
+## Debugging
+
+### `CIBW_DEBUG_KEEP_CONTAINER`
+
+Enable this flag to keep the container around for inspection after a build. This
+option is provided for debugging purposes only.
+
+Default: Off (0).
+
+!!! caution
+    This option can only be set as environment variable on the host machine
+
+#### Examples
+
+!!! tab examples "Linux"
+
+    ```shell
+    export CIBW_DEBUG_KEEP_CONTAINER=TRUE
+    ```
+
+!!! tab examples "Windows"
+
+    ```shell
+    set CIBW_DEBUG_KEEP_CONTAINER=TRUE
+    ```
+
+!!! tab examples "MacOS"
+
+    ```shell
+    export CIBW_DEBUG_KEEP_CONTAINER=TRUE
+    ```
+
 ## Other
 
 ### `CIBW_BUILD_VERBOSITY` {: #build-verbosity}

From a1bebe5362a5cb4c6c2d2ae8f6d3d64646b1c41d Mon Sep 17 00:00:00 2001
From: Robin De Schepper <robin.deschepper93@gmail.com>
Date: Tue, 19 Sep 2023 16:39:23 +0200
Subject: [PATCH 2/3] addressed comments from review

---
 docs/options.md | 22 +++-------------------
 1 file changed, 3 insertions(+), 19 deletions(-)

diff --git a/docs/options.md b/docs/options.md
index f44e0b75..660894a1 100644
--- a/docs/options.md
+++ b/docs/options.md
@@ -1440,25 +1440,9 @@ Default: Off (0).
 
 #### Examples
 
-!!! tab examples "Linux"
-
-    ```shell
-    export CIBW_DEBUG_KEEP_CONTAINER=TRUE
-    ```
-
-!!! tab examples "Windows"
-
-    ```shell
-    set CIBW_DEBUG_KEEP_CONTAINER=TRUE
-    ```
-
-!!! tab examples "MacOS"
-
-    ```shell
-    export CIBW_DEBUG_KEEP_CONTAINER=TRUE
-    ```
-
-## Other
+```shell
+export CIBW_DEBUG_KEEP_CONTAINER=TRUE
+```
 
 ### `CIBW_BUILD_VERBOSITY` {: #build-verbosity}
 > Increase/decrease the output of pip wheel

From 28ad6e4b400f92fecd4be360da5be267178b872d Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Tue, 19 Sep 2023 19:00:48 +0000
Subject: [PATCH 3/3] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 cibuildwheel/oci_container.py | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/cibuildwheel/oci_container.py b/cibuildwheel/oci_container.py
index b6b01338..1b2e207b 100644
--- a/cibuildwheel/oci_container.py
+++ b/cibuildwheel/oci_container.py
@@ -17,7 +17,13 @@ from types import TracebackType
 from typing import IO, Dict, Literal
 
 from .typing import PathOrStr, PopenBytes
-from .util import CIProvider, call, detect_ci_provider, parse_key_value_string, strtobool
+from .util import (
+    CIProvider,
+    call,
+    detect_ci_provider,
+    parse_key_value_string,
+    strtobool,
+)
 
 ContainerEngineName = Literal["docker", "podman"]