Add CIBW_ENVIRONMENT to README and reorder options

README.md

@@ -113,42 +113,6 @@ 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]`.
 
-| Environment variable: `CIBW_TEST_COMMAND`
-| ---
-
-Optional.
-
-Shell command to run the tests. The project root should be included in the command as "{project}". The wheel will be installed automatically and available for import from the tests.
-
-Example: `nosetests {project}/tests`
-
-| 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`
-
-| Environment variable: `CIBW_BEFORE_BUILD`
-| ---
-
-Optional.
-
-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}`. These are useful when you need to write `python3` or `pip3` on a Python 3.x build.
-
-Example: `{pip} install .`  
-Example: `{pip} install pybind11`
-
-Platform-specific variants also available:  
- `CIBW_BEFORE_BUILD_MACOS` | `CIBW_BEFORE_BUILD_WINDOWS` | `CIBW_BEFORE_BUILD_LINUX`
-
 | Environment variable: `CIBW_SKIP`
 | ---
 
@@ -168,6 +132,61 @@ Example: `cp27-macosx_10_6_intel `  (don't build on Python 2 on Mac)
 Example: `cp27-win*`  (don't build on Python 2.7 on Windows)  
 Example: `cp34-* cp35-*`  (don't build on Python 3.4 or Python 3.5)  
 
+| 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`
+
+| Environment variable: `CIBW_BEFORE_BUILD`
+| ---
+
+Optional.
+
+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}`. These are useful when you need to write `python3` or `pip3` on a Python 3.x build.
+
+Example: `{pip} install .`  
+Example: `{pip} install pybind11`
+
+Platform-specific variants also available:  
+ `CIBW_BEFORE_BUILD_MACOS` | `CIBW_BEFORE_BUILD_WINDOWS` | `CIBW_BEFORE_BUILD_LINUX`
+
+| 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. The project root should be included in the command as "{project}".
+
+Example: `nosetests {project}/tests`
+
+| 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`
+
 --
 
 #### Example YML syntax