179 lines
9.3 KiB
Markdown
179 lines
9.3 KiB
Markdown
## Options summary
|
|
|
|
`cibuildwheel` allows for easy customization of the various phases of the build process demonstrated above:
|
|
|
|
| | Option | |
|
|
|---|---|---|
|
|
| **Target wheels** | `CIBW_PLATFORM` | Override the auto-detected target platform |
|
|
| | `CIBW_BUILD` | Build only certain Python versions |
|
|
| | `CIBW_SKIP` | Skip certain Python versions |
|
|
| **Build parameters** | `CIBW_BUILD_VERBOSITY` | Increase or decrease the output of `pip wheel` |
|
|
| **Build environment** | `CIBW_ENVIRONMENT` | Set environment variables needed during the build |
|
|
| | `CIBW_BEFORE_BUILD` | Execute a shell command preparing each wheel's build |
|
|
| | `CIBW_MANYLINUX1_X86_64_IMAGE` | Specify an alternative manylinx1 x86_64 docker image |
|
|
| | `CIBW_MANYLINUX1_I686_IMAGE` | Specify an alternative manylinux1 i686 docker image |
|
|
| **Tests** | `CIBW_TEST_COMMAND` | Execute a shell command to test all built wheels |
|
|
| | `CIBW_TEST_REQUIRES` | Install Python dependencies before running the tests |
|
|
| | `CIBW_TEST_EXTRAS` | Install Python dependencies before running the tests using ``extras_require``|
|
|
|
|
Most of the config is via environment variables. These go into `.travis.yml`, `appveyor.yml`, and `.circleci/config.yml` nicely.
|
|
|
|
## Build selection
|
|
|
|
### CIBW_PLATFORM
|
|
|
|
Options: `auto` `linux` `macos` `windows`
|
|
|
|
Default: `auto`
|
|
|
|
`auto` will auto-detect platform using environment variables, such as `TRAVIS_OS_NAME`/`APPVEYOR`/`CIRCLECI`.
|
|
|
|
For `linux` you need Docker running, on Mac or Linux. For `macos`, you need a Mac machine, and note that this script is going to automatically install MacPython on your system, so don't run on your development machine. For `windows`, you need to run in Windows, and it will build and test for all versions of Python at `C:\PythonXX[-x64]`.
|
|
|
|
### CIBW_BUILD and CIBW_SKIP
|
|
|
|
Space-separated list of builds to build and skip. Each build has an identifier like `cp27-manylinux1_x86_64` or `cp34-macosx_10_6_intel` - 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.
|
|
|
|
The format is `python_tag-platform_tag`. The tags are as defined in [PEP 0425](https://www.python.org/dev/peps/pep-0425/#details).
|
|
|
|
Python tags look like `cp27` `cp34` `cp35` `cp36` `cp37`
|
|
|
|
Platform tags look like `macosx_10_6_intel` `manylinux1_x86_64` `manylinux1_i686` `win32` `win_amd64`
|
|
|
|
You can also use shell-style globbing syntax (as per `fnmatch`)
|
|
|
|
Examples:
|
|
|
|
- Only build on Python 3.6: `CIBW_BUILD=cp36-*`
|
|
- Skip building on Python 2.7 on the Mac: `CIBW_SKIP=cp27-macosx_10_6_intel`
|
|
- Skip building on Python 2.7 on all platforms: `CIBW_SKIP=cp27-*`
|
|
- Skip Python 2.7 on Windows: `CIBW_SKIP=cp27-win*`
|
|
- Skip Python 2.7 on 32-bit Windows: `CIBW_SKIP=cp27-win32`
|
|
- Skip Python 3.4 and Python 3.5: `CIBW_SKIP=cp34-* cp35-*`
|
|
- Skip Python 3.6 on Linux: `CIBW_SKIP=cp36-manylinux*`
|
|
- Only build on Python 3 and skip 32-bit builds: `CIBW_BUILD=cp3?-*` and `CIBW_SKIP=*-win32 *-manylinux1_i686`
|
|
|
|
## Build environment
|
|
|
|
### CIBW_ENVIRONMENT
|
|
|
|
A space-separated 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.
|
|
|
|
You can use `$PATH` syntax to insert other variables, or the `$(pwd)` syntax to insert the output of other shell commands.
|
|
|
|
Example: `CFLAGS="-g -Wall" CXXFLAGS="-Wall"`
|
|
Example: `PATH=$PATH:/usr/local/bin`
|
|
Example: `BUILD_TIME="$(date)"`
|
|
Example: `PIP_EXTRA_INDEX_URL="https://pypi.myorg.com/simple"`
|
|
|
|
Platform-specific variants also available:
|
|
`CIBW_ENVIRONMENT_MACOS` | `CIBW_ENVIRONMENT_WINDOWS` | `CIBW_ENVIRONMENT_LINUX`
|
|
|
|
In addition to the above, `cibuildwheel` always defines the environment variable `CIBUILDWHEEL=1`. This can be useful for [building wheels with optional extensions](https://github.com/joerick/cibuildwheel/wiki/Building-packages-with-optional-C-extensions).
|
|
|
|
### CIBW_BEFORE_BUILD
|
|
|
|
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), set this to `pip install .`, and the dependencies will be installed automatically by pip. However, this means your package will be built twice - if your package takes a long time to build, you might wish to manually list the dependencies here instead.
|
|
|
|
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. `{project}` can be used as a placeholder for the absolute path to the project's root.
|
|
|
|
Example: `pip install .`
|
|
Example: `pip install pybind11`
|
|
Example: `yum install -y libffi-dev && pip install .`
|
|
|
|
Platform-specific variants also available:
|
|
`CIBW_BEFORE_BUILD_MACOS` | `CIBW_BEFORE_BUILD_WINDOWS` | `CIBW_BEFORE_BUILD_LINUX`
|
|
|
|
### CIBW_MANYLINUX1_X86_64_IMAGE and CIBW_MANYLINUX1_I686_IMAGE
|
|
|
|
An alternative docker image to be used for building [`manylinux1`](https://github.com/pypa/manylinux) wheels. `cibuildwheel` will then pull these instead of the official images, [`quay.io/pypa/manylinux1_x86_64`](https://quay.io/pypa/manylinux1_i686) and [`quay.io/pypa/manylinux1_i686`](https://quay.io/pypa/manylinux1_i686).
|
|
|
|
Beware to specify a valid docker image that can be used the same 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 manylinux1-compatible in order to produce valid `manylinux1` wheels (see https://github.com/pypa/manylinux and [PEP 513](https://www.python.org/dev/peps/pep-0513/) for more details).
|
|
|
|
Example: `dockcross/manylinux-x64`
|
|
Example: `dockcross/manylinux-x86`
|
|
|
|
## Testing
|
|
|
|
### CIBW_TEST_COMMAND
|
|
|
|
Shell command to run tests after the build. The wheel will be installed automatically and available for import from the tests. `{project}` can be used as a placeholder for the absolute path to the project's root and will be replaced by `cibuildwheel`.
|
|
|
|
On Linux and Mac, the command runs in a shell, so you can write things like `cmd1 && cmd2`.
|
|
|
|
Example: `nosetests {project}/tests`
|
|
|
|
Platform-specific variants also available:
|
|
`CIBW_TEST_COMMAND_MACOS` | `CIBW_TEST_COMMAND_WINDOWS` | `CIBW_TEST_COMMAND_LINUX`
|
|
|
|
### CIBW_TEST_REQUIRES
|
|
|
|
Space-separated list of dependencies required for running the tests.
|
|
|
|
Example: `pytest`
|
|
Example: `nose==1.3.7 moto==0.4.31`
|
|
|
|
Platform-specific variants also available:
|
|
`CIBW_TEST_REQUIRES_MACOS` | `CIBW_TEST_REQUIRES_WINDOWS` | `CIBW_TEST_REQUIRES_LINUX`
|
|
|
|
### CIBW_TEST_EXTRAS
|
|
|
|
Comma-separated 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`.
|
|
|
|
Example: `test,qt` (will cause the wheel to be installed with `pip install <wheel_file>[test,qt]`)
|
|
|
|
|
|
Platform-specific variants also available:
|
|
`CIBW_TEST_EXTRAS_MACOS` | `CIBW_TEST_EXTRAS_WINDOWS` | `CIBW_TEST_EXTRAS_LINUX`
|
|
|
|
## Other
|
|
|
|
### CIBW_BUILD_VERBOSITY
|
|
|
|
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:
|
|
`CIBW_BUILD_VERBOSITY_MACOS` | `CIBW_BUILD_VERBOSITY_WINDOWS` | `CIBW_BUILD_VERBOSITY_LINUX`
|
|
|
|
## Command line options
|
|
|
|
```
|
|
usage: cibuildwheel [-h] [--platform {auto,linux,macos,windows}]
|
|
[--output-dir OUTPUT_DIR] [--print-build-identifiers]
|
|
[project_dir]
|
|
|
|
Build wheels for all the platforms.
|
|
|
|
positional arguments:
|
|
project_dir Path to the project that you want wheels for.
|
|
Default: the current directory.
|
|
|
|
optional arguments:
|
|
-h, --help show this help message and exit
|
|
--platform {auto,linux,macos,windows}
|
|
Platform to build for. For "linux" you need docker
|
|
running, on Mac or Linux. For "macos", you need a Mac
|
|
machine, and note that this script is going to
|
|
automatically install MacPython on your system, so
|
|
don't run on your development machine. For "windows",
|
|
you need to run in Windows, and it will build and test
|
|
for all versions of Python at C:\PythonXX[-x64].
|
|
--output-dir OUTPUT_DIR
|
|
Destination folder for the wheels.
|
|
--print-build-identifiers
|
|
Print the build identifiers matched by the current
|
|
invocation and exit.
|
|
|
|
```
|