From aae6a2c71c519a609239c4135cbc67429c84c48c Mon Sep 17 00:00:00 2001 From: Henry Schreiner Date: Thu, 18 Jul 2024 16:24:04 -0400 Subject: [PATCH] docs: move overrides to page, expand Signed-off-by: Henry Schreiner --- docs/configuration.md | 36 +------- docs/index.md | 1 + docs/overrides.md | 186 ++++++++++++++++++++++++++++++++++++++++++ docs/schema.md | 3 - 4 files changed, 190 insertions(+), 36 deletions(-) create mode 100644 docs/overrides.md diff --git a/docs/configuration.md b/docs/configuration.md index 6fb8b5ee..10f9bdf7 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -697,39 +697,9 @@ experimental = true ## Overrides -Scikit-build-core has an override system, similar to cibuildwheel and mypy. You -specify a `tool.scikit-build.overrides` array with an `if` key. That if key can -take several values, including several based on [PEP 508][]: - -- `python-version`: The two-digit Python version. Takes a specifier set. -- `platform-system`: The value of `sys.platform`. Takes a regex. -- `platform-machine`: The value of `platform.machine()`. Takes a regex. -- `platform-node`: The value of `platform.node()`. Takes a regex. -- `implementation-name`: The value of `sys.implementation.name`. Takes a regex. -- `implementation-version`: Derived from `sys.implementation.version`, following - PEP 508. Takes a specifier set. -- `env`: A table of environment variables mapped to either string regexs, or - booleans. Valid "truthy" environment variables are case insensitive `true`, - `on`, `yes`, `y`, `t`, or a number more than 0. -- `state`: The state of the build, one of `sdist`, `wheel`, `editable`, - `metadata_wheel`, and `metadata_editable`. Takes a regex. - -At least one must be provided. Then you can specify any collection of valid -options, and those will override if all the items in the `if` are true. They -will match top to bottom, overriding previous matches. For example: - -```toml -[[tool.scikit-build.overrides]] -if.platform-system = "darwin" -cmake.version = ">=3.18" -``` - -If you use `if.any` instead of `if`, then the override is true if any one of the -items in it are true. +The overrides system allows you to customize for a wide variety of situations. +It is described at [](#overrides). ## Full Schema -You can see the full schema at [](#full-schema). - - -[pep 508]: https://peps.python.org/pep-0508/#environment-markers +You can see the full schema at [](#schema). diff --git a/docs/index.md b/docs/index.md index 7162a9a5..3b592f40 100644 --- a/docs/index.md +++ b/docs/index.md @@ -30,6 +30,7 @@ first Friday of every month at the same time. Our past meeting minutes are getting_started configuration +overrides cmakelists crosscompile migration_guide diff --git a/docs/overrides.md b/docs/overrides.md new file mode 100644 index 00000000..6a1775ae --- /dev/null +++ b/docs/overrides.md @@ -0,0 +1,186 @@ +# Overrides + +Scikit-build-core has an override system, similar to cibuildwheel and mypy. You +specify a `tool.scikit-build.overrides` array with an `if` key. That `if` key can +take several values, including several based on [PEP 508][]. Inside the override, +you can set any value `tool.scikit-build` supports, and it will override if the +`if` condition is true. + +## If conditions + +There are three types of conditions. Booleans, strings, and version numbers. +Booleans take a bool; if the boolean matches the bool you give, the override +matches. If the value is a string (such as an environment variable), it will +match truth-like values. Strings take a regex which will try to match. Version +numbers take a specifier set, like `>=1.0`. + +If multiple conditions are given, they all must be true. Use `if.any` (below) +if you would rather matching on any one of multiple conditions being true. + +At least one must be provided. Then you can specify any collection of valid +options, and those will override if all the items in the `if` are true. They +will match top to bottom, overriding previous matches. + +### `python-version` (version) + +The two-digit Python version. Takes a specifier set. + +Example: + +```toml +[[tool.scikit-build.overrides]] +if.python_version = ">=3.13" +wheel.cmake = false +``` + + +### `platform-system` (string) + +The value of `sys.platform`. Takes a regex. Like `sys.platform`, you should allow +suffixes. Common values: + +| System | `platform-system` (w/o suffix) | +|----------------|--------------------------------| +| AIX | `aix` | +| Android[^1] | `android` | +| FreeBSD | `freebsd` | +| iOS | `ios` | +| Linux | `linux` | +| Mac OS X | `darwin` | +| OpenBSD | `openbsd` | +| Pyodide | `emscripten` | +| WASI | `wasi` | +| Windows | `win32` | +| Windows/Cygwin | `cygwin` | +| Windows/MSYS2 | `msys` | + + +[^1]: Before CPython 3.13, this returned `linux`. + +Example: + +```toml +[[tool.scikit-build.overrides]] +if.platform-system = "$darwin" +cmake.version = ">=3.18" +``` + + +### `platform-machine` (string) + +The value of `platform.machine()`. Takes a regex. +A few sample values: + +| OS | Machine | `platform-system` | +|---------|---------------|-------------------| +| Unix | Intel 64-bit | `x86_64` | +| Linux | Intel 32-bit | `i686` | +| macOS | ARM | `arm64` | +| Linux | ARM | `aarch64` | +| Linux | Power PC | `ppc64le` | +| Linux | s390x | `s390x` | +| Windows | Intel 64-bit | `AMD64` | +| Windows | Intel 32-bit | `x86` | +| Windows | ARM | `ARM64` | + + +### `platform-node` (string) + +The value of `platform.node()`. This is generally your computer's name. Takes a +regex. + +### `implementation-name` (string) + +The value of `sys.implementation.name`. Takes a regex. Some common values: + +| Implementation | `implementation-name` | +|----------------|-----------------------| +| CPython | `cpython` | +| PyPy | `pypy` | + +### `implementation-version` (version) + +Derived from `sys.implementation.version`, following [PEP 508][]. Takes a +specifier set. This is the PyPy version on PyPy, for example. + +### `env.*` (string or bool) + +A table of environment variables mapped to either string regexs, or booleans. +Valid "truthy" environment variables are case insensitive `true`, `on`, `yes`, +`y`, `t`, or a number more than 0. + +Example: + +```toml +[[tool.scikit-build.overrides]] +if.env.CI = true +cmake.version = ">=3.30" +``` + +This is often combined with `if.any`. + +### `state` (string) + +The state of the build, one of `sdist`, `wheel`, `editable`, `metadata_wheel`, +and `metadata_editable`. Takes a regex. + +Note that you can build directly to wheel; you don't have to go through an +SDist. + +## Any matching condition + +If you use `if.any` instead of `if`, then the override is true if any one of the +items in it are true. + +If you have both `if` and `if.any` conditions, then all the `if` conditions and +one of the `if.any` conditions must match. + +Example: + + +```toml +[tool.scikit-build] +wheel.cmake = false + +[[tool.scikit-build.overrides]] +if.any.env.CIBUILDWHEEL = true +if.any.env.BUILD_MY_LIB = true +wheel.cmake = true +``` + +Above, either `CIBUILDWHEEL` or `BUILD_MY_LIB` being truthy will trigger a +binary build. + +## Inheriting for tables and arrays + +If you specify `inherit. = "append"` or `"prepend"`, then an override +will append or prepend tables and lists, either from the base configuration or +a previous override. For a table, the difference is apparent when you have +matching keys; `"append"` means the override replaces the old key, while +`"prepend"` will leave the key alone. + +Example: + +```toml +[tool.scikit-build] +cmake.define.FOO = "0" +cmake.define.BAR = "0" + +[[tool.scikit-build.overrides]] +if.env.SET_FOO = "ON" +inherit.cmake.define = "append" +cmake.define.FOO = "1" + +[[tool.scikit-build.overrides]] +if.env.SET_BAR = "ON" +inherit.cmake.define = "append" +cmake.define.BAR = "1" +``` + +In the above example, setting `SET_FOO` will add `FOO` as a define, and +likewise for `SET_BAR` and `BAR`. Without the inherit, setting one would remove +the other, as the table would be replaced. And `"prepend"` wouldn't be useful +at all, since FOO and BAR are already defined, so the original definition would +win. + +[pep 508]: https://peps.python.org/pep-0508/#environment-markers diff --git a/docs/schema.md b/docs/schema.md index e74f8f29..78fc12a2 100644 --- a/docs/schema.md +++ b/docs/schema.md @@ -1,6 +1,3 @@ - -(full-schema)= - # Schema The full schema for the `tool.scikit-build` table is below: