feat: package-declared config-settings

docs/api/scikit_build_core.settings.rst

@@ -25,6 +25,14 @@ scikit\_build\_core.settings.auto\_requires module
    :show-inheritance:
    :undoc-members:
 
+scikit\_build\_core.settings.config\_settings module
+----------------------------------------------------
+
+.. automodule:: scikit_build_core.settings.config_settings
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
 scikit\_build\_core.settings.documentation module
 -------------------------------------------------
 

docs/configuration/config_settings.md

@@ -0,0 +1,91 @@
+# Package config-settings
+
+Packages can declare their own config-settings, giving users a documented,
+package-level interface for configuring the build, with no need to expose raw
+CMake defines like `-C cmake.define.ZMQ_PREFIX=...`. Declared settings can be
+passed as PEP 517 config-settings (`-C name=value`), bound to an environment
+variable, and forwarded to CMake.
+
+:::{versionadded} 1.1
+
+:::
+
+## Declaring settings
+
+Each setting is declared in the `tool.scikit-build.config-setting` table. Names
+must have at least two dot-separated segments; using your import package name as
+the first segment is recommended to avoid clashes with other tools'
+config-settings:
+
+```toml
+[tool.scikit-build.config-setting."zmq.prefix"]
+help = "Prefix to search for libzmq"
+env = "ZMQ_PREFIX"
+
+[tool.scikit-build.config-setting."zmq.libzmq"]
+help = "Where libzmq comes from"
+default = "system"
+```
+
+The supported keys are:
+
+- `help`: A description of the setting, for documentation purposes.
+- `type`: Either `"str"` (default) or `"bool"`. Boolean values are parsed like
+  environment variables in overrides (case insensitive `true`, `on`, `yes`, `y`,
+  `t`, or a positive number are truthy).
+- `default`: The value used when the setting is not passed; must match the type.
+  If not set, the setting is "unset" when not passed.
+- `env`: An environment variable that is also read for this setting.
+
+Users can then configure the build with either interface:
+
+```console
+$ pip install . -Czmq.libzmq=bundled
+$ ZMQ_PREFIX=/opt/zmq pip install .
+```
+
+The environment variable takes precedence over the config-setting, which takes
+precedence over the default (the same ordering used for scikit-build-core's own
+settings). Declared names are matched verbatim, are exempt from `strict-config`
+validation, and get "did you mean" suggestions when mistyped.
+
+Declaring config-settings requires `minimum-version = "1.1"` (or unset).
+
+## Passing values to CMake
+
+A `cmake.define` entry can reference a setting, similar to the `{env = ...}`
+form:
+
+```toml
+[tool.scikit-build.cmake.define]
+ZMQ_PREFIX = { config-setting = "zmq.prefix" }
+```
+
+The define is left unset when the setting resolves to no value, so
+`if(DEFINED ZMQ_PREFIX)` works in CMake, and `-C cmake.define.NAME=...` or
+`SKBUILD_CMAKE_DEFINE` still win over the referenced value.
+
+## Use in overrides
+
+Declared settings can drive [overrides](./overrides.md) with the
+`if.config-setting` condition, which matches the resolved value (so `-C` and the
+bound environment variable behave identically):
+
+```toml
+[[tool.scikit-build.overrides]]
+if.config-setting."zmq.libzmq" = "bundled"
+cmake.define.ZMQ_LIBZMQ = "ON"
+messages.after-success = "{green}Using bundled libzmq"
+```
+
+String conditions are regexes; boolean conditions match the truthiness of the
+value (unset matches `false`).
+
+:::{warning}
+
+Some build frontends (like pip) pass the same `-C` settings to every package
+built in a single command, so a setting intended for one package may reach
+another, where it is unrecognized and rejected under `strict-config`. Prefer
+installing such packages in separate commands when passing config-settings.
+
+:::

docs/configuration/overrides.md

@@ -130,6 +130,27 @@ This is often combined with `if.any`.
 
 :::
 
+### `config-setting.*` (string or bool)
+
+A table of [package-declared config-settings](./config_settings.md) mapped to
+either string regexes, or booleans. The condition matches the _resolved_ value
+(from the bound environment variable, the `-C` config-setting, or the default),
+so both user interfaces behave identically. An unset setting never matches a
+string condition and matches a `false` boolean condition. The setting must be
+declared in `tool.scikit-build.config-setting`.
+
+Example:
+
+```toml
+[[tool.scikit-build.overrides]]
+if.config-setting."zmq.libzmq" = "bundled"
+cmake.define.ZMQ_LIBZMQ = "ON"
+```
+
+:::{versionadded} 1.1
+
+:::
+
 ### `state` (string)
 
 The state of the build, one of `sdist`, `wheel`, `editable`, `metadata_wheel`,

docs/index.md

@@ -39,6 +39,7 @@ guide/faqs
 configuration/index
 configuration/editable
 configuration/overrides
+configuration/config_settings
 configuration/dynamic
 configuration/advanced
 ```

src/scikit_build_core/resources/scikit-build.schema.json

@@ -70,6 +70,20 @@
                       ]
                     }
                   }
+                },
+                {
+                  "type": "object",
+                  "required": [
+                    "config-setting"
+                  ],
+                  "additionalProperties": false,
+                  "properties": {
+                    "config-setting": {
+                      "type": "string",
+                      "minLength": 1,
+                      "description": "The declared config-setting name whose resolved value this define takes; the define is dropped when unset."
+                    }
+                  }
                 }
               ]
             }
@@ -601,6 +615,48 @@
       "default": "",
       "description": "The CMake build directory. Defaults to a unique temporary directory."
     },
+    "config-setting": {
+      "type": "object",
+      "description": "Declare package-specific config-settings, settable via `-C name=value` or a bound environment variable.",
+      "additionalProperties": false,
+      "patternProperties": {
+        "^[A-Za-z0-9_-]+(\\.[A-Za-z0-9_-]+)+$": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "help": {
+              "type": "string",
+              "default": "",
+              "description": "A description of the setting."
+            },
+            "type": {
+              "enum": [
+                "str",
+                "bool"
+              ],
+              "default": "str",
+              "description": "The type of the setting."
+            },
+            "default": {
+              "oneOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "boolean"
+                }
+              ],
+              "description": "The value used when the setting is not passed; must match the type."
+            },
+            "env": {
+              "type": "string",
+              "description": "An environment variable also read for this setting; it takes precedence over `-C`.",
+              "minLength": 1
+            }
+          }
+        }
+      }
+    },
     "overrides": {
       "type": "array",
       "description": "A list of overrides to apply to the settings, based on the `if` selector.",
@@ -889,6 +945,24 @@
           "additionalProperties": false,
           "minProperties": 1,
           "description": "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."
+        },
+        "config-setting": {
+          "type": "object",
+          "patternProperties": {
+            ".*": {
+              "oneOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "boolean"
+                }
+              ]
+            }
+          },
+          "additionalProperties": false,
+          "minProperties": 1,
+          "description": "A table of declared config-settings (tool.scikit-build.config-setting) mapped to either string regexs, or booleans. Matches the resolved value (env var, `-C`, or default)."
         }
       }
     },