Merge pull request #482 from asfaltboy/support-quemu-on-github

Support qemu in GitHub Actions

docs/faq.md

@@ -24,6 +24,26 @@ Linux wheels are built in the [`manylinux` docker images](https://github.com/pyp
 
 - Alternative dockers images can be specified with the `CIBW_MANYLINUX_X86_64_IMAGE`, `CIBW_MANYLINUX_I686_IMAGE`, and `CIBW_MANYLINUX_PYPY_X86_64_IMAGE` options to allow for a custom, preconfigured build environment for the Linux builds. See [options](options.md#manylinux-image) for more details.
 
+### Building non-native architectures using emulation  {: #emulation}
+
+cibuildwheel supports building non-native architectures on Linux, via
+emulation through the binfmt_misc kernel feature. The easiest way to use this
+is via the [docker/setup-qemu-action][setup-qemu-action] on Github Actions or
+[tonistiigi/binfmt][binfmt].
+
+[setup-qemu-action]: https://github.com/docker/setup-qemu-action
+[binfmt]: https://hub.docker.com/r/tonistiigi/binfmt
+
+Check out the following config for an example of how to set it up on Github
+Actions. Once QEMU is set up and registered, you just need to set the
+`CIBW_ARCHS_LINUX` environment variable (or use the `--archs` option on
+Linux), and the other architectures are emulated automatically.
+
+> .github/workflows/build.yml
+```yaml
+{% include "../examples/github-with-qemu.yml" %}
+```
+
 ### Building packages with optional C extensions
 
 `cibuildwheel` defines the environment variable `CIBUILDWHEEL` to the value `1` allowing projects for which the C extension is optional to make it mandatory when building wheels.

docs/options.md

@@ -155,6 +155,28 @@ CIBW_SKIP: pp*
   }
 </style>
 
+### `CIBW_ARCHS_LINUX` {: #archs}
+> Build non-native architectures
+
+A space-separated list of architectures to build. Use this in conjunction with
+emulation, such as that provided by [docker/setup-qemu-action][setup-qemu-action]
+or [tonistiigi/binfmt][binfmt], to build architectures other than those your
+machine natively supports.
+
+Options: `auto` `x86_64` `i686` `aarch64` `ppc64le` `s390x`
+
+Default: `auto`, meaning the native archs supported on the build machine. For
+example, on an `x86_64` machine, `auto` expands to `x86_64` and `i686`.
+
+[setup-qemu-action]: https://github.com/docker/setup-qemu-action
+[binfmt]: https://hub.docker.com/r/tonistiigi/binfmt
+
+#### Examples
+
+```yaml
+# On an intel runner with qemu installed, build Intel and ARM wheels
+CIBW_ARCHS_LINUX: "auto aarch64"
+```
 
 ## Build customization
 
@@ -488,7 +510,8 @@ CIBW_BUILD_VERBOSITY: 1
 
 ```text
 usage: cibuildwheel [-h] [--platform {auto,linux,macos,windows}]
-                    [--output-dir OUTPUT_DIR] [--print-build-identifiers]
+                    [--archs ARCHS] [--output-dir OUTPUT_DIR]
+                    [--print-build-identifiers]
                     [package_dir]
 
 Build wheels for all the platforms.
@@ -510,6 +533,12 @@ optional arguments:
                         don't run on your development machine. For "windows",
                         you need to run in Windows, and it will build and test
                         for all versions of Python. Default: auto.
+  --archs ARCHS         Comma-separated list of CPU architectures to build
+                        for. If unspecified, builds the architectures natively
+                        supported on this machine. Set this option to build an
+                        architecture via emulation, for example, using
+                        binfmt_misc and qemu. Default: auto Choices: auto,
+                        x86_64, i686, aarch64, ppc64le, s390x, x86, AMD64
   --output-dir OUTPUT_DIR
                         Destination folder for the wheels.
   --print-build-identifiers