feat: configuration support (#684)

* feat: configuration support

* refactor: include manylinux, minor redesign

* "project global" overrides "default platform"

This allows overriding `repair-wheel-command` in the `[tool.cibuildwheel.global]` section.

* fix: add PyPy images

* refactor: remove global

* fix: support tables and arrays

* docs: add pyproject.toml config to docs

* docs: updates based on feedback

* fix: only join if sensible

* refactor: remove manylinux dict

* docs: examples headers and sections on each

* feat: support changing the config from the command line

* fix: use {package}

* tests: add a few tests and mention config one more place

* Restyle examples tabs to remove indent

* Unrelated docs improvements

* Absorb extra content into the tab

* Make the tabs smaller and to the right

* Copy edits to options

* Fix header ids

* Use fewer [tool.cibuildwheel] headers

* docs: minor additions/fixes

* feat: disallow options on some platforms

* docs: make the examples a tiny bit more tabby

* fix: enforce tables/lists are optionally separate

* Some unrelated fixes to the other tab styling

* Minor fix to tab styling

* Refactor to make code a bit more linear and immutable

* Minor docs changes

Co-authored-by: mayeut <mayeut@users.noreply.github.com>
Co-authored-by: Joe Rickerby <joerick@mac.com>

README.md

@@ -123,6 +123,7 @@ Options
 |   | [`CIBW_TEST_SKIP`](https://cibuildwheel.readthedocs.io/en/stable/options/#test-skip)  | Skip running tests on some builds |
 | **Other** | [`CIBW_BUILD_VERBOSITY`](https://cibuildwheel.readthedocs.io/en/stable/options/#build-verbosity)  | Increase/decrease the output of pip wheel |
 
+These options can be specified in a pyproject.toml file, as well; see [configuration](https://cibuildwheel.readthedocs.io/en/stable/options/#configuration).
 
 Working examples
 ----------------

cibuildwheel/__main__.py

@@ -5,7 +5,7 @@ import textwrap
 import traceback
 from configparser import ConfigParser
 from pathlib import Path
-from typing import Dict, List, Optional, Set, Union, overload
+from typing import Dict, List, Optional, Set, Union
 
 from packaging.specifiers import SpecifierSet
 
@@ -16,6 +16,7 @@ import cibuildwheel.util
 import cibuildwheel.windows
 from cibuildwheel.architecture import Architecture, allowed_architectures_check
 from cibuildwheel.environment import EnvironmentParseError, parse_environment
+from cibuildwheel.options import ConfigOptions
 from cibuildwheel.projectfiles import get_requires_python_str
 from cibuildwheel.typing import PLATFORMS, PlatformName, assert_never
 from cibuildwheel.util import (
@@ -28,39 +29,16 @@ from cibuildwheel.util import (
     resources_dir,
 )
 
-
+MANYLINUX_ARCHS = (
-@overload
+    "x86_64",
-def get_option_from_environment(
+    "i686",
-    option_name: str, *, platform: Optional[str] = None, default: str
+    "pypy_x86_64",
-) -> str:
+    "aarch64",
-    ...  # noqa: E704
+    "ppc64le",
-
+    "s390x",
-
+    "pypy_aarch64",
-@overload
+    "pypy_i686",
-def get_option_from_environment(
+)
-    option_name: str, *, platform: Optional[str] = None, default: None = None
-) -> Optional[str]:
-    ...  # noqa: E704 E302
-
-
-def get_option_from_environment(
-    option_name: str, *, platform: Optional[str] = None, default: Optional[str] = None
-) -> Optional[str]:  # noqa: E302
-    """
-    Returns an option from the environment, optionally scoped by the platform.
-
-    Example:
-      get_option_from_environment('CIBW_COLOR', platform='macos')
-
-      This will return the value of CIBW_COLOR_MACOS if it exists, otherwise the value of
-      CIBW_COLOR.
-    """
-    if platform:
-        option = os.environ.get(f"{option_name}_{platform.upper()}")
-        if option is not None:
-            return option
-
-    return os.environ.get(option_name, default)
 
 
 def main() -> None:
@@ -69,8 +47,9 @@ def main() -> None:
     parser = argparse.ArgumentParser(
         description="Build wheels for all the platforms.",
         epilog="""
-            Most options are supplied via environment variables.
+            Most options are supplied via environment variables or in
-            See https://github.com/pypa/cibuildwheel#options for info.
+            --config-file (pyproject.toml usually). See
+            https://github.com/pypa/cibuildwheel#options for info.
         """,
     )
 
@@ -104,10 +83,17 @@ def main() -> None:
 
     parser.add_argument(
         "--output-dir",
-        default=os.environ.get("CIBW_OUTPUT_DIR", "wheelhouse"),
         help="Destination folder for the wheels.",
     )
 
+    parser.add_argument(
+        "--config-file",
+        help="""
+            TOML config file for cibuildwheel. Defaults to pyproject.toml, but
+            can be overridden with this option.
+        """,
+    )
+
     parser.add_argument(
         "package_dir",
         default=".",
@@ -176,40 +162,40 @@ def main() -> None:
         sys.exit(2)
 
     package_dir = Path(args.package_dir)
-    output_dir = Path(args.output_dir)
 
-    if platform == "linux":
+    manylinux_identifiers = {
-        repair_command_default = "auditwheel repair -w {dest_dir} {wheel}"
+        f"manylinux-{build_platform}-image" for build_platform in MANYLINUX_ARCHS
-    elif platform == "macos":
+    }
-        repair_command_default = "delocate-listdeps {wheel} && delocate-wheel --require-archs {delocate_archs} -w {dest_dir} {wheel}"
+    disallow = {
-    elif platform == "windows":
+        "linux": {"dependency-versions"},
-        repair_command_default = ""
+        "macos": manylinux_identifiers,
-    else:
+        "windows": manylinux_identifiers,
-        assert_never(platform)
+    }
+    options = ConfigOptions(package_dir, args.config_file, platform=platform, disallow=disallow)
+    output_dir = Path(
+        args.output_dir
+        if args.output_dir is not None
+        else os.environ.get("CIBW_OUTPUT_DIR", "wheelhouse")
+    )
+
+    build_config = options("build", env_plat=False, sep=" ") or "*"
+    skip_config = options("skip", env_plat=False, sep=" ")
+    test_skip = options("test-skip", env_plat=False, sep=" ")
+
+    archs_config_str = args.archs or options("archs", sep=" ")
+
+    environment_config = options("environment", table={"item": '{k}="{v}"', "sep": " "})
+    before_all = options("before-all", sep=" && ")
+    before_build = options("before-build", sep=" && ")
+    repair_command = options("repair-wheel-command", sep=" && ")
+
+    dependency_versions = options("dependency-versions")
+    test_command = options("test-command", sep=" && ")
+    before_test = options("before-test", sep=" && ")
+    test_requires = options("test-requires", sep=" ").split()
+    test_extras = options("test-extras", sep=",")
+    build_verbosity_str = options("build-verbosity")
 
-    build_config = os.environ.get("CIBW_BUILD") or "*"
-    skip_config = os.environ.get("CIBW_SKIP", "")
-    test_skip = os.environ.get("CIBW_TEST_SKIP", "")
-    environment_config = get_option_from_environment(
-        "CIBW_ENVIRONMENT", platform=platform, default=""
-    )
-    before_all = get_option_from_environment("CIBW_BEFORE_ALL", platform=platform, default="")
-    before_build = get_option_from_environment("CIBW_BEFORE_BUILD", platform=platform)
-    repair_command = get_option_from_environment(
-        "CIBW_REPAIR_WHEEL_COMMAND", platform=platform, default=repair_command_default
-    )
-    dependency_versions = get_option_from_environment(
-        "CIBW_DEPENDENCY_VERSIONS", platform=platform, default="pinned"
-    )
-    test_command = get_option_from_environment("CIBW_TEST_COMMAND", platform=platform)
-    before_test = get_option_from_environment("CIBW_BEFORE_TEST", platform=platform)
-    test_requires = get_option_from_environment(
-        "CIBW_TEST_REQUIRES", platform=platform, default=""
-    ).split()
-    test_extras = get_option_from_environment("CIBW_TEST_EXTRAS", platform=platform, default="")
-    build_verbosity_str = get_option_from_environment(
-        "CIBW_BUILD_VERBOSITY", platform=platform, default=""
-    )
     prerelease_pythons = args.prerelease_pythons or cibuildwheel.util.strtobool(
         os.environ.get("CIBW_PRERELEASE_PYTHONS", "0")
     )
@@ -218,11 +204,11 @@ def main() -> None:
 
     if not any(package_dir.joinpath(name).exists() for name in package_files):
         names = ", ".join(sorted(package_files, reverse=True))
-        print(
+        msg = f"cibuildwheel: Could not find any of {{{names}}} at root of package"
-            f"cibuildwheel: Could not find any of {{{names}}} at root of package", file=sys.stderr
+        print(msg, file=sys.stderr)
-        )
         sys.exit(2)
 
+    # This is not supported in tool.cibuildwheel, as it comes from a standard location.
     # Passing this in as an environment variable will override pyproject.toml, setup.cfg, or setup.py
     requires_python_str: Optional[str] = os.environ.get(
         "CIBW_PROJECT_REQUIRES_PYTHON"
@@ -270,13 +256,6 @@ def main() -> None:
     # This needs to be passed on to the docker container in linux.py
     os.environ["CIBUILDWHEEL"] = "1"
 
-    if args.archs is not None:
-        archs_config_str = args.archs
-    else:
-        archs_config_str = get_option_from_environment(
-            "CIBW_ARCHS", platform=platform, default="auto"
-        )
-
     archs = Architecture.parse_config(archs_config_str, platform=platform)
 
     identifiers = get_build_identifiers(platform, build_selector, archs)
@@ -286,7 +265,7 @@ def main() -> None:
             print(identifier)
         sys.exit(0)
 
-    manylinux_images: Optional[Dict[str, str]] = None
+    manylinux_images: Dict[str, str] = {}
     if platform == "linux":
         pinned_docker_images_file = resources_dir / "pinned_docker_images.cfg"
         all_pinned_docker_images = ConfigParser()
@@ -297,22 +276,10 @@ def main() -> None:
         #   'pypy_x86_64': {'manylinux2010': '...' }
         #   ... }
 
-        manylinux_images = {}
+        for build_platform in MANYLINUX_ARCHS:
-
-        for build_platform in [
-            "x86_64",
-            "i686",
-            "pypy_x86_64",
-            "aarch64",
-            "ppc64le",
-            "s390x",
-            "pypy_aarch64",
-            "pypy_i686",
-        ]:
             pinned_images = all_pinned_docker_images[build_platform]
 
-            config_name = f"CIBW_MANYLINUX_{build_platform.upper()}_IMAGE"
+            config_value = options(f"manylinux-{build_platform}-image")
-            config_value = os.environ.get(config_name)
 
             if config_value is None:
                 # default to manylinux2010 if it's available, otherwise manylinux2014
@@ -340,7 +307,7 @@ def main() -> None:
         repair_command=repair_command,
         environment=environment,
         dependency_constraints=dependency_constraints,
-        manylinux_images=manylinux_images,
+        manylinux_images=manylinux_images or None,
     )
 
     # Python is buffering by default when running on the CI platforms, giving problems interleaving subprocess call output with unflushed calls to 'print'

cibuildwheel/options.py

@@ -0,0 +1,171 @@
+import os
+from pathlib import Path
+from typing import Any, Dict, List, Mapping, Optional, Set, Tuple, Union
+
+import toml
+
+from .typing import PLATFORMS, TypedDict
+from .util import resources_dir
+
+Setting = Union[Dict[str, str], List[str], str]
+
+
+class TableFmt(TypedDict):
+    item: str
+    sep: str
+
+
+class ConfigOptionError(KeyError):
+    pass
+
+
+def _dig_first(*pairs: Tuple[Mapping[str, Any], str]) -> Setting:
+    """
+    Return the first dict item that matches from pairs of dicts and keys.
+    Final result is will throw a KeyError if missing.
+
+    _dig_first((dict1, "key1"), (dict2, "key2"), ...)
+    """
+    (dict_like, key), *others = pairs
+    return dict_like.get(key, _dig_first(*others)) if others else dict_like[key]
+
+
+class ConfigOptions:
+    """
+    Gets options from the environment, config or defaults, optionally scoped
+    by the platform.
+
+    Example:
+      >>> options = ConfigOptions(package_dir, platform='macos')
+      >>> options('cool-color')
+
+      This will return the value of CIBW_COOL_COLOR_MACOS if it exists,
+      otherwise the value of CIBW_COOL_COLOR, otherwise
+      'tool.cibuildwheel.macos.cool-color' or 'tool.cibuildwheel.cool-color'
+      from pyproject.toml, or from cibuildwheel/resources/defaults.toml. An
+      error is thrown if there are any unexpected keys or sections in
+      tool.cibuildwheel.
+    """
+
+    def __init__(
+        self,
+        package_path: Path,
+        config_file: Optional[str] = None,
+        *,
+        platform: str,
+        disallow: Optional[Dict[str, Set[str]]] = None,
+    ) -> None:
+        self.platform = platform
+        self.disallow = disallow or {}
+
+        # Open defaults.toml, loading both global and platform sections
+        defaults_path = resources_dir / "defaults.toml"
+        self.default_options, self.default_platform_options = self._load_file(defaults_path)
+
+        # load the project config file
+        config_options: Dict[str, Any] = {}
+        config_platform_options: Dict[str, Any] = {}
+
+        if config_file is not None:
+            config_path = Path(config_file.format(package=package_path))
+            config_options, config_platform_options = self._load_file(config_path)
+        else:
+            # load pyproject.toml, if it's available
+            pyproject_toml_path = package_path / "pyproject.toml"
+            if pyproject_toml_path.exists():
+                config_options, config_platform_options = self._load_file(pyproject_toml_path)
+
+        # validate project config
+        for option_name in config_options:
+            if not self._is_valid_global_option(option_name):
+                raise ConfigOptionError(f'Option "{option_name}" not supported in a config file')
+
+        for option_name in config_platform_options:
+            if not self._is_valid_platform_option(option_name):
+                raise ConfigOptionError(
+                    f'Option "{option_name}" not supported in the "{self.platform}" section'
+                )
+
+        self.config_options = config_options
+        self.config_platform_options = config_platform_options
+
+    def _is_valid_global_option(self, name: str) -> bool:
+        """
+        Returns True if an option with this name is allowed in the
+        [tool.cibuildwheel] section of a config file.
+        """
+        allowed_option_names = self.default_options.keys() | PLATFORMS
+
+        return name in allowed_option_names
+
+    def _is_valid_platform_option(self, name: str) -> bool:
+        """
+        Returns True if an option with this name is allowed in the
+        [tool.cibuildwheel.<current-platform>] section of a config file.
+        """
+        disallowed_platform_options = self.disallow.get(self.platform, set())
+        if name in disallowed_platform_options:
+            return False
+
+        allowed_option_names = self.default_options.keys() | self.default_platform_options.keys()
+
+        return name in allowed_option_names
+
+    def _load_file(self, filename: Path) -> Tuple[Dict[str, Any], Dict[str, Any]]:
+        """
+        Load a toml file, returns global and platform as separate dicts.
+        """
+        config = toml.load(filename)
+
+        global_options = config.get("tool", {}).get("cibuildwheel", {})
+        platform_options = global_options.get(self.platform, {})
+
+        return global_options, platform_options
+
+    def __call__(
+        self,
+        name: str,
+        *,
+        env_plat: bool = True,
+        sep: Optional[str] = None,
+        table: Optional[TableFmt] = None,
+    ) -> str:
+        """
+        Get and return the value for the named option from environment,
+        configuration file, or the default. If env_plat is False, then don't
+        accept platform versions of the environment variable. If this is an
+        array it will be merged with "sep" before returning. If it is a table,
+        it will be formatted with "table['item']" using {k} and {v} and merged
+        with "table['sep']".
+        """
+
+        if name not in self.default_options and name not in self.default_platform_options:
+            raise ConfigOptionError(f"{name} must be in cibuildwheel/resources/defaults.toml file")
+
+        # Environment variable form
+        envvar = f"CIBW_{name.upper().replace('-', '_')}"
+        plat_envvar = f"{envvar}_{self.platform.upper()}"
+
+        # get the option from the environment, then the config file, then finally the default.
+        # platform-specific options are preferred, if they're allowed.
+        result = _dig_first(
+            (os.environ if env_plat else {}, plat_envvar),  # type: ignore
+            (os.environ, envvar),
+            (self.config_platform_options, name),
+            (self.config_options, name),
+            (self.default_platform_options, name),
+            (self.default_options, name),
+        )
+
+        if isinstance(result, dict):
+            if table is None:
+                raise ConfigOptionError(f"{name} does not accept a table")
+            return table["sep"].join(table["item"].format(k=k, v=v) for k, v in result.items())
+        elif isinstance(result, list):
+            if sep is None:
+                raise ConfigOptionError(f"{name} does not accept a list")
+            return sep.join(result)
+        elif isinstance(result, int):
+            return str(result)
+        else:
+            return result

cibuildwheel/resources/defaults.toml

@@ -0,0 +1,39 @@
+[tool.cibuildwheel]
+build = "*"
+skip = ""
+test-skip = ""
+
+archs = ["auto"]
+dependency-versions = "pinned"
+environment = {}
+build-verbosity = ""
+
+before-all = ""
+before-build = ""
+repair-wheel-command = ""
+
+test-command = ""
+before-test = ""
+test-requires = []
+test-extras = []
+
+manylinux-x86_64-image = "manylinux2010"
+manylinux-i686-image = "manylinux2010"
+manylinux-aarch64-image = "manylinux2014"
+manylinux-ppc64le-image = "manylinux2014"
+manylinux-s390x-image = "manylinux2014"
+manylinux-pypy_x86_64-image = "manylinux2010"
+manylinux-pypy_i686-image = "manylinux2010"
+manylinux-pypy_aarch64-image = "manylinux2014"
+
+
+[tool.cibuildwheel.linux]
+repair-wheel-command = "auditwheel repair -w {dest_dir} {wheel}"
+
+[tool.cibuildwheel.macos]
+repair-wheel-command = [
+  "delocate-listdeps {wheel}",
+  "delocate-wheel --require-archs {delocate_archs} -w {dest_dir} {wheel}",
+]
+
+[tool.cibuildwheel.windows]

docs/extra.css

@@ -1,6 +1,10 @@
 
 /* Global styles */
 
+body {
+    overflow-wrap: break-word;
+}
+
 p {
     margin-bottom: 12px;
     line-height: 26px;
@@ -20,7 +24,7 @@ code, pre, tt {
     font-family: SFMono-Regular, Consolas, Liberation Mono, Menlo, monospace;
 }
 
-.hljs {
+pre code, pre code.hljs {
   padding: 1em;
   background-color: #f6f8fa;
 }
@@ -112,7 +116,21 @@ h1, h2, h3, h4, h5, h6 {
   background-color: white;
   display: flex;
   justify-content: flex-start;
-  border-bottom: 2px solid #ccc;
+  overflow-x: auto;
+  overflow-y: hidden;
+  position: relative;
+}
+.tabs-header::before {
+  position: absolute;
+  content: "";
+  bottom: 0;
+  left: 0;
+  right: 0;
+  height: 2px;
+  background: #ccc;
+}
+.tabs-header > * {
+  position: relative;
 }
 
 /* Style the buttons that are used to open the tab content */
@@ -126,15 +144,13 @@ h1, h2, h3, h4, h5, h6 {
   font-size: 0.9em;
   font-weight: 600;
   padding: 8px 16px;
-  border-bottom: 2px solid transparent;
+  border-bottom: 2px solid #ccc;
-
-  /* put the border on top of the parent border */
-  margin-bottom: -2px;
 }
 
 .tabs-header button:focus-visible {
   /* preserve an outline for accesibility purposes */
   outline: 1px solid currentColor;
+  outline-offset: -1px;
 }
 
 /* Change background color of buttons on hover */
@@ -153,4 +169,53 @@ h1, h2, h3, h4, h5, h6 {
   background-color: #f1f6fa;
   padding: 1px 1em;
   padding-top: 0.8em;
+
+  /* don't collapse inner margins */
+  overflow-y: hidden;
+}
+
+/* Examples tabs styling */
+
+.tabs.examples .tabs-header {
+  justify-content: flex-end;
+  background-color: transparent;
+  border-bottom-style: none;
+  padding: 0;
+}
+.tabs.examples .tabs-header::before {
+  height: 0;
+}
+.tabs.examples .tabs-header button {
+  padding: 6px 12px;
+  border-bottom: none;
+  color: rgba(0, 0, 0, 0.3);
+  font-size: 0.8em;
+  border-top-left-radius: 4px;
+  border-top-right-radius: 4px;
+}
+.tabs-header button:hover {
+  background-color: unset;
+}
+
+.tabs.examples .tabs-header button.active {
+  border-bottom-style: none;
+  background: #f6f8fa;
+  color: inherit;
+}
+.tabs.examples .tabs-content {
+  padding: 0;
+  background-color: transparent;
+  background-color: #f6f8fa;
+}
+.tabs.examples .tabs-content .tab > * {
+  padding-left: 0.8em;
+  padding-right: 0.8em;
+}
+.tabs.examples .tabs-content .tab > pre {
+  padding-left: 0;
+  padding-right: 0;
+  margin-bottom: 0.5em;
+}
+.tabs.examples pre:first-child {
+  margin-top: 0;
 }

docs/extra.js

@@ -20,6 +20,17 @@ while (true) {
   tabContainer.insertBefore(firstTab);
   tabContainer.append(headerContainer, contentContainer)
 
+  // add extra classes from the first tab to the container
+  const classes = Array.from(firstTab[0].classList)
+
+  for (let i = 0; i < classes.length; i++) {
+    const element = classes[i];
+    if (element == 'tab' || element == 'admonition') {
+      continue
+    }
+    tabContainer.addClass(element)
+  }
+
   const selectTab = function (index) {
     headerContainer.children().removeClass('active')
     headerContainer.children().eq(index).addClass('active')

docs/options.md

@@ -1,15 +1,12 @@
-## Options summary
-
-<div class="options-toc"></div>
-
 ## Setting options
 
-cibuildwheel is configured using environment variables that can be set using
+cibuildwheel can either be configured using environment variables, or from
-your CI config.
+config file such as `pyproject.toml`.
 
-For example, to configure cibuildwheel to run tests, add the following YAML to
+### Environment variables {: #environment-variables}
-your CI config file:
 
+Environment variables can be set in your CI config. For example, to configure
+cibuildwheel to run tests, add the following YAML to your CI config file:
 
 !!! tab "GitHub Actions"
 
@@ -76,7 +73,43 @@ your CI config file:
         CIBW_TEST_COMMAND: "pytest {project}/tests"
     ```
 
+### Configuration file {: #configuration-file}
 
+You can configure cibuildwheel with a config file, such as `pyproject.toml`.
+Options have the same names as the environment variable overrides, but are
+placed in `[tool.cibuildwheel]` and are lower case, with dashes, following
+common [TOML][] practice. Anything placed in subsections `linux`, `windows`,
+or `macos` will only affect those platforms. Lists can be used instead of
+strings for items that are natually a list. Multiline strings also work just
+like in in the environment variables. Environment variables will take
+precedence if defined.
+
+The example above using environment variables could have been written like this:
+
+```toml
+[tool.cibuildwheel]
+test-requires = "pytest"
+test-command = "pytest {project}/tests"
+```
+
+The complete set of defaults for the current version of cibuildwheel are shown below:
+
+```toml
+{% include "../cibuildwheel/resources/defaults.toml" %}
+```
+
+
+!!! tip
+    Static configuration works across all CI systems, and can be used locally if
+    you run `cibuildwheel --plat linux`. This is preferred, but environment
+    variables are better if you need to change per-matrix element
+    (`CIBW_BUILD` is often in this category, for example), or if you cannot or do
+    not want to change a `pyproject.toml` file. You can specify a different file to
+    use with `--config-file` on the command line, as well.
+
+## Options summary
+
+<div class="options-toc"></div>
 
 ## Build selection
 
@@ -94,7 +127,7 @@ Default: `auto`
 - For `macos`, you need a Mac machine. Note that cibuildwheel is going to install MacPython on your system, so you probably don't want to run this on your development machine.
 - For `windows`, you need to run in Windows. cibuildwheel will install required versions of Python to `C:\cibw\python` using NuGet.
 
-This option can also be set using the [command-line option](#command-line) `--platform`.
+This option can also be set using the [command-line option](#command-line) `--platform`. This option is not available in the `pyproject.toml` config.
 
 !!! tip
     If you have Docker installed, you can locally debug your cibuildwheel Linux config, instead of pushing to CI to test every change. For example:
@@ -110,7 +143,7 @@ This option can also be set using the [command-line option](#command-line) `--pl
 
 > Choose the Python versions to build
 
-Space-separated list of builds to build and skip. Each build has an identifier like `cp38-manylinux_x86_64` or `cp37-macosx_x86_64` - you can list specific ones to build and cibuildwheel will only build those, and/or list ones to skip and cibuildwheel won't try to build them.
+List of builds to build and skip. Each build has an identifier like `cp38-manylinux_x86_64` or `cp37-macosx_x86_64` - you can list specific ones to build and cibuildwheel will only build those, and/or list ones to skip and cibuildwheel won't try to build them.
 
 When both options are specified, both conditions are applied and only builds with a tag that matches `CIBW_BUILD` and does not match `CIBW_SKIP` will be built.
 
@@ -136,6 +169,8 @@ See the [cibuildwheel 1 documentation](https://cibuildwheel.readthedocs.io/en/1.
 
 #### Examples
 
+!!! tab examples "Environment variables"
+
     ```yaml
     # Only build on CPython 3.6
     CIBW_BUILD: cp36-*
@@ -168,6 +203,47 @@ CIBW_SKIP: "*-win32 *-manylinux_i686"
     CIBW_SKIP: pp*
     ```
 
+    Separate multiple selectors with a space.
+
+!!! tab examples "pyproject.toml"
+
+    ```toml
+    [tool.cibuildwheel]
+    # Only build on CPython 3.6
+    build = "cp36-*"
+
+    # Skip building on CPython 3.6 on the Mac
+    skip = "cp36-macosx_x86_64"
+
+    # Skip building on CPython 3.8 on the Mac
+    skip = "cp38-macosx_x86_64"
+
+    # Skip building on CPython 3.6 on all platforms
+    skip = "cp36-*"
+
+    # Skip CPython 3.6 on Windows
+    skip = "cp36-win*"
+
+    # Skip CPython 3.6 on 32-bit Windows
+    skip = "cp36-win32"
+
+    # Skip CPython 3.6 and CPython 3.7
+    skip = ["cp36-*", "cp37-*"]
+
+    # Skip Python 3.6 on Linux
+    skip = "cp36-manylinux*"
+
+    # Skip 32-bit builds
+    skip = ["*-win32", "*-manylinux_i686"]
+
+    # Disable building PyPy wheels on all platforms
+    skip = "pp*"
+    ```
+
+    It is generally recommened to set `CIBW_BUILD` as an environment variable, though `skip`
+    tends to be useful in a config file; you can statically declare that you don't
+    support pypy, for example.
+
 <style>
   .build-id-table-marker + table {
     font-size: 90%;
@@ -191,7 +267,7 @@ CIBW_SKIP: pp*
 ### `CIBW_ARCHS` {: #archs}
 > Change the architectures built on your machine by default.
 
-A space-separated list of architectures to build.
+A list of architectures to build.
 
 On macOS, this option can be used to cross-compile between `x86_64`,
 `universal2` and `arm64` for Apple Silicon support.
@@ -226,13 +302,15 @@ If not listed above, `auto` is the same as `native`.
 [setup-qemu-action]: https://github.com/docker/setup-qemu-action
 [binfmt]: https://hub.docker.com/r/tonistiigi/binfmt
 
-Platform-specific variants also available:<br/>
+Platform-specific environment variables are also available:<br/>
  `CIBW_ARCHS_MACOS` | `CIBW_ARCHS_WINDOWS` | `CIBW_ARCHS_LINUX`
 
 This option can also be set using the [command-line option](#command-line) `--archs`.
 
 #### Examples
 
+!!! tab examples "Environment variables"
+
     ```yaml
     # Build `universal2` and `arm64` wheels on an Intel runner.
     # Note that the `arm64` wheel and the `arm64` part of the `universal2`
@@ -243,6 +321,26 @@ CIBW_ARCHS_MACOS: "x86_64 universal2 arm64"
     CIBW_ARCHS_LINUX: "auto aarch64"
     ```
 
+    Separate multiple archs with a space.
+
+!!! tab examples "pyproject.toml"
+
+    ```toml
+    # Build `universal2` and `arm64` wheels on an Intel runner.
+    # Note that the `arm64` wheel and the `arm64` part of the `universal2`
+    # wheel cannot be tested in this configuration.
+    [tool.cibuildwheel.macos]
+    archs: ["x86_64", "universal2", "arm64"]
+
+    # On an Linux Intel runner with qemu installed, build Intel and ARM wheels
+    [tool.cibuildwheel.linux]
+    archs: ["auto", "aarch64"]
+    ```
+
+    It is generally recommmended to use the environment variable or
+    command-line option for Linux, as selecting archs often depends
+    on your specific runner having qemu installed.
+
 
 ###  `CIBW_PROJECT_REQUIRES_PYTHON` {: #requires-python}
 > Manually set the Python compatibility of your project
@@ -293,8 +391,16 @@ the package is compatible with all versions of Python that it can build.
         [options]
         python_requires = ">=3.6"
 
+
+This option is not available in `pyproject.toml` under
+`tool.cibuildwheel.project-requires-python`, since it should be set with the
+[PEP621](https://www.python.org/dev/peps/pep-0621/) location instead,
+`project.requires-python`.
+
 #### Examples
 
+!!! tab examples "Environment variables"
+
     ```yaml
     CIBW_PROJECT_REQUIRES_PYTHON: ">=3.6"
     ```
@@ -316,10 +422,12 @@ like to test wheel building with these versions, you can enable this flag.
 
 Default: Off (0) if Python is available in beta phase. No effect otherwise.
 
-This option can also be set using the [command-line option](#command-line) `--prerelease-pythons`.
+This option can also be set using the [command-line option](#command-line) `--prerelease-pythons`. This option is not available in the `pyproject.toml` config.
 
 #### Examples
 
+!!! tab examples "Environment variables"
+
     ```yaml
     # Include latest Python beta
     CIBW_PRERELEASE_PYTHONS: True
@@ -330,7 +438,7 @@ CIBW_PRERELEASE_PYTHONS: True
 ### `CIBW_ENVIRONMENT` {: #environment}
 > Set environment variables needed during the build
 
-A space-separated list of environment variables to set during the build. Bash syntax should be used, even on Windows.
+A list of environment variables to set during the build. Bash syntax should be used, even on Windows.
 
 You must set this variable to pass variables to Linux builds (since they execute in a Docker container). It also works for the other platforms.
 
@@ -338,10 +446,13 @@ You can use `$PATH` syntax to insert other variables, or the `$(pwd)` syntax to
 
 To specify more than one environment variable, separate the assignments by spaces.
 
-Platform-specific variants also available:<br/>
+Platform-specific environment variables are also available:<br/>
 `CIBW_ENVIRONMENT_MACOS` | `CIBW_ENVIRONMENT_WINDOWS` | `CIBW_ENVIRONMENT_LINUX`
 
 #### Examples
+
+!!! tab examples "Environment variables"
+
     ```yaml
     # Set some compiler flags
     CIBW_ENVIRONMENT: "CFLAGS='-g -Wall' CXXFLAGS='-Wall'"
@@ -355,10 +466,43 @@ CIBW_ENVIRONMENT: "BUILD_TIME=$(date)"
     # Supply options to `pip` to affect how it downloads dependencies
     CIBW_ENVIRONMENT: "PIP_EXTRA_INDEX_URL=https://pypi.myorg.com/simple"
 
-# Set two flags
+    # Set two flags on linux only
-CIBW_ENVIRONMENT: "BUILD_TIME=$(date) SAMPLE_TEXT=\"sample text\""
+    CIBW_ENVIRONMENT_LINUX: "BUILD_TIME=$(date) SAMPLE_TEXT=\"sample text\""
     ```
 
+    Separate multiple values with a space.
+
+!!! tab examples "pyproject.toml"
+
+    ```toml
+    [tool.cibuildwheel]
+    # Set some compiler flags
+    environment = "CFLAGS='-g -Wall' CXXFLAGS='-Wall'"
+
+    # Set some compiler flags using a TOML table
+    environment = { CFLAGS="-g -Wall", CXXFLAGS="-Wall" }
+
+    # Append a directory to the PATH variable (this is expanded in the build environment)
+    environment = { PATH="$PATH:/usr/local/bin" }
+
+    # Set BUILD_TIME to the output of the `date` command
+    environment = { BUILD_TIME="$(date)" }
+
+    # Supply options to `pip` to affect how it downloads dependencies
+    environment = { PIP_EXTRA_INDEX_URL="https://pypi.myorg.com/simple" }
+
+    # Set two flags on linux only
+    [tool.cibuildwheel.linux]
+    environment = { BUILD_TIME="$(date)", SAMPLE_TEXT="sample text" }
+
+    # Alternate form with out-of-line table for setting a few values
+    [tool.cibuildwheel.linux.environment]
+    BUILD_TIME = "$(date)"
+    SAMPLE_TEXT = "sample text"
+    ```
+
+    In configuration mode, you can use a [TOML][] table instead of a raw string as shown above.
+
 !!! note
     cibuildwheel always defines the environment variable `CIBUILDWHEEL=1`. This can be useful for [building wheels with optional extensions](faq.md#building-packages-with-optional-c-extensions).
 
@@ -367,24 +511,57 @@ CIBW_ENVIRONMENT: "BUILD_TIME=$(date) SAMPLE_TEXT=\"sample text\""
 
 Shell command to prepare a common part of the project (e.g. build or install libraries which does not depend on the specific version of Python).
 
-This option is very useful for the Linux build, where builds take place in isolated Docker containers managed by cibuildwheel. This command will run inside the container before the wheel builds start. Note, if you're building both x86_64 and i686 wheels (the default), your build uses two different Docker images. In that case, this command will execute twice - once per build container.
+This option is very useful for the Linux build, where builds take place in isolated Docker containers managed by cibuildwheel. This command will run inside the container before the wheel builds start. Note, if you're building both `x86_64` and `i686` wheels (the default), your build uses two different Docker images. In that case, this command will execute twice - once per build container.
 
 The placeholder `{package}` can be used here; it will be replaced by the path to the package being built by cibuildwheel.
 
 On Windows and macOS, the version of Python available inside `CIBW_BEFORE_ALL` is whatever is available on the host machine. On Linux, a modern Python version is available on PATH.
 
-Platform-specific variants also available:<br/>
+Platform-specific environment variables also available:<br/>
 `CIBW_BEFORE_ALL_MACOS` | `CIBW_BEFORE_ALL_WINDOWS` | `CIBW_BEFORE_ALL_LINUX`
 
 #### Examples
+
+!!! tab examples "Environment variables"
+
     ```yaml
-# build third party library
+    # Build third party library
     CIBW_BEFORE_ALL: make -C third_party_lib
 
-# install system library
+    # Install system library
     CIBW_BEFORE_ALL_LINUX: yum install -y libffi-dev
+
+    # Chain multiple commands using && and > in a YAML file, like:
+    CIBW_BEFORE_ALL: >
+      yum install bzip2 -y &&
+      make third_party
     ```
 
+    For multiline commands, see the last example. The character `>` means that
+    whitespace is collapsed to a single line, and '&&' between each command
+    ensures that errors are not ignored. [Further reading on multiline YAML
+    here.](https://yaml-multiline.info).
+
+!!! tab examples "pyproject.toml"
+
+    ```toml
+    # Build third party library
+    [tool.cibuildwheel]
+    before-all = "make -C third_party_lib"
+
+    # Install system library
+    [tool.cibuildwheel.linux]
+    before-all = "yum install -y libffi-dev"
+
+    # Run multiple commands using an array
+    before-all = [
+      "yum install bzip2 -y",
+      "make third_party",
+    ]
+    ```
+
+    In configuration files, you can use a TOML array, and each line will be run sequentially - joined with `&&`.
+
 Note that manylinux2_24 builds occur inside a Debian9 docker, where
 manylinux2010 and manylinux2014 builds occur inside a CentOS one. So for
 `manylinux2_24` the `CIBW_BEFORE_ALL_LINUX` command must use `apt-get -y`
@@ -395,33 +572,63 @@ instead.
 
 A shell command to run before building the wheel. This option allows you to run a command in **each** Python environment before the `pip wheel` command. This is useful if you need to set up some dependency so it's available during the build.
 
-If dependencies are required to build your wheel (for example if you include a header from a Python module), instead of using this command, we recommend adding requirements to a pyproject.toml file. This is reproducible, and users who do not get your wheels (such as Alpine or ClearLinux users) will still benefit.
+If dependencies are required to build your wheel (for example if you include a header from a Python module), instead of using this command, we recommend adding requirements to a `pyproject.toml` file's `build-system.requires` array instead. This is reproducible, and users who do not get your wheels (such as Alpine or ClearLinux users) will still benefit.
 
 The active Python binary can be accessed using `python`, and pip with `pip`; cibuildwheel makes sure the right version of Python and pip will be executed. The placeholder `{package}` can be used here; it will be replaced by the path to the package being built by cibuildwheel.
 
 The command is run in a shell, so you can write things like `cmd1 && cmd2`.
 
-Platform-specific variants also available:<br/>
+Platform-specific environment variables are also available:<br/>
  `CIBW_BEFORE_BUILD_MACOS` | `CIBW_BEFORE_BUILD_WINDOWS` | `CIBW_BEFORE_BUILD_LINUX`
 
 #### Examples
+
+!!! tab examples "Environment variables"
+
     ```yaml
-# install something required for the build (you might want to use pyproject.toml instead)
+    # Install something required for the build (you might want to use pyproject.toml instead)
     CIBW_BEFORE_BUILD: pip install pybind11
 
-# chain commands using &&
+    # Chain commands using &&
-CIBW_BEFORE_BUILD_LINUX: yum install -y libffi-dev && make clean
+    CIBW_BEFORE_BUILD_LINUX: python scripts/install-deps.py && make clean
 
-# run a script that's inside your project
+    # Run a script that's inside your project
     CIBW_BEFORE_BUILD: bash scripts/prepare_for_build.sh
 
-# if cibuildwheel is called with a package_dir argument, it's available as {package}
+    # If cibuildwheel is called with a package_dir argument, it's available as {package}
     CIBW_BEFORE_BUILD: "{package}/script/prepare_for_build.sh"
     ```
 
+!!! tab examples "pyproject.toml"
+
+    ```toml
+    [tool.cibuildwheel]
+
+    # Install something required for the build
+    # (you might want to use build-system.requires instead)
+    before-build = "pip install pybind11"
+
+    # Chain commands using && or make an array.
+    before-build = "python scripts/install-deps.py && make clean"
+    before-build = [
+        "python scripts/install-deps.py",
+        "make clean",
+    ]
+
+    # Run a script that's inside your project
+    before-build = "bash scripts/prepare_for_build.sh"
+
+    # If cibuildwheel is called with a package_dir argument, it's available as {package}
+    before-build = "{package}/script/prepare_for_build.sh"
+    ```
+
+    In configuration mode, you can use a array, and the items will be joined with `&&`. In TOML, using a single-quote string will avoid escapes - useful for
+    Windows paths.
+
 !!! note
-    If you need dependencies installed for the build, we recommend using
+    If you need Python dependencies installed for the build, we recommend using
-    `pyproject.toml`. This is an example `pyproject.toml` file:
+    `pyproject.toml`'s `build-system.requires` instead. This is an example
+    `pyproject.toml` file:
 
         [build-system]
         requires = [
@@ -445,6 +652,7 @@ CIBW_BEFORE_BUILD: "{package}/script/prepare_for_build.sh"
     [PEP 517]: https://www.python.org/dev/peps/pep-0517/
     [PEP 518]: https://www.python.org/dev/peps/pep-0517/
 
+
 ### `CIBW_REPAIR_WHEEL_COMMAND` {: #repair-wheel-command}
 > Execute a shell command to repair each (non-pure Python) built wheel
 
@@ -465,7 +673,7 @@ The following placeholders must be used inside the command and will be replaced
 
 The command is run in a shell, so you can run multiple commands like `cmd1 && cmd2`.
 
-Platform-specific variants also available:<br/>
+Platform-specific environment variables are also available:<br/>
 `CIBW_REPAIR_WHEEL_COMMAND_MACOS` | `CIBW_REPAIR_WHEEL_COMMAND_WINDOWS` | `CIBW_REPAIR_WHEEL_COMMAND_LINUX`
 
 !!! tip
@@ -479,19 +687,39 @@ Platform-specific variants also available:<br/>
 
 #### Examples
 
+!!! tab examples "Environment variables"
+
     ```yaml
-# use delvewheel on windows (only works on Python 3.6+)
+    # Use delvewheel on windows
     CIBW_BEFORE_BUILD_WINDOWS: "pip install delvewheel"
     CIBW_REPAIR_WHEEL_COMMAND_WINDOWS: "delvewheel repair -w {dest_dir} {wheel}"
 
-# don't repair macOS wheels
+    # Don't repair macOS wheels
     CIBW_REPAIR_WHEEL_COMMAND_MACOS: ""
 
-# pass the `--lib-sdir .` flag to auditwheel on Linux
+    # Pass the `--lib-sdir .` flag to auditwheel on Linux
     CIBW_REPAIR_WHEEL_COMMAND_LINUX: "auditwheel repair --lib-sdir . -w {dest_dir} {wheel}"
-
     ```
 
+!!! tab examples "pyproject.toml"
+
+    ```toml
+    # Use delvewheel on windows
+    [tool.cibuildwheel.windows]
+    before_build = "pip install delvewheel"
+    repair_wheel_command = "delvewheel repair -w {dest_dir} {wheel}"
+
+    # Don't repair macOS wheels
+    [tool.cibuildwheel.macos]
+    repair_wheel_command = ""
+
+    # Pass the `--lib-sdir .` flag to auditwheel on Linux
+    [tool.cibuildwheel.linux]
+    repair_wheel_command = "auditwheel repair --lib-sdir . -w {dest_dir} {wheel}"
+    ```
+
+    In configuration mode, you can use an inline array, and the items will be joined with `&&`.
+
 
 ### CIBW_MANYLINUX_*_IMAGE {: #manylinux-image}
 > Specify alternative manylinux Docker images
@@ -519,31 +747,62 @@ Auditwheel detects the version of the manylinux standard in the Docker image thr
 
 #### Examples
 
+
+!!! tab examples "Environment variables"
+
     ```yaml
-# build using the manylinux1 image to ensure manylinux1 wheels are produced
+    # Build using the manylinux1 image to ensure manylinux1 wheels are produced
-# skip PyPy, since there is no PyPy manylinux1 image
+    # Not setting PyPy to manylinux1, since there is no manylinux1 PyPy image.
     CIBW_MANYLINUX_X86_64_IMAGE: manylinux1
     CIBW_MANYLINUX_I686_IMAGE: manylinux1
-CIBW_SKIP: pp*
 
-# build using the manylinux2014 image
+    # Build using the manylinux2014 image
     CIBW_MANYLINUX_X86_64_IMAGE: manylinux2014
     CIBW_MANYLINUX_I686_IMAGE: manylinux2014
     CIBW_MANYLINUX_PYPY_X86_64_IMAGE: manylinux2014
     CIBW_MANYLINUX_PYPY_I686_IMAGE: manylinux2014
 
-# build using the latest manylinux2010 release, instead of the cibuildwheel
+    # Build using the latest manylinux2010 release, instead of the cibuildwheel
     # pinned version
     CIBW_MANYLINUX_X86_64_IMAGE: quay.io/pypa/manylinux2010_x86_64:latest
     CIBW_MANYLINUX_I686_IMAGE: quay.io/pypa/manylinux2010_i686:latest
     CIBW_MANYLINUX_PYPY_X86_64_IMAGE: quay.io/pypa/manylinux2010_x86_64:latest
     CIBW_MANYLINUX_PYPY_I686_IMAGE: quay.io/pypa/manylinux2010_i686:latest
 
-# build using a different image from the docker registry
+    # Build using a different image from the docker registry
     CIBW_MANYLINUX_X86_64_IMAGE: dockcross/manylinux-x64
     CIBW_MANYLINUX_I686_IMAGE: dockcross/manylinux-x86
     ```
 
+!!! tab examples "pyproject.toml"
+
+    ```toml
+    [tool.cibuildwheel]
+    # Build using the manylinux1 image to ensure manylinux1 wheels are produced
+    # Not setting PyPy to manylinux1, since there is no manylinux1 PyPy image.
+    manylinux-x86_64-image = "manylinux1"
+    manylinux-i686-image = "manylinux1"
+
+    # Build using the manylinux2014 image
+    manylinux-x86_64_image = "manylinux2014"
+    manylinux-i686-image = "manylinux2014"
+    manylinux-pypy_x86_64-image = "manylinux2014"
+    manylinux-pypy_i686-image = "manylinux2014"
+
+    # Build using the latest manylinux2010 release, instead of the cibuildwheel
+    # pinned version
+    manylinux-x86_64-image = "quay.io/pypa/manylinux2010_x86_64:latest"
+    manylinux-i686-image = "quay.io/pypa/manylinux2010_i686:latest"
+    manylinux-pypy_x86_64-image = "quay.io/pypa/manylinux2010_x86_64:latest"
+    manylinux-pypy_i686-image = "quay.io/pypa/manylinux2010_i686:latest"
+
+    # Build using a different image from the docker registry
+    manylinux-x86_64-image = "dockcross/manylinux-x64"
+    manylinux-i686-image = "dockcross/manylinux-x86"
+    ```
+
+    Like any other option, these can be placed in `[tool.cibuildwheel.linux]`
+    if you perfer; they have no effect on `macos` and `windows`.
 
 ### `CIBW_DEPENDENCY_VERSIONS` {: #dependency-versions}
 > Specify how cibuildwheel controls the versions of the tools it uses
@@ -572,7 +831,7 @@ here and it will be used instead.
     `./constraints-python37.txt` on Python 3.7, or fallback to
     `./constraints.txt` if that's not found.
 
-Platform-specific variants also available:<br/>
+Platform-specific environment variables are also available:<br/>
 `CIBW_DEPENDENCY_VERSIONS_MACOS` | `CIBW_DEPENDENCY_VERSIONS_WINDOWS`
 
 !!! note
@@ -583,17 +842,32 @@ Platform-specific variants also available:<br/>
 
 #### Examples
 
+!!! tab examples "Environment variables"
+
     ```yaml
-# use tools versions that are bundled with cibuildwheel (this is the default)
+    # Use tools versions that are bundled with cibuildwheel (this is the default)
     CIBW_DEPENDENCY_VERSIONS: pinned
 
-# use the latest versions available on PyPI
+    # Use the latest versions available on PyPI
     CIBW_DEPENDENCY_VERSIONS: latest
 
-# use your own pip constraints file
+    # Use your own pip constraints file
     CIBW_DEPENDENCY_VERSIONS: ./constraints.txt
     ```
 
+!!! tab examples "pyproject.toml"
+
+    ```toml
+    [tool.cibuildwheel]
+    # Use tools versions that are bundled with cibuildwheel (this is the default)
+    dependency-versions = "pinned"
+
+    # Use the latest versions available on PyPI
+    dependency-versions = "latest"
+
+    # Use your own pip constraints file
+    dependency-versions = "./constraints.txt"
+    ```
 
 ## Testing
 
@@ -614,22 +888,40 @@ not be installed after building.
 
 The command is run in a shell, so you can write things like `cmd1 && cmd2`.
 
-Platform-specific variants also available:<br/>
+Platform-specific environment variables are also available:<br/>
 `CIBW_TEST_COMMAND_MACOS` | `CIBW_TEST_COMMAND_WINDOWS` | `CIBW_TEST_COMMAND_LINUX`
 
 #### Examples
 
+!!! tab examples "Environment variables"
+
     ```yaml
-# run the project tests against the installed wheel using `nose`
+    # Run the project tests against the installed wheel using `nose`
     CIBW_TEST_COMMAND: nosetests {project}/tests
 
-# run the package tests using `pytest`
+    # Run the package tests using `pytest`
     CIBW_TEST_COMMAND: pytest {package}/tests
 
-# trigger an install of the package, but run nothing of note
+    # Trigger an install of the package, but run nothing of note
     CIBW_TEST_COMMAND: "echo Wheel installed"
     ```
 
+!!! tab examples "pyproject.toml"
+
+    ```toml
+    [tool.cibuildwheel]
+    # Run the project tests against the installed wheel using `nose`
+    test-command = "nosetests {project}/tests"
+
+    # Run the package tests using `pytest`
+    test-command = "pytest {package}/tests"
+
+    # Trigger an install of the package, but run nothing of note
+    test-command = "echo Wheel installed"
+    ```
+
+    In configuration files, you can use an array, and the items will be joined with `&&`.
+
 
 ### `CIBW_BEFORE_TEST` {: #before-test}
 > Execute a shell command before testing each wheel
@@ -641,73 +933,137 @@ The active Python binary can be accessed using `python`, and pip with `pip`; cib
 
 The command is run in a shell, so you can write things like `cmd1 && cmd2`.
 
-Platform-specific variants also available:<br/>
+Platform-specific environment variables are also available:<br/>
  `CIBW_BEFORE_TEST_MACOS` | `CIBW_BEFORE_TEST_WINDOWS` | `CIBW_BEFORE_TEST_LINUX`
 
 #### Examples
+
+!!! tab examples "Environment variables"
+
     ```yaml
-# install test dependencies with overwritten environment variables.
+    # Install test dependencies with overwritten environment variables.
     CIBW_BEFORE_TEST: CC=gcc CXX=g++ pip install -r requirements.txt
 
-# chain commands using &&
+    # Chain commands using &&
     CIBW_BEFORE_TEST: rm -rf ./data/cache && mkdir -p ./data/cache
 
-# install non pip python package
+    # Install non pip python package
     CIBW_BEFORE_TEST: cd some_dir; ./configure; make; make install
 
-# install python packages that are required to install test dependencies
+    # Install python packages that are required to install test dependencies
     CIBW_BEFORE_TEST: pip install cmake scikit-build
     ```
 
+!!! tab examples "pyproject.toml"
+
+    ```toml
+    [tool.cibuildwheel]
+    # Install test dependencies with overwritten environment variables.
+    before-test = "CC=gcc CXX=g++ pip install -r requirements.txt"
+
+    # Chain commands using && or using an array
+    before-test = "rm -rf ./data/cache && mkdir -p ./data/cache"
+    before-test = [
+        "rm -rf ./data/cache",
+        "mkdir -p ./data/cache",
+    ]
+
+    # Install non pip python package
+    before-test = [
+        "cd some_dir",
+        "./configure",
+        "make",
+        "make install",
+    ]
+
+    # Install python packages that are required to install test dependencies
+    [tool.cibuildwheel]
+    before-test = "pip install cmake scikit-build"
+    ```
+
+    In configuration files, you can use an array, and the items will be joined with `&&`.
+
 
 ### `CIBW_TEST_REQUIRES` {: #test-requires}
 > Install Python dependencies before running the tests
 
 Space-separated list of dependencies required for running the tests.
 
-Platform-specific variants also available:<br/>
+Platform-specific environment variables are also available:<br/>
 `CIBW_TEST_REQUIRES_MACOS` | `CIBW_TEST_REQUIRES_WINDOWS` | `CIBW_TEST_REQUIRES_LINUX`
 
 #### Examples
 
+!!! tab examples "Environment variables"
+
     ```yaml
-# install pytest before running CIBW_TEST_COMMAND
+    # Install pytest before running CIBW_TEST_COMMAND
     CIBW_TEST_REQUIRES: pytest
 
-# install specific versions of test dependencies
+    # Install specific versions of test dependencies
     CIBW_TEST_REQUIRES: nose==1.3.7 moto==0.4.31
     ```
 
+!!! tab examples "pyproject.toml"
+
+    ```toml
+    # Install pytest before running CIBW_TEST_COMMAND
+    [tool.cibuildwheel]
+    test-requires = "pytest"
+
+    # Install specific versions of test dependencies
+    [tool.cibuildwheel]
+    test-requires = ["nose==1.3.7", "moto==0.4.31"]
+    ```
+
+    In configuration files, you can use an array, and the items will be joined with a space.
+
 
 ### `CIBW_TEST_EXTRAS` {: #test-extras}
 > Install your wheel for testing using `extras_require`
 
-Comma-separated list of
+List of
 [extras_require](https://setuptools.readthedocs.io/en/latest/setuptools.html#declaring-extras-optional-features-with-their-own-dependencies)
 options that should be included when installing the wheel prior to running the
 tests. This can be used to avoid having to redefine test dependencies in
 `CIBW_TEST_REQUIRES` if they are already defined in `setup.py` or
 `setup.cfg`.
 
-Platform-specific variants also available:<br/>
+Platform-specific environment variables are also available:<br/>
 `CIBW_TEST_EXTRAS_MACOS` | `CIBW_TEST_EXTRAS_WINDOWS` | `CIBW_TEST_EXTRAS_LINUX`
 
 #### Examples
 
+!!! tab examples "Environment variables"
+
     ```yaml
-# will cause the wheel to be installed with `pip install <wheel_file>[test,qt]`
+    # Will cause the wheel to be installed with `pip install <wheel_file>[test,qt]`
-CIBW_TEST_EXTRAS: test,qt
+    CIBW_TEST_EXTRAS: "test,qt"
     ```
 
+    Seperate multiple items with a comma.
+
+!!! tab examples "pyproject.toml"
+
+    ```toml
+    [tool.cibuildwheel]
+    # Will cause the wheel to be installed with `pip install <wheel_file>[test,qt]`
+    test-extras: ["test", "qt"]
+    ```
+
+    In configuration files, you can use an inline array, and the items will be joined with a comma.
+
 ### `CIBW_TEST_SKIP` {: #test-skip}
 > Skip running tests on some builds
 
 This will skip testing on any identifiers that match the given skip patterns (see [`CIBW_SKIP`](#build-skip)). This can be used to mask out tests for wheels that have missing dependencies upstream that are slow or hard to build, or to skip slow tests on emulated architectures.
 
-With macOS `universal2` wheels, you can also skip the the individual archs inside the wheel using an `:arch` suffix. For example, `cp39-macosx_universal2:x86_64` or `cp39-macosx_universal2:arm64`.
+With macOS `universal2` wheels, you can also skip the individual archs inside the wheel using an `:arch` suffix. For example, `cp39-macosx_universal2:x86_64` or `cp39-macosx_universal2:arm64`.
 
 #### Examples
 
+!!! tab examples "Environment variables"
+
     ```yaml
     # Will avoid testing on emulated architectures
     CIBW_TEST_SKIP: "*-manylinux_{aarch64,ppc64le,s390x}"
@@ -716,6 +1072,16 @@ CIBW_TEST_SKIP: "*-manylinux_{aarch64,ppc64le,s390x}"
     CIBW_TEST_SKIP: "*-macosx_arm64 *-macosx_universal2:arm64"
     ```
 
+!!! tab examples "pyproject.toml"
+
+    ```toml
+    [tool.cibuildwheel]
+    # Will avoid testing on emulated architectures
+    test-skip = "*-manylinux_{aarch64,ppc64le,s390x}"
+
+    # Skip trying to test arm64 builds on Intel Macs
+    test-skip = "*-macosx_arm64 *-macosx_universal2:arm64"
+    ```
 
 ## Other
 
@@ -724,24 +1090,34 @@ CIBW_TEST_SKIP: "*-macosx_arm64 *-macosx_universal2:arm64"
 
 An number from 1 to 3 to increase the level of verbosity (corresponding to invoking pip with `-v`, `-vv`, and `-vvv`), between -1 and -3 (`-q`, `-qq`, and `-qqq`), or just 0 (default verbosity). These flags are useful while debugging a build when the output of the actual build invoked by `pip wheel` is required.
 
-Platform-specific variants also available:<br/>
+Platform-specific environment variables are also available:<br/>
 `CIBW_BUILD_VERBOSITY_MACOS` | `CIBW_BUILD_VERBOSITY_WINDOWS` | `CIBW_BUILD_VERBOSITY_LINUX`
 
 #### Examples
 
+!!! tab examples "Environment variables"
+
     ```yaml
-# increase pip debugging output
+    # Increase pip debugging output
     CIBW_BUILD_VERBOSITY: 1
     ```
 
+!!! tab examples "pyproject.toml"
+
+    ```toml
+    [tool.cibuildwheel]
+    # Increase pip debugging output
+    build-verbosity = 1
+    ```
+
 
 ## Command line options {: #command-line}
 
 ```text
 usage: cibuildwheel [-h] [--platform {auto,linux,macos,windows}]
                     [--archs ARCHS] [--output-dir OUTPUT_DIR]
-                    [--print-build-identifiers] [--allow-empty]
+                    [--config-file CONFIG_FILE] [--print-build-identifiers]
-                    [--prerelease-pythons]
+                    [--allow-empty] [--prerelease-pythons]
                     [package_dir]
 
 Build wheels for all the platforms.
@@ -772,12 +1148,21 @@ optional arguments:
                         aarch64, ppc64le, s390x, universal2, arm64, x86, AMD64
   --output-dir OUTPUT_DIR
                         Destination folder for the wheels.
+  --config-file CONFIG_FILE
+                        TOML config file for cibuildwheel; usually
+                        pyproject.toml, but can be overridden with this
+                        option. Use {package} for the package directory.
   --print-build-identifiers
                         Print the build identifiers matched by the current
                         invocation and exit.
   --allow-empty         Do not report an error code if the build does not
                         match any wheels.
   --prerelease-pythons  Enable pre-release Python versions if available.
+
+Most options are supplied via environment variables or in --config-file
+(pyproject.toml usually). See https://github.com/pypa/cibuildwheel#options for
+info.
+```
 ```
 
 <style>
@@ -899,3 +1284,5 @@ optional arguments:
     console.log('readme options markdown\n', markdown)
   });
 </script>
+
+[TOML]: https://toml.io

unit_test/main_tests/main_options_test.py

@@ -200,7 +200,7 @@ def test_test_command(
 
     main()
 
-    assert intercepted_build_args.args[0].test_command == test_command
+    assert intercepted_build_args.args[0].test_command == (test_command or "")
 
 
 @pytest.mark.parametrize("before_build", [None, "before --build"])
@@ -217,7 +217,7 @@ def test_before_build(
 
     main()
 
-    assert intercepted_build_args.args[0].before_build == before_build
+    assert intercepted_build_args.args[0].before_build == (before_build or "")
 
 
 @pytest.mark.parametrize("build_verbosity", [None, 0, 2, -2, 4, -4])
@@ -286,7 +286,4 @@ def test_before_all(before_all, platform_specific, platform, intercepted_build_a
 
     main()
 
-    if before_all is None:
+    assert intercepted_build_args.args[0].before_all == (before_all or "")
-        before_all = ""
-
-    assert intercepted_build_args.args[0].before_all == before_all

unit_test/options_toml_test.py

@@ -0,0 +1,190 @@
+import pytest
+
+from cibuildwheel.options import ConfigOptionError, ConfigOptions
+
+PYPROJECT_1 = """
+[tool.cibuildwheel]
+build = "cp39*"
+environment = {THING = "OTHER", FOO="BAR"}
+
+test-command = "pyproject"
+test-requires = "something"
+test-extras = ["one", "two"]
+
+manylinux-x86_64-image = "manylinux1"
+
+[tool.cibuildwheel.macos]
+test-requires = "else"
+
+[tool.cibuildwheel.linux]
+test-requires = ["other", "many"]
+"""
+
+
+@pytest.fixture(params=["linux", "macos", "windows"])
+def platform(request):
+    return request.param
+
+
+@pytest.mark.parametrize("fname", ["pyproject.toml", "cibuildwheel.toml"])
+def test_simple_settings(tmp_path, platform, fname):
+    with tmp_path.joinpath(fname).open("w") as f:
+        f.write(PYPROJECT_1)
+
+    options = ConfigOptions(tmp_path, f"{{package}}/{fname}", platform=platform)
+
+    assert options("build", env_plat=False, sep=" ") == "cp39*"
+
+    assert options("test-command") == "pyproject"
+    assert options("archs", sep=" ") == "auto"
+    assert (
+        options("test-requires", sep=" ")
+        == {"windows": "something", "macos": "else", "linux": "other many"}[platform]
+    )
+
+    # Also testing options for support for both lists and tables
+    assert (
+        options("environment", table={"item": '{k}="{v}"', "sep": " "}) == 'THING="OTHER" FOO="BAR"'
+    )
+    assert (
+        options("environment", sep="x", table={"item": '{k}="{v}"', "sep": " "})
+        == 'THING="OTHER" FOO="BAR"'
+    )
+    assert options("test-extras", sep=",") == "one,two"
+    assert options("test-extras", sep=",", table={"item": '{k}="{v}"', "sep": " "}) == "one,two"
+
+    assert options("manylinux-x86_64-image") == "manylinux1"
+    assert options("manylinux-i686-image") == "manylinux2010"
+
+    with pytest.raises(ConfigOptionError):
+        options("environment", sep=" ")
+
+    with pytest.raises(ConfigOptionError):
+        options("test-extras", table={"item": '{k}="{v}"', "sep": " "})
+
+
+def test_envvar_override(tmp_path, platform, monkeypatch):
+    monkeypatch.setenv("CIBW_BUILD", "cp38*")
+    monkeypatch.setenv("CIBW_MANYLINUX_X86_64_IMAGE", "manylinux2014")
+    monkeypatch.setenv("CIBW_TEST_COMMAND", "mytest")
+    monkeypatch.setenv("CIBW_TEST_REQUIRES", "docs")
+    monkeypatch.setenv("CIBW_TEST_REQUIRES_LINUX", "scod")
+
+    with tmp_path.joinpath("pyproject.toml").open("w") as f:
+        f.write(PYPROJECT_1)
+
+    options = ConfigOptions(tmp_path, platform=platform)
+
+    assert options("archs", sep=" ") == "auto"
+
+    assert options("build", sep=" ") == "cp38*"
+    assert options("manylinux-x86_64-image") == "manylinux2014"
+    assert options("manylinux-i686-image") == "manylinux2010"
+
+    assert (
+        options("test-requires", sep=" ")
+        == {"windows": "docs", "macos": "docs", "linux": "scod"}[platform]
+    )
+    assert options("test-command") == "mytest"
+
+
+def test_project_global_override_default_platform(tmp_path, platform):
+    tmp_path.joinpath("pyproject.toml").write_text(
+        """
+[tool.cibuildwheel]
+repair-wheel-command = "repair-project-global"
+"""
+    )
+    options = ConfigOptions(tmp_path, platform=platform)
+    assert options("repair-wheel-command") == "repair-project-global"
+
+
+def test_env_global_override_default_platform(tmp_path, platform, monkeypatch):
+    monkeypatch.setenv("CIBW_REPAIR_WHEEL_COMMAND", "repair-env-global")
+    options = ConfigOptions(tmp_path, platform=platform)
+    assert options("repair-wheel-command") == "repair-env-global"
+
+
+def test_env_global_override_project_platform(tmp_path, platform, monkeypatch):
+    monkeypatch.setenv("CIBW_REPAIR_WHEEL_COMMAND", "repair-env-global")
+    tmp_path.joinpath("pyproject.toml").write_text(
+        """
+[tool.cibuildwheel.linux]
+repair-wheel-command = "repair-project-linux"
+[tool.cibuildwheel.windows]
+repair-wheel-command = "repair-project-windows"
+[tool.cibuildwheel.macos]
+repair-wheel-command = "repair-project-macos"
+"""
+    )
+    options = ConfigOptions(tmp_path, platform=platform)
+    assert options("repair-wheel-command") == "repair-env-global"
+
+
+def test_global_platform_order(tmp_path, platform):
+    tmp_path.joinpath("pyproject.toml").write_text(
+        """
+[tool.cibuildwheel.linux]
+repair-wheel-command = "repair-project-linux"
+[tool.cibuildwheel.windows]
+repair-wheel-command = "repair-project-windows"
+[tool.cibuildwheel.macos]
+repair-wheel-command = "repair-project-macos"
+[tool.cibuildwheel]
+repair-wheel-command = "repair-project-global"
+"""
+    )
+    options = ConfigOptions(tmp_path, platform=platform)
+    assert options("repair-wheel-command") == f"repair-project-{platform}"
+
+
+def test_unexpected_key(tmp_path):
+    # Note that platform contents are only checked when running
+    # for that platform.
+    tmp_path.joinpath("pyproject.toml").write_text(
+        """
+[tool.cibuildwheel]
+repairs-wheel-command = "repair-project-linux"
+"""
+    )
+
+    with pytest.raises(ConfigOptionError):
+        ConfigOptions(tmp_path, platform="linux")
+
+
+def test_unexpected_table(tmp_path):
+    tmp_path.joinpath("pyproject.toml").write_text(
+        """
+[tool.cibuildwheel.linus]
+repair-wheel-command = "repair-project-linux"
+"""
+    )
+    with pytest.raises(ConfigOptionError):
+        ConfigOptions(tmp_path, platform="linux")
+
+
+def test_unsupported_join(tmp_path):
+    tmp_path.joinpath("pyproject.toml").write_text(
+        """
+[tool.cibuildwheel]
+build = ["1", "2"]
+"""
+    )
+    options = ConfigOptions(tmp_path, platform="linux")
+
+    assert "1, 2" == options("build", sep=", ")
+    with pytest.raises(ConfigOptionError):
+        options("build")
+
+
+def test_disallowed_a(tmp_path):
+    tmp_path.joinpath("pyproject.toml").write_text(
+        """
+[tool.cibuildwheel.windows]
+manylinux-x64_86-image = "manylinux1"
+"""
+    )
+    disallow = {"windows": {"manylinux-x64_86-image"}}
+    ConfigOptions(tmp_path, platform="linux", disallow=disallow)
+    with pytest.raises(ConfigOptionError):
+        ConfigOptions(tmp_path, platform="windows", disallow=disallow)