From 0cfa3f74d43af9a0914b0abd21d319c3ed2c7d61 Mon Sep 17 00:00:00 2001
From: Joe Rickerby <joerick@mac.com>
Date: Fri, 18 Jun 2021 16:38:42 +0100
Subject: [PATCH 1/5] Rework the setup page to include information about local
 builds before going to CI

---
 docs/extra.css |   1 +
 docs/setup.md  | 119 ++++++++++++++++++++++++++++++++++++++++++++++---
 2 files changed, 113 insertions(+), 7 deletions(-)

diff --git a/docs/extra.css b/docs/extra.css
index 4ed1e23d2..99659ef2d 100644
--- a/docs/extra.css
+++ b/docs/extra.css
@@ -22,6 +22,7 @@ code {
 
 code, pre, tt {
     font-family: SFMono-Regular, Consolas, Liberation Mono, Menlo, monospace;
+    line-height: 1.4;
 }
 
 pre code, pre code.hljs {
diff --git a/docs/setup.md b/docs/setup.md
index 6763863f1..33cd24ed3 100644
--- a/docs/setup.md
+++ b/docs/setup.md
@@ -2,7 +2,108 @@
 title: 'Setup'
 ---
 
-# GitHub Actions [linux/mac/windows] {: #github-actions}
+# Build your wheel locally
+
+Before starting to configure cibuildwheel, it's useful to try to build a wheel
+on your local machine. It's much easier to debug problems on your machine than
+inside a CI system!
+
+## Invoking a build
+
+Start with a clean checkout of your project, inside a new clean virtual
+environment. Make sure your `pip` is up to date, and then invoke:
+
+```shell
+pip wheel -w wheelhouse .
+```
+
+If your build completes without a problem, congratulations! You can move on to
+the next step. Otherwise, you might have one of the following issues:
+
+### Missing build dependencies
+
+If your build needs Python dependencies, you can resolve this by adding
+package names to the
+[`build-system.requires`](https://www.python.org/dev/peps/pep-0518/#build-system-table)
+section of your pyproject.toml. For example, if your project requires Cython
+to build, your pyproject.toml might include a section like this:
+
+```toml
+[build-system]
+requires = [
+    "setuptools>=42",
+    "wheel",
+    "Cython",
+]
+
+build-backend = "setuptools.build_meta"
+```
+
+If you have other dependencies, you should make a note of these, you'll be
+able to install them using the cibuildwheel options [`CIBW_BEFORE_BUILD`](options.md#before-build) or
+[`CIBW_BEFORE_ALL`](options.md#before-all).
+
+### Actions you need to perform before building
+
+You might need to run some other commands before building, like running a
+script that performs codegen or downloading some data that's not stored in
+your source tree. There are a couple ways to deal with this:
+
+-   Incorporate this into your build process, by adding it to your package's
+    `setup.py`. You can add extra build steps using a structure like this:
+
+    ```python
+    import subprocess
+    import setuptools
+    import setuptools.command.build_py
+
+
+    class BuildPyCommand(setuptools.command.build_py.build_py):
+      """Custom build command."""
+
+      def run(self):
+        # your custom build steps here
+        # e.g.
+        #   subprocess.run(['python', 'scripts/my_custom_script.py'], check=True)
+        setuptools.command.build_py.build_py.run(self)
+
+
+    setuptools.setup(
+        cmdclass={
+            'build_py': BuildPyCommand,
+        },
+        # Usual setup() args.
+        # ...
+    )
+    ```
+
+    This method is usually preferred because in addition to adding being
+    included in the wheel build process, it will help users building from
+    source tarballs as well.
+
+-   Alternatively, you can instruct cibuildwheel to run commands before
+    building your wheel. Take a look at the cibuildwheel options
+    [`CIBW_BEFORE_BUILD`](options.md#before-build) or
+    [`CIBW_BEFORE_ALL`](options.md#before-all).
+
+### Environment variables
+
+Your wheel build might need some environment variables to be set. Consider
+incorporating these into setup.py to allow source tarballs to build (for
+example, using [`extra_compile_args` or
+`extra_link_args`](https://docs.python.org/3/distutils/setupscript.html#other-options)),
+but otherwise, make a note of these for inclusion in the cibuildwheel option
+[`CIBW_ENVIRONMENT`](options.md#environment).
+
+# Run cibuildwheel locally
+
+`cibuildwheel --platform linux`
+
+TODO
+
+# Configure a CI service
+
+## GitHub Actions [linux/mac/windows] {: #github-actions}
 
 To build Linux, Mac, and Windows wheels using GitHub Actions, create a `.github/workflows/build_wheels.yml` file in your repo.
 
@@ -99,7 +200,7 @@ For more info on this file, check out the [docs](https://help.github.com/en/acti
 [`examples/github-deploy.yml`](https://github.com/pypa/cibuildwheel/blob/main/examples/github-deploy.yml) extends this minimal example with a demonstration of how to automatically upload the built wheels to PyPI.
 
 
-# Azure Pipelines [linux/mac/windows] {: #azure-pipelines}
+## Azure Pipelines [linux/mac/windows] {: #azure-pipelines}
 
 To build Linux, Mac, and Windows wheels on Azure Pipelines, create a `azure-pipelines.yml` file in your repo.
 
@@ -113,7 +214,7 @@ Commit this file, enable building of your repo on Azure Pipelines, and push.
 
 Wheels will be stored for you and available through the Pipelines interface. For more info on this file, check out the [docs](https://docs.microsoft.com/en-us/azure/devops/pipelines/yaml-schema).
 
-# Travis CI [linux/windows] {: #travis-ci}
+## Travis CI [linux/windows] {: #travis-ci}
 
 To build Linux and Windows wheels on Travis CI, create a `.travis.yml` file in your repo.
 
@@ -129,7 +230,7 @@ Then setup a deployment method by following the [Travis CI deployment docs](http
 
 [`examples/travis-ci-deploy.yml`](https://github.com/pypa/cibuildwheel/blob/main/examples/travis-ci-deploy.yml) extends this minimal example with a demonstration of how to automatically upload the built wheels to PyPI.
 
-# AppVeyor [linux/mac/windows] {: #appveyor}
+## AppVeyor [linux/mac/windows] {: #appveyor}
 
 To build Linux, Mac, and Windows wheels on AppVeyor, create an `appveyor.yml` file in your repo.
 
@@ -145,7 +246,7 @@ AppVeyor will store the built wheels for you - you can access them from the proj
 
 For more info on this config file, check out the [docs](https://www.appveyor.com/docs/).
 
-# CircleCI [linux/mac] {: #circleci}
+## CircleCI [linux/mac] {: #circleci}
 
 To build Linux and Mac wheels on CircleCI, create a `.circleci/config.yml` file in your repo,
 
@@ -162,7 +263,7 @@ Commit this file, enable building of your repo on CircleCI, and push.
 
 CircleCI will store the built wheels for you - you can access them from the project console. Check out the CircleCI [docs](https://circleci.com/docs/2.0/configuration-reference/#section=configuration) for more info on this config file.
 
-# Gitlab CI [linux] {: #gitlab-ci}
+## Gitlab CI [linux] {: #gitlab-ci}
 
 To build Linux wheels on Gitlab CI, create a `.gitlab-ci.yml` file in your repo,
 
@@ -178,9 +279,13 @@ Gitlab will store the built wheels for you - you can access them from the Pipeli
 
 > ⚠️ Got an error? Check the [FAQ](faq.md).
 
+# Further setup
+
+Once you've got the wheel building successfully, you might want to set up [testing](options.md#test-command) or [automatic releases to PyPI](deliver-to-pypi.md#automatic-method).
+
 <script>
   document.addEventListener('DOMContentLoaded', function() {
-    $('.toctree-l2 a, .rst-content h1').each(function(i, el) {
+    $('a.toctree-l3, .rst-content h2').each(function(i, el) {
       var text = $(el).text()
       var match = text.match(/(.*) \[([a-z/]+)\]/);
 

From ad66e7cc6c11621646bf147fda5cc6bac9371476 Mon Sep 17 00:00:00 2001
From: Joe Rickerby <joerick@mac.com>
Date: Tue, 22 Jun 2021 20:02:24 +0100
Subject: [PATCH 2/5] More progress on Setup docs

---
 docs/extra.css | 11 ++++++++---
 docs/setup.md  | 50 ++++++++++++++++++++++++++++++++++++++++++++------
 2 files changed, 52 insertions(+), 9 deletions(-)

diff --git a/docs/extra.css b/docs/extra.css
index 99659ef2d..6f6c82848 100644
--- a/docs/extra.css
+++ b/docs/extra.css
@@ -10,6 +10,14 @@ p {
     line-height: 26px;
 }
 
+pre {
+  margin: 1em 0;
+}
+
+pre:first-child {
+  margin-top: 0;
+}
+
 code {
     font-size: 85%;
     background-color: rgba(27,31,35,.05);
@@ -217,6 +225,3 @@ h1, h2, h3, h4, h5, h6 {
   padding-right: 0;
   margin-bottom: 0.5em;
 }
-.tabs.examples pre:first-child {
-  margin-top: 0;
-}
diff --git a/docs/setup.md b/docs/setup.md
index 33cd24ed3..efe9dc717 100644
--- a/docs/setup.md
+++ b/docs/setup.md
@@ -8,8 +8,6 @@ Before starting to configure cibuildwheel, it's useful to try to build a wheel
 on your local machine. It's much easier to debug problems on your machine than
 inside a CI system!
 
-## Invoking a build
-
 Start with a clean checkout of your project, inside a new clean virtual
 environment. Make sure your `pip` is up to date, and then invoke:
 
@@ -17,8 +15,8 @@ environment. Make sure your `pip` is up to date, and then invoke:
 pip wheel -w wheelhouse .
 ```
 
-If your build completes without a problem, congratulations! You can move on to
-the next step. Otherwise, you might have one of the following issues:
+If your build completes without a problem, you're in good shape! You can move on to
+the next step. Otherwise, you might have one of the following issues.
 
 ### Missing build dependencies
 
@@ -97,9 +95,49 @@ but otherwise, make a note of these for inclusion in the cibuildwheel option
 
 # Run cibuildwheel locally
 
-`cibuildwheel --platform linux`
+If you've got [Docker](https://www.docker.com/products/docker-desktop)
+installed on your development machine, you can run a Linux build without even
+touching CI.
+
+!!! tip
+    Even Windows can run Linux containers these days, but there are a few
+    hoops to jump through. Check [this
+    document](https://docs.microsoft.com/en-us/virtualization/windowscontainers/quick-start/quick-start-windows-10-linux)
+    for more info.
+
+This is convenient as it's quicker to iterate, and because the builds are
+happening in manylinux Docker containers, they're perfectly reproducable.
+
+Install cibuildwheel and run a build like this:
+
+```sh
+pip install cibuildwheel
+cibuildwheel --platform linux
+```
+
+You should see the builds taking place. You can experiment with options by exporting environment variables, for example:
+
+!!! tab "POSIX shell (Linux/macOS)"
 
-TODO
+    ```sh
+    # build only CPython 3.9
+    export CIBW_BUILD='cp39-*'
+    # run a command to set up the build system
+    export CIBW_BEFORE_ALL='apt install libpng-dev'
+
+    cibuildwheel --platform linux
+    ```
+
+!!! tab "CMD (Windows)"
+
+    ```
+    # build only CPython 3.9
+    set CIBW_BUILD='cp39-*'
+    # run a command to set up the build system
+    set CIBW_BEFORE_ALL='apt install libpng-dev'
+
+    cibuildwheel --platform linux
+    ```
 
 # Configure a CI service
 

From 6e7716e7a2145d40ac037155c65ebc4be940d53a Mon Sep 17 00:00:00 2001
From: Joe Rickerby <joerick@mac.com>
Date: Fri, 20 Aug 2021 17:00:22 +0100
Subject: [PATCH 3/5] Move the build-in advice to faq.md

---
 docs/faq.md   |  67 ++++++++++++++++++++++++++
 docs/setup.md | 130 +++++++++++---------------------------------------
 2 files changed, 95 insertions(+), 102 deletions(-)

diff --git a/docs/faq.md b/docs/faq.md
index 97a7469f7..bc9be4354 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -2,6 +2,73 @@
 title: Tips and tricks
 ---
 
+### Alternatives to cibuildwheel options
+
+cibuildwheel provides lots of opportunities to configure the build
+environment. However, sometimes there's a way to add this build configuration
+into the package itself - in general, this is prefered, because users of your
+package's sdist will also benefit.
+
+#### Missing build dependencies
+
+If your build needs Python dependencies, rather than using CIBW_BEFORE_BUILD, it's best to add these to the
+[`build-system.requires`](https://www.python.org/dev/peps/pep-0518/#build-system-table)
+section of your pyproject.toml. For example, if your project requires Cython
+to build, your pyproject.toml might include a section like this:
+
+```toml
+[build-system]
+requires = [
+    "setuptools>=42",
+    "wheel",
+    "Cython",
+]
+
+build-backend = "setuptools.build_meta"
+```
+
+#### Actions you need to perform before building
+
+You might need to run some other commands before building, like running a
+script that performs codegen or downloading some data that's not stored in
+your source tree.
+
+Rather than using CIBW_BEFORE_ALL or CIBW_BEFORE_BUILD, you could incorporate
+these steps into your package's build process. For example, if you're using
+setuptools, you can add steps to your package's `setup.py` using a structure
+like this:
+
+    ```python
+    import subprocess
+    import setuptools
+    import setuptools.command.build_py
+
+
+    class BuildPyCommand(setuptools.command.build_py.build_py):
+      """Custom build command."""
+
+      def run(self):
+        # your custom build steps here
+        # e.g.
+        #   subprocess.run(['python', 'scripts/my_custom_script.py'], check=True)
+        setuptools.command.build_py.build_py.run(self)
+
+
+    setuptools.setup(
+        cmdclass={
+            'build_py': BuildPyCommand,
+        },
+        # Usual setup() args.
+        # ...
+    )
+    ```
+
+#### Compiler flags
+
+Your build might need some compiler flags to be set through environment variables.
+Consider incorporating these into your package, for example, in `setup.py` using [`extra_compile_args` or
+`extra_link_args`](https://docs.python.org/3/distutils/setupscript.html#other-options).
+
 ### Troubleshooting
 
 If your wheel didn't compile, check the list below for some debugging tips.
diff --git a/docs/setup.md b/docs/setup.md
index efe9dc717..7793ad58a 100644
--- a/docs/setup.md
+++ b/docs/setup.md
@@ -2,97 +2,6 @@
 title: 'Setup'
 ---
 
-# Build your wheel locally
-
-Before starting to configure cibuildwheel, it's useful to try to build a wheel
-on your local machine. It's much easier to debug problems on your machine than
-inside a CI system!
-
-Start with a clean checkout of your project, inside a new clean virtual
-environment. Make sure your `pip` is up to date, and then invoke:
-
-```shell
-pip wheel -w wheelhouse .
-```
-
-If your build completes without a problem, you're in good shape! You can move on to
-the next step. Otherwise, you might have one of the following issues.
-
-### Missing build dependencies
-
-If your build needs Python dependencies, you can resolve this by adding
-package names to the
-[`build-system.requires`](https://www.python.org/dev/peps/pep-0518/#build-system-table)
-section of your pyproject.toml. For example, if your project requires Cython
-to build, your pyproject.toml might include a section like this:
-
-```toml
-[build-system]
-requires = [
-    "setuptools>=42",
-    "wheel",
-    "Cython",
-]
-
-build-backend = "setuptools.build_meta"
-```
-
-If you have other dependencies, you should make a note of these, you'll be
-able to install them using the cibuildwheel options [`CIBW_BEFORE_BUILD`](options.md#before-build) or
-[`CIBW_BEFORE_ALL`](options.md#before-all).
-
-### Actions you need to perform before building
-
-You might need to run some other commands before building, like running a
-script that performs codegen or downloading some data that's not stored in
-your source tree. There are a couple ways to deal with this:
-
--   Incorporate this into your build process, by adding it to your package's
-    `setup.py`. You can add extra build steps using a structure like this:
-
-    ```python
-    import subprocess
-    import setuptools
-    import setuptools.command.build_py
-
-
-    class BuildPyCommand(setuptools.command.build_py.build_py):
-      """Custom build command."""
-
-      def run(self):
-        # your custom build steps here
-        # e.g.
-        #   subprocess.run(['python', 'scripts/my_custom_script.py'], check=True)
-        setuptools.command.build_py.build_py.run(self)
-
-
-    setuptools.setup(
-        cmdclass={
-            'build_py': BuildPyCommand,
-        },
-        # Usual setup() args.
-        # ...
-    )
-    ```
-
-    This method is usually preferred because in addition to adding being
-    included in the wheel build process, it will help users building from
-    source tarballs as well.
-
--   Alternatively, you can instruct cibuildwheel to run commands before
-    building your wheel. Take a look at the cibuildwheel options
-    [`CIBW_BEFORE_BUILD`](options.md#before-build) or
-    [`CIBW_BEFORE_ALL`](options.md#before-all).
-
-### Environment variables
-
-Your wheel build might need some environment variables to be set. Consider
-incorporating these into setup.py to allow source tarballs to build (for
-example, using [`extra_compile_args` or
-`extra_link_args`](https://docs.python.org/3/distutils/setupscript.html#other-options)),
-but otherwise, make a note of these for inclusion in the cibuildwheel option
-[`CIBW_ENVIRONMENT`](options.md#environment).
-
 # Run cibuildwheel locally
 
 If you've got [Docker](https://www.docker.com/products/docker-desktop)
@@ -106,7 +15,7 @@ touching CI.
     for more info.
 
 This is convenient as it's quicker to iterate, and because the builds are
-happening in manylinux Docker containers, they're perfectly reproducable.
+happening in manylinux Docker containers, they're perfectly reproducible.
 
 Install cibuildwheel and run a build like this:
 
@@ -115,30 +24,47 @@ pip install cibuildwheel
 cibuildwheel --platform linux
 ```
 
-You should see the builds taking place. You can experiment with options by exporting environment variables, for example:
+You should see the builds taking place. You can experiment with options using environment variables or pyproject.toml.
 
-!!! tab "POSIX shell (Linux/macOS)"
+!!! tab "Environment variables"
+
+    cibuildwheel will read config from the environment. Syntax varies, depending on your shell:
+
+    > POSIX shell (Linux/macOS)
 
     ```sh
-    # build only CPython 3.9
-    export CIBW_BUILD='cp39-*'
     # run a command to set up the build system
     export CIBW_BEFORE_ALL='apt install libpng-dev'
 
     cibuildwheel --platform linux
     ```
 
-!!! tab "CMD (Windows)"
+    > CMD (Windows)
 
-    ```
-    # build only CPython 3.9
-    set CIBW_BUILD='cp39-*'
-    # run a command to set up the build system
+    ```bat
     set CIBW_BEFORE_ALL='apt install libpng-dev'
 
     cibuildwheel --platform linux
     ```
 
+!!! tab "pyproject.toml"
+
+    If you write your options into [`pyproject.toml`](options.md#configuration-file), you can work on your options locally, and they'll be automatically picked up when running in CI.
+
+    > pyproject.toml
+
+    ```
+    [tool.cibuildwheel]
+    before-all = "apt install libpng-dev"
+    ```
+
+    Then invoke cibuildwheel, like:
+
+    ```console
+    cibuildwheel --platform linux
+    ```
+
+
 # Configure a CI service
 
 ## GitHub Actions [linux/mac/windows] {: #github-actions}
@@ -317,7 +243,7 @@ Gitlab will store the built wheels for you - you can access them from the Pipeli
 
 > ⚠️ Got an error? Check the [FAQ](faq.md).
 
-# Further setup
+# Next steps
 
 Once you've got the wheel building successfully, you might want to set up [testing](options.md#test-command) or [automatic releases to PyPI](deliver-to-pypi.md#automatic-method).
 

From 3cbc86bd33c1c8be19caa073b77804c2f1471c6f Mon Sep 17 00:00:00 2001
From: Joe Rickerby <joerick@mac.com>
Date: Fri, 20 Aug 2021 17:29:51 +0100
Subject: [PATCH 4/5] Big tidy of the Tips and tricks page

---
 docs/faq.md   | 296 +++++++++++++++++++++++---------------------------
 docs/setup.md |   2 +-
 2 files changed, 139 insertions(+), 159 deletions(-)

diff --git a/docs/faq.md b/docs/faq.md
index bc9be4354..4d0d28067 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -2,102 +2,23 @@
 title: Tips and tricks
 ---
 
-### Alternatives to cibuildwheel options
-
-cibuildwheel provides lots of opportunities to configure the build
-environment. However, sometimes there's a way to add this build configuration
-into the package itself - in general, this is prefered, because users of your
-package's sdist will also benefit.
-
-#### Missing build dependencies
-
-If your build needs Python dependencies, rather than using CIBW_BEFORE_BUILD, it's best to add these to the
-[`build-system.requires`](https://www.python.org/dev/peps/pep-0518/#build-system-table)
-section of your pyproject.toml. For example, if your project requires Cython
-to build, your pyproject.toml might include a section like this:
-
-```toml
-[build-system]
-requires = [
-    "setuptools>=42",
-    "wheel",
-    "Cython",
-]
-
-build-backend = "setuptools.build_meta"
-```
-
-#### Actions you need to perform before building
-
-You might need to run some other commands before building, like running a
-script that performs codegen or downloading some data that's not stored in
-your source tree.
-
-Rather than using CIBW_BEFORE_ALL or CIBW_BEFORE_BUILD, you could incorporate
-these steps into your package's build process. For example, if you're using
-setuptools, you can add steps to your package's `setup.py` using a structure
-like this:
-
-    ```python
-    import subprocess
-    import setuptools
-    import setuptools.command.build_py
-
-
-    class BuildPyCommand(setuptools.command.build_py.build_py):
-      """Custom build command."""
-
-      def run(self):
-        # your custom build steps here
-        # e.g.
-        #   subprocess.run(['python', 'scripts/my_custom_script.py'], check=True)
-        setuptools.command.build_py.build_py.run(self)
-
-
-    setuptools.setup(
-        cmdclass={
-            'build_py': BuildPyCommand,
-        },
-        # Usual setup() args.
-        # ...
-    )
-    ```
-
-#### Compiler flags
-
-Your build might need some compiler flags to be set through environment variables.
-Consider incorporating these into your package, for example, in `setup.py` using [`extra_compile_args` or
-`extra_link_args`](https://docs.python.org/3/distutils/setupscript.html#other-options).
-
-### Troubleshooting
-
-If your wheel didn't compile, check the list below for some debugging tips.
-
-- A mistake in your config. To quickly test your config without doing a git push and waiting for your code to build on CI, you can test the Linux build in a Docker container. On Mac or Linux, with Docker running, try `cibuildwheel --platform linux`. You'll have to bring your config into the current environment first.
-
-- Missing dependency. You might need to install something on the build machine. You can do this in `.travis.yml`, `appveyor.yml`, or `.circleci/config.yml`, with apt-get, brew or choco. Given how the Linux build works, you'll need to use the [`CIBW_BEFORE_BUILD`](options.md#before-build) option.
-
-- Windows: missing C feature. The Windows C compiler doesn't support C language features invented after 1990, so you'll have to backport your C code to C90. For me, this mostly involved putting my variable declarations at the top of the function like an animal.
-
-- MacOS: calling cibuildwheel from a python3 script and getting a `ModuleNotFoundError`? Due to a (fixed) [bug](https://bugs.python.org/issue22490) in CPython, you'll need to [unset the `__PYVENV_LAUNCHER__` variable](https://github.com/pypa/cibuildwheel/issues/133#issuecomment-478288597) before activating a venv.
-
-### Building Python 2.7 / PyPy2 wheels
-
-See the [cibuildwheel verison 1 docs](https://cibuildwheel.readthedocs.io/en/1.x/) for information about building Python 2.7 or PyPy2 wheels. There are lots of tricks and workaround there that are no longer required for Python 3 in cibuildwheel 2.
+## Tips
 
 ### Linux builds on Docker
 
 Linux wheels are built in the [`manylinux` docker images](https://github.com/pypa/manylinux) to provide binary compatible wheels on Linux, according to [PEP 571](https://www.python.org/dev/peps/pep-0571/). Because of this, when building with `cibuildwheel` on Linux, a few things should be taken into account:
 
-- Programs and libraries are not installed on the Travis CI Ubuntu host, but rather should be installed inside of the Docker image (using `yum` for `manylinux2010` or `manylinux2014`, and `apt-get` for `manylinux_2_24`) or manually. The same goes for environment variables that are potentially needed to customize the wheel building. `cibuildwheel` supports this by providing the `CIBW_ENVIRONMENT` and `CIBW_BEFORE_BUILD` options to setup the build environment inside the running Docker image. See [the options docs](options.md#build-environment) for details on these options.
+-   Programs and libraries are not installed on the CI runner host, but rather should be installed inside of the Docker image - using `yum` for `manylinux2010` or `manylinux2014`, and `apt-get` for `manylinux_2_24`, or manually. The same goes for environment variables that are potentially needed to customize the wheel building.
+
+    `cibuildwheel` supports this by providing the [`CIBW_ENVIRONMENT`](options.md#environment) and [`CIBW_BEFORE_ALL`](options.md#before-all) options to setup the build environment inside the running Docker image.
 
-- The project directory is mounted in the running Docker instance as `/project`, the output directory for the wheels as `/output`. In general, this is handled transparently by `cibuildwheel`. For a more finegrained level of control however, the root of the host file system is mounted as `/host`, allowing for example to access shared files, caches, etc. on the host file system.  Note that this is not available on CircleCI due to their Docker policies.
+-   The project directory is mounted in the running Docker instance as `/project`, the output directory for the wheels as `/output`. In general, this is handled transparently by `cibuildwheel`. For a more finegrained level of control however, the root of the host file system is mounted as `/host`, allowing for example to access shared files, caches, etc. on the host file system.  Note that `/host` is not available on CircleCI due to their Docker policies.
 
-- 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.
+-   Alternative Docker images can be specified with the `CIBW_MANYLINUX_*_IMAGE` options to allow for a custom, preconfigured build environment for the Linux builds. See [options](options.md#manylinux-image) for more details.
 
 ### Building macOS wheels for Apple Silicon {: #apple-silicon}
 
-`cibuildwheel` supports cross-compiling `universal2` and `arm64` wheels on `x86_64` runners. With the introduction of Apple Silicon, you now have several choices for wheels for Python 3.9+:
+`cibuildwheel` supports cross-compiling `universal2` and `arm64` wheels on `x86_64` runners. With the introduction of Apple Silicon, you now have several choices for wheels for Python 3.8+:
 
 #### `x86_64`
 
@@ -156,6 +77,7 @@ by default, and require opt-in by setting `CIBW_ARCHS_MACOS`.
 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" %}
 ```
@@ -181,33 +103,6 @@ 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.2 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.
@@ -222,51 +117,6 @@ myextension = Extension(
 )
 ```
 
-### 'No module named XYZ' errors after running cibuildwheel on macOS
-
-`cibuildwheel` on Mac installs the distributions from Python.org system-wide during its operation. This is necessary, but it can cause some confusing errors after cibuildwheel has finished.
-
-Consider the build script:
-
-```bash
-python3 -m pip install twine cibuildwheel
-python3 -m cibuildwheel --output-dir wheelhouse
-python3 -m twine upload wheelhouse/*.whl
-# error: no module named 'twine'
-```
-
-This doesn't work because while `cibuildwheel` was running, it installed a few new versions of 'python3', so the `python3` run on line 3 isn't the same as the `python3` that ran on line 1.
-
-Solutions to this vary, but the simplest is to install tools immediately before they're used:
-
-```bash
-python3 -m pip install cibuildwheel
-python3 -m cibuildwheel --output-dir wheelhouse
-python3 -m pip install twine
-python3 -m twine upload wheelhouse/*.whl
-```
-
-### 'ImportError: DLL load failed: The specific module could not be found' error on Windows
-
-Visual Studio and MSVC link the compiled binary wheels to the Microsoft Visual C++ Runtime. Normally, these are included with Python, but when compiling with a newer version of Visual Studio, it is possible users will run into problems on systems that do not have these runtime libraries installed. The solution is to ask users to download the corresponding Visual C++ Redistributable from the [Microsoft website](https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads) and install it. Since a Python installation normally includes these VC++ Redistributable files for [the version of the MSVC compiler used to compile Python](https://wiki.python.org/moin/WindowsCompilers), this is typically only a problem when compiling a Python C extension with a newer compiler.
-
-Additionally, Visual Studio 2019 started linking to an even newer DLL, `VCRUNTIME140_1.dll`, besides the `VCRUNTIME140.dll` that is included with recent Python versions (starting from Python 3.5; see [here](https://wiki.python.org/moin/WindowsCompilers) for more details on the corresponding Visual Studio & MSVC versions used to compile the different Python versions). To avoid this extra dependency on `VCRUNTIME140_1.dll`, the [`/d2FH4-` flag](https://devblogs.microsoft.com/cppblog/making-cpp-exception-handling-smaller-x64/) can be added to the MSVC invocations (check out [this issue](https://github.com/pypa/cibuildwheel/issues/423) for details and references).
-
-To add the `/d2FH4-` flag to a standard `setup.py` using `setuptools`, the `extra_compile_args` option can be used:
-
-```python
-    ext_modules=[
-        Extension(
-            'c_module',
-            sources=['extension.c'],
-            extra_compile_args=['/d2FH4-'] if sys.platform == 'win32' else []
-        )
-    ],
-```
-
-To investigate the dependencies of a C extension (i.e., the `.pyd` file, a DLL in disguise) on Windows, [Dependency Walker](http://www.dependencywalker.com/) is a great tool.
-
-
 ### Automatic updates {: #automatic-updates}
 
 Selecting a moving target (like the latest release) is generally a bad idea in CI. If something breaks, you can't tell whether it was your code or an upstream update that caused the breakage, and in a worse-case scenario, it could occur during a release.
@@ -318,3 +168,133 @@ updates:
 ```
 
 This will also try to update other pins in all requirement files, so be sure you want to do that. The only control you have over the files used is via the directory option.
+
+
+### Alternatives to cibuildwheel options {: #cibw-options-alternatives}
+
+cibuildwheel provides lots of opportunities to configure the build
+environment. However, you  might consider adding this build configuration into
+the package itself - in general, this is preferred, because users of your
+package 'sdist' will also benefit.
+
+#### Missing build dependencies {: #cibw-options-alternatives-deps}
+
+If your build needs Python dependencies, rather than using CIBW_BEFORE_BUILD, it's best to add these to the
+[`build-system.requires`](https://www.python.org/dev/peps/pep-0518/#build-system-table)
+section of your pyproject.toml. For example, if your project requires Cython
+to build, your pyproject.toml might include a section like this:
+
+```toml
+[build-system]
+requires = [
+    "setuptools>=42",
+    "wheel",
+    "Cython",
+]
+
+build-backend = "setuptools.build_meta"
+```
+
+#### Actions you need to perform before building
+
+You might need to run some other commands before building, like running a
+script that performs codegen or downloading some data that's not stored in
+your source tree.
+
+Rather than using CIBW_BEFORE_ALL or CIBW_BEFORE_BUILD, you could incorporate
+these steps into your package's build process. For example, if you're using
+setuptools, you can add steps to your package's `setup.py` using a structure
+like this:
+
+    ```python
+    import subprocess
+    import setuptools
+    import setuptools.command.build_py
+
+
+    class BuildPyCommand(setuptools.command.build_py.build_py):
+      """Custom build command."""
+
+      def run(self):
+        # your custom build steps here
+        # e.g.
+        #   subprocess.run(['python', 'scripts/my_custom_script.py'], check=True)
+        setuptools.command.build_py.build_py.run(self)
+
+
+    setuptools.setup(
+        cmdclass={
+            'build_py': BuildPyCommand,
+        },
+        # Usual setup() args.
+        # ...
+    )
+    ```
+
+#### Compiler flags
+
+Your build might need some compiler flags to be set through environment variables.
+Consider incorporating these into your package, for example, in `setup.py` using [`extra_compile_args` or
+`extra_link_args`](https://docs.python.org/3/distutils/setupscript.html#other-options).
+
+### Python 2.7 / PyPy2 wheels
+
+See the [cibuildwheel version 1 docs](https://cibuildwheel.readthedocs.io/en/1.x/) for information about building Python 2.7 or PyPy2 wheels. There are lots of tricks and workaround there that are no longer required for Python 3 in cibuildwheel 2.
+
+## Troubleshooting
+
+If your wheel didn't compile, you might have a mistake in your config.
+
+To quickly test your config without doing a git push and waiting for your code to build on CI, you can [test the Linux build in a local Docker container](setup.md#local).
+
+### Missing dependencies
+
+You might need to install something on the build machine. You can do this with apt/yum, brew or choco, using the [`CIBW_BEFORE_ALL`](options.md#before-all) option. Or, for a Python dependency, consider [adding it to pyproject.toml](#cibw-options-alternatives-deps).
+
+### ModuleNotFoundError on macOS
+
+Calling cibuildwheel from a python3 script and getting a `ModuleNotFoundError`? Due to a (fixed) [bug](https://bugs.python.org/issue22490) in CPython, you'll need to [unset the `__PYVENV_LAUNCHER__` variable](https://github.com/pypa/cibuildwheel/issues/133#issuecomment-478288597) before activating a venv.
+
+### 'No module named XYZ' errors after running cibuildwheel on macOS
+
+`cibuildwheel` on Mac installs the distributions from Python.org system-wide during its operation. This is necessary, but it can cause some confusing errors after cibuildwheel has finished.
+
+Consider the build script:
+
+```bash
+python3 -m pip install twine cibuildwheel
+python3 -m cibuildwheel --output-dir wheelhouse
+python3 -m twine upload wheelhouse/*.whl
+# error: no module named 'twine'
+```
+
+This doesn't work because while `cibuildwheel` was running, it installed a few new versions of 'python3', so the `python3` run on line 3 isn't the same as the `python3` that ran on line 1.
+
+Solutions to this vary, but the simplest is to install tools immediately before they're used:
+
+```bash
+python3 -m pip install cibuildwheel
+python3 -m cibuildwheel --output-dir wheelhouse
+python3 -m pip install twine
+python3 -m twine upload wheelhouse/*.whl
+```
+
+### 'ImportError: DLL load failed: The specific module could not be found' error on Windows
+
+Visual Studio and MSVC link the compiled binary wheels to the Microsoft Visual C++ Runtime. Normally, these are included with Python, but when compiling with a newer version of Visual Studio, it is possible users will run into problems on systems that do not have these runtime libraries installed. The solution is to ask users to download the corresponding Visual C++ Redistributable from the [Microsoft website](https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads) and install it. Since a Python installation normally includes these VC++ Redistributable files for [the version of the MSVC compiler used to compile Python](https://wiki.python.org/moin/WindowsCompilers), this is typically only a problem when compiling a Python C extension with a newer compiler.
+
+Additionally, Visual Studio 2019 started linking to an even newer DLL, `VCRUNTIME140_1.dll`, besides the `VCRUNTIME140.dll` that is included with recent Python versions (starting from Python 3.5; see [here](https://wiki.python.org/moin/WindowsCompilers) for more details on the corresponding Visual Studio & MSVC versions used to compile the different Python versions). To avoid this extra dependency on `VCRUNTIME140_1.dll`, the [`/d2FH4-` flag](https://devblogs.microsoft.com/cppblog/making-cpp-exception-handling-smaller-x64/) can be added to the MSVC invocations (check out [this issue](https://github.com/pypa/cibuildwheel/issues/423) for details and references).
+
+To add the `/d2FH4-` flag to a standard `setup.py` using `setuptools`, the `extra_compile_args` option can be used:
+
+```python
+    ext_modules=[
+        Extension(
+            'c_module',
+            sources=['extension.c'],
+            extra_compile_args=['/d2FH4-'] if sys.platform == 'win32' else []
+        )
+    ],
+```
+
+To investigate the dependencies of a C extension (i.e., the `.pyd` file, a DLL in disguise) on Windows, [Dependency Walker](http://www.dependencywalker.com/) is a great tool.
diff --git a/docs/setup.md b/docs/setup.md
index 7793ad58a..6a485315c 100644
--- a/docs/setup.md
+++ b/docs/setup.md
@@ -2,7 +2,7 @@
 title: 'Setup'
 ---
 
-# Run cibuildwheel locally
+# Run cibuildwheel locally {: #local}
 
 If you've got [Docker](https://www.docker.com/products/docker-desktop)
 installed on your development machine, you can run a Linux build without even

From 326a9a942b8fd30ada63bf656fb3aacaa5197e8e Mon Sep 17 00:00:00 2001
From: Joe Rickerby <joerick@mac.com>
Date: Sat, 28 Aug 2021 12:24:21 +0100
Subject: [PATCH 5/5] Make clear local builds are optional

---
 docs/setup.md | 19 +++++++++++++------
 1 file changed, 13 insertions(+), 6 deletions(-)

diff --git a/docs/setup.md b/docs/setup.md
index 12cb6b756..ef9a77ef0 100644
--- a/docs/setup.md
+++ b/docs/setup.md
@@ -2,16 +2,18 @@
 title: 'Setup'
 ---
 
-# Run cibuildwheel locally {: #local}
+# Run cibuildwheel locally (optional) {: #local}
 
-If you've got [Docker](https://www.docker.com/products/docker-desktop)
-installed on your development machine, you can run a Linux build without even
+Before getting to CI setup, it can be convenient to test cibuildwheel
+locally to quickly iterate and track down issues. If you've got
+[Docker](https://www.docker.com/products/docker-desktop) installed on
+your development machine, you can run a Linux build without even
 touching CI.
 
 !!! tip
-    Even Windows can run Linux containers these days, but there are a few
-    hoops to jump through. Check [this
-    document](https://docs.microsoft.com/en-us/virtualization/windowscontainers/quick-start/quick-start-windows-10-linux)
+    You can run the Linux build on any platform. Even Windows can run
+    Linux containers these days, but there are a few  hoops to jump
+    through. Check [this document](https://docs.microsoft.com/en-us/virtualization/windowscontainers/quick-start/quick-start-windows-10-linux)
     for more info.
 
 This is convenient as it's quicker to iterate, and because the builds are
@@ -24,6 +26,11 @@ pip install cibuildwheel
 cibuildwheel --platform linux
 ```
 
+Or, using [pipx](https://github.com/pypa/pipx):
+```sh
+pipx run cibuildwheel --platform linux
+```
+
 You should see the builds taking place. You can experiment with options using environment variables or pyproject.toml.
 
 !!! tab "Environment variables"