From c4bb04567baaba1c8b5ffd24cb08fc4442c968af Mon Sep 17 00:00:00 2001
From: Joe Rickerby <joerick@mac.com>
Date: Wed, 29 Jun 2022 21:06:24 +0100
Subject: [PATCH] Add docs for CIBW_CONTAINER_ENGINE

---
 README.md       |  1 +
 docs/options.md | 39 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 40 insertions(+)

diff --git a/README.md b/README.md
index 74f2adf4..fb40fc7f 100644
--- a/README.md
+++ b/README.md
@@ -130,6 +130,7 @@ Options
 |   | [`CIBW_BEFORE_BUILD`](https://cibuildwheel.readthedocs.io/en/stable/options/#before-build)  | Execute a shell command preparing each wheel's build |
 |   | [`CIBW_REPAIR_WHEEL_COMMAND`](https://cibuildwheel.readthedocs.io/en/stable/options/#repair-wheel-command)  | Execute a shell command to repair each built wheel |
 |   | [`CIBW_MANYLINUX_*_IMAGE`<br/>`CIBW_MUSLLINUX_*_IMAGE`](https://cibuildwheel.readthedocs.io/en/stable/options/#linux-image)  | Specify alternative manylinux / musllinux Docker images |
+|   | [`CIBW_CONTAINER_ENGINE`](https://cibuildwheel.readthedocs.io/en/stable/options/#container-engine)  | Specify which container engine to use when building Linux wheels |
 |   | [`CIBW_DEPENDENCY_VERSIONS`](https://cibuildwheel.readthedocs.io/en/stable/options/#dependency-versions)  | Specify how cibuildwheel controls the versions of the tools it uses |
 | **Testing** | [`CIBW_TEST_COMMAND`](https://cibuildwheel.readthedocs.io/en/stable/options/#test-command)  | Execute a shell command to test each built wheel |
 |   | [`CIBW_BEFORE_TEST`](https://cibuildwheel.readthedocs.io/en/stable/options/#before-test)  | Execute a shell command before testing each wheel |
diff --git a/docs/options.md b/docs/options.md
index 01ac29b0..6b899654 100644
--- a/docs/options.md
+++ b/docs/options.md
@@ -964,6 +964,44 @@ Auditwheel detects the version of the manylinux / musllinux standard in the imag
     Like any other option, these can be placed in `[tool.cibuildwheel.linux]`
     if you prefer; they have no effect on `macos` and `windows`.
 
+
+### `CIBW_CONTAINER_ENGINE` {: #container-engine}
+> Specify which container engine to use when building Linux wheels
+
+Options: `docker` `podman`
+
+Default: `docker`
+
+Set the container engine to use. Docker is the default, or you can switch to
+[Podman](https://podman.io/). To use Docker, you need to have a Docker daemon
+running and `docker` available on PATH. To use Podman, it needs to be
+installed and `podman` available on PATH.
+
+!!! tip
+
+    While most users will stick with Docker, Podman is available in different
+    contexts - for example, it can be run inside a Docker container, or without
+    root access. Thanks to the [OCI], images are compatible between engines, so
+    you can still use the regular manylinux/musllinux containers.
+
+[OCI]: https://opencontainers.org/
+
+#### Examples
+
+!!! tab examples "Environment variables"
+
+    ```yaml
+    CIBW_CONTAINER_ENGINE: podman
+    ```
+
+!!! tab examples "pyproject.toml"
+
+    ```toml
+    [tool.cibuildwheel]
+    container-engine = "podman"
+    ```
+
+
 ### `CIBW_DEPENDENCY_VERSIONS` {: #dependency-versions}
 > Specify how cibuildwheel controls the versions of the tools it uses
 
@@ -1029,6 +1067,7 @@ Platform-specific environment variables are also available:<br/>
     dependency-versions = "./constraints.txt"
     ```
 
+
 ## Testing
 
 ### `CIBW_TEST_COMMAND` {: #test-command}