From b49754dc7d0c813150f9821049b4777a73ad6015 Mon Sep 17 00:00:00 2001 From: Joe Rickerby Date: Sun, 29 Sep 2019 20:28:37 +0100 Subject: [PATCH 01/30] mkdocs setup --- docs/mkdocs.yml | 2 ++ docs/pages/index.md | 17 +++++++++++++++++ requirements-dev.txt | 2 ++ 3 files changed, 21 insertions(+) create mode 100644 docs/mkdocs.yml create mode 100644 docs/pages/index.md diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml new file mode 100644 index 00000000..3fe64b17 --- /dev/null +++ b/docs/mkdocs.yml @@ -0,0 +1,2 @@ +site_name: My Docs +docs_dir: pages diff --git a/docs/pages/index.md b/docs/pages/index.md new file mode 100644 index 00000000..d3880397 --- /dev/null +++ b/docs/pages/index.md @@ -0,0 +1,17 @@ +# Welcome to MkDocs + +For full documentation visit [mkdocs.org](https://mkdocs.org). + +## Commands + +* `mkdocs new [dir-name]` - Create a new project. +* `mkdocs serve` - Start the live-reloading docs server. +* `mkdocs build` - Build the documentation site. +* `mkdocs help` - Print this help message. + +## Project layout + + mkdocs.yml # The configuration file. + docs/ + index.md # The documentation homepage. + ... # Other markdown pages, images and other files. diff --git a/requirements-dev.txt b/requirements-dev.txt index ae60ed5f..c6677778 100644 --- a/requirements-dev.txt +++ b/requirements-dev.txt @@ -1,2 +1,4 @@ -e . pytest +mkdocs==1.0.4 + From d280f0f16afdcb6fc0600523b29e94f687d1079f Mon Sep 17 00:00:00 2001 From: Joe Rickerby Date: Sun, 29 Sep 2019 21:53:18 +0100 Subject: [PATCH 02/30] Add options to docs --- README.md | 352 -------------------------------------------- docs/index.md | 39 +++++ docs/mkdocs.yml | 2 - docs/options.md | 178 ++++++++++++++++++++++ docs/pages/index.md | 17 --- docs/setup.md | 141 ++++++++++++++++++ mkdocs.yml | 10 ++ 7 files changed, 368 insertions(+), 371 deletions(-) create mode 100644 docs/index.md delete mode 100644 docs/mkdocs.yml create mode 100644 docs/options.md delete mode 100644 docs/pages/index.md create mode 100644 docs/setup.md create mode 100644 mkdocs.yml diff --git a/README.md b/README.md index cec3816e..c4c93c99 100644 --- a/README.md +++ b/README.md @@ -40,194 +40,6 @@ Usage `cibuildwheel` is not intended to run on your development machine. It will try to install packages globally; this is no good. Travis CI, CircleCI, and AppVeyor run their builds in isolated environments, so are ideal for this kind of script. -### Minimal setup - -
- Azure Pipelines - - - - - -- Using Azure pipelines, you can build all three platforms on the same service. Create a `azure-pipelines.yml` file in your repo. - -**azure-pipelines.yml** -```yaml -jobs: -- job: linux - pool: {vmImage: 'Ubuntu-16.04'} - steps: - - task: UsePythonVersion@0 - - bash: | - python -m pip install --upgrade pip - pip install cibuildwheel==0.12.0 - cibuildwheel --output-dir wheelhouse . - - task: PublishBuildArtifacts@1 - inputs: {pathtoPublish: 'wheelhouse'} -- job: macos - pool: {vmImage: 'macOS-10.13'} - steps: - - task: UsePythonVersion@0 - - bash: | - python -m pip install --upgrade pip - pip install cibuildwheel==0.12.0 - cibuildwheel --output-dir wheelhouse . - - task: PublishBuildArtifacts@1 - inputs: {pathtoPublish: 'wheelhouse'} -- job: windows - pool: {vmImage: 'vs2017-win2016'} - steps: - - {task: UsePythonVersion@0, inputs: {versionSpec: '2.7', architecture: x86}} - - {task: UsePythonVersion@0, inputs: {versionSpec: '2.7', architecture: x64}} - - {task: UsePythonVersion@0, inputs: {versionSpec: '3.5', architecture: x86}} - - {task: UsePythonVersion@0, inputs: {versionSpec: '3.5', architecture: x64}} - - {task: UsePythonVersion@0, inputs: {versionSpec: '3.6', architecture: x86}} - - {task: UsePythonVersion@0, inputs: {versionSpec: '3.6', architecture: x64}} - - {task: UsePythonVersion@0, inputs: {versionSpec: '3.7', architecture: x86}} - - {task: UsePythonVersion@0, inputs: {versionSpec: '3.7', architecture: x64}} - - script: choco install vcpython27 -f -y - displayName: Install Visual C++ for Python 2.7 - - bash: | - python -m pip install --upgrade pip - pip install cibuildwheel==0.12.0 - cibuildwheel --output-dir wheelhouse . - - task: PublishBuildArtifacts@1 - inputs: {pathtoPublish: 'wheelhouse'} -``` - -
- -
- Travis CI - - - - -- To build Linux and Mac wheels on Travis CI, create a `.travis.yml` file in your repo. - - ``` - language: python - - matrix: - include: - - sudo: required - services: - - docker - env: PIP=pip - - os: osx - language: generic - env: PIP=pip2 - - script: - - $PIP install cibuildwheel==0.12.0 - - cibuildwheel --output-dir wheelhouse - ``` - - Then setup a deployment method by following the [Travis CI deployment docs](https://docs.travis-ci.com/user/deployment/), or see [Delivering to PyPI](#delivering-to-pypi) below. - -
- -
- CircleCI - - - - -- To build Linux and Mac wheels on CircleCI, create a `.circleci/config.yml` file in your repo, - - ``` - version: 2 - - jobs: - linux-wheels: - working_directory: ~/linux-wheels - docker: - - image: circleci/python:3.6 - steps: - - checkout - - setup_remote_docker - - run: - name: Build the Linux wheels. - command: | - pip install --user cibuildwheel - cibuildwheel --output-dir wheelhouse - - store_artifacts: - path: wheelhouse/ - - osx-wheels: - working_directory: ~/osx-wheels - macos: - xcode: "10.0.0" - steps: - - checkout - - run: - name: Build the OS X wheels. - command: | - pip install --user cibuildwheel - cibuildwheel --output-dir wheelhouse - - store_artifacts: - path: wheelhouse/ - - workflows: - version: 2 - all-tests: - jobs: - - linux-wheels - - osx-wheels - ``` - - Note: CircleCI doesn't enable free macOS containers for open source by default, but you can ask for access. See [here](https://circleci.com/docs/2.0/oss/#overview) for more information. - - CircleCI will store the built wheels for you - you can access them from the project console. - -
- - -
- AppVeyor - - - -- To build Windows wheels on AppVeyor, create an `appveyor.yml` file in your repo. - - ``` - build_script: - - pip install cibuildwheel==0.12.0 - - cibuildwheel --output-dir wheelhouse - artifacts: - - path: "wheelhouse\\*.whl" - name: Wheels - ``` - - AppVeyor will store the built wheels for you - you can access them from the project console. Alternatively, you may want to store them in the same place as the Travis CI build. See [AppVeyor deployment docs](https://www.appveyor.com/docs/deployment/) for more info, or see [Delivering to PyPI](#delivering-to-pypi) below. - -
- -- Commit those files, enable building of your repo on Travis CI and AppVeyor, and push. - -All being well, you should get wheels delivered to you in a few minutes. - -> ⚠️ Got an error? Check the [checklist](#it-didnt-work) below. - -### Configuration overview - -`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``| - -A more detailed description of the options, the allowed values, and some examples can be found in the [Options](#options) section. ### Linux builds on Docker @@ -269,170 +81,6 @@ optional arguments: ``` -Most of the config is via environment variables. These go into `.travis.yml`, `appveyor.yml`, and `.circleci/config.yml` nicely. - -*** - -| Environment variable: `CIBW_PLATFORM` | Command line argument: `--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]`. - -*** - -| Environment variables: `CIBW_BUILD` and `CIBW_SKIP` -| --- - -Optional. - -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` - -*** - -| Environment variable: `CIBW_BUILD_VERBOSITY` -| --- - -Optional. - -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` - -*** - -| Environment variable: `CIBW_ENVIRONMENT` -| --- - -Optional. - -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). - -*** - -| Environment variable: `CIBW_BEFORE_BUILD` -| --- - -Optional. - -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` - -*** - -| Environment variables: `CIBW_MANYLINUX1_X86_64_IMAGE` and `CIBW_MANYLINUX1_I686_IMAGE` -| --- - -Optional. - -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` - -*** - -| Environment variable: `CIBW_TEST_COMMAND` -| --- - -Optional. - -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` - -*** - -| Environment variable: `CIBW_TEST_REQUIRES` -| --- - -Optional. - -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` - -*** - -| Environment variable: `CIBW_TEST_EXTRAS` -| --- - -Optional. - -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 [test,qt]`) - - -Platform-specific variants also available: -`CIBW_TEST_EXTRAS_MACOS` | `CIBW_TEST_EXTRAS_WINDOWS` | `CIBW_TEST_EXTRAS_LINUX` - ### Example YML syntax diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..01e0d0cd --- /dev/null +++ b/docs/index.md @@ -0,0 +1,39 @@ +Home +==== + +Python wheels are great. Building them across **Mac, Linux, Windows**, on **multiple versions of Python**, is not. + +`cibuildwheel` is here to help. `cibuildwheel` runs on your CI server - currently it supports Azure Pipelines, Travis CI, AppVeyor, and CircleCI - and it builds and tests your wheels across all of your platforms. + +**`cibuildwheel` is in beta**. It's brand new - I'd love for you to try it and help make it better! + +What does it do? +---------------- + +| | macOS 10.6+ | manylinux i686 | manylinux x86_64 | Windows 32bit | Windows 64bit | +|---|---|---|---|---|---| +| Python 2.7 | ✅ | ✅ | ✅ | ✅ | ✅ | +| Python 3.4 | ✅ | ✅ | ✅ | ✅* | ✅* | +| Python 3.5 | ✅ | ✅ | ✅ | ✅ | ✅ | +| Python 3.6 | ✅ | ✅ | ✅ | ✅ | ✅ | +| Python 3.7 | ✅ | ✅ | ✅ | ✅ | ✅ | + +> \* Not supported on Azure Pipelines + +- Builds manylinux, macOS and Windows (32 and 64bit) wheels using Azure Pipelines, Travis CI, AppVeyor, and CircleCI +- Bundles shared library dependencies on Linux and macOS through [auditwheel](https://github.com/pypa/auditwheel) and [delocate](https://github.com/matthew-brett/delocate) +- Runs the library test suite against the wheel-installed version of your library + +Usage +----- + +`cibuildwheel` currently works **Travis CI** and **CircleCI** to build Linux and Mac wheels, and **AppVeyor** to build Windows wheels. **Azure Pipelines** supports all three. + +| | Linux | macOS | Windows | +|-----------------|-------|-------|---------| +| Azure Pipelines | ✅ | ✅ | ✅ | +| Travis CI | ✅ | ✅ | | +| AppVeyor | | | ✅ | +| CircleCI | ✅ | ✅ | | + +`cibuildwheel` is not intended to run on your development machine. It will try to install packages globally; this is no good. Travis CI, CircleCI, and AppVeyor run their builds in isolated environments, so are ideal for this kind of script. diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml deleted file mode 100644 index 3fe64b17..00000000 --- a/docs/mkdocs.yml +++ /dev/null @@ -1,2 +0,0 @@ -site_name: My Docs -docs_dir: pages diff --git a/docs/options.md b/docs/options.md new file mode 100644 index 00000000..6174e1b9 --- /dev/null +++ b/docs/options.md @@ -0,0 +1,178 @@ +## 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 [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. + +``` diff --git a/docs/pages/index.md b/docs/pages/index.md deleted file mode 100644 index d3880397..00000000 --- a/docs/pages/index.md +++ /dev/null @@ -1,17 +0,0 @@ -# Welcome to MkDocs - -For full documentation visit [mkdocs.org](https://mkdocs.org). - -## Commands - -* `mkdocs new [dir-name]` - Create a new project. -* `mkdocs serve` - Start the live-reloading docs server. -* `mkdocs build` - Build the documentation site. -* `mkdocs help` - Print this help message. - -## Project layout - - mkdocs.yml # The configuration file. - docs/ - index.md # The documentation homepage. - ... # Other markdown pages, images and other files. diff --git a/docs/setup.md b/docs/setup.md new file mode 100644 index 00000000..5fb1c3ac --- /dev/null +++ b/docs/setup.md @@ -0,0 +1,141 @@ +## Azure Pipelines [linux/mac/windows] + +Using Azure pipelines, you can build all three platforms on the same service. Create a `azure-pipelines.yml` file in your repo. + +**azure-pipelines.yml** +```yaml +jobs: +- job: linux + pool: {vmImage: 'Ubuntu-16.04'} + steps: + - task: UsePythonVersion@0 + - bash: | + python -m pip install --upgrade pip + pip install cibuildwheel==0.12.0 + cibuildwheel --output-dir wheelhouse . + - task: PublishBuildArtifacts@1 + inputs: {pathtoPublish: 'wheelhouse'} +- job: macos + pool: {vmImage: 'macOS-10.13'} + steps: + - task: UsePythonVersion@0 + - bash: | + python -m pip install --upgrade pip + pip install cibuildwheel==0.12.0 + cibuildwheel --output-dir wheelhouse . + - task: PublishBuildArtifacts@1 + inputs: {pathtoPublish: 'wheelhouse'} +- job: windows + pool: {vmImage: 'vs2017-win2016'} + steps: + - {task: UsePythonVersion@0, inputs: {versionSpec: '2.7', architecture: x86}} + - {task: UsePythonVersion@0, inputs: {versionSpec: '2.7', architecture: x64}} + - {task: UsePythonVersion@0, inputs: {versionSpec: '3.5', architecture: x86}} + - {task: UsePythonVersion@0, inputs: {versionSpec: '3.5', architecture: x64}} + - {task: UsePythonVersion@0, inputs: {versionSpec: '3.6', architecture: x86}} + - {task: UsePythonVersion@0, inputs: {versionSpec: '3.6', architecture: x64}} + - {task: UsePythonVersion@0, inputs: {versionSpec: '3.7', architecture: x86}} + - {task: UsePythonVersion@0, inputs: {versionSpec: '3.7', architecture: x64}} + - script: choco install vcpython27 -f -y + displayName: Install Visual C++ for Python 2.7 + - bash: | + python -m pip install --upgrade pip + pip install cibuildwheel==0.12.0 + cibuildwheel --output-dir wheelhouse . + - task: PublishBuildArtifacts@1 + inputs: {pathtoPublish: 'wheelhouse'} +``` + +## Travis CI [linux/mac] + +To build Linux and Mac wheels on Travis CI, create a `.travis.yml` file in your repo. + +```yaml +language: python + +matrix: + include: + - sudo: required + services: + - docker + env: PIP=pip + - os: osx + language: generic + env: PIP=pip2 + +script: + - $PIP install cibuildwheel==0.12.0 + - cibuildwheel --output-dir wheelhouse +``` + +Then setup a deployment method by following the [Travis CI deployment docs](https://docs.travis-ci.com/user/deployment/), or see [Delivering to PyPI](#delivering-to-pypi) below. + +## CircleCI [linux/mac] + +To build Linux and Mac wheels on CircleCI, create a `.circleci/config.yml` file in your repo, + +```yaml +version: 2 + +jobs: + linux-wheels: + working_directory: ~/linux-wheels + docker: + - image: circleci/python:3.6 + steps: + - checkout + - setup_remote_docker + - run: + name: Build the Linux wheels. + command: | + pip install --user cibuildwheel + cibuildwheel --output-dir wheelhouse + - store_artifacts: + path: wheelhouse/ + + osx-wheels: + working_directory: ~/osx-wheels + macos: + xcode: "10.0.0" + steps: + - checkout + - run: + name: Build the OS X wheels. + command: | + pip install --user cibuildwheel + cibuildwheel --output-dir wheelhouse + - store_artifacts: + path: wheelhouse/ + +workflows: + version: 2 + all-tests: + jobs: + - linux-wheels + - osx-wheels +``` + +Note: CircleCI doesn't enable free macOS containers for open source by default, but you can ask for access. See [here](https://circleci.com/docs/2.0/oss/#overview) for more information. + +CircleCI will store the built wheels for you - you can access them from the project console. + +## AppVeyor [windows] + +To build Windows wheels on AppVeyor, create an `appveyor.yml` file in your repo. + +```yaml +build_script: + - pip install cibuildwheel==0.12.0 + - cibuildwheel --output-dir wheelhouse +artifacts: + - path: "wheelhouse\\*.whl" + name: Wheels +``` + +AppVeyor will store the built wheels for you - you can access them from the project console. Alternatively, you may want to store them in the same place as the Travis CI build. See [AppVeyor deployment docs](https://www.appveyor.com/docs/deployment/) for more info, or see [Delivering to PyPI](#delivering-to-pypi) below. + +Commit those files, enable building of your repo on Travis CI and AppVeyor, and push. + +All being well, you should get wheels delivered to you in a few minutes. + +> ⚠️ Got an error? Check the [checklist](#it-didnt-work) below. diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 00000000..5d5bb2fb --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,10 @@ +site_name: cibuildwheel +docs_dir: docs +theme: readthedocs +nav: + - Home: index.md + - "Setup guide": setup.md + - "Options": options.md +markdown_extensions: +- codehilite +- fenced_code \ No newline at end of file From c006fdab36780119945992cbe81ab93eb6575691 Mon Sep 17 00:00:00 2001 From: Joe Rickerby Date: Wed, 2 Oct 2019 09:49:31 +0100 Subject: [PATCH 03/30] Migrate more README over to the docs --- README.md | 317 ++++------------------------------------ docs/changelog.md | 174 ++++++++++++++++++++++ docs/contributing.md | 21 +++ docs/deliver-to-pypi.md | 35 +++++ docs/faq.md | 23 +++ docs/index.md | 37 +---- docs/options.md | 64 ++++---- docs/setup.md | 3 +- mkdocs.yml | 13 +- 9 files changed, 327 insertions(+), 360 deletions(-) create mode 100644 docs/changelog.md create mode 100644 docs/contributing.md create mode 100644 docs/deliver-to-pypi.md create mode 100644 docs/faq.md diff --git a/README.md b/README.md index c4c93c99..88052821 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ cibuildwheel ============ -[![PyPI](https://img.shields.io/pypi/v/cibuildwheel.svg)](https://pypi.python.org/pypi/cibuildwheel) [![Build Status](https://travis-ci.org/joerick/cibuildwheel.svg?branch=master)](https://travis-ci.org/joerick/cibuildwheel) [![Build status](https://ci.appveyor.com/api/projects/status/wbsgxshp05tt1tif/branch/master?svg=true)](https://ci.appveyor.com/project/joerick/cibuildwheel/branch/master) [![CircleCI](https://circleci.com/gh/joerick/cibuildwheel.svg?style=svg)](https://circleci.com/gh/joerick/cibuildwheel) +[Documentation](cibuildwheel.readthedocs.org) [![PyPI](https://img.shields.io/pypi/v/cibuildwheel.svg)](https://pypi.python.org/pypi/cibuildwheel) [![Build Status](https://travis-ci.org/joerick/cibuildwheel.svg?branch=master)](https://travis-ci.org/joerick/cibuildwheel) [![Build status](https://ci.appveyor.com/api/projects/status/wbsgxshp05tt1tif/branch/master?svg=true)](https://ci.appveyor.com/project/joerick/cibuildwheel/branch/master) [![CircleCI](https://circleci.com/gh/joerick/cibuildwheel.svg?style=svg)](https://circleci.com/gh/joerick/cibuildwheel) Python wheels are great. Building them across **Mac, Linux, Windows**, on **multiple versions of Python**, is not. @@ -40,107 +40,39 @@ Usage `cibuildwheel` is not intended to run on your development machine. It will try to install packages globally; this is no good. Travis CI, CircleCI, and AppVeyor run their builds in isolated environments, so are ideal for this kind of script. +Example setup +------------- -### Linux builds on Docker +To build manylinux and macOS wheels on Travis CI, and upload them to PyPI whenever you tag a version, you could use this `.travis.yml`: -Linux wheels are built in the [`manylinux1` docker images](https://github.com/pypa/manylinux) to provide binary compatible wheels on Linux, according to [PEP 513](https://www.python.org/dev/peps/pep-0513/). Because of this, when building with `cibuildwheel` on Linux, a few things should be taken into account: -- Programs and libraries cannot be installed on the Travis CI Ubuntu host with `apt-get`, but can be installed inside of the Docker image using `yum` or manually. The same goes for environment variables that are potentially needed to customize the wheel building. `cibuildwheel` supports this by providing the `CIBW_ENVIRONMENT` and `CIBW_BEFORE_BUILD` options to setup the build environment inside the running Docker image. See [below](#options) for details on these options. -- The project directory is mounted in the running Docker instance as `/project`, the output directory for the wheels as `/output`. In general, this is handled transparently by `cibuildwheel`. For a more finegrained level of control however, the root of the host file system is mounted as `/host`, allowing for example to access shared files, caches, etc. on the host file system. Note that this is not available on CircleCI due to their Docker policies. -- Alternative dockers images can be specified with the `CIBW_MANYLINUX1_X86_64_IMAGE` and `CIBW_MANYLINUX1_I686_IMAGE` options to allow for a custom, preconfigured build environment for the Linux builds. See [below](#options) for more details. +```yaml +language: python +matrix: + include: + - sudo: required + services: + - docker + env: PIP=pip + - os: osx + language: generic + env: PIP=pip2 -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. - -``` - -### Example YML syntax - -
- - -
example .travis.yml environment variables
env:
+env:
   global:
-    - CIBW_TEST_REQUIRES=nose
-    - CIBW_TEST_COMMAND="nosetests {project}/tests"
-
example appveyor.yml environment variables
environment:
-  global:
-    CIBW_TEST_REQUIRES: nose
-    CIBW_TEST_COMMAND: "nosetests {project}\\tests"
-
+ - TWINE_USERNAME=joerick + # Note: TWINE_PASSWORD is set in Travis settings -Delivering to PyPI ------------------- - -After you've built your wheels, you'll probably want to deliver them to PyPI. - -### Manual method - -On your development machine, do the following... - -```bash -# Clear out your 'dist' folder. -rm -rf dist -# Make a source distribution -python setup.py sdist - -# 🏃🏻 -# Go and download your wheel files from wherever you put them. Put -# them all into the 'dist' folder. - -# Upload using 'twine' (you may need to 'pip install twine') -twine upload dist/* +script: + - $PIP install cibuildwheel==0.12.0 + - cibuildwheel --output-dir wheelhouse + - | + if [[ $TRAVIS_TAG ]]; then + python -m pip install twine + python -m twine upload wheelhouse/*.whl + fi ``` -### Semi-automatic method using wheelhouse-uploader - -Obviously, manual steps are for chumps, so we can automate this a little by using [wheelhouse-uploader](https://github.com/ogrisel/wheelhouse-uploader). - -> Quick note from me - using S3 as a storage didn't work due to a [bug](https://issues.apache.org/jira/browse/LIBCLOUD-792) in libcloud. Feel free to use my fork of that package that fixes the bug `pip install https://github.com/joerick/libcloud/archive/v1.5.0-s3fix.zip` - -### Automatic method - -If you don't need much control over the release of a package, you can set up cibuildwheel to deliver the wheels straight to PyPI. This doesn't require any cloud storage to work - you just need to bump the version and tag it. - -Check out [this example repo](https://github.com/joerick/cibuildwheel-autopypi-example) for instructions on how to set this up. - -It didn't work! ---------------- - -If your wheel didn't compile, check the list below for some debugging tips. - -- A mistake in your config. To quickly test your config without doing a git push and waiting for your code to build on CI, you can run the Linux build in a Docker container. On Mac or Linux, with Docker running, try `cibuildwheel --platform linux`. You'll have to bring your config into the current environment first. -- Missing dependency. You might need to install something on the build machine. You can do this in `.travis.yml`, `appveyor.yml`, or `.circleci/config.yml`, with apt-get, brew or whatever Windows uses :P . Given how the Linux build works, we'll probably have to build something into `cibuildwheel`. Let's chat about that over in the issues! -- Windows: missing C feature. The Windows C compiler doesn't support C language features invented after 1990, so you'll have to backport your C code to C90. For me, this mostly involved putting my variable declarations at the top of the function like an animal. -- MacOS: calling cibuildwheel from a python3 script and getting a `ModuleNotFoundError`? Due to a [bug](https://bugs.python.org/issue22490) in CPython, you'll need to [unset the `__PYVENV_LAUNCHER__` variable](https://github.com/joerick/cibuildwheel/issues/133#issuecomment-478288597) before activating a venv. - Working examples ---------------- @@ -168,203 +100,6 @@ It helps ensure that the library can run without any dependencies outside of the This is similar to static linking, so it might have some licence implications. Check the license for any code you're pulling in to make sure that's allowed. -Changelog -========= - -### 0.12.0 - -_29 September 2019_ - -- ✨ Add CIBW_TEST_EXTRAS option, to allow testing using extra_require - options. For example, set `CIBW_TEST_EXTRAS=test,qt` to make the wheel - installed with `pip install [test,qt]` -- 🛠 Update Python from 3.7.2 to 3.7.4 on macOS -- 🛠 Update OpenSSL patch to 1.0.2t on macOS - -### 0.11.1 - -_28 May 2019_ - -- 🐛 Fix missing file in the release tarball, that was causing problems with - Windows builds (#141) - -### 0.11.0 - -_26 May 2019_ - -- ✨ Add support for building on Azure pipelines! This lets you build all - Linux, Mac and Windows wheels on one service, so it promises to be the - easiest to set up! Check out the quickstart in the docs, or - [cibuildwheel-azure-example](https://github.com/joerick/cibuildwheel-azure-example) - for an example project. (#126, #132) -- 🛠 Internal change - the end-to-end test projects format was updated, so we - can more precisely assert what should be produced for each one. (#136, #137). - -### 0.10.2 - -_10 March 2019_ - -- 🛠 Revert temporary fix in macOS, that was working around a bug in pip 19 (#129) -- 🛠 Update Python to 2.7.16 on macOS -- 🛠 Update OpenSSL patch to 1.0.2r on macOS - -### 0.10.1 - -_3 February 2019_ - -- 🐛 Fix build stalling on macOS (that was introduced in pip 19) (#122) -- 🐛 Fix "AttributeError: 'Popen' object has no attribute 'args'" on Python 2.7 for Linux builds (#108) -- 🛠 Update Python from 3.6.7, 3.7.1 to 3.6.8, 3.7.2 on macOS -- 🛠 Update openssl patch from 1.0.2p to 1.0.2q on macOS -- 🛠 Sorting build options dict items when printing preamble (#114) - -### 0.10.0 - -_23 September 2018_ - -- ✨ Add `CIBW_BUILD` option, for specifying which specific builds to perform (#101) -- ✨ Add support for building Mac and Linux on CircleCI (#91, #97) -- 🛠 Improved support for building universal wheels (#95) -- 🛠 Ensure log output is unbuffered and therefore in the correct order (#92) -- 🛠 Improved error reporting for errors that occur inside a package's setup.py (#88) -- ⚠️ Removed support for Python 3.3 on Windows. - -### 0.9.4 - -_29 July 2018_ - -- 🛠 CIBW_TEST_COMMAND now runs in a shell on Mac (as well as Linux) (#81) - -### 0.9.3 - -_10 July 2018_ - -- 🛠 Update to Python 3.6.6 on macOS (#82) -- ✨ Add support for building Python 3.7 wheels on Windows (#76) -- ⚠️ Deprecated support for Python 3.3 on Windows. - -### 0.9.2 - -_1 July 2018_ - -- 🛠 Update Python 3.7.0rc1 to 3.7.0 on macOS (#79) - -### 0.9.1 - -_18 June 2018_ - -- 🛠 Removed the need to use `{python}` and `{pip}` in `CIBW_BEFORE_BUILD` statements, by ensuring the correct version is always on the path at `python` and `pip` instead. (#60) -- 🛠 We now patch the _ssl module on Python 3.4 and 3.5 so these versions can still make SSL web requests using TLS 1.2 while building. (#71) - -### 0.9.0 - -_18 June 2018_ - -- ✨ Add support for Python 3.7 (#73) - -### 0.8.0 - -_4 May 2018_ - -- ⚠️ Drop support for Python 3.3 on Linux (#67) -- 🐛 Fix TLS by updating setuptools (#69) - -### 0.7.1 - -_2 April 2017_ - -- 🐛 macOS: Fix Pip bugs resulting from PyPI TLS 1.2 enforcement -- 🐛 macOS: Fix brew Python3 version problems in the CI - -### 0.7.0 - -_7 January 2018_ - -- ✨ You can now specify a custom docker image using the `CIBW_MANYLINUX1_X86_64_IMAGE` and `CIBW_MANYLINUX1_I686_IMAGE` options. (#46) -- 🐛 Fixed a bug where cibuildwheel would download and build a package from PyPI(!) instead of building the package on the local machine. (#51) - -### 0.6.0 - -_9 October 2017_ - -- ✨ On the Linux build, the host filesystem is now accessible via `/host` (#36) -- 🐛 Fixed a bug where setup.py scripts would run the wrong version of Python when running subprocesses on Linux (#35) - -### 0.5.1 - -_10 September 2017_ - -- 🐛 Fixed a couple of bugs on Python 3. -- ✨ Added experimental support for Mac builds on [Bitrise.io](https://www.bitrise.io) - -### 0.5.0 - -_7 September 2017_ - -- ✨ `CIBW_ENVIRONMENT` added. You can now set environment variables for each build, even within the Docker container on Linux. This is a big one! (#21) -- ✨ `CIBW_BEFORE_BUILD` now runs in a system shell on all platforms. You can now do things like `CIBW_BEFORE_BUILD="cmd1 && cmd2"`. (#32) - -### 0.4.1 - -_14 August 2017_ - -- 🐛 Fixed a bug on Windows where subprocess' output was hidden (#23) -- 🐛 Fixed a bug on AppVeyor where logs would appear in the wrong order due to output buffering (#24, thanks @YannickJadoul!) - -### 0.4.0 - -_23 July 2017_ - -- 🐛 Fixed a bug that was increasing the build time by building the wheel twice. This was a problem for large projects that have a long build time. If you're upgrading and you need the old behaviour, use `CIBW_BEFORE_BUILD={pip} install .`, or install exactly the dependencies you need in `CIBW_BEFORE_BUILD`. See #18. - -### 0.3.0 - -_27 June 2017_ - -- ⚠️ Removed Python 2.6 support on Linux (#12) - -### 0.2.1 - -_11 June 2017_ - -- 🛠 Changed the build process to install the package before building the wheel - this allows direct dependencies to be installed first (#9, thanks @tgarc!) -- ✨ Added Python 3 support for the main process, for systems where Python 3 is the default (#8, thanks @tgarc). - -### 0.2.0 - -_13 April 2017_ - -- ✨ Added `CIBW_SKIP` option, letting users explicitly skip a build -- ✨ Added `CIBW_BEFORE_BUILD` option, letting users run a shell command before the build starts - -### 0.1.3 - -_31 March 2017_ - -- 🌟 First public release! - -Contributing -============ - -Wheel-building is pretty complex. I expect users to find many edge-cases - please help the rest of the community out by documenting these, adding features to support them, and reporting bugs. - -I plan to be pretty liberal in accepting pull requests, as long as they align with the design goals below. - -`cibuildwheel` is indie open source. I'm not paid to work on this. - -Design Goals ------------- - -- `cibuildwheel` should wrap the complexity of wheel building. -- The user interface to `cibuildwheel` is the build script (e.g. `.travis.yml`). Feature additions should not increase the complexity of this script. -- Options should be environment variables (these lend themselves better to YML config files). They should be prefixed with `CIBW_`. -- Options should be generalise to all platforms. If platform-specific options are required, they should be namespaced e.g. `CIBW_TEST_COMMAND_MACOS` - -Other notes: - -- The platforms are very similar, until they're not. I'd rather have straight-forward code than totally DRY code, so let's keep airy platfrom abstractions to a minimum. -- I might want to break the options into a shared config file one day, so that config is more easily shared. That has motivated some of the design decisions. - Maintainers ----------- diff --git a/docs/changelog.md b/docs/changelog.md new file mode 100644 index 00000000..a09072e5 --- /dev/null +++ b/docs/changelog.md @@ -0,0 +1,174 @@ +Changelog +========= + +### 0.12.0 + +_29 September 2019_ + +- ✨ Add CIBW_TEST_EXTRAS option, to allow testing using extra_require + options. For example, set `CIBW_TEST_EXTRAS=test,qt` to make the wheel + installed with `pip install [test,qt]` +- 🛠 Update Python from 3.7.2 to 3.7.4 on macOS +- 🛠 Update OpenSSL patch to 1.0.2t on macOS + +### 0.11.1 + +_28 May 2019_ + +- 🐛 Fix missing file in the release tarball, that was causing problems with + Windows builds (#141) + +### 0.11.0 + +_26 May 2019_ + +- ✨ Add support for building on Azure pipelines! This lets you build all + Linux, Mac and Windows wheels on one service, so it promises to be the + easiest to set up! Check out the quickstart in the docs, or + [cibuildwheel-azure-example](https://github.com/joerick/cibuildwheel-azure-example) + for an example project. (#126, #132) +- 🛠 Internal change - the end-to-end test projects format was updated, so we + can more precisely assert what should be produced for each one. (#136, #137). + +### 0.10.2 + +_10 March 2019_ + +- 🛠 Revert temporary fix in macOS, that was working around a bug in pip 19 (#129) +- 🛠 Update Python to 2.7.16 on macOS +- 🛠 Update OpenSSL patch to 1.0.2r on macOS + +### 0.10.1 + +_3 February 2019_ + +- 🐛 Fix build stalling on macOS (that was introduced in pip 19) (#122) +- 🐛 Fix "AttributeError: 'Popen' object has no attribute 'args'" on Python 2.7 for Linux builds (#108) +- 🛠 Update Python from 3.6.7, 3.7.1 to 3.6.8, 3.7.2 on macOS +- 🛠 Update openssl patch from 1.0.2p to 1.0.2q on macOS +- 🛠 Sorting build options dict items when printing preamble (#114) + +### 0.10.0 + +_23 September 2018_ + +- ✨ Add `CIBW_BUILD` option, for specifying which specific builds to perform (#101) +- ✨ Add support for building Mac and Linux on CircleCI (#91, #97) +- 🛠 Improved support for building universal wheels (#95) +- 🛠 Ensure log output is unbuffered and therefore in the correct order (#92) +- 🛠 Improved error reporting for errors that occur inside a package's setup.py (#88) +- ⚠️ Removed support for Python 3.3 on Windows. + +### 0.9.4 + +_29 July 2018_ + +- 🛠 CIBW_TEST_COMMAND now runs in a shell on Mac (as well as Linux) (#81) + +### 0.9.3 + +_10 July 2018_ + +- 🛠 Update to Python 3.6.6 on macOS (#82) +- ✨ Add support for building Python 3.7 wheels on Windows (#76) +- ⚠️ Deprecated support for Python 3.3 on Windows. + +### 0.9.2 + +_1 July 2018_ + +- 🛠 Update Python 3.7.0rc1 to 3.7.0 on macOS (#79) + +### 0.9.1 + +_18 June 2018_ + +- 🛠 Removed the need to use `{python}` and `{pip}` in `CIBW_BEFORE_BUILD` statements, by ensuring the correct version is always on the path at `python` and `pip` instead. (#60) +- 🛠 We now patch the _ssl module on Python 3.4 and 3.5 so these versions can still make SSL web requests using TLS 1.2 while building. (#71) + +### 0.9.0 + +_18 June 2018_ + +- ✨ Add support for Python 3.7 (#73) + +### 0.8.0 + +_4 May 2018_ + +- ⚠️ Drop support for Python 3.3 on Linux (#67) +- 🐛 Fix TLS by updating setuptools (#69) + +### 0.7.1 + +_2 April 2017_ + +- 🐛 macOS: Fix Pip bugs resulting from PyPI TLS 1.2 enforcement +- 🐛 macOS: Fix brew Python3 version problems in the CI + +### 0.7.0 + +_7 January 2018_ + +- ✨ You can now specify a custom docker image using the `CIBW_MANYLINUX1_X86_64_IMAGE` and `CIBW_MANYLINUX1_I686_IMAGE` options. (#46) +- 🐛 Fixed a bug where cibuildwheel would download and build a package from PyPI(!) instead of building the package on the local machine. (#51) + +### 0.6.0 + +_9 October 2017_ + +- ✨ On the Linux build, the host filesystem is now accessible via `/host` (#36) +- 🐛 Fixed a bug where setup.py scripts would run the wrong version of Python when running subprocesses on Linux (#35) + +### 0.5.1 + +_10 September 2017_ + +- 🐛 Fixed a couple of bugs on Python 3. +- ✨ Added experimental support for Mac builds on [Bitrise.io](https://www.bitrise.io) + +### 0.5.0 + +_7 September 2017_ + +- ✨ `CIBW_ENVIRONMENT` added. You can now set environment variables for each build, even within the Docker container on Linux. This is a big one! (#21) +- ✨ `CIBW_BEFORE_BUILD` now runs in a system shell on all platforms. You can now do things like `CIBW_BEFORE_BUILD="cmd1 && cmd2"`. (#32) + +### 0.4.1 + +_14 August 2017_ + +- 🐛 Fixed a bug on Windows where subprocess' output was hidden (#23) +- 🐛 Fixed a bug on AppVeyor where logs would appear in the wrong order due to output buffering (#24, thanks @YannickJadoul!) + +### 0.4.0 + +_23 July 2017_ + +- 🐛 Fixed a bug that was increasing the build time by building the wheel twice. This was a problem for large projects that have a long build time. If you're upgrading and you need the old behaviour, use `CIBW_BEFORE_BUILD={pip} install .`, or install exactly the dependencies you need in `CIBW_BEFORE_BUILD`. See #18. + +### 0.3.0 + +_27 June 2017_ + +- ⚠️ Removed Python 2.6 support on Linux (#12) + +### 0.2.1 + +_11 June 2017_ + +- 🛠 Changed the build process to install the package before building the wheel - this allows direct dependencies to be installed first (#9, thanks @tgarc!) +- ✨ Added Python 3 support for the main process, for systems where Python 3 is the default (#8, thanks @tgarc). + +### 0.2.0 + +_13 April 2017_ + +- ✨ Added `CIBW_SKIP` option, letting users explicitly skip a build +- ✨ Added `CIBW_BEFORE_BUILD` option, letting users run a shell command before the build starts + +### 0.1.3 + +_31 March 2017_ + +- 🌟 First public release! diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 00000000..ce13a3a0 --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,21 @@ +Contributing +============ + +Wheel-building is pretty complex. I expect users to find many edge-cases - please help the rest of the community out by documenting these, adding features to support them, and reporting bugs. + +I plan to be pretty liberal in accepting pull requests, as long as they align with the design goals below. + +`cibuildwheel` is indie open source. I'm not paid to work on this. + +Design Goals +------------ + +- `cibuildwheel` should wrap the complexity of wheel building. +- The user interface to `cibuildwheel` is the build script (e.g. `.travis.yml`). Feature additions should not increase the complexity of this script. +- Options should be environment variables (these lend themselves better to YML config files). They should be prefixed with `CIBW_`. +- Options should be generalise to all platforms. If platform-specific options are required, they should be namespaced e.g. `CIBW_TEST_COMMAND_MACOS` + +Other notes: + +- The platforms are very similar, until they're not. I'd rather have straight-forward code than totally DRY code, so let's keep airy platfrom abstractions to a minimum. +- I might want to break the options into a shared config file one day, so that config is more easily shared. That has motivated some of the design decisions. diff --git a/docs/deliver-to-pypi.md b/docs/deliver-to-pypi.md new file mode 100644 index 00000000..7c184231 --- /dev/null +++ b/docs/deliver-to-pypi.md @@ -0,0 +1,35 @@ +--- +title: Deliver to PyPI +--- + +After you've built your wheels, you'll probably want to deliver them to PyPI. + +### Manual method + +On your development machine, do the following... + +```bash +# Clear out your 'dist' folder. +rm -rf dist +# Make a source distribution +python setup.py sdist + +# 🏃🏻 +# Go and download your wheel files from wherever you put them. Put +# them all into the 'dist' folder. + +# Upload using 'twine' (you may need to 'pip install twine') +twine upload dist/* +``` + +### Semi-automatic method using wheelhouse-uploader + +Obviously, manual steps are for chumps, so we can automate this a little by using [wheelhouse-uploader](https://github.com/ogrisel/wheelhouse-uploader). + +> Quick note from me - using S3 as a storage didn't work due to a [bug](https://issues.apache.org/jira/browse/LIBCLOUD-792) in libcloud. Feel free to use my fork of that package that fixes the bug `pip install https://github.com/joerick/libcloud/archive/v1.5.0-s3fix.zip` + +### Automatic method + +If you don't need much control over the release of a package, you can set up cibuildwheel to deliver the wheels straight to PyPI. This doesn't require any cloud storage to work - you just need to bump the version and tag it. + +Check out [this example repo](https://github.com/joerick/cibuildwheel-autopypi-example) for instructions on how to set this up. diff --git a/docs/faq.md b/docs/faq.md new file mode 100644 index 00000000..fe6731fb --- /dev/null +++ b/docs/faq.md @@ -0,0 +1,23 @@ +--- +title: It didn't work! +--- + +If your wheel didn't compile, check the list below for some debugging tips. + +- A mistake in your config. To quickly test your config without doing a git push and waiting for your code to build on CI, you can test the Linux build in a Docker container. On Mac or Linux, with Docker running, try `cibuildwheel --platform linux`. You'll have to bring your config into the current environment first. + +- Missing dependency. You might need to install something on the build machine. You can do this in `.travis.yml`, `appveyor.yml`, or `.circleci/config.yml`, with apt-get, brew or whatever Windows uses :P . Given how the Linux build works, we'll probably have to build something into `cibuildwheel`. Let's chat about that over in the issues! + +- Windows: missing C feature. The Windows C compiler doesn't support C language features invented after 1990, so you'll have to backport your C code to C90. For me, this mostly involved putting my variable declarations at the top of the function like an animal. + +- MacOS: calling cibuildwheel from a python3 script and getting a `ModuleNotFoundError`? Due to a [bug](https://bugs.python.org/issue22490) in CPython, you'll need to [unset the `__PYVENV_LAUNCHER__` variable](https://github.com/joerick/cibuildwheel/issues/133#issuecomment-478288597) before activating a venv. + +### Linux builds on Docker + +Linux wheels are built in the [`manylinux1` docker images](https://github.com/pypa/manylinux) to provide binary compatible wheels on Linux, according to [PEP 513](https://www.python.org/dev/peps/pep-0513/). Because of this, when building with `cibuildwheel` on Linux, a few things should be taken into account: + +- Programs and libraries cannot be installed on the Travis CI Ubuntu host with `apt-get`, but can be installed inside of the Docker image using `yum` or manually. The same goes for environment variables that are potentially needed to customize the wheel building. `cibuildwheel` supports this by providing the `CIBW_ENVIRONMENT` and `CIBW_BEFORE_BUILD` options to setup the build environment inside the running Docker image. See [below](options.md#build-environment) for details on these options. + +- The project directory is mounted in the running Docker instance as `/project`, the output directory for the wheels as `/output`. In general, this is handled transparently by `cibuildwheel`. For a more finegrained level of control however, the root of the host file system is mounted as `/host`, allowing for example to access shared files, caches, etc. on the host file system. Note that this is not available on CircleCI due to their Docker policies. + +- Alternative dockers images can be specified with the `CIBW_MANYLINUX1_X86_64_IMAGE` and `CIBW_MANYLINUX1_I686_IMAGE` options to allow for a custom, preconfigured build environment for the Linux builds. See [options](options.md#manylinux-image) for more details. diff --git a/docs/index.md b/docs/index.md index 01e0d0cd..ff963eb8 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,39 +1,6 @@ Home ==== -Python wheels are great. Building them across **Mac, Linux, Windows**, on **multiple versions of Python**, is not. +Welcome to the cibuildwheel docs. -`cibuildwheel` is here to help. `cibuildwheel` runs on your CI server - currently it supports Azure Pipelines, Travis CI, AppVeyor, and CircleCI - and it builds and tests your wheels across all of your platforms. - -**`cibuildwheel` is in beta**. It's brand new - I'd love for you to try it and help make it better! - -What does it do? ----------------- - -| | macOS 10.6+ | manylinux i686 | manylinux x86_64 | Windows 32bit | Windows 64bit | -|---|---|---|---|---|---| -| Python 2.7 | ✅ | ✅ | ✅ | ✅ | ✅ | -| Python 3.4 | ✅ | ✅ | ✅ | ✅* | ✅* | -| Python 3.5 | ✅ | ✅ | ✅ | ✅ | ✅ | -| Python 3.6 | ✅ | ✅ | ✅ | ✅ | ✅ | -| Python 3.7 | ✅ | ✅ | ✅ | ✅ | ✅ | - -> \* Not supported on Azure Pipelines - -- Builds manylinux, macOS and Windows (32 and 64bit) wheels using Azure Pipelines, Travis CI, AppVeyor, and CircleCI -- Bundles shared library dependencies on Linux and macOS through [auditwheel](https://github.com/pypa/auditwheel) and [delocate](https://github.com/matthew-brett/delocate) -- Runs the library test suite against the wheel-installed version of your library - -Usage ------ - -`cibuildwheel` currently works **Travis CI** and **CircleCI** to build Linux and Mac wheels, and **AppVeyor** to build Windows wheels. **Azure Pipelines** supports all three. - -| | Linux | macOS | Windows | -|-----------------|-------|-------|---------| -| Azure Pipelines | ✅ | ✅ | ✅ | -| Travis CI | ✅ | ✅ | | -| AppVeyor | | | ✅ | -| CircleCI | ✅ | ✅ | | - -`cibuildwheel` is not intended to run on your development machine. It will try to install packages globally; this is no good. Travis CI, CircleCI, and AppVeyor run their builds in isolated environments, so are ideal for this kind of script. +To get started, head over to the [setup guide](setup.md). diff --git a/docs/options.md b/docs/options.md index 6174e1b9..12814d01 100644 --- a/docs/options.md +++ b/docs/options.md @@ -1,26 +1,28 @@ -## Options summary +cibuildwheel is configured using environment variables, that can be set using +your CI config. -`cibuildwheel` allows for easy customization of the various phases of the build process demonstrated above: + + + + +
example .travis.yml environment variables
env:
+  global:
+    - CIBW_TEST_REQUIRES=nose
+    - CIBW_TEST_COMMAND="nosetests {project}/tests"
+
example appveyor.yml environment variables
environment:
+  global:
+    CIBW_TEST_REQUIRES: nose
+    CIBW_TEST_COMMAND: "nosetests {project}\\tests"
+
example .circleci/config.yml environment variables
jobs:
+  job_name:
+    environment:
+      CIBW_TEST_REQUIRES: nose
+      CIBW_TEST_COMMAND: "nosetests {project}\\tests"
+
-| | 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``| +## 🚩Build selection -Most of the config is via environment variables. These go into `.travis.yml`, `appveyor.yml`, and `.circleci/config.yml` nicely. - -## Build selection - -### CIBW_PLATFORM +### CIBW_PLATFORM - Override the auto-detected target platform {: #platform} Options: `auto` `linux` `macos` `windows` @@ -30,7 +32,7 @@ Default: `auto` 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 +### CIBW_BUILD, CIBW_SKIP - Choose the Python versions to build {: #build-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. @@ -55,9 +57,9 @@ Examples: - 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 +## 🌎 Build environment -### CIBW_ENVIRONMENT +### CIBW_ENVIRONMENT - Set environment variables needed during the build {: #environment} A space-separated list of environment variables to set during the build. Bash syntax should be used (even on Windows!). @@ -75,7 +77,7 @@ Platform-specific variants also available: 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 +### CIBW_BEFORE_BUILD - Execute a shell command preparing each wheel's build {: #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. @@ -90,7 +92,7 @@ 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 +### CIBW_MANYLINUX1_X86_64_IMAGE, CIBW_MANYLINUX1_I686_IMAGE - Specify alternative manylinux1 x86_64 docker images {: #manylinux-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). @@ -99,9 +101,9 @@ Beware to specify a valid docker image that can be used the same as the official Example: `dockcross/manylinux-x64` Example: `dockcross/manylinux-x86` -## Testing +## 🔬 Testing -### CIBW_TEST_COMMAND +### CIBW_TEST_COMMAND - Execute a shell command to test all built wheels {: #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`. @@ -112,7 +114,7 @@ Example: `nosetests {project}/tests` Platform-specific variants also available: `CIBW_TEST_COMMAND_MACOS` | `CIBW_TEST_COMMAND_WINDOWS` | `CIBW_TEST_COMMAND_LINUX` -### CIBW_TEST_REQUIRES +### CIBW_TEST_REQUIRES - Install Python dependencies before running the tests {: #test-requires} Space-separated list of dependencies required for running the tests. @@ -122,7 +124,7 @@ 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 +### CIBW_TEST_EXTRAS - Install your wheel for testing using `extras_require` {: #test-extras} Comma-separated list of [extras_require](https://setuptools.readthedocs.io/en/latest/setuptools.html#declaring-extras-optional-features-with-their-own-dependencies) @@ -137,9 +139,9 @@ Example: `test,qt` (will cause the wheel to be installed with `pip install Date: Sun, 6 Oct 2019 11:38:24 +0100 Subject: [PATCH 04/30] Move changelog back into the readme --- README.md | 175 ++++++++++++++++++++++++++++++++++++++++++++++ docs/changelog.md | 174 --------------------------------------------- mkdocs.yml | 1 - 3 files changed, 175 insertions(+), 175 deletions(-) delete mode 100644 docs/changelog.md diff --git a/README.md b/README.md index 88052821..1e025c06 100644 --- a/README.md +++ b/README.md @@ -100,6 +100,181 @@ It helps ensure that the library can run without any dependencies outside of the This is similar to static linking, so it might have some licence implications. Check the license for any code you're pulling in to make sure that's allowed. +Changelog +========= + +### 0.12.0 + +_29 September 2019_ + +- ✨ Add CIBW_TEST_EXTRAS option, to allow testing using extra_require + options. For example, set `CIBW_TEST_EXTRAS=test,qt` to make the wheel + installed with `pip install [test,qt]` +- 🛠 Update Python from 3.7.2 to 3.7.4 on macOS +- 🛠 Update OpenSSL patch to 1.0.2t on macOS + +### 0.11.1 + +_28 May 2019_ + +- 🐛 Fix missing file in the release tarball, that was causing problems with + Windows builds (#141) + +### 0.11.0 + +_26 May 2019_ + +- ✨ Add support for building on Azure pipelines! This lets you build all + Linux, Mac and Windows wheels on one service, so it promises to be the + easiest to set up! Check out the quickstart in the docs, or + [cibuildwheel-azure-example](https://github.com/joerick/cibuildwheel-azure-example) + for an example project. (#126, #132) +- 🛠 Internal change - the end-to-end test projects format was updated, so we + can more precisely assert what should be produced for each one. (#136, #137). + +### 0.10.2 + +_10 March 2019_ + +- 🛠 Revert temporary fix in macOS, that was working around a bug in pip 19 (#129) +- 🛠 Update Python to 2.7.16 on macOS +- 🛠 Update OpenSSL patch to 1.0.2r on macOS + +### 0.10.1 + +_3 February 2019_ + +- 🐛 Fix build stalling on macOS (that was introduced in pip 19) (#122) +- 🐛 Fix "AttributeError: 'Popen' object has no attribute 'args'" on Python 2.7 for Linux builds (#108) +- 🛠 Update Python from 3.6.7, 3.7.1 to 3.6.8, 3.7.2 on macOS +- 🛠 Update openssl patch from 1.0.2p to 1.0.2q on macOS +- 🛠 Sorting build options dict items when printing preamble (#114) + +### 0.10.0 + +_23 September 2018_ + +- ✨ Add `CIBW_BUILD` option, for specifying which specific builds to perform (#101) +- ✨ Add support for building Mac and Linux on CircleCI (#91, #97) +- 🛠 Improved support for building universal wheels (#95) +- 🛠 Ensure log output is unbuffered and therefore in the correct order (#92) +- 🛠 Improved error reporting for errors that occur inside a package's setup.py (#88) +- ⚠️ Removed support for Python 3.3 on Windows. + +### 0.9.4 + +_29 July 2018_ + +- 🛠 CIBW_TEST_COMMAND now runs in a shell on Mac (as well as Linux) (#81) + +### 0.9.3 + +_10 July 2018_ + +- 🛠 Update to Python 3.6.6 on macOS (#82) +- ✨ Add support for building Python 3.7 wheels on Windows (#76) +- ⚠️ Deprecated support for Python 3.3 on Windows. + +### 0.9.2 + +_1 July 2018_ + +- 🛠 Update Python 3.7.0rc1 to 3.7.0 on macOS (#79) + +### 0.9.1 + +_18 June 2018_ + +- 🛠 Removed the need to use `{python}` and `{pip}` in `CIBW_BEFORE_BUILD` statements, by ensuring the correct version is always on the path at `python` and `pip` instead. (#60) +- 🛠 We now patch the _ssl module on Python 3.4 and 3.5 so these versions can still make SSL web requests using TLS 1.2 while building. (#71) + +### 0.9.0 + +_18 June 2018_ + +- ✨ Add support for Python 3.7 (#73) + +### 0.8.0 + +_4 May 2018_ + +- ⚠️ Drop support for Python 3.3 on Linux (#67) +- 🐛 Fix TLS by updating setuptools (#69) + +### 0.7.1 + +_2 April 2017_ + +- 🐛 macOS: Fix Pip bugs resulting from PyPI TLS 1.2 enforcement +- 🐛 macOS: Fix brew Python3 version problems in the CI + +### 0.7.0 + +_7 January 2018_ + +- ✨ You can now specify a custom docker image using the `CIBW_MANYLINUX1_X86_64_IMAGE` and `CIBW_MANYLINUX1_I686_IMAGE` options. (#46) +- 🐛 Fixed a bug where cibuildwheel would download and build a package from PyPI(!) instead of building the package on the local machine. (#51) + +### 0.6.0 + +_9 October 2017_ + +- ✨ On the Linux build, the host filesystem is now accessible via `/host` (#36) +- 🐛 Fixed a bug where setup.py scripts would run the wrong version of Python when running subprocesses on Linux (#35) + +### 0.5.1 + +_10 September 2017_ + +- 🐛 Fixed a couple of bugs on Python 3. +- ✨ Added experimental support for Mac builds on [Bitrise.io](https://www.bitrise.io) + +### 0.5.0 + +_7 September 2017_ + +- ✨ `CIBW_ENVIRONMENT` added. You can now set environment variables for each build, even within the Docker container on Linux. This is a big one! (#21) +- ✨ `CIBW_BEFORE_BUILD` now runs in a system shell on all platforms. You can now do things like `CIBW_BEFORE_BUILD="cmd1 && cmd2"`. (#32) + +### 0.4.1 + +_14 August 2017_ + +- 🐛 Fixed a bug on Windows where subprocess' output was hidden (#23) +- 🐛 Fixed a bug on AppVeyor where logs would appear in the wrong order due to output buffering (#24, thanks @YannickJadoul!) + +### 0.4.0 + +_23 July 2017_ + +- 🐛 Fixed a bug that was increasing the build time by building the wheel twice. This was a problem for large projects that have a long build time. If you're upgrading and you need the old behaviour, use `CIBW_BEFORE_BUILD={pip} install .`, or install exactly the dependencies you need in `CIBW_BEFORE_BUILD`. See #18. + +### 0.3.0 + +_27 June 2017_ + +- ⚠️ Removed Python 2.6 support on Linux (#12) + +### 0.2.1 + +_11 June 2017_ + +- 🛠 Changed the build process to install the package before building the wheel - this allows direct dependencies to be installed first (#9, thanks @tgarc!) +- ✨ Added Python 3 support for the main process, for systems where Python 3 is the default (#8, thanks @tgarc). + +### 0.2.0 + +_13 April 2017_ + +- ✨ Added `CIBW_SKIP` option, letting users explicitly skip a build +- ✨ Added `CIBW_BEFORE_BUILD` option, letting users run a shell command before the build starts + +### 0.1.3 + +_31 March 2017_ + +- 🌟 First public release! + Maintainers ----------- diff --git a/docs/changelog.md b/docs/changelog.md deleted file mode 100644 index a09072e5..00000000 --- a/docs/changelog.md +++ /dev/null @@ -1,174 +0,0 @@ -Changelog -========= - -### 0.12.0 - -_29 September 2019_ - -- ✨ Add CIBW_TEST_EXTRAS option, to allow testing using extra_require - options. For example, set `CIBW_TEST_EXTRAS=test,qt` to make the wheel - installed with `pip install [test,qt]` -- 🛠 Update Python from 3.7.2 to 3.7.4 on macOS -- 🛠 Update OpenSSL patch to 1.0.2t on macOS - -### 0.11.1 - -_28 May 2019_ - -- 🐛 Fix missing file in the release tarball, that was causing problems with - Windows builds (#141) - -### 0.11.0 - -_26 May 2019_ - -- ✨ Add support for building on Azure pipelines! This lets you build all - Linux, Mac and Windows wheels on one service, so it promises to be the - easiest to set up! Check out the quickstart in the docs, or - [cibuildwheel-azure-example](https://github.com/joerick/cibuildwheel-azure-example) - for an example project. (#126, #132) -- 🛠 Internal change - the end-to-end test projects format was updated, so we - can more precisely assert what should be produced for each one. (#136, #137). - -### 0.10.2 - -_10 March 2019_ - -- 🛠 Revert temporary fix in macOS, that was working around a bug in pip 19 (#129) -- 🛠 Update Python to 2.7.16 on macOS -- 🛠 Update OpenSSL patch to 1.0.2r on macOS - -### 0.10.1 - -_3 February 2019_ - -- 🐛 Fix build stalling on macOS (that was introduced in pip 19) (#122) -- 🐛 Fix "AttributeError: 'Popen' object has no attribute 'args'" on Python 2.7 for Linux builds (#108) -- 🛠 Update Python from 3.6.7, 3.7.1 to 3.6.8, 3.7.2 on macOS -- 🛠 Update openssl patch from 1.0.2p to 1.0.2q on macOS -- 🛠 Sorting build options dict items when printing preamble (#114) - -### 0.10.0 - -_23 September 2018_ - -- ✨ Add `CIBW_BUILD` option, for specifying which specific builds to perform (#101) -- ✨ Add support for building Mac and Linux on CircleCI (#91, #97) -- 🛠 Improved support for building universal wheels (#95) -- 🛠 Ensure log output is unbuffered and therefore in the correct order (#92) -- 🛠 Improved error reporting for errors that occur inside a package's setup.py (#88) -- ⚠️ Removed support for Python 3.3 on Windows. - -### 0.9.4 - -_29 July 2018_ - -- 🛠 CIBW_TEST_COMMAND now runs in a shell on Mac (as well as Linux) (#81) - -### 0.9.3 - -_10 July 2018_ - -- 🛠 Update to Python 3.6.6 on macOS (#82) -- ✨ Add support for building Python 3.7 wheels on Windows (#76) -- ⚠️ Deprecated support for Python 3.3 on Windows. - -### 0.9.2 - -_1 July 2018_ - -- 🛠 Update Python 3.7.0rc1 to 3.7.0 on macOS (#79) - -### 0.9.1 - -_18 June 2018_ - -- 🛠 Removed the need to use `{python}` and `{pip}` in `CIBW_BEFORE_BUILD` statements, by ensuring the correct version is always on the path at `python` and `pip` instead. (#60) -- 🛠 We now patch the _ssl module on Python 3.4 and 3.5 so these versions can still make SSL web requests using TLS 1.2 while building. (#71) - -### 0.9.0 - -_18 June 2018_ - -- ✨ Add support for Python 3.7 (#73) - -### 0.8.0 - -_4 May 2018_ - -- ⚠️ Drop support for Python 3.3 on Linux (#67) -- 🐛 Fix TLS by updating setuptools (#69) - -### 0.7.1 - -_2 April 2017_ - -- 🐛 macOS: Fix Pip bugs resulting from PyPI TLS 1.2 enforcement -- 🐛 macOS: Fix brew Python3 version problems in the CI - -### 0.7.0 - -_7 January 2018_ - -- ✨ You can now specify a custom docker image using the `CIBW_MANYLINUX1_X86_64_IMAGE` and `CIBW_MANYLINUX1_I686_IMAGE` options. (#46) -- 🐛 Fixed a bug where cibuildwheel would download and build a package from PyPI(!) instead of building the package on the local machine. (#51) - -### 0.6.0 - -_9 October 2017_ - -- ✨ On the Linux build, the host filesystem is now accessible via `/host` (#36) -- 🐛 Fixed a bug where setup.py scripts would run the wrong version of Python when running subprocesses on Linux (#35) - -### 0.5.1 - -_10 September 2017_ - -- 🐛 Fixed a couple of bugs on Python 3. -- ✨ Added experimental support for Mac builds on [Bitrise.io](https://www.bitrise.io) - -### 0.5.0 - -_7 September 2017_ - -- ✨ `CIBW_ENVIRONMENT` added. You can now set environment variables for each build, even within the Docker container on Linux. This is a big one! (#21) -- ✨ `CIBW_BEFORE_BUILD` now runs in a system shell on all platforms. You can now do things like `CIBW_BEFORE_BUILD="cmd1 && cmd2"`. (#32) - -### 0.4.1 - -_14 August 2017_ - -- 🐛 Fixed a bug on Windows where subprocess' output was hidden (#23) -- 🐛 Fixed a bug on AppVeyor where logs would appear in the wrong order due to output buffering (#24, thanks @YannickJadoul!) - -### 0.4.0 - -_23 July 2017_ - -- 🐛 Fixed a bug that was increasing the build time by building the wheel twice. This was a problem for large projects that have a long build time. If you're upgrading and you need the old behaviour, use `CIBW_BEFORE_BUILD={pip} install .`, or install exactly the dependencies you need in `CIBW_BEFORE_BUILD`. See #18. - -### 0.3.0 - -_27 June 2017_ - -- ⚠️ Removed Python 2.6 support on Linux (#12) - -### 0.2.1 - -_11 June 2017_ - -- 🛠 Changed the build process to install the package before building the wheel - this allows direct dependencies to be installed first (#9, thanks @tgarc!) -- ✨ Added Python 3 support for the main process, for systems where Python 3 is the default (#8, thanks @tgarc). - -### 0.2.0 - -_13 April 2017_ - -- ✨ Added `CIBW_SKIP` option, letting users explicitly skip a build -- ✨ Added `CIBW_BEFORE_BUILD` option, letting users run a shell command before the build starts - -### 0.1.3 - -_31 March 2017_ - -- 🌟 First public release! diff --git a/mkdocs.yml b/mkdocs.yml index c5d37fa9..4c187bd6 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -10,7 +10,6 @@ nav: - deliver-to-pypi.md - faq.md - contributing.md - - changelog.md markdown_extensions: - fenced_code - toc: From 4c86af69a5b0326abb530594b7ef4d5716e4f966 Mon Sep 17 00:00:00 2001 From: Joe Rickerby Date: Sun, 6 Oct 2019 11:38:36 +0100 Subject: [PATCH 05/30] Readme tweaks --- README.md | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 1e025c06..0cf3ac5c 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,14 @@ cibuildwheel ============ -[Documentation](cibuildwheel.readthedocs.org) [![PyPI](https://img.shields.io/pypi/v/cibuildwheel.svg)](https://pypi.python.org/pypi/cibuildwheel) [![Build Status](https://travis-ci.org/joerick/cibuildwheel.svg?branch=master)](https://travis-ci.org/joerick/cibuildwheel) [![Build status](https://ci.appveyor.com/api/projects/status/wbsgxshp05tt1tif/branch/master?svg=true)](https://ci.appveyor.com/project/joerick/cibuildwheel/branch/master) [![CircleCI](https://circleci.com/gh/joerick/cibuildwheel.svg?style=svg)](https://circleci.com/gh/joerick/cibuildwheel) +[![PyPI](https://img.shields.io/pypi/v/cibuildwheel.svg)](https://pypi.python.org/pypi/cibuildwheel) [![Build Status](https://travis-ci.org/joerick/cibuildwheel.svg?branch=master)](https://travis-ci.org/joerick/cibuildwheel) [![Build status](https://ci.appveyor.com/api/projects/status/wbsgxshp05tt1tif/branch/master?svg=true)](https://ci.appveyor.com/project/joerick/cibuildwheel/branch/master) [![CircleCI](https://circleci.com/gh/joerick/cibuildwheel.svg?style=svg)](https://circleci.com/gh/joerick/cibuildwheel) + +[Documentation](https://cibuildwheel.readthedocs.org) Python wheels are great. Building them across **Mac, Linux, Windows**, on **multiple versions of Python**, is not. `cibuildwheel` is here to help. `cibuildwheel` runs on your CI server - currently it supports Azure Pipelines, Travis CI, AppVeyor, and CircleCI - and it builds and tests your wheels across all of your platforms. -**`cibuildwheel` is in beta**. It's brand new - I'd love for you to try it and help make it better! What does it do? ---------------- @@ -31,14 +32,7 @@ Usage `cibuildwheel` currently works **Travis CI** and **CircleCI** to build Linux and Mac wheels, and **AppVeyor** to build Windows wheels. **Azure Pipelines** supports all three. -| | Linux | macOS | Windows | -|-----------------|-------|-------|---------| -| Azure Pipelines | ✅ | ✅ | ✅ | -| Travis CI | ✅ | ✅ | | -| AppVeyor | | | ✅ | -| CircleCI | ✅ | ✅ | | - -`cibuildwheel` is not intended to run on your development machine. It will try to install packages globally; this is no good. Travis CI, CircleCI, and AppVeyor run their builds in isolated environments, so are ideal for this kind of script. +`cibuildwheel` is not intended to run on your development machine. Because it uses system Python from Python.org it will try to install packages globally - not what you expect from a build tool! Instead, isolated CI services like Travis CI, CircleCI, Azure Pipelines and AppVeyor are ideal. Example setup ------------- @@ -50,10 +44,12 @@ language: python matrix: include: + # perform a linux build - sudo: required services: - docker env: PIP=pip + # and a mac build - os: osx language: generic env: PIP=pip2 @@ -65,7 +61,11 @@ env: script: - $PIP install cibuildwheel==0.12.0 + + # build the wheels, put them into './wheelhouse' - cibuildwheel --output-dir wheelhouse + + # if the release was tagged, upload them to PyPI - | if [[ $TRAVIS_TAG ]]; then python -m pip install twine @@ -73,6 +73,8 @@ script: fi ``` +For more information, including how to build on Appveyor, Azure, CircleCI, check out the [documentation](https://cibuildwheel.readthedocs.org). + Working examples ---------------- @@ -89,7 +91,7 @@ Here are some repos that use cibuildwheel. - [TgCrypto](https://github.com/pyrogram/tgcrypto) - [Twisted](https://github.com/twisted/twisted) -> Add repo here! Send a PR. +> Add your repo here! Send a PR. Legal note ---------- From 44d0dcba12937f8d8c5cda5d43717ac0e4c8817c Mon Sep 17 00:00:00 2001 From: Joe Rickerby Date: Sun, 6 Oct 2019 11:38:48 +0100 Subject: [PATCH 06/30] Update license copyright --- LICENSE | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/LICENSE b/LICENSE index 827bf6b4..e9b2ceee 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ This project is licensed under the 'BSD 2-clause license'. -Copyright (c) 2017, Joe Rickerby. All rights reserved. +Copyright (c) 2017-2019, Joe Rickerby and contributors. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: From bb2a5f8d170ab5c9859b5b4c7a02ed3565977478 Mon Sep 17 00:00:00 2001 From: Joe Rickerby Date: Sun, 6 Oct 2019 20:36:21 +0100 Subject: [PATCH 07/30] Formatting improvements --- docs/extra.css | 72 ++++++++++++++++++++++++++++++++++++++++++++ docs/extra.js | 5 ++++ docs/options.md | 79 ++++++++++++++++++++++++++++++++++++++++++------- docs/setup.md | 31 +++++++++++++++++-- mkdocs.yml | 13 +++++++- 5 files changed, 187 insertions(+), 13 deletions(-) create mode 100644 docs/extra.css create mode 100644 docs/extra.js diff --git a/docs/extra.css b/docs/extra.css new file mode 100644 index 00000000..42095298 --- /dev/null +++ b/docs/extra.css @@ -0,0 +1,72 @@ + +/* Global styles */ + +p { + margin-bottom: 12px; +} + +code { + font-size: 85%; + background-color: rgba(27,31,35,.05); + border-radius: 3px; + padding: .2em .4em; + color: inherit; + border: none; + margin: 0 1px; +} + +code, pre, tt { + font-family: SFMono-Regular, Consolas, Liberation Mono, Menlo, monospace; +} + +.hljs { + padding: 1em; + background-color: #f6f8fa; +} + +/* + Code block filename style + + Use by putting a quote before a code block e.g. + + > filename.txt + + ``` + code here + ``` + + JS adds the relevant classes to make the following selectors work. +*/ +.rst-content .code-block-filename { + margin: 0; + padding: 2px 1em; + background-color: #eff1f3; + font-size: 85%; + font-weight: bold; + + border-top-left-radius: 3px; + border-top-right-radius: 3px; + + border-bottom: 1px solid #e6e8e9; + color: #444; +} + +.rst-content .code-block-filename * { + font-size: inherit; +} +.rst-content .code-block-filename :last-child { + margin-bottom: 0; +} + +.code-block-filename + pre { + margin-top: 0; + border-top-left-radius: 0; + border-top-right-radius: 0; +} + +.code-block-filename + pre code { + padding-top: 0.9em; +} + +/* import font awesome 4 for icons */ +@import url(https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css); diff --git a/docs/extra.js b/docs/extra.js new file mode 100644 index 00000000..d32c3cc0 --- /dev/null +++ b/docs/extra.js @@ -0,0 +1,5 @@ + +$('.rst-content pre') + .prev('blockquote') + .addClass('code-block-filename'); + diff --git a/docs/options.md b/docs/options.md index 12814d01..8c6146fc 100644 --- a/docs/options.md +++ b/docs/options.md @@ -1,24 +1,42 @@ +### Setting options + cibuildwheel is configured using environment variables, that can be set using your CI config. - - - - -
example .travis.yml environment variables
env:
+For example, to configure cibuildwheel to run tests, add the following YAML to
+your CI config file:
+
+> .travis.yml ([docs](https://docs.travis-ci.com/user/environment-variables/))
+```yaml
+env:
   global:
     - CIBW_TEST_REQUIRES=nose
     - CIBW_TEST_COMMAND="nosetests {project}/tests"
-
example appveyor.yml environment variables
environment:
+```
+
+> appveyor.yml ([docs](https://www.appveyor.com/docs/build-configuration/#environment-variables))
+```yaml
+environment:
   global:
     CIBW_TEST_REQUIRES: nose
     CIBW_TEST_COMMAND: "nosetests {project}\\tests"
-
example .circleci/config.yml environment variables
jobs:
+```
+
+> .circleci/config.yml ([docs](https://circleci.com/docs/2.0/configuration-reference/#environment))
+```yaml
+jobs:
   job_name:
     environment:
       CIBW_TEST_REQUIRES: nose
-      CIBW_TEST_COMMAND: "nosetests {project}\\tests"
-
+ CIBW_TEST_COMMAND: "nosetests {project}/tests" +``` + +> azure-pipelines.yml ([docs](https://docs.microsoft.com/en-us/azure/devops/pipelines/process/variables)) +```yaml +variables: + CIBW_TEST_REQUIRES: nose + CIBW_TEST_COMMAND: "nosetests {project}/tests" +``` ## 🚩Build selection @@ -150,7 +168,7 @@ Platform-specific variants also available: ## Command line options -``` +```text usage: cibuildwheel [-h] [--platform {auto,linux,macos,windows}] [--output-dir OUTPUT_DIR] [--print-build-identifiers] [project_dir] @@ -178,3 +196,44 @@ optional arguments: invocation and exit. ``` + + + + diff --git a/docs/setup.md b/docs/setup.md index 2e87c5a8..3ec28623 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -2,7 +2,7 @@ Using Azure pipelines, you can build all three platforms on the same service. Create a `azure-pipelines.yml` file in your repo. -**azure-pipelines.yml** +> azure-pipelines.yml ```yaml jobs: - job: linux @@ -50,6 +50,7 @@ jobs: To build Linux and Mac wheels on Travis CI, create a `.travis.yml` file in your repo. +> .travis.yml ```yaml language: python @@ -74,6 +75,7 @@ Then setup a deployment method by following the [Travis CI deployment docs](http To build Linux and Mac wheels on CircleCI, create a `.circleci/config.yml` file in your repo, +> .circleci/config.yml ```yaml version: 2 @@ -124,6 +126,8 @@ CircleCI will store the built wheels for you - you can access them from the proj To build Windows wheels on AppVeyor, create an `appveyor.yml` file in your repo. +> appveyor.yml + ```yaml build_script: - pip install cibuildwheel==0.12.0 @@ -139,4 +143,27 @@ Commit those files, enable building of your repo on Travis CI and AppVeyor, and All being well, you should get wheels delivered to you in a few minutes. -> ⚠️ Got an error? Check the [checklist](#it-didnt-work) below. +> ⚠️ Got an error? Check the [FAQ](faq.md). + + \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 4c187bd6..2c9caadc 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,8 +1,18 @@ site_name: cibuildwheel docs_dir: docs -theme: readthedocs +theme: + name: readthedocs + highlightjs: true + hljs_languages: + - yaml repo_url: https://github.com/joerick/cibuildwheel +extra_css: + - extra.css + +extra_javascript: + - extra.js + nav: - Home: index.md - "Setup guide": setup.md @@ -10,6 +20,7 @@ nav: - deliver-to-pypi.md - faq.md - contributing.md + markdown_extensions: - fenced_code - toc: From 3ba7aa3532fef3e748e412aa50d450f6bc1e5fc5 Mon Sep 17 00:00:00 2001 From: Joe Rickerby Date: Sun, 6 Oct 2019 20:36:37 +0100 Subject: [PATCH 08/30] Copy improvements --- docs/contributing.md | 10 +++++++++- docs/deliver-to-pypi.md | 9 +++++---- docs/faq.md | 6 +++--- 3 files changed, 17 insertions(+), 8 deletions(-) diff --git a/docs/contributing.md b/docs/contributing.md index ce13a3a0..d16540cd 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -1,7 +1,7 @@ Contributing ============ -Wheel-building is pretty complex. I expect users to find many edge-cases - please help the rest of the community out by documenting these, adding features to support them, and reporting bugs. +Wheel-building can be pretty complex. I expect users to find many edge-cases - please help the rest of the community out by documenting these, adding features to support them, and reporting bugs. I plan to be pretty liberal in accepting pull requests, as long as they align with the design goals below. @@ -19,3 +19,11 @@ Other notes: - The platforms are very similar, until they're not. I'd rather have straight-forward code than totally DRY code, so let's keep airy platfrom abstractions to a minimum. - I might want to break the options into a shared config file one day, so that config is more easily shared. That has motivated some of the design decisions. + +### cibuildwheel's relationship with build errors + +cibuildwheel doesn't really do anything itself - it's always deferring to other tools (pip, wheel, auditwheel, delocate, docker). Without cibuildwheel, the process is really fragmented. Different tools, across different OSs need to be stitched together in just the right way to make it work. + +We're not responsible for errors in those tools, for fixing errors/crashes there. But cibuildwheel's job is providing users with an 'integrated' user experience across those tools. We provide an abstraction. The user says 'build me some wheels', not 'open the docker container, build a wheel with pip, fix up the symbols with auditwheel' etc. However, errors have a habit of breaking abstractions. And this is where users get confused, because the mechanism of cibuildwheel is laid bare, and they must understand a little bit how it works to debug. + +So, if we can, I'd like to improve the experience on errors as well. In [this](https://github.com/joerick/cibuildwheel/issues/139) case, it takes a bit of knowledge to understand that the linux builds are happening in a totally different OS via docker, that the linked symbols won't match, that auditwheel will fail because of this. A problem with how the tools fit together, instead of the tools themselves. diff --git a/docs/deliver-to-pypi.md b/docs/deliver-to-pypi.md index 7c184231..15d2317e 100644 --- a/docs/deliver-to-pypi.md +++ b/docs/deliver-to-pypi.md @@ -1,5 +1,5 @@ --- -title: Deliver to PyPI +title: Delivering to PyPI --- After you've built your wheels, you'll probably want to deliver them to PyPI. @@ -15,8 +15,9 @@ rm -rf dist python setup.py sdist # 🏃🏻 -# Go and download your wheel files from wherever you put them. Put -# them all into the 'dist' folder. +# Go and download your wheel files from wherever you put them. e.g. your CI +# provider can be configured to store them for you. Put them all into the +# 'dist' folder. # Upload using 'twine' (you may need to 'pip install twine') twine upload dist/* @@ -30,6 +31,6 @@ Obviously, manual steps are for chumps, so we can automate this a little by usin ### Automatic method -If you don't need much control over the release of a package, you can set up cibuildwheel to deliver the wheels straight to PyPI. This doesn't require any cloud storage to work - you just need to bump the version and tag it. +If you don't need much control over the release of a package, you can set up cibuildwheel to deliver the wheels straight to PyPI. This doesn't require anycloud storage to work - you just need to bump the version and tag it. Check out [this example repo](https://github.com/joerick/cibuildwheel-autopypi-example) for instructions on how to set this up. diff --git a/docs/faq.md b/docs/faq.md index fe6731fb..fbc97ef3 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -6,7 +6,7 @@ If your wheel didn't compile, check the list below for some debugging tips. - A mistake in your config. To quickly test your config without doing a git push and waiting for your code to build on CI, you can test the Linux build in a Docker container. On Mac or Linux, with Docker running, try `cibuildwheel --platform linux`. You'll have to bring your config into the current environment first. -- Missing dependency. You might need to install something on the build machine. You can do this in `.travis.yml`, `appveyor.yml`, or `.circleci/config.yml`, with apt-get, brew or whatever Windows uses :P . Given how the Linux build works, we'll probably have to build something into `cibuildwheel`. Let's chat about that over in the issues! +- Missing dependency. You might need to install something on the build machine. You can do this in `.travis.yml`, `appveyor.yml`, or `.circleci/config.yml`, with apt-get, brew or choco. Given how the Linux build works, you'll need to use the [CIBW_BEFORE_BUILD](options.md#before-build) option. - Windows: missing C feature. The Windows C compiler doesn't support C language features invented after 1990, so you'll have to backport your C code to C90. For me, this mostly involved putting my variable declarations at the top of the function like an animal. @@ -14,9 +14,9 @@ If your wheel didn't compile, check the list below for some debugging tips. ### Linux builds on Docker -Linux wheels are built in the [`manylinux1` docker images](https://github.com/pypa/manylinux) to provide binary compatible wheels on Linux, according to [PEP 513](https://www.python.org/dev/peps/pep-0513/). Because of this, when building with `cibuildwheel` on Linux, a few things should be taken into account: +Linux wheels are built in the [`manylinux` docker images](https://github.com/pypa/manylinux) to provide binary compatible wheels on Linux, according to [PEP 513](https://www.python.org/dev/peps/pep-0513/). Because of this, when building with `cibuildwheel` on Linux, a few things should be taken into account: -- Programs and libraries cannot be installed on the Travis CI Ubuntu host with `apt-get`, but can be installed inside of the Docker image using `yum` or manually. The same goes for environment variables that are potentially needed to customize the wheel building. `cibuildwheel` supports this by providing the `CIBW_ENVIRONMENT` and `CIBW_BEFORE_BUILD` options to setup the build environment inside the running Docker image. See [below](options.md#build-environment) for details on these options. +- Programs and libraries cannot be installed on the Travis CI Ubuntu host with `apt-get`, but can be installed inside of the Docker image using `yum` or manually. The same goes for environment variables that are potentially needed to customize the wheel building. `cibuildwheel` supports this by providing the `CIBW_ENVIRONMENT` and `CIBW_BEFORE_BUILD` options to setup the build environment inside the running Docker image. See [the options docs](options.md#build-environment) for details on these options. - The project directory is mounted in the running Docker instance as `/project`, the output directory for the wheels as `/output`. In general, this is handled transparently by `cibuildwheel`. For a more finegrained level of control however, the root of the host file system is mounted as `/host`, allowing for example to access shared files, caches, etc. on the host file system. Note that this is not available on CircleCI due to their Docker policies. From 05385b1cb03ecb310d627127c74d0e533ba95f5e Mon Sep 17 00:00:00 2001 From: Joe Rickerby Date: Sun, 6 Oct 2019 22:57:41 +0100 Subject: [PATCH 09/30] Add readthedocs config --- .readthedocs.yml | 9 +++++++++ 1 file changed, 9 insertions(+) create mode 100644 .readthedocs.yml diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 00000000..366facc5 --- /dev/null +++ b/.readthedocs.yml @@ -0,0 +1,9 @@ +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details +version: 2 + +mkdocs: + configuration: mkdocs.yml + +python: + version: 3.7 From 1741d7ce1fc11b061f7d916394e0ab0d10f037e1 Mon Sep 17 00:00:00 2001 From: Joe Rickerby Date: Sun, 6 Oct 2019 23:05:41 +0100 Subject: [PATCH 10/30] Docs samples should pin versions --- docs/setup.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/setup.md b/docs/setup.md index 3ec28623..30efaf37 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -90,7 +90,7 @@ jobs: - run: name: Build the Linux wheels. command: | - pip install --user cibuildwheel + pip install --user cibuildwheel==0.12.0 cibuildwheel --output-dir wheelhouse - store_artifacts: path: wheelhouse/ @@ -104,7 +104,7 @@ jobs: - run: name: Build the OS X wheels. command: | - pip install --user cibuildwheel + pip install --user cibuildwheel==0.12.0 cibuildwheel --output-dir wheelhouse - store_artifacts: path: wheelhouse/ From c1572e4ff4fc489d91033af6d33caf0a424da055 Mon Sep 17 00:00:00 2001 From: Joe Rickerby Date: Sun, 6 Oct 2019 23:09:34 +0100 Subject: [PATCH 11/30] Ensure the pinned versions in docs are bumped --- setup.cfg | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/setup.cfg b/setup.cfg index ea616ddf..957a2e96 100644 --- a/setup.cfg +++ b/setup.cfg @@ -12,6 +12,10 @@ message = Bump version search = cibuildwheel=={current_version} replace = cibuildwheel=={new_version} +[bumpversion:file:docs/setup.md] +search = cibuildwheel=={current_version} +replace = cibuildwheel=={new_version} + [bdist_wheel] universal = 1 From 89bb2d352d0dfdb5f872c02aa1b088fa11f4229c Mon Sep 17 00:00:00 2001 From: Joe Rickerby Date: Mon, 7 Oct 2019 09:15:59 +0100 Subject: [PATCH 12/30] Add docs links to the setup guide --- docs/setup.md | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/docs/setup.md b/docs/setup.md index 30efaf37..3eb80639 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -46,6 +46,10 @@ jobs: inputs: {pathtoPublish: 'wheelhouse'} ``` +Commit this file, enable building of your repo on Azure Pipelines, and push. + +Wheels will be stored for you and available through the Pipelines interface. For more info on this file, check out the [docs](https://docs.microsoft.com/en-us/azure/devops/pipelines/yaml-schema). + ## Travis CI [linux/mac] To build Linux and Mac wheels on Travis CI, create a `.travis.yml` file in your repo. @@ -69,7 +73,9 @@ script: - cibuildwheel --output-dir wheelhouse ``` -Then setup a deployment method by following the [Travis CI deployment docs](https://docs.travis-ci.com/user/deployment/), or see [Delivering to PyPI](#delivering-to-pypi) below. +Commit this file, enable building of your repo on Travis CI, and push. + +Then setup a deployment method by following the [Travis CI deployment docs](https://docs.travis-ci.com/user/deployment/), or see [Delivering to PyPI](deliver-to-pypi.md). For more info on `.travis.yml`, check out the [docs](https://docs.travis-ci.com/). ## CircleCI [linux/mac] @@ -117,10 +123,12 @@ workflows: - osx-wheels ``` +Commit this file, enable building of your repo on CircleCI, and push. + !!! note CircleCI doesn't enable free macOS containers for open source by default, but you can ask for access. See [here](https://circleci.com/docs/2.0/oss/#overview) for more information. -CircleCI will store the built wheels for you - you can access them from the project console. +CircleCI will store the built wheels for you - you can access them from the project console. Check out the CircleCI [docs](https://circleci.com/docs/2.0/configuration-reference/#section=configuration) for more info on this config file. ## AppVeyor [windows] @@ -136,12 +144,12 @@ artifacts: - path: "wheelhouse\\*.whl" name: Wheels ``` - -AppVeyor will store the built wheels for you - you can access them from the project console. Alternatively, you may want to store them in the same place as the Travis CI build. See [AppVeyor deployment docs](https://www.appveyor.com/docs/deployment/) for more info, or see [Delivering to PyPI](#delivering-to-pypi) below. -Commit those files, enable building of your repo on Travis CI and AppVeyor, and push. +Commit this file, enable building of your repo on AppVeyor, and push. -All being well, you should get wheels delivered to you in a few minutes. +AppVeyor will store the built wheels for you - you can access them from the project console. Alternatively, you may want to store them in the same place as the Travis CI build. See [AppVeyor deployment docs](https://www.appveyor.com/docs/deployment/) for more info, or see [Delivering to PyPI](deliver-to-pypi.md) below. + +For more info on this config file, check out the [docs](https://www.appveyor.com/docs/). > ⚠️ Got an error? Check the [FAQ](faq.md). From b577c5f00f1f8f58505a60532511d976533241dd Mon Sep 17 00:00:00 2001 From: Joe Rickerby Date: Sun, 20 Oct 2019 19:43:13 +0100 Subject: [PATCH 13/30] Misc copy edits --- README.md | 7 ++++++- docs/contributing.md | 2 +- 2 files changed, 7 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 0cf3ac5c..890c9406 100644 --- a/README.md +++ b/README.md @@ -277,6 +277,11 @@ _31 March 2017_ - 🌟 First public release! +Contributing +============ + +For more info on how to contribute to cibuildwheel, see the [docs](https://cibuildwheel.readthedocs.io/en/latest/contributing/). + Maintainers ----------- @@ -301,7 +306,7 @@ Massive props also to- - @mayeut for a [phenomenal PR](https://github.com/joerick/cibuildwheel/pull/71) patching Python itself for better compatibility! See also --------- +======== If you'd like to keep wheel building separate from the package itself, check out [astrofrog/autowheel](https://github.com/astrofrog/autowheel). It builds packages using cibuildwheel from source distributions on PyPI. diff --git a/docs/contributing.md b/docs/contributing.md index d16540cd..764cda17 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -5,7 +5,7 @@ Wheel-building can be pretty complex. I expect users to find many edge-cases - p I plan to be pretty liberal in accepting pull requests, as long as they align with the design goals below. -`cibuildwheel` is indie open source. I'm not paid to work on this. +`cibuildwheel` is indie open source. We're not paid to work on this. Design Goals ------------ From 46865a5f40b29614405fc4f9855f333341cd8551 Mon Sep 17 00:00:00 2001 From: Joe Rickerby Date: Sun, 20 Oct 2019 20:39:50 +0100 Subject: [PATCH 14/30] Options page rework (incomplete) --- docs/options.md | 196 ++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 175 insertions(+), 21 deletions(-) diff --git a/docs/options.md b/docs/options.md index 8c6146fc..ea3e8f01 100644 --- a/docs/options.md +++ b/docs/options.md @@ -1,4 +1,58 @@ -### Setting options +## Options + +
+ +| | | | +|---|---|---| +| **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``| + + +- 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``| + +## Options summary + +
+ +## Setting options cibuildwheel is configured using environment variables, that can be set using your CI config. @@ -38,9 +92,10 @@ variables: CIBW_TEST_COMMAND: "nosetests {project}/tests" ``` -## 🚩Build selection +## Build selection -### CIBW_PLATFORM - Override the auto-detected target platform {: #platform} +### CIBW_PLATFORM {: #platform} +> Override the auto-detected target platform Options: `auto` `linux` `macos` `windows` @@ -50,7 +105,8 @@ Default: `auto` 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, CIBW_SKIP - Choose the Python versions to build {: #build-skip} +### CIBW_BUILD, CIBW_SKIP {: #build-skip} +> Choose the Python versions to build 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. @@ -75,9 +131,10 @@ Examples: - 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 +## Build environment -### CIBW_ENVIRONMENT - Set environment variables needed during the build {: #environment} +### 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!). @@ -95,7 +152,8 @@ Platform-specific variants also available: 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 - Execute a shell command preparing each wheel's build {: #before-build} +### CIBW_BEFORE_BUILD {: #before-build} +> Execute a shell command preparing each wheel's 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. @@ -110,7 +168,8 @@ 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, CIBW_MANYLINUX1_I686_IMAGE - Specify alternative manylinux1 x86_64 docker images {: #manylinux-image} +### CIBW_MANYLINUX1_X86_64_IMAGE, CIBW_MANYLINUX1_I686_IMAGE {: #manylinux-image} +> Specify alternative manylinux1 x86_64 docker images 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). @@ -119,9 +178,10 @@ Beware to specify a valid docker image that can be used the same as the official Example: `dockcross/manylinux-x64` Example: `dockcross/manylinux-x86` -## 🔬 Testing +## Testing -### CIBW_TEST_COMMAND - Execute a shell command to test all built wheels {: #test-command} +### CIBW_TEST_COMMAND {: #test-command} +> Execute a shell command to test all built wheels 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`. @@ -132,7 +192,8 @@ Example: `nosetests {project}/tests` Platform-specific variants also available: `CIBW_TEST_COMMAND_MACOS` | `CIBW_TEST_COMMAND_WINDOWS` | `CIBW_TEST_COMMAND_LINUX` -### CIBW_TEST_REQUIRES - Install Python dependencies before running the tests {: #test-requires} +### CIBW_TEST_REQUIRES {: #test-requires} +> Install Python dependencies before running the tests Space-separated list of dependencies required for running the tests. @@ -142,7 +203,8 @@ 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 - Install your wheel for testing using `extras_require` {: #test-extras} +### CIBW_TEST_EXTRAS {: #test-extras} +> Install your wheel for testing using `extras_require` Comma-separated list of [extras_require](https://setuptools.readthedocs.io/en/latest/setuptools.html#declaring-extras-optional-features-with-their-own-dependencies) @@ -157,9 +219,10 @@ Example: `test,qt` (will cause the wheel to be installed with `pip install Increase/decrease the output of pip wheel 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. @@ -201,17 +264,40 @@ optional arguments: .cibw-option-header { margin-top: 5px; /* border-bottom: 1px solid rgba(0, 0, 0, 0.05); */ + font-size: 80%; + text-transform: uppercase; } .cibw-option-header:hover { background-color: transparent !important; } .cibw-option-name { - display: block; - font-weight: bold; } .cibw-option-description { font-size: 0.9em; } + .toctree-l3 { + border-left: 10px solid transparent; + } + .rst-content .section .toc-grid-marker + table td { + border: none !important; + background-color: transparent !important; + } + .options-toc { + display: grid; + grid-auto-columns: fit-content(20%) 1fr; + grid-gap: 10px; + gap: 10px; + font-size: 90%; + margin-bottom: 24px; + } + .options-toc .header { + grid-column: 1 / 3; + font-weight: bold; + margin-top: 15px; + } + .options-toc .header:first-child { + margin-top: 0; + } From 5db3763b2d030795aef76fc6b9716b1519db70c2 Mon Sep 17 00:00:00 2001 From: Joe Rickerby Date: Sun, 3 Nov 2019 18:30:15 +0000 Subject: [PATCH 15/30] Add plugin to import sections of readme into the documentation --- README.md | 4 ++ docs/index.md | 6 +++ .../__init__.py | 0 .../mkdocs_include_markdown_plugin/plugin.py | 53 +++++++++++++++++++ docs/mkdocs_include_markdown_plugin/setup.py | 15 ++++++ mkdocs.yml | 3 ++ 6 files changed, 81 insertions(+) create mode 100644 docs/mkdocs_include_markdown_plugin/mkdocs_include_markdown_plugin/__init__.py create mode 100644 docs/mkdocs_include_markdown_plugin/mkdocs_include_markdown_plugin/plugin.py create mode 100644 docs/mkdocs_include_markdown_plugin/setup.py diff --git a/README.md b/README.md index 890c9406..b71fdfac 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,8 @@ cibuildwheel [Documentation](https://cibuildwheel.readthedocs.org) + + Python wheels are great. Building them across **Mac, Linux, Windows**, on **multiple versions of Python**, is not. `cibuildwheel` is here to help. `cibuildwheel` runs on your CI server - currently it supports Azure Pipelines, Travis CI, AppVeyor, and CircleCI - and it builds and tests your wheels across all of your platforms. @@ -34,6 +36,8 @@ Usage `cibuildwheel` is not intended to run on your development machine. Because it uses system Python from Python.org it will try to install packages globally - not what you expect from a build tool! Instead, isolated CI services like Travis CI, CircleCI, Azure Pipelines and AppVeyor are ideal. + + Example setup ------------- diff --git a/docs/index.md b/docs/index.md index ff963eb8..6ff84d00 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,3 +4,9 @@ Home Welcome to the cibuildwheel docs. To get started, head over to the [setup guide](setup.md). + +{% + includemarkdown "../README.md" + start="" + end="" +%} diff --git a/docs/mkdocs_include_markdown_plugin/mkdocs_include_markdown_plugin/__init__.py b/docs/mkdocs_include_markdown_plugin/mkdocs_include_markdown_plugin/__init__.py new file mode 100644 index 00000000..e69de29b diff --git a/docs/mkdocs_include_markdown_plugin/mkdocs_include_markdown_plugin/plugin.py b/docs/mkdocs_include_markdown_plugin/mkdocs_include_markdown_plugin/plugin.py new file mode 100644 index 00000000..289c7a8e --- /dev/null +++ b/docs/mkdocs_include_markdown_plugin/mkdocs_include_markdown_plugin/plugin.py @@ -0,0 +1,53 @@ +import mkdocs, re, os, io, cgi +from pprint import pprint + +TAG_REGEX_PATTERN = re.compile( + r''' + {% # opening tag + \s* + includemarkdown # directive name + \s+ + "(?P[^"]+)" # "filename" + (?:\s+start="(?P[^"]+)")? # optional start expression + (?:\s+end="(?P[^"]+)")? # optional end expression + \s* + %} # closing tag + ''', + flags=re.VERBOSE, +) + +class ImportMarkdownPlugin(mkdocs.plugins.BasePlugin): + def on_page_markdown(self, markdown, page, **kwargs): + page_src_path = page.file.abs_src_path + + def found_import_markdown_tag(match): + filename = match.group('filename') + start = match.group('start') + end = match.group('end') + print('got a match', filename, start, end) + + file_path_abs = os.path.join(os.path.dirname(page_src_path), filename) + + if not os.path.exists(file_path_abs): + raise ValueError('file not found', filename) + + with io.open(file_path_abs, encoding='utf8') as f: + text_to_include = f.read() + + if start: + _, _, text_to_include = text_to_include.partition(start) + + if end: + text_to_include, _, _ = text_to_include.partition(end) + + return ( + '' % ( + filename, cgi.escape(start), cgi.escape(end) + ) + + text_to_include + + '' + ) + + markdown = re.sub(TAG_REGEX_PATTERN, found_import_markdown_tag, markdown) + return markdown + \ No newline at end of file diff --git a/docs/mkdocs_include_markdown_plugin/setup.py b/docs/mkdocs_include_markdown_plugin/setup.py new file mode 100644 index 00000000..0f8b6a18 --- /dev/null +++ b/docs/mkdocs_include_markdown_plugin/setup.py @@ -0,0 +1,15 @@ +from setuptools import setup + +setup( + name='mkdocs_include_markdown_plugin', + version='1.0', + author='Joe Rickerby', + license='Apache 2', + packages=['mkdocs_include_markdown_plugin'], + entry_points={ + 'mkdocs.plugins': [ + 'importmarkdown = mkdocs_include_markdown_plugin.plugin:ImportMarkdownPlugin', + ] + }, + zip_safe=False +) diff --git a/mkdocs.yml b/mkdocs.yml index 2c9caadc..a0ada14e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -27,3 +27,6 @@ markdown_extensions: permalink: True - attr_list - admonition + +plugins: + - importmarkdown From 2360c406bfa9af1cf14737320c55e74d09502d49 Mon Sep 17 00:00:00 2001 From: Joe Rickerby Date: Sun, 3 Nov 2019 18:35:06 +0000 Subject: [PATCH 16/30] Add JS code to generate a table of contents --- docs/extra.css | 4 +++ docs/options.md | 77 +++++++++++++++---------------------------------- 2 files changed, 28 insertions(+), 53 deletions(-) diff --git a/docs/extra.css b/docs/extra.css index 42095298..ddebc211 100644 --- a/docs/extra.css +++ b/docs/extra.css @@ -24,6 +24,10 @@ code, pre, tt { background-color: #f6f8fa; } +h1, h2, h3, h4, h5, h6 { + margin-top: 2em; +} + /* Code block filename style diff --git a/docs/options.md b/docs/options.md index ea3e8f01..48973e4e 100644 --- a/docs/options.md +++ b/docs/options.md @@ -106,6 +106,7 @@ Default: `auto` 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, CIBW_SKIP {: #build-skip} + > Choose the Python versions to build 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. @@ -285,8 +286,8 @@ optional arguments: .options-toc { display: grid; grid-auto-columns: fit-content(20%) 1fr; - grid-gap: 10px; - gap: 10px; + grid-gap: 16px 32px; + gap: 16px 32px; font-size: 90%; margin-bottom: 24px; } @@ -298,44 +299,15 @@ optional arguments: .options-toc .header:first-child { margin-top: 0; } + .options-toc a.option { + display: block; + margin-bottom: 5px; + } From f55b663ea78cdb066633655533debb67621db941 Mon Sep 17 00:00:00 2001 From: Joe Rickerby Date: Sun, 3 Nov 2019 18:35:17 +0000 Subject: [PATCH 17/30] Add requirement for our markdown plugin --- .readthedocs.yml | 2 ++ requirements-dev.txt | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/.readthedocs.yml b/.readthedocs.yml index 366facc5..301901d8 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -7,3 +7,5 @@ mkdocs: python: version: 3.7 + install: + - requirements: requirements-dev.txt diff --git a/requirements-dev.txt b/requirements-dev.txt index c6677778..1ecc8596 100644 --- a/requirements-dev.txt +++ b/requirements-dev.txt @@ -1,4 +1,4 @@ -e . +-e ./docs/mkdocs_include_markdown_plugin pytest mkdocs==1.0.4 - From 51649fd8069133c9bd9d31604b9897c4881ccdb6 Mon Sep 17 00:00:00 2001 From: Joe Rickerby Date: Sun, 3 Nov 2019 18:40:14 +0000 Subject: [PATCH 18/30] Add page from wiki to 'tips and tricks' page --- docs/faq.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/docs/faq.md b/docs/faq.md index fbc97ef3..461225e9 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -1,5 +1,5 @@ --- -title: It didn't work! +title: Tips and tricks --- If your wheel didn't compile, check the list below for some debugging tips. @@ -21,3 +21,17 @@ Linux wheels are built in the [`manylinux` docker images](https://github.com/pyp - The project directory is mounted in the running Docker instance as `/project`, the output directory for the wheels as `/output`. In general, this is handled transparently by `cibuildwheel`. For a more finegrained level of control however, the root of the host file system is mounted as `/host`, allowing for example to access shared files, caches, etc. on the host file system. Note that this is not available on CircleCI due to their Docker policies. - Alternative dockers images can be specified with the `CIBW_MANYLINUX1_X86_64_IMAGE` and `CIBW_MANYLINUX1_I686_IMAGE` options to allow for a custom, preconfigured build environment for the Linux builds. See [options](options.md#manylinux-image) for more details. + +### Building packages with optional C extensions + +`cibuildwheel` defines the environment variable `CIBUILDWHEEL` to the value `1` allowing projects for which the C extension is optional to make it mandatory when building wheels. + +An easy way to do it in Python 3 is through the `optional` named argument of `Extension` constructor in your `setup.py`: + +```python +myextension = Extension( + "myextension", + ["myextension.c"], + optional=os.environ.get('CIBUILDWHEEL', '0') != '1', +) +``` From 1446529f7c81637f76f2f20c32a8111aab111be2 Mon Sep 17 00:00:00 2001 From: Joe Rickerby Date: Sun, 3 Nov 2019 19:06:33 +0000 Subject: [PATCH 19/30] Sort out page titles --- docs/faq.md | 4 +++- docs/options.md | 50 ------------------------------------------------- mkdocs.yml | 4 ++-- 3 files changed, 5 insertions(+), 53 deletions(-) diff --git a/docs/faq.md b/docs/faq.md index 461225e9..aa6faec8 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -2,11 +2,13 @@ title: Tips and tricks --- +### Troubleshooting + If your wheel didn't compile, check the list below for some debugging tips. - A mistake in your config. To quickly test your config without doing a git push and waiting for your code to build on CI, you can test the Linux build in a Docker container. On Mac or Linux, with Docker running, try `cibuildwheel --platform linux`. You'll have to bring your config into the current environment first. -- Missing dependency. You might need to install something on the build machine. You can do this in `.travis.yml`, `appveyor.yml`, or `.circleci/config.yml`, with apt-get, brew or choco. Given how the Linux build works, you'll need to use the [CIBW_BEFORE_BUILD](options.md#before-build) option. +- Missing dependency. You might need to install something on the build machine. You can do this in `.travis.yml`, `appveyor.yml`, or `.circleci/config.yml`, with apt-get, brew or choco. Given how the Linux build works, you'll need to use the [`CIBW_BEFORE_BUILD`](options.md#before-build) option. - Windows: missing C feature. The Windows C compiler doesn't support C language features invented after 1990, so you'll have to backport your C code to C90. For me, this mostly involved putting my variable declarations at the top of the function like an animal. diff --git a/docs/options.md b/docs/options.md index 48973e4e..c38bf78f 100644 --- a/docs/options.md +++ b/docs/options.md @@ -1,53 +1,3 @@ -## Options - -
- -| | | | -|---|---|---| -| **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``| - - -- 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``| - ## Options summary
diff --git a/mkdocs.yml b/mkdocs.yml index a0ada14e..43e5be2d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -15,8 +15,8 @@ extra_javascript: nav: - Home: index.md - - "Setup guide": setup.md - - "Options": options.md + - setup.md + - options.md - deliver-to-pypi.md - faq.md - contributing.md From 73cba728a1e68b05b900bd65aa19c9196c3e951c Mon Sep 17 00:00:00 2001 From: Joe Rickerby Date: Sun, 3 Nov 2019 19:06:48 +0000 Subject: [PATCH 20/30] Have the page generate markdown for the README --- docs/options.md | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/docs/options.md b/docs/options.md index c38bf78f..d85d166c 100644 --- a/docs/options.md +++ b/docs/options.md @@ -310,5 +310,40 @@ optional arguments: .appendTo(tocTable); } } + + // write the markdown table for the README + + var markdown = '' + + markdown += '| | Option | Description |\n' + markdown += '|---|--------|-------------|\n' + + var prevHeader = null + + for (var i = 0; i < headers.length; i += 1) { + var header = headers[i]; + var headerOptions = options[header]; + for (var j = 0; j < headerOptions.length; j += 1) { + var option = headerOptions[j]; + + if (j == 0) { + markdown += '| **'+header+'** ' + } else { + markdown += '| ' + } + + var optionNames = option.name.trim().split(', ') + var url = 'https://cibuildwheel.readthedocs.io/en/stable/options/#'+option.id; + var namesMarkdown = $.map(optionNames, function(n) { + return '[`'+n+'`]('+url+') ' + }).join(' ') + + markdown += '| '+namesMarkdown+' ' + markdown += '| '+option.description.trim()+' ' + markdown += '|\n' + } + } + + console.log('readme options markdown\n', markdown) }); From eb8c926ebab78b105a139b2e20a3f1237a013465 Mon Sep 17 00:00:00 2001 From: Joe Rickerby Date: Sun, 3 Nov 2019 19:11:38 +0000 Subject: [PATCH 21/30] Remove unused CSS and visual tweaks --- docs/options.md | 23 +++-------------------- 1 file changed, 3 insertions(+), 20 deletions(-) diff --git a/docs/options.md b/docs/options.md index d85d166c..e956382d 100644 --- a/docs/options.md +++ b/docs/options.md @@ -212,39 +212,22 @@ optional arguments: ``` -## Build environment ### `CIBW_ENVIRONMENT` {: #environment} > Set environment variables needed during the build From ccd22e5a5ae355f77dccaefb58bf63a2a76799ee Mon Sep 17 00:00:00 2001 From: Joe Rickerby Date: Sun, 10 Nov 2019 13:22:35 +0000 Subject: [PATCH 27/30] Allow line breaks in table headers --- docs/extra.css | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/extra.css b/docs/extra.css index 2cee641f..4a965b22 100644 --- a/docs/extra.css +++ b/docs/extra.css @@ -36,6 +36,10 @@ h1, h2, h3, h4, h5, h6 { margin-bottom: 14px; } +.rst-content th { + white-space: normal; +} + /* Code block filename style From 22ae365ae9bedbe4371122a3681d451a888dbc39 Mon Sep 17 00:00:00 2001 From: Joe Rickerby Date: Sun, 10 Nov 2019 13:22:44 +0000 Subject: [PATCH 28/30] Clean up plugin --- .../mkdocs_include_markdown_plugin/plugin.py | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/mkdocs_include_markdown_plugin/mkdocs_include_markdown_plugin/plugin.py b/docs/mkdocs_include_markdown_plugin/mkdocs_include_markdown_plugin/plugin.py index 289c7a8e..69409318 100644 --- a/docs/mkdocs_include_markdown_plugin/mkdocs_include_markdown_plugin/plugin.py +++ b/docs/mkdocs_include_markdown_plugin/mkdocs_include_markdown_plugin/plugin.py @@ -1,5 +1,4 @@ import mkdocs, re, os, io, cgi -from pprint import pprint TAG_REGEX_PATTERN = re.compile( r''' @@ -24,7 +23,6 @@ class ImportMarkdownPlugin(mkdocs.plugins.BasePlugin): filename = match.group('filename') start = match.group('start') end = match.group('end') - print('got a match', filename, start, end) file_path_abs = os.path.join(os.path.dirname(page_src_path), filename) From 8e274700f411b499e0019e7412f85e26eb120b31 Mon Sep 17 00:00:00 2001 From: Joe Rickerby Date: Sun, 10 Nov 2019 14:54:56 +0000 Subject: [PATCH 29/30] Reformat examples on the options page and add a comment for each one --- docs/options.md | 127 ++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 101 insertions(+), 26 deletions(-) diff --git a/docs/options.md b/docs/options.md index 9fa436e9..580825aa 100644 --- a/docs/options.md +++ b/docs/options.md @@ -42,9 +42,12 @@ variables: CIBW_TEST_COMMAND: "nosetests {project}/tests" ``` + ## Build selection + ### `CIBW_PLATFORM` {: #platform} + > Override the auto-detected target platform Options: `auto` `linux` `macos` `windows` @@ -55,6 +58,7 @@ Default: `auto` 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`, `CIBW_SKIP` {: #build-skip} > Choose the Python versions to build @@ -80,24 +84,35 @@ The format is `python_tag-platform_tag`, with tags similar to those in [PEP 425] #### Examples -- `CIBW_BUILD=cp36-*` Only build on Python 3.6 +```yaml +# Only build on Python 3.6 +CIBW_BUILD: cp36-* -- `CIBW_SKIP=cp27-macosx_10_6_intel` Skip building on Python 2.7 on the Mac +# Skip building on Python 2.7 on the Mac +CIBW_SKIP: cp27-macosx_10_6_intel -- `CIBW_SKIP=cp38-macosx_10_9_x86_64` Skip building on Python 3.8 on the Mac +# Skip building on Python 3.8 on the Mac +CIBW_SKIP: cp38-macosx_10_9_x86_64 -- `CIBW_SKIP=cp27-*` Skip building on Python 2.7 on all platforms +# Skip building on Python 2.7 on all platforms +CIBW_SKIP: cp27-* -- `CIBW_SKIP=cp27-win*` Skip Python 2.7 on Windows +# Skip Python 2.7 on Windows +CIBW_SKIP: cp27-win* -- `CIBW_SKIP=cp27-win32` Skip Python 2.7 on 32-bit Windows +# Skip Python 2.7 on 32-bit Windows +CIBW_SKIP: cp27-win32 -- `CIBW_SKIP=cp27-* cp35-*` Skip Python 2.7 and Python 3.5 +# Skip Python 2.7 and Python 3.5 +CIBW_SKIP: cp27-* cp35-* -- `CIBW_SKIP=cp36-manylinux*` Skip Python 3.6 on Linux - -- `CIBW_BUILD=cp3?-*` and `CIBW_SKIP=*-win32 *-manylinux_i686` Only build on Python 3 and skip 32-bit builds +# Skip Python 3.6 on Linux +CIBW_SKIP: cp36-manylinux* +# Only build on Python 3 and skip 32-bit builds +CIBW_BUILD: cp3?-* +CIBW_SKIP: "*-win32 *-manylinux_i686" +``` +## Build customization + + ### `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 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"` +#### Examples +```yaml +# Set some compiler flags +CIBW_ENVIRONMENT: "CFLAGS='-g -Wall' CXXFLAGS='-Wall'" + +# Append a directory to the PATH variable (this is expanded in the build environment) +CIBW_ENVIRONMENT: "PATH=$PATH:/usr/local/bin" + +# Set BUILD_TIME to the output of the `date` command +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" +``` 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](faq.md#building-packages-with-optional-c-extensions). +!!! 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). ### `CIBW_BEFORE_BUILD` {: #before-build} @@ -149,9 +178,17 @@ If dependencies are required to build your wheel (for example if you include a h 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 .` +#### Examples +```yaml +# install your project and dependencies before building +CIBW_BEFORE_BUILD: pip install . + +# install something required for the build +CIBW_BEFORE_BUILD: pip install pybind11 + +# chain commands using && +CIBW_BEFORE_BUILD: yum install -y libffi-dev && pip install . +``` Platform-specific variants also available: `CIBW_BEFORE_BUILD_MACOS` | `CIBW_BEFORE_BUILD_WINDOWS` | `CIBW_BEFORE_BUILD_LINUX` @@ -168,9 +205,17 @@ Beware to specify a valid Docker image that can be used in the same way as the o Note that `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="manylinux2010_$(uname -m)"`). -Example: `manylinux1` -Example: `dockcross/manylinux-x64` -Example: `dockcross/manylinux-x86` +#### Examples + +```yaml +# build using the manylinux1 image to ensure manylinux1 wheels are produced +CIBW_MANYLINUX_X86_64_IMAGE: manylinux1 +CIBW_MANYLINUX_I686_IMAGE: manylinux1 + +# build using a different image from the docker registry +CIBW_MANYLINUX_X86_64_IMAGE: dockcross/manylinux-x64 +CIBW_MANYLINUX_I686_IMAGE: dockcross/manylinux-x86 +``` ## Testing @@ -181,18 +226,34 @@ Shell command to run tests after the build. The wheel will be installed automati On Linux and Mac, the command runs in a shell, so you can write things like `cmd1 && cmd2`. -Example: `nosetests {project}/tests` +#### Examples + +```yaml +# run the project tests against the installed wheel using `nose` +CIBW_TEST_COMMAND: nosetests {project}/tests + +# run the project tests using `pytest` +CIBW_TEST_COMMAND: nosetests {project}/tests +``` Platform-specific variants also available: `CIBW_TEST_COMMAND_MACOS` | `CIBW_TEST_COMMAND_WINDOWS` | `CIBW_TEST_COMMAND_LINUX` + ### `CIBW_TEST_REQUIRES` {: #test-requires} > Install Python dependencies before running the tests Space-separated list of dependencies required for running the tests. -Example: `pytest` -Example: `nose==1.3.7 moto==0.4.31` +#### Examples + +```yaml +# install pytest before running CIBW_TEST_COMMAND +CIBW_TEST_REQUIRES: pytest + +# install specific versions of test dependencies +CIBW_TEST_REQUIRES: 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` @@ -207,8 +268,12 @@ 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 [test,qt]`) +#### Examples +```yaml +# will cause the wheel to be installed with `pip install [test,qt]` +CIBW_TEST_EXTRAS: test,qt +``` Platform-specific variants also available: `CIBW_TEST_EXTRAS_MACOS` | `CIBW_TEST_EXTRAS_WINDOWS` | `CIBW_TEST_EXTRAS_LINUX` @@ -220,6 +285,13 @@ Platform-specific variants also available: 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. +#### Examples + +```yaml +# increase pip debugging output +CIBW_BUILD_VERBOSITY: 1 +``` + Platform-specific variants also available: `CIBW_BUILD_VERBOSITY_MACOS` | `CIBW_BUILD_VERBOSITY_WINDOWS` | `CIBW_BUILD_VERBOSITY_LINUX` @@ -279,6 +351,9 @@ optional arguments: display: block; margin-bottom: 5px; } + h3 code { + font-size: 100%; + }