Skip to content

Commit 55c8985

Browse files
docs: clarify environment precedence (#2905)
1 parent 2f9a352 commit 55c8985

2 files changed

Lines changed: 13 additions & 5 deletions

File tree

‎docs/configuration.md‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -64,10 +64,12 @@ You can configure cibuildwheel with a config file, such as `pyproject.toml`.
6464
Options have the same names as the environment variable overrides, but are
6565
placed in `[tool.cibuildwheel]` and are lower case, with dashes, following
6666
common [TOML](https://toml.io) practice. Anything placed in subsections
67-
named after a platform will only affect those platforms. Lists can be used
68-
instead of strings for items that are naturally a list. Multiline strings also
69-
work just like in the environment variables. Environment variables will take
70-
precedence if defined.
67+
named after a platform will only affect those platforms. Platform-specific
68+
values replace the corresponding global value for that platform; table options
69+
are not merged key by key. Lists can be used instead of strings for items that
70+
are naturally a list. Multiline strings also work just like in the environment
71+
variables. Environment variable overrides, such as `CIBW_TEST_COMMAND` and
72+
`CIBW_TEST_COMMAND_LINUX`, will take precedence if defined.
7173

7274
The example above using environment variables could have been written like this:
7375

@@ -178,7 +180,7 @@ on Python 3.11, and will have `environment = {FOO="BAZ", "PYTHON"="MONTY", "HAM"
178180
In the TOML configuration, you can choose how tables and lists are inherited.
179181
By default, all values are overridden completely (`"none"`) but sometimes you'd
180182
rather `"append"` or `"prepend"` to an existing list or table. You can do this
181-
with the `inherit` table in overrides. For example, if you want to add an environment
183+
with the `inherit` table in overrides. For example, if you want to add an environment
182184
variable for CPython 3.11, without `inherit` you'd have to repeat all the
183185
original environment variables in the override. With `inherit`, it's just:
184186

‎docs/options.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -593,6 +593,12 @@ You must use this variable to pass variables to Linux builds, since they execute
593593
You can use `$PATH` syntax to insert other variables, or the `$(pwd)` syntax to insert the output of other shell commands.
594594
Variables are evaluated in the order they appear. Any variable referenced before it is set will evaluate to an empty string.
595595

596+
The environment seen by the build and test steps starts with the build
597+
environment. On Linux, this is the container environment, plus any variables
598+
passed through with [`environment-pass`](#environment-pass). On other platforms,
599+
the host environment is already available. Assignments in `environment` are
600+
evaluated after that base environment and replace any duplicate variable names.
601+
596602
To specify more than one environment variable, separate the assignments by spaces.
597603

598604
Platform-specific environment variables are also available:<br/>

0 commit comments

Comments
 (0)