Merge pull request #1620 from Helveg/cibw-debug-keep-container

feat: `CIBW_DEBUG_KEEP_CONTAINER`: debug container after build

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
+from .util import (
+    CIProvider,
+    call,
+    detect_ci_provider,
+    parse_key_value_string,
+    strtobool,
+)
 
 ContainerEngineName = Literal["docker", "podman"]
 
@@ -188,6 +194,8 @@ class OCIContainer:
 
         assert isinstance(self.name, str)
 
+        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,

docs/options.md

@@ -1422,7 +1422,23 @@ This option is not supported in the overrides section in `pyproject.toml`.
     test-skip = "*-macosx_arm64 *-macosx_universal2:arm64"
     ```
 
-## Other
+## 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
+
+```shell
+export CIBW_DEBUG_KEEP_CONTAINER=TRUE
+```
 
 ### `CIBW_BUILD_VERBOSITY` {: #build-verbosity}
 > Increase/decrease the output of pip wheel