Skip to content

Commit

Permalink
doc: add clarification regarding linux docker environment
Browse files Browse the repository at this point in the history
  • Loading branch information
@doronz88
doronz88 committed Nov 30, 2023
1 parent 796361d commit 3dbe5e5
Showing 1 changed file with 58 additions and 42 deletions.
100 changes: 58 additions & 42 deletions docs/setup.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,6 @@ Install cibuildwheel and run a build like this:
cibuildwheel --platform macos
```


!!! tab "Windows"

Using [pipx](https://github.com/pypa/pipx):
Expand All @@ -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"

Expand All @@ -61,15 +61,15 @@ 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
```

> 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
```
Expand All @@ -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:
Expand All @@ -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.
Expand All @@ -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
Expand All @@ -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

Expand All @@ -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

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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}

Expand All @@ -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}

Expand All @@ -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}

Expand All @@ -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/).

Expand All @@ -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}

Expand All @@ -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}

Expand All @@ -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).

<script>
document.addEventListener('DOMContentLoaded', function() {
Expand Down

0 comments on commit 3dbe5e5

Please sign in to comment.