From 8c68e4882cd999542ef82b1223cf33106c02aa39 Mon Sep 17 00:00:00 2001
From: Joe Rickerby <joerick@mac.com>
Date: Sun, 24 Jan 2021 16:43:42 +0000
Subject: [PATCH] Add FAQ entry explaining Apple Silicon support

---
 docs/faq.md                       | 25 +++++++++++++++++++++++++
 examples/github-apple-silicon.yml | 20 ++++++++++++++++++++
 2 files changed, 45 insertions(+)
 create mode 100644 examples/github-apple-silicon.yml

diff --git a/docs/faq.md b/docs/faq.md
index 799059d9..da8bc522 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -44,6 +44,31 @@ Linux), and the other architectures are emulated automatically.
 {% include "../examples/github-with-qemu.yml" %}
 ```
 
+### Building Apple Silicon wheels on Intel {: #apple-silicon}
+
+`cibuildwheel` supports cross-compiling `universal2` and `arm64` wheels on `x86_64` runners.
+
+These wheels are not built by default, but can be enabled by setting the [`CIBW_ARCHS_MACOS` option](options.md#archs) to `x86_64 arm64 universal2`. Cross-compilation is provided by the Xcode toolchain.
+
+!!! important
+    When cross-compiling on Intel, it is not possible to test `arm64` and the `arm64` part of a `universal2` wheel.
+
+    `cibuildwheel` will raise a warning to notify you of this - these warnings be be silenced by skipping testing on these platforms: `CIBW_TEST_SKIP: *_arm64 *_universal2:arm64`.
+
+Hopefully, this is a temporary situation. Once we have widely available Apple Silicon CI runners, we can build and test `arm64` and `universal2` wheels more natively. That's why `universal2` wheels are not yet built by default, and require opt-in by setting `CIBW_ARCHS_MACOS`.
+
+!!! note
+    Your runner image needs Xcode Command Line Tools 12 or later to build `universal2` and `arm64`.
+
+    So far, only CPython 3.9 supports `universal2` and `arm64` wheels.
+
+Here's an example Github Actions workflow with a job that builds for Apple Silicon:
+
+> .github/workflows/build_macos.yml
+```yml
+{% include "../examples/github-apple-silicon.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.
diff --git a/examples/github-apple-silicon.yml b/examples/github-apple-silicon.yml
new file mode 100644
index 00000000..e1ec7087
--- /dev/null
+++ b/examples/github-apple-silicon.yml
@@ -0,0 +1,20 @@
+name: Build
+
+on: [push, pull_request]
+
+jobs:
+  build_wheels_macos:
+    name: Build wheels on macos-11.0
+    runs-on: macos-11.0
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Build wheels
+        run: |
+          pipx run cibuildwheel==1.8.0 --output-dir wheelhouse
+        env:
+          CIBW_ARCHS_MACOS: x86_64 universal2 arm64
+
+      - uses: actions/upload-artifact@v2
+        with:
+          path: ./wheelhouse/*.whl