From 46865a5f40b29614405fc4f9855f333341cd8551 Mon Sep 17 00:00:00 2001 From: Joe Rickerby Date: Sun, 20 Oct 2019 20:39:50 +0100 Subject: [PATCH] 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; + }