diff --git a/docs/setup.md b/docs/setup.md index cddf46a21..ad20a8bad 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -37,7 +37,6 @@ Install cibuildwheel and run a build like this: cibuildwheel --platform macos ``` - !!! tab "Windows" Using [pipx](https://github.com/pypa/pipx): @@ -52,6 +51,7 @@ Install cibuildwheel and run a build like this: ``` You should see the builds taking place. You can experiment with options using environment variables or pyproject.toml. +Please take into account the build is performed on a wide variety of linux distros with different package managers. !!! tab "Environment variables" @@ -61,7 +61,7 @@ You should see the builds taking place. You can experiment with options using en ```sh # run a command to set up the build system - export CIBW_BEFORE_ALL='apt install libpng-dev' + export CIBW_BEFORE_ALL='yum install -y openssl-devel || apk add --upgrade libressl-dev || apt-get install libssl-dev' cibuildwheel --platform linux ``` @@ -69,7 +69,7 @@ You should see the builds taking place. You can experiment with options using en > CMD (Windows) ```bat - set CIBW_BEFORE_ALL='apt install libpng-dev' + set CIBW_BEFORE_ALL='yum install -y openssl-devel || apk add --upgrade libressl-dev || apt-get install libssl-dev' cibuildwheel --platform linux ``` @@ -82,7 +82,7 @@ You should see the builds taking place. You can experiment with options using en ``` [tool.cibuildwheel] - before-all = "apt install libpng-dev" + before-all = "yum install -y openssl-devel || apk add --upgrade libressl-dev || apt-get install libssl-dev" ``` Then invoke cibuildwheel, like: @@ -97,10 +97,11 @@ If you've got [Docker](https://www.docker.com/products/docker-desktop) installed your development machine, you can run a Linux build. !!! tip - You can run the Linux build on any platform. Even Windows can run - Linux containers these days, but there are a few hoops to jump - through. Check [this document](https://docs.microsoft.com/en-us/virtualization/windowscontainers/quick-start/quick-start-windows-10-linux) - for more info. +You can run the Linux build on any platform. Even Windows can run +Linux containers these days, but there are a few hoops to jump +through. +Check [this document](https://docs.microsoft.com/en-us/virtualization/windowscontainers/quick-start/quick-start-windows-10-linux) +for more info. Because the builds are happening in manylinux Docker containers, they're perfectly reproducible. @@ -123,8 +124,8 @@ reported in the printed preamble of each run (e.g. "Cache folder: /Users/Matt/Li You can override the cache folder using the ``CIBW_CACHE_PATH`` environment variable. !!! warning - cibuildwheel uses official python.org macOS installers for CPython but - those can only be installed globally. +cibuildwheel uses official python.org macOS installers for CPython but +those can only be installed globally. In order not to mess with your system, cibuildwheel won't install those if they are missing. Instead, it will error out with a message to let you install the missing @@ -138,17 +139,17 @@ You can override the cache folder using the ``CIBW_CACHE_PATH`` environment vari Download link: https://www.python.org/ftp/python/3.6.8/python-3.6.8-macosx10.9.pkg ``` - ## Configure a CI service ### GitHub Actions [linux/mac/windows] {: #github-actions} -To build Linux, Mac, and Windows wheels using GitHub Actions, create a `.github/workflows/build_wheels.yml` file in your repo. +To build Linux, Mac, and Windows wheels using GitHub Actions, create a `.github/workflows/build_wheels.yml` file in your +repo. !!! tab "Action" - For GitHub Actions, `cibuildwheel` provides an action you can use. This is - concise and enables easier auto updating via GitHub's Dependabot; see - [Automatic updates](faq.md#automatic-updates). +For GitHub Actions, `cibuildwheel` provides an action you can use. This is +concise and enables easier auto updating via GitHub's Dependabot; see +[Automatic updates](faq.md#automatic-updates). > .github/workflows/build_wheels.yml @@ -161,9 +162,9 @@ To build Linux, Mac, and Windows wheels using GitHub Actions, create a `.github/ locations (those values are the defaults). !!! tab "pipx" - The GitHub Actions runners have pipx installed, so you can easily build in - just one line. This is internally how the action works; the main benefit of - the action form is easy updates via GitHub's Dependabot. +The GitHub Actions runners have pipx installed, so you can easily build in +just one line. This is internally how the action works; the main benefit of +the action form is easy updates via GitHub's Dependabot. > .github/workflows/build_wheels.yml @@ -192,10 +193,10 @@ To build Linux, Mac, and Windows wheels using GitHub Actions, create a `.github/ ``` !!! tab "Generic" - This is the most generic form using setup-python and pip; it looks the most - like the other CI examples. If you want to avoid having setup that takes - advantage of GitHub Actions features or pipx being preinstalled, this might - appeal to you. +This is the most generic form using setup-python and pip; it looks the most +like the other CI examples. If you want to avoid having setup that takes +advantage of GitHub Actions features or pipx being preinstalled, this might +appeal to you. > .github/workflows/build_wheels.yml @@ -229,13 +230,14 @@ To build Linux, Mac, and Windows wheels using GitHub Actions, create a `.github/ path: ./wheelhouse/*.whl ``` +Commit this file, and push to GitHub - either to your default branch, or to a PR branch. The build should start +automatically. -Commit this file, and push to GitHub - either to your default branch, or to a PR branch. The build should start automatically. - -For more info on this file, check out the [docs](https://help.github.com/en/actions/reference/workflow-syntax-for-github-actions). - -[`examples/github-deploy.yml`](https://github.com/pypa/cibuildwheel/blob/main/examples/github-deploy.yml) extends this minimal example with a demonstration of how to automatically upload the built wheels to PyPI. +For more info on this file, check out +the [docs](https://help.github.com/en/actions/reference/workflow-syntax-for-github-actions). +[`examples/github-deploy.yml`](https://github.com/pypa/cibuildwheel/blob/main/examples/github-deploy.yml) extends this +minimal example with a demonstration of how to automatically upload the built wheels to PyPI. ### Azure Pipelines [linux/mac/windows] {: #azure-pipelines} @@ -244,12 +246,13 @@ To build Linux, Mac, and Windows wheels on Azure Pipelines, create a `azure-pipe > azure-pipelines.yml ```yaml -{% include "../examples/azure-pipelines-minimal.yml" %} +{ % include "../examples/azure-pipelines-minimal.yml" % } ``` 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). +Wheels will be stored for you and available through the Pipelines interface. For more info on this file, check out +the [docs](https://docs.microsoft.com/en-us/azure/devops/pipelines/yaml-schema). ### Travis CI [linux/windows] {: #travis-ci} @@ -258,14 +261,18 @@ To build Linux and Windows wheels on Travis CI, create a `.travis.yml` file in y > .travis.yml ```yaml -{% include "../examples/travis-ci-minimal.yml" %} +{ % include "../examples/travis-ci-minimal.yml" % } ``` 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/). +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/). -[`examples/travis-ci-deploy.yml`](https://github.com/pypa/cibuildwheel/blob/main/examples/travis-ci-deploy.yml) extends this minimal example with a demonstration of how to automatically upload the built wheels to PyPI. +[`examples/travis-ci-deploy.yml`](https://github.com/pypa/cibuildwheel/blob/main/examples/travis-ci-deploy.yml) extends +this minimal example with a demonstration of how to automatically upload the built wheels to PyPI. ### AppVeyor [linux/mac/windows] {: #appveyor} @@ -274,12 +281,15 @@ To build Linux, Mac, and Windows wheels on AppVeyor, create an `appveyor.yml` fi > appveyor.yml ```yaml -{% include "../examples/appveyor-minimal.yml" %} +{ % include "../examples/appveyor-minimal.yml" % } ``` Commit this file, enable building of your repo on AppVeyor, and push. -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. +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/). @@ -290,15 +300,18 @@ To build Linux and Mac wheels on CircleCI, create a `.circleci/config.yml` file > .circleci/config.yml ```yaml -{% include "../examples/circleci-minimal.yml" %} +{ % include "../examples/circleci-minimal.yml" % } ``` 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 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. Check out the CircleCI [docs](https://circleci.com/docs/2.0/configuration-reference/#section=configuration) for more info on this config file. +CircleCI will store the built wheels for you - you can access them from the project console. Check out the +CircleCI [docs](https://circleci.com/docs/2.0/configuration-reference/#section=configuration) for more info on this +config file. ### Gitlab CI [linux] {: #gitlab-ci} @@ -307,12 +320,13 @@ To build Linux wheels on Gitlab CI, create a `.gitlab-ci.yml` file in your repo, > .gitlab-ci.yml ```yaml -{% include "../examples/gitlab-minimal.yml" %} +{ % include "../examples/gitlab-minimal.yml" % } ``` Commit this file, and push to Gitlab. The pipeline should start automatically. -Gitlab will store the built wheels for you - you can access them from the Pipelines view. Check out the Gitlab [docs](https://docs.gitlab.com/ee/ci/yaml/) for more info on this config file. +Gitlab will store the built wheels for you - you can access them from the Pipelines view. Check out the +Gitlab [docs](https://docs.gitlab.com/ee/ci/yaml/) for more info on this config file. ### Cirrus CI [linux/mac/windows] {: #cirrus-ci} @@ -321,18 +335,20 @@ To build Linux, Mac, and Windows wheels on Cirrus CI, create a `.cirrus.yml` fil > .cirrus.yml ```yaml -{% include "../examples/cirrus-ci-minimal.yml" %} +{ % include "../examples/cirrus-ci-minimal.yml" % } ``` Commit this file, enable building of your repo on Cirrus CI, and push. -Cirrus CI will store the built wheels for you - you can access them from the individual task view. Check out the Cirrus CI [docs](https://cirrus-ci.org/guide/writing-tasks/) for more info on this config file. +Cirrus CI will store the built wheels for you - you can access them from the individual task view. Check out the Cirrus +CI [docs](https://cirrus-ci.org/guide/writing-tasks/) for more info on this config file. > ⚠️ Got an error? Check the [FAQ](faq.md). ## Next steps -Once you've got the wheel building successfully, you might want to set up [testing](options.md#test-command) or [automatic releases to PyPI](deliver-to-pypi.md#automatic-method). +Once you've got the wheel building successfully, you might want to set up [testing](options.md#test-command) +or [automatic releases to PyPI](deliver-to-pypi.md#automatic-method).