Skip to content

Commit 411d2c4

Browse files
henryiiihenryiii
authored
docs: move overrides to page, expand (#815)
This needs to be expanded and made its own page. Signed-off-by: Henry Schreiner <[email protected]>
1 parent d18713f commit 411d2c4

File tree

4 files changed

+190
-36
lines changed

4 files changed

+190
-36
lines changed

‎docs/configuration.md

Lines changed: 3 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -697,39 +697,9 @@ experimental = true
697697

698698
## Overrides
699699

700-
Scikit-build-core has an override system, similar to cibuildwheel and mypy. You
701-
specify a `tool.scikit-build.overrides` array with an `if` key. That if key can
702-
take several values, including several based on [PEP 508][]:
703-
704-
- `python-version`: The two-digit Python version. Takes a specifier set.
705-
- `platform-system`: The value of `sys.platform`. Takes a regex.
706-
- `platform-machine`: The value of `platform.machine()`. Takes a regex.
707-
- `platform-node`: The value of `platform.node()`. Takes a regex.
708-
- `implementation-name`: The value of `sys.implementation.name`. Takes a regex.
709-
- `implementation-version`: Derived from `sys.implementation.version`, following
710-
PEP 508. Takes a specifier set.
711-
- `env`: A table of environment variables mapped to either string regexs, or
712-
booleans. Valid "truthy" environment variables are case insensitive `true`,
713-
`on`, `yes`, `y`, `t`, or a number more than 0.
714-
- `state`: The state of the build, one of `sdist`, `wheel`, `editable`,
715-
`metadata_wheel`, and `metadata_editable`. Takes a regex.
716-
717-
At least one must be provided. Then you can specify any collection of valid
718-
options, and those will override if all the items in the `if` are true. They
719-
will match top to bottom, overriding previous matches. For example:
720-
721-
```toml
722-
[[tool.scikit-build.overrides]]
723-
if.platform-system = "darwin"
724-
cmake.version = ">=3.18"
725-
```
726-
727-
If you use `if.any` instead of `if`, then the override is true if any one of the
728-
items in it are true.
700+
The overrides system allows you to customize for a wide variety of situations.
701+
It is described at [](#overrides).
729702

730703
## Full Schema
731704

732-
You can see the full schema at [](#full-schema).
733-
734-
735-
[pep 508]: https://peps.python.org/pep-0508/#environment-markers
705+
You can see the full schema at [](#schema).

‎docs/index.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ first Friday of every month at the same time. Our past meeting minutes are
3030
3131
getting_started
3232
configuration
33+
overrides
3334
cmakelists
3435
crosscompile
3536
migration_guide

‎docs/overrides.md

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
# Overrides
2+
3+
Scikit-build-core has an override system, similar to cibuildwheel and mypy. You
4+
specify a `tool.scikit-build.overrides` array with an `if` key. That `if` key can
5+
take several values, including several based on [PEP 508][]. Inside the override,
6+
you can set any value `tool.scikit-build` supports, and it will override if the
7+
`if` condition is true.
8+
9+
## If conditions
10+
11+
There are three types of conditions. Booleans, strings, and version numbers.
12+
Booleans take a bool; if the boolean matches the bool you give, the override
13+
matches. If the value is a string (such as an environment variable), it will
14+
match truth-like values. Strings take a regex which will try to match. Version
15+
numbers take a specifier set, like `>=1.0`.
16+
17+
If multiple conditions are given, they all must be true. Use `if.any` (below)
18+
if you would rather matching on any one of multiple conditions being true.
19+
20+
At least one must be provided. Then you can specify any collection of valid
21+
options, and those will override if all the items in the `if` are true. They
22+
will match top to bottom, overriding previous matches.
23+
24+
### `python-version` (version)
25+
26+
The two-digit Python version. Takes a specifier set.
27+
28+
Example:
29+
30+
```toml
31+
[[tool.scikit-build.overrides]]
32+
if.python_version = ">=3.13"
33+
wheel.cmake = false
34+
```
35+
36+
37+
### `platform-system` (string)
38+
39+
The value of `sys.platform`. Takes a regex. Like `sys.platform`, you should allow
40+
suffixes. Common values:
41+
42+
| System | `platform-system` (w/o suffix) |
43+
|----------------|--------------------------------|
44+
| AIX | `aix` |
45+
| Android[^1] | `android` |
46+
| FreeBSD | `freebsd` |
47+
| iOS | `ios` |
48+
| Linux | `linux` |
49+
| Mac OS X | `darwin` |
50+
| OpenBSD | `openbsd` |
51+
| Pyodide | `emscripten` |
52+
| WASI | `wasi` |
53+
| Windows | `win32` |
54+
| Windows/Cygwin | `cygwin` |
55+
| Windows/MSYS2 | `msys` |
56+
57+
58+
[^1]: Before CPython 3.13, this returned `linux`.
59+
60+
Example:
61+
62+
```toml
63+
[[tool.scikit-build.overrides]]
64+
if.platform-system = "$darwin"
65+
cmake.version = ">=3.18"
66+
```
67+
68+
69+
### `platform-machine` (string)
70+
71+
The value of `platform.machine()`. Takes a regex.
72+
A few sample values:
73+
74+
| OS | Machine | `platform-system` |
75+
|---------|---------------|-------------------|
76+
| Unix | Intel 64-bit | `x86_64` |
77+
| Linux | Intel 32-bit | `i686` |
78+
| macOS | ARM | `arm64` |
79+
| Linux | ARM | `aarch64` |
80+
| Linux | Power PC | `ppc64le` |
81+
| Linux | s390x | `s390x` |
82+
| Windows | Intel 64-bit | `AMD64` |
83+
| Windows | Intel 32-bit | `x86` |
84+
| Windows | ARM | `ARM64` |
85+
86+
87+
### `platform-node` (string)
88+
89+
The value of `platform.node()`. This is generally your computer's name. Takes a
90+
regex.
91+
92+
### `implementation-name` (string)
93+
94+
The value of `sys.implementation.name`. Takes a regex. Some common values:
95+
96+
| Implementation | `implementation-name` |
97+
|----------------|-----------------------|
98+
| CPython | `cpython` |
99+
| PyPy | `pypy` |
100+
101+
### `implementation-version` (version)
102+
103+
Derived from `sys.implementation.version`, following [PEP 508][]. Takes a
104+
specifier set. This is the PyPy version on PyPy, for example.
105+
106+
### `env.*` (string or bool)
107+
108+
A table of environment variables mapped to either string regexs, or booleans.
109+
Valid "truthy" environment variables are case insensitive `true`, `on`, `yes`,
110+
`y`, `t`, or a number more than 0.
111+
112+
Example:
113+
114+
```toml
115+
[[tool.scikit-build.overrides]]
116+
if.env.CI = true
117+
cmake.version = ">=3.30"
118+
```
119+
120+
This is often combined with `if.any`.
121+
122+
### `state` (string)
123+
124+
The state of the build, one of `sdist`, `wheel`, `editable`, `metadata_wheel`,
125+
and `metadata_editable`. Takes a regex.
126+
127+
Note that you can build directly to wheel; you don't have to go through an
128+
SDist.
129+
130+
## Any matching condition
131+
132+
If you use `if.any` instead of `if`, then the override is true if any one of the
133+
items in it are true.
134+
135+
If you have both `if` and `if.any` conditions, then all the `if` conditions and
136+
one of the `if.any` conditions must match.
137+
138+
Example:
139+
140+
141+
```toml
142+
[tool.scikit-build]
143+
wheel.cmake = false
144+
145+
[[tool.scikit-build.overrides]]
146+
if.any.env.CIBUILDWHEEL = true
147+
if.any.env.BUILD_MY_LIB = true
148+
wheel.cmake = true
149+
```
150+
151+
Above, either `CIBUILDWHEEL` or `BUILD_MY_LIB` being truthy will trigger a
152+
binary build.
153+
154+
## Inheriting for tables and arrays
155+
156+
If you specify `inherit.<thing> = "append"` or `"prepend"`, then an override
157+
will append or prepend tables and lists, either from the base configuration or
158+
a previous override. For a table, the difference is apparent when you have
159+
matching keys; `"append"` means the override replaces the old key, while
160+
`"prepend"` will leave the key alone.
161+
162+
Example:
163+
164+
```toml
165+
[tool.scikit-build]
166+
cmake.define.FOO = "0"
167+
cmake.define.BAR = "0"
168+
169+
[[tool.scikit-build.overrides]]
170+
if.env.SET_FOO = "ON"
171+
inherit.cmake.define = "append"
172+
cmake.define.FOO = "1"
173+
174+
[[tool.scikit-build.overrides]]
175+
if.env.SET_BAR = "ON"
176+
inherit.cmake.define = "append"
177+
cmake.define.BAR = "1"
178+
```
179+
180+
In the above example, setting `SET_FOO` will add `FOO` as a define, and
181+
likewise for `SET_BAR` and `BAR`. Without the inherit, setting one would remove
182+
the other, as the table would be replaced. And `"prepend"` wouldn't be useful
183+
at all, since FOO and BAR are already defined, so the original definition would
184+
win.
185+
186+
[pep 508]: https://peps.python.org/pep-0508/#environment-markers

‎docs/schema.md

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,3 @@
1-
2-
(full-schema)=
3-
41
# Schema
52

63
The full schema for the `tool.scikit-build` table is below:

0 commit comments

Comments
 (0)