From 0140bbc15b51582d4d6cd8efaf4b29f9d6a20463 Mon Sep 17 00:00:00 2001 From: mayeut Date: Sun, 19 Sep 2021 17:47:46 +0200 Subject: [PATCH] doc: combine `CIBW_MANYLINUX_*_IMAGE` & `CIBW_MUSLLINUX_*_IMAGE` options --- README.md | 3 +- docs/changelog.md | 6 ++-- docs/faq.md | 2 +- docs/options.md | 79 ++++++++++++++++++++--------------------------- 4 files changed, 39 insertions(+), 51 deletions(-) diff --git a/README.md b/README.md index 26171c1d2..14aac912e 100644 --- a/README.md +++ b/README.md @@ -114,8 +114,7 @@ Options | | [`CIBW_BEFORE_ALL`](https://cibuildwheel.readthedocs.io/en/stable/options/#before-all) | Execute a shell command on the build system before any wheels are built. | | | [`CIBW_BEFORE_BUILD`](https://cibuildwheel.readthedocs.io/en/stable/options/#before-build) | Execute a shell command preparing each wheel's build | | | [`CIBW_REPAIR_WHEEL_COMMAND`](https://cibuildwheel.readthedocs.io/en/stable/options/#repair-wheel-command) | Execute a shell command to repair each (non-pure Python) built wheel | -| | [`CIBW_MANYLINUX_*_IMAGE`](https://cibuildwheel.readthedocs.io/en/stable/options/#manylinux-image) | Specify alternative manylinux Docker images | -| | [`CIBW_MUSLLINUX_*_IMAGE`](https://cibuildwheel.readthedocs.io/en/stable/options/#musllinux-image) | Specify alternative musllinux Docker images | +| | [`CIBW_MANYLINUX_*_IMAGE`
`CIBW_MUSLLINUX_*_IMAGE`](https://cibuildwheel.readthedocs.io/en/stable/options/#linux-image) | Specify alternative manylinux / musllinux Docker images | | | [`CIBW_DEPENDENCY_VERSIONS`](https://cibuildwheel.readthedocs.io/en/stable/options/#dependency-versions) | Specify how cibuildwheel controls the versions of the tools it uses | | **Testing** | [`CIBW_TEST_COMMAND`](https://cibuildwheel.readthedocs.io/en/stable/options/#test-command) | Execute a shell command to test each built wheel | | | [`CIBW_BEFORE_TEST`](https://cibuildwheel.readthedocs.io/en/stable/options/#before-test) | Execute a shell command before testing each wheel | diff --git a/docs/changelog.md b/docs/changelog.md index ec91947a2..38c93b109 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -66,7 +66,7 @@ _1 May 2021_ _22 Feb 2021_ - ✨ Added `manylinux_2_24` support. To use these new Debian-based manylinux - images, set your [manylinux image](https://cibuildwheel.readthedocs.io/en/stable/options/#manylinux-image) + images, set your [manylinux image](https://cibuildwheel.readthedocs.io/en/stable/options/#linux-image) options to `manylinux_2_24`. - 🛠 On macOS, we now set `MACOSX_DEPLOYMENT_TARGET` in before running `CIBW_BEFORE_ALL`. This is useful when using `CIBW_BEFORE_ALL` to build a @@ -321,7 +321,7 @@ _2 May 2020_ Studio can still effect things. This can be controlled using the [CIBW_DEPENDENCY_VERSIONS](https://cibuildwheel.readthedocs.io/en/stable/options/#dependency-versions) - and [manylinux image](https://cibuildwheel.readthedocs.io/en/stable/options/#manylinux-image) + and [manylinux image](https://cibuildwheel.readthedocs.io/en/stable/options/#linux-image) options - if you always want to use the latest toolchain, you can still do that, or you can specify your own pip constraints file and manylinux image. (#256) @@ -396,7 +396,7 @@ _10 November 2019_ build using the manylinux2010 images by default. If your project is still manylinux1 compatible, you should get both manylinux1 and manylinux2010 wheels - you can upload both to PyPI. If you always require manylinux1 wheels, you can - build using the old manylinux1 image using the [manylinux image](https://cibuildwheel.readthedocs.io/en/stable/options/#manylinux-image) option. + build using the old manylinux1 image using the [manylinux image](https://cibuildwheel.readthedocs.io/en/stable/options/#linux-image) option. (#155) - 📚 Documentation is now on its [own mini-site](https://cibuildwheel.readthedocs.io), rather than on the README (#169) diff --git a/docs/faq.md b/docs/faq.md index 132935477..b82f92850 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -14,7 +14,7 @@ Linux wheels are built in the [`manylinux`/`musllinux` docker images](https://gi - 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 Docker images can be specified with the `CIBW_MANYLINUX_*_IMAGE`/`CIBW_MUSLLINUX_*_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`/`CIBW_MUSLLINUX_*_IMAGE` options to allow for a custom, preconfigured build environment for the Linux builds. See [options](options.md#linux-image) for more details. ### Building macOS wheels for Apple Silicon {: #apple-silicon} diff --git a/docs/options.md b/docs/options.md index 2e66a445d..36573ada3 100644 --- a/docs/options.md +++ b/docs/options.md @@ -151,14 +151,14 @@ When setting the options, you can use shell-style globbing syntax, as per [fnmat
-| | macOS | Windows | Manylinux Intel | Manylinux Other | Musllinux Intel | Musllinux Other | -|--------------|------------------------------------------------------------------------|----------------------------------|--------------------------------------------------|-------------------------------------------------------------------------------|-------------------------------------------------|-------------------------------------------------------------------------------| -| Python 3.6 | cp36-macosx_x86_64 | cp36-win_amd64
cp36-win32 | cp36-manylinux_x86_64
cp36-manylinux_i686 | cp36-manylinux_aarch64
cp36-manylinux_ppc64le
cp36-manylinux_s390x | cp36-musllinux_x86_64
cp36-musllinux_i686 | cp36-musllinux_aarch64
cp36-musllinux_ppc64le
cp36-musllinux_s390x | -| Python 3.7 | cp37-macosx_x86_64 | cp37-win_amd64
cp37-win32 | cp37-manylinux_x86_64
cp37-manylinux_i686 | cp37-manylinux_aarch64
cp37-manylinux_ppc64le
cp37-manylinux_s390x | cp37-musllinux_x86_64
cp37-musllinux_i686 | cp37-musllinux_aarch64
cp37-musllinux_ppc64le
cp37-musllinux_s390x | -| Python 3.8 | cp38-macosx_x86_64
cp38-macosx_universal2
cp38-macosx_arm64 | cp38-win_amd64
cp38-win32 | cp38-manylinux_x86_64
cp38-manylinux_i686 | cp38-manylinux_aarch64
cp38-manylinux_ppc64le
cp38-manylinux_s390x | cp38-musllinux_x86_64
cp38-musllinux_i686 | cp38-musllinux_aarch64
cp38-musllinux_ppc64le
cp38-musllinux_s390x | -| Python 3.9 | cp39-macosx_x86_64
cp39-macosx_universal2
cp39-macosx_arm64 | cp39-win_amd64
cp39-win32 | cp39-manylinux_x86_64
cp39-manylinux_i686 | cp39-manylinux_aarch64
cp39-manylinux_ppc64le
cp39-manylinux_s390x | cp39-musllinux_x86_64
cp39-musllinux_i686 | cp39-musllinux_aarch64
cp39-musllinux_ppc64le
cp39-musllinux_s390x | -| Python 3.10 | cp310-macosx_x86_64
cp310-macosx_universal2
cp310-macosx_arm64 | cp310-win_amd64
cp310-win32 | cp310-manylinux_x86_64
cp310-manylinux_i686 | cp310-manylinux_aarch64
cp310-manylinux_ppc64le
cp310-manylinux_s390x | cp310-musllinux_x86_64
cp310-musllinux_i686 | cp310-musllinux_aarch64
cp310-musllinux_ppc64le
cp310-musllinux_s390x | -| PyPy3.7 v7.3 | pp37-macosx_x86_64 | pp37-win_amd64 | pp37-manylinux_x86_64 | | | | +| | macOS | Windows | Linux Intel | Linux Other | +|--------------|------------------------------------------------------------------------|----------------------------------|-----------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Python 3.6 | cp36-macosx_x86_64 | cp36-win_amd64
cp36-win32 | cp36-manylinux_x86_64
cp36-manylinux_i686
cp36-musllinux_x86_64
cp36-musllinux_i686 | cp36-manylinux_aarch64
cp36-manylinux_ppc64le
cp36-manylinux_s390x
cp36-musllinux_aarch64
cp36-musllinux_ppc64le
cp36-musllinux_s390x | +| Python 3.7 | cp37-macosx_x86_64 | cp37-win_amd64
cp37-win32 | cp37-manylinux_x86_64
cp37-manylinux_i686
cp37-musllinux_x86_64
cp37-musllinux_i686 | cp37-manylinux_aarch64
cp37-manylinux_ppc64le
cp37-manylinux_s390x
cp37-musllinux_aarch64
cp37-musllinux_ppc64le
cp37-musllinux_s390x | +| Python 3.8 | cp38-macosx_x86_64
cp38-macosx_universal2
cp38-macosx_arm64 | cp38-win_amd64
cp38-win32 | cp38-manylinux_x86_64
cp38-manylinux_i686
cp38-musllinux_x86_64
cp38-musllinux_i686 | cp38-manylinux_aarch64
cp38-manylinux_ppc64le
cp38-manylinux_s390x
cp38-musllinux_aarch64
cp38-musllinux_ppc64le
cp38-musllinux_s390x | +| Python 3.9 | cp39-macosx_x86_64
cp39-macosx_universal2
cp39-macosx_arm64 | cp39-win_amd64
cp39-win32 | cp39-manylinux_x86_64
cp39-manylinux_i686
cp39-musllinux_x86_64
cp39-musllinux_i686 | cp39-manylinux_aarch64
cp39-manylinux_ppc64le
cp39-manylinux_s390x
cp39-musllinux_aarch64
cp39-musllinux_ppc64le
cp39-musllinux_s390x | +| Python 3.10 | cp310-macosx_x86_64
cp310-macosx_universal2
cp310-macosx_arm64 | cp310-win_amd64
cp310-win32 | cp310-manylinux_x86_64
cp310-manylinux_i686
cp310-musllinux_x86_64
cp310-musllinux_i686 | cp310-manylinux_aarch64
cp310-manylinux_ppc64le
cp310-manylinux_s390x
cp310-musllinux_aarch64
cp310-musllinux_ppc64le
cp310-musllinux_s390x | +| PyPy3.7 v7.3 | pp37-macosx_x86_64 | pp37-win_amd64 | pp37-manylinux_x86_64 | | The list of supported and currently selected build identifiers can also be retrieved by passing the `--print-build-identifiers` flag to cibuildwheel. The format is `python_tag-platform_tag`, with tags similar to those in [PEP 425](https://www.python.org/dev/peps/pep-0425/#details). @@ -780,28 +780,37 @@ Platform-specific environment variables are also available:
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 +### CIBW_MANYLINUX_*_IMAGE / CIBW_MUSLLINUX_*_IMAGE {: #linux-image} +> Specify alternative manylinux / musllinux Docker images -The available options are: +The available options are (default value): -- `CIBW_MANYLINUX_X86_64_IMAGE` -- `CIBW_MANYLINUX_I686_IMAGE` -- `CIBW_MANYLINUX_PYPY_X86_64_IMAGE` -- `CIBW_MANYLINUX_AARCH64_IMAGE` -- `CIBW_MANYLINUX_PPC64LE_IMAGE` -- `CIBW_MANYLINUX_S390X_IMAGE` -- `CIBW_MANYLINUX_PYPY_AARCH64_IMAGE` -- `CIBW_MANYLINUX_PYPY_I686_IMAGE` +- `CIBW_MANYLINUX_X86_64_IMAGE` ([`quay.io/pypa/manylinux2010_x86_64`](https://quay.io/pypa/manylinux2010_x86_64)) +- `CIBW_MANYLINUX_I686_IMAGE` ([`quay.io/pypa/manylinux2010_i686`](https://quay.io/pypa/manylinux2010_i686)) +- `CIBW_MANYLINUX_PYPY_X86_64_IMAGE` ([`quay.io/pypa/manylinux2010_x86_64`](https://quay.io/pypa/manylinux2010_x86_64)) +- `CIBW_MANYLINUX_AARCH64_IMAGE` ([`quay.io/pypa/manylinux2014_aarch64`](https://quay.io/pypa/manylinux2014_aarch64)) +- `CIBW_MANYLINUX_PPC64LE_IMAGE` ([`quay.io/pypa/manylinux2014_ppc64le`](https://quay.io/pypa/manylinux2014_ppc64le)) +- `CIBW_MANYLINUX_S390X_IMAGE` ([`quay.io/pypa/manylinux2014_s390x`](https://quay.io/pypa/manylinux2010_s390x)) +- `CIBW_MANYLINUX_PYPY_AARCH64_IMAGE` ([`quay.io/pypa/manylinux2014_aarch64`](https://quay.io/pypa/manylinux2014_aarch64)) +- `CIBW_MANYLINUX_PYPY_I686_IMAGE` ([`quay.io/pypa/manylinux2010_i686`](https://quay.io/pypa/manylinux2010_i686)) +- `CIBW_MUSLLINUX_X86_64_IMAGE` ([`quay.io/pypa/musllinux_1_1_x86_64`](https://quay.io/pypa/musllinux_1_1_x86_64)) +- `CIBW_MUSLLINUX_I686_IMAGE` ([`quay.io/pypa/musllinux_1_1_i686`](https://quay.io/pypa/musllinux_1_1_i686)) +- `CIBW_MUSLLINUX_AARCH64_IMAGE` ([`quay.io/pypa/musllinux_1_1_aarch64`](https://quay.io/pypa/musllinux_1_1_aarch64)) +- `CIBW_MUSLLINUX_PPC64LE_IMAGE` ([`quay.io/pypa/musllinux_1_1_ppc64le`](https://quay.io/pypa/musllinux_1_1_ppc64le)) +- `CIBW_MUSLLINUX_S390X_IMAGE` ([`quay.io/pypa/musllinux_1_1_s390x`](https://quay.io/pypa/musllinux_1_1_s390x)) -Set an alternative Docker image to be used for building [manylinux](https://github.com/pypa/manylinux) wheels. cibuildwheel will then pull these instead of the default images, [`quay.io/pypa/manylinux2010_x86_64`](https://quay.io/pypa/manylinux2010_x86_64), [`quay.io/pypa/manylinux2010_i686`](https://quay.io/pypa/manylinux2010_i686), [`quay.io/pypa/manylinux2010_x86_64`](https://quay.io/pypa/manylinux2010_x86_64), [`quay.io/pypa/manylinux2014_aarch64`](https://quay.io/pypa/manylinux2014_aarch64), [`quay.io/pypa/manylinux2014_ppc64le`](https://quay.io/pypa/manylinux2014_ppc64le), and [`quay.io/pypa/manylinux2014_s390x`](https://quay.io/pypa/manylinux2010_s390x). +Set an alternative Docker image to be used for building [manylinux / musllinux](https://github.com/pypa/manylinux) wheels. -The value of this option can either be set to `manylinux1`, `manylinux2010`, `manylinux2014` or `manylinux_2_24` to use a pinned version of the [official manylinux images](https://github.com/pypa/manylinux). Alternatively, set these options to any other valid Docker image name. For PyPy, the `manylinux1` image is not available. For architectures other -than x86 (x86\_64 and i686) `manylinux2014` or `manylinux_2_24` must be used, because the first version of the manylinux specification that supports additional architectures is `manylinux2014`. If this option is blank, it will fall though to the next available definition (environment variable -> pyproject.toml -> default). +For `CIBW_MANYLINUX_*_IMAGE`, the value of this option can either be set to `manylinux1`, `manylinux2010`, `manylinux2014` or `manylinux_2_24` to use a pinned version of the [official manylinux images](https://github.com/pypa/manylinux). Alternatively, set these options to any other valid Docker image name. For PyPy, the `manylinux1` image is not available. For architectures other +than x86 (x86\_64 and i686) `manylinux2014` or `manylinux_2_24` must be used, because the first version of the manylinux specification that supports additional architectures is `manylinux2014`. -If setting a custom Docker image, you'll need to make sure it can be used in the same way as the official, default Docker images: all necessary Python and pip versions need to be present in `/opt/python/`, and the auditwheel tool needs to be present for cibuildwheel to work. Apart from that, the architecture and relevant shared system libraries need to be compatible to the relevant standard to produce valid manylinux1/manylinux2010/manylinux2014/manylinux_2_24 wheels (see [pypa/manylinux on GitHub](https://github.com/pypa/manylinux), [PEP 513](https://www.python.org/dev/peps/pep-0513/), [PEP 571](https://www.python.org/dev/peps/pep-0571/), [PEP 599](https://www.python.org/dev/peps/pep-0599/) and [PEP 600](https://www.python.org/dev/peps/pep-0600/) for more details). +For `CIBW_MUSLLINUX_*_IMAGE`, the value of this option can either be set to `musllinux_1_1` to use a pinned version of the [official musllinux images](https://github.com/pypa/musllinux). Alternatively, set these options to any other valid Docker image name. -Auditwheel detects the version of the manylinux standard in the Docker image through the `AUDITWHEEL_PLAT` environment variable, as cibuildwheel has no way of detecting the correct `--plat` command line argument to pass to auditwheel for a custom image. If a Docker image does not correctly set this `AUDITWHEEL_PLAT` environment variable, the `CIBW_ENVIRONMENT` option can be used to do so (e.g., `CIBW_ENVIRONMENT='AUDITWHEEL_PLAT="manylinux2010_$(uname -m)"'`). +If this option is blank, it will fall though to the next available definition (environment variable -> pyproject.toml -> default). + +If setting a custom Docker image, you'll need to make sure it can be used in the same way as the official, default Docker images: all necessary Python and pip versions need to be present in `/opt/python/`, and the auditwheel tool needs to be present for cibuildwheel to work. Apart from that, the architecture and relevant shared system libraries need to be compatible to the relevant standard to produce valid manylinux1/manylinux2010/manylinux2014/manylinux_2_24/musllinux_1_1 wheels (see [pypa/manylinux on GitHub](https://github.com/pypa/manylinux), [PEP 513](https://www.python.org/dev/peps/pep-0513/), [PEP 571](https://www.python.org/dev/peps/pep-0571/), [PEP 599](https://www.python.org/dev/peps/pep-0599/), [PEP 600](https://www.python.org/dev/peps/pep-0600/) and [PEP 656](https://www.python.org/dev/peps/pep-0656/) for more details). + +Auditwheel detects the version of the manylinux / musllinux standard in the Docker image through the `AUDITWHEEL_PLAT` environment variable, as cibuildwheel has no way of detecting the correct `--plat` command line argument to pass to auditwheel for a custom image. If a Docker image does not correctly set this `AUDITWHEEL_PLAT` environment variable, the `CIBW_ENVIRONMENT` option can be used to do so (e.g., `CIBW_ENVIRONMENT='AUDITWHEEL_PLAT="manylinux2010_$(uname -m)"'`). #### Examples @@ -862,26 +871,6 @@ Auditwheel detects the version of the manylinux standard in the Docker image thr Like any other option, these can be placed in `[tool.cibuildwheel.linux]` if you prefer; they have no effect on `macos` and `windows`. -### CIBW_MUSLLINUX_*_IMAGE {: #musllinux-image} -> Specify alternative musllinux Docker images - -The available options are: - -- `CIBW_MUSLLINUX_X86_64_IMAGE` -- `CIBW_MUSLLINUX_I686_IMAGE` -- `CIBW_MUSLLINUX_AARCH64_IMAGE` -- `CIBW_MUSLLINUX_PPC64LE_IMAGE` -- `CIBW_MUSLLINUX_S390X_IMAGE` - -Set an alternative Docker image to be used for building [musllinux](https://github.com/pypa/manylinux) wheels. cibuildwheel will then pull these instead of the default images, [`quay.io/pypa/musllinux_1_1_x86_64`](https://quay.io/pypa/musllinux_1_1_x86_64), [`quay.io/pypa/musllinux_1_1_i686`](https://quay.io/pypa/musllinux_1_1_i686), [`quay.io/pypa/musllinux_1_1_aarch64`](https://quay.io/pypa/musllinux_1_1_aarch64), [`quay.io/pypa/musllinux_1_1_ppc64le`](https://quay.io/pypa/musllinux_1_1_ppc64le), and [`quay.io/pypa/musllinux_1_1_s390x`](https://quay.io/pypa/musllinux_1_1_s390x). - -The value of this option can either be set to `musllinux_1_1` to use a pinned version of the [official musllinux images](https://github.com/pypa/musllinux). Alternatively, set these options to any other valid Docker image name. -If this option is blank, it will fall though to the next available definition (environment variable -> pyproject.toml -> default). - -If setting a custom Docker image, you'll need to make sure it can be used in the same way as the official, default Docker images: all necessary Python and pip versions need to be present in `/opt/python/`, and the auditwheel tool needs to be present for cibuildwheel to work. Apart from that, the architecture and relevant shared system libraries need to be compatible to the relevant standard to produce valid musllinux_1_1 wheels (see [pypa/manylinux on GitHub](https://github.com/pypa/manylinux) and [PEP 656](https://www.python.org/dev/peps/pep-0656/) for more details). - -Auditwheel detects the version of the musllinux standard in the Docker image through the `AUDITWHEEL_PLAT` environment variable, as cibuildwheel has no way of detecting the correct `--plat` command line argument to pass to auditwheel for a custom image. If a Docker image does not correctly set this `AUDITWHEEL_PLAT` environment variable, the `CIBW_ENVIRONMENT` option can be used to do so (e.g., `CIBW_ENVIRONMENT='AUDITWHEEL_PLAT="musllinux_1_1_$(uname -m)"'`). - ### `CIBW_DEPENDENCY_VERSIONS` {: #dependency-versions} > Specify how cibuildwheel controls the versions of the tools it uses @@ -915,7 +904,7 @@ Platform-specific environment variables are also available:
!!! note This option does not affect the tools used on the Linux build - those versions are bundled with the manylinux/musllinux image that cibuildwheel uses. To change - dependency versions on Linux, use the [CIBW_MANYLINUX_*](#manylinux-image) / [CIBW_MUSLLINUX_*](#musllinux-image) + dependency versions on Linux, use the [CIBW_MANYLINUX_* / CIBW_MUSLLINUX_*](#linux-image) options. #### Examples