scikit-build.schema.json

{
  "$schema": "http://json-schema.org/draft-07/schema",
  "$id": "https://github.com/scikit-build/scikit-build-core/blob/main/src/scikit_build_core/resources/scikit-build.schema.json",
  "description": "Scikit-build-core's settings.",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "cmake": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "minimum-version": {
          "type": "string",
          "description": "DEPRECATED in 0.8; use version instead.",
          "deprecated": true
        },
        "version": {
          "type": "string",
          "description": "The versions of CMake to allow as a python-compatible specifier."
        },
        "args": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "A list of args to pass to CMake when configuring the project."
        },
        "define": {
          "type": "object",
          "patternProperties": {
            ".+": {
              "oneOf": [
                {
                  "oneOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "boolean"
                    },
                    {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  ]
                },
                {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "env"
                  ],
                  "properties": {
                    "env": {
                      "type": "string",
                      "minLength": 1
                    },
                    "default": {
                      "oneOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "boolean"
                        },
                        {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      ]
                    }
                  }
                }
              ]
            }
          },
          "description": "A table of defines to pass to CMake when configuring the project. Additive."
        },
        "verbose": {
          "type": "boolean",
          "description": "DEPRECATED in 0.10, use build.verbose instead.",
          "deprecated": true
        },
        "build-type": {
          "type": "string",
          "default": "Release",
          "description": "The build type to use when building the project."
        },
        "source-dir": {
          "type": "string",
          "default": ".",
          "description": "The source directory to use when building the project."
        },
        "targets": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "DEPRECATED in 0.10; use build.targets instead.",
          "deprecated": true
        },
        "toolchain-file": {
          "type": "string",
          "description": "The CMAKE_TOOLCHAIN_FILE / --toolchain used for cross-compilation.",
          "scikit-build:override-only": true
        },
        "python-hints": {
          "type": "boolean",
          "default": true,
          "description": "Do not pass the current environment's python hints such as ``Python_EXECUTABLE``."
        }
      }
    },
    "ninja": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "minimum-version": {
          "type": "string",
          "description": "DEPRECATED in 0.8; use version instead.",
          "deprecated": true
        },
        "version": {
          "type": "string",
          "default": ">=1.5",
          "description": "The versions of Ninja to allow."
        },
        "make-fallback": {
          "type": "boolean",
          "default": true,
          "description": "Use Make as a fallback if a suitable Ninja executable is not found."
        }
      }
    },
    "logging": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "level": {
          "enum": [
            "NOTSET",
            "DEBUG",
            "INFO",
            "WARNING",
            "ERROR",
            "CRITICAL"
          ],
          "default": "WARNING",
          "description": "The logging level to display."
        }
      }
    },
    "sdist": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "include": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Files to include in the SDist even if they are skipped by default. Supports gitignore syntax."
        },
        "exclude": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Files to exclude from the SDist even if they are included by default. Supports gitignore syntax."
        },
        "inclusion-mode": {
          "enum": [
            "classic",
            "default",
            "manual"
          ],
          "description": "Method to use to compute the files to include and exclude."
        },
        "reproducible": {
          "type": "boolean",
          "default": true,
          "description": "Try to build a reproducible distribution."
        },
        "cmake": {
          "type": "boolean",
          "default": false,
          "description": "If set to True, CMake will be run before building the SDist."
        },
        "dereference": {
          "type": "boolean",
          "default": true,
          "description": "If set to True, symlinks in the SDist will be dereferenced and their contents"
        }
      }
    },
    "wheel": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "packages": {
          "oneOf": [
            {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            {
              "type": "object",
              "patternProperties": {
                ".+": {
                  "type": "string"
                }
              }
            }
          ],
          "description": "A list of packages to auto-copy into the wheel."
        },
        "py-api": {
          "type": "string",
          "default": "",
          "description": "The Python version tag used in the wheel file."
        },
        "expand-macos-universal-tags": {
          "type": "boolean",
          "default": false,
          "description": "Fill out extra tags that are not required."
        },
        "install-dir": {
          "type": "string",
          "default": "",
          "description": "The CMake install prefix relative to the platlib wheel path."
        },
        "license-files": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "A list of license files to include in the wheel. Supports glob patterns."
        },
        "cmake": {
          "type": "boolean",
          "default": true,
          "description": "Run CMake as part of building the wheel."
        },
        "platlib": {
          "type": "boolean",
          "description": "Target the platlib or the purelib."
        },
        "exclude": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "A set of patterns to exclude from the wheel."
        },
        "build-tag": {
          "type": "string",
          "default": "",
          "description": "The build tag to use for the wheel. If empty, no build tag is used."
        },
        "tags": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Wheel tags to manually force, {interpreter}-{abi}-{platform} format.",
          "scikit-build:override-only": true
        }
      }
    },
    "backport": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "find-python": {
          "type": "string",
          "default": "3.26.1",
          "description": "If CMake is less than this value, backport a copy of FindPython."
        }
      }
    },
    "editable": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "mode": {
          "enum": [
            "redirect",
            "inplace"
          ],
          "default": "redirect",
          "description": "Select the editable mode to use. Can be \"redirect\" (default) or \"inplace\"."
        },
        "verbose": {
          "type": "boolean",
          "default": true,
          "description": "Turn on verbose output for the editable mode rebuilds."
        },
        "rebuild": {
          "type": "boolean",
          "default": false,
          "description": "Rebuild the project when the package is imported."
        }
      }
    },
    "build": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "tool-args": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Extra args to pass directly to the builder in the build step."
        },
        "targets": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The build targets to use when building the project."
        },
        "verbose": {
          "type": "boolean",
          "default": false,
          "description": "Verbose printout when building."
        },
        "requires": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Additional ``build-system.requires``."
        }
      }
    },
    "install": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "components": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The components to install."
        },
        "strip": {
          "type": "boolean",
          "description": "Whether to strip the binaries."
        }
      }
    },
    "generate": {
      "type": "array",
      "items": {
        "oneOf": [
          {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "path",
              "template"
            ],
            "properties": {
              "path": {
                "type": "string",
                "description": "The path (relative to platlib) for the file to generate.",
                "minLength": 1
              },
              "template": {
                "type": "string",
                "description": "The template string to use for the file.",
                "minLength": 1
              },
              "location": {
                "enum": [
                  "install",
                  "build",
                  "source"
                ],
                "default": "install",
                "description": "The place to put the generated file."
              }
            }
          },
          {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "path",
              "template-path"
            ],
            "properties": {
              "path": {
                "type": "string",
                "description": "The path (relative to platlib) for the file to generate.",
                "minLength": 1
              },
              "template-path": {
                "type": "string",
                "description": "The path to the template file. If empty, a template must be set.",
                "minLength": 1
              },
              "location": {
                "enum": [
                  "install",
                  "build",
                  "source"
                ],
                "default": "install",
                "description": "The place to put the generated file."
              }
            }
          }
        ]
      }
    },
    "messages": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "after-failure": {
          "type": "string",
          "default": "",
          "description": "A message to print after a build failure."
        },
        "after-success": {
          "type": "string",
          "default": "",
          "description": "A message to print after a successful build."
        }
      }
    },
    "search": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "site-packages": {
          "type": "boolean",
          "default": true,
          "description": "Add the python build environment site_packages folder to the CMake prefix paths."
        }
      }
    },
    "metadata": {
      "type": "object",
      "description": "List dynamic metadata fields and hook locations in this table.",
      "additionalProperties": false,
      "properties": {
        "version": {
          "$ref": "#/$defs/metadata"
        },
        "description": {
          "$ref": "#/$defs/metadata"
        },
        "license": {
          "$ref": "#/$defs/metadata"
        },
        "readme": {
          "$ref": "#/$defs/metadata"
        },
        "requires-python": {
          "$ref": "#/$defs/metadata"
        },
        "dependencies": {
          "$ref": "#/$defs/metadata"
        },
        "optional-dependencies": {
          "$ref": "#/$defs/metadata"
        },
        "entrypoints": {
          "$ref": "#/$defs/metadata"
        },
        "authors": {
          "$ref": "#/$defs/metadata"
        },
        "maintainers": {
          "$ref": "#/$defs/metadata"
        },
        "urls": {
          "$ref": "#/$defs/metadata"
        },
        "classifiers": {
          "$ref": "#/$defs/metadata"
        },
        "keywords": {
          "$ref": "#/$defs/metadata"
        },
        "scripts": {
          "$ref": "#/$defs/metadata"
        },
        "gui-scripts": {
          "$ref": "#/$defs/metadata"
        }
      }
    },
    "strict-config": {
      "type": "boolean",
      "default": true,
      "description": "Strictly check all config options."
    },
    "experimental": {
      "type": "boolean",
      "default": false,
      "description": "Enable early previews of features not finalized yet."
    },
    "minimum-version": {
      "type": "string",
      "description": "If set, this will provide a method for backward compatibility."
    },
    "build-dir": {
      "type": "string",
      "default": "",
      "description": "The CMake build directory. Defaults to a unique temporary directory."
    },
    "overrides": {
      "type": "array",
      "description": "A list of overrides to apply to the settings, based on the `if` selector.",
      "items": {
        "type": "object",
        "required": [
          "if"
        ],
        "minProperties": 2,
        "additionalProperties": false,
        "properties": {
          "if": {
            "anyOf": [
              {
                "$ref": "#/$defs/if_overrides"
              },
              {
                "type": "object",
                "properties": {
                  "any": {
                    "$ref": "#/$defs/if_overrides"
                  }
                },
                "required": [
                  "any"
                ],
                "additionalProperties": false
              }
            ]
          },
          "inherit": {
            "type": "object",
            "properties": {
              "cmake": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "args": {
                    "$ref": "#/$defs/inherit"
                  },
                  "define": {
                    "$ref": "#/$defs/inherit"
                  },
                  "targets": {
                    "$ref": "#/$defs/inherit"
                  }
                }
              },
              "sdist": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "include": {
                    "$ref": "#/$defs/inherit"
                  },
                  "exclude": {
                    "$ref": "#/$defs/inherit"
                  }
                }
              },
              "wheel": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "packages": {
                    "$ref": "#/$defs/inherit"
                  },
                  "license-files": {
                    "$ref": "#/$defs/inherit"
                  },
                  "exclude": {
                    "$ref": "#/$defs/inherit"
                  },
                  "tags": {
                    "$ref": "#/$defs/inherit"
                  }
                }
              },
              "build": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "tool-args": {
                    "$ref": "#/$defs/inherit"
                  },
                  "targets": {
                    "$ref": "#/$defs/inherit"
                  },
                  "requires": {
                    "$ref": "#/$defs/inherit"
                  }
                }
              },
              "install": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "components": {
                    "$ref": "#/$defs/inherit"
                  }
                }
              }
            },
            "additionalProperties": false
          },
          "cmake": {
            "$ref": "#/properties/cmake"
          },
          "ninja": {
            "$ref": "#/properties/ninja"
          },
          "logging": {
            "$ref": "#/properties/logging"
          },
          "sdist": {
            "$ref": "#/properties/sdist"
          },
          "wheel": {
            "$ref": "#/properties/wheel"
          },
          "backport": {
            "$ref": "#/properties/backport"
          },
          "editable": {
            "$ref": "#/properties/editable"
          },
          "build": {
            "$ref": "#/properties/build"
          },
          "install": {
            "$ref": "#/properties/install"
          },
          "generate": {
            "$ref": "#/properties/generate"
          },
          "messages": {
            "$ref": "#/properties/messages"
          },
          "search": {
            "$ref": "#/properties/search"
          },
          "metadata": {
            "$ref": "#/properties/metadata"
          },
          "strict-config": {
            "$ref": "#/properties/strict-config"
          },
          "experimental": {
            "$ref": "#/properties/experimental"
          },
          "minimum-version": {
            "$ref": "#/properties/minimum-version"
          },
          "build-dir": {
            "$ref": "#/properties/build-dir"
          },
          "fail": {
            "type": "boolean",
            "description": "Immediately fail the build. This is only allowed in overrides or config-settings."
          }
        }
      }
    }
  },
  "$defs": {
    "metadata": {
      "type": "object",
      "properties": {
        "provider": {
          "type": "string"
        },
        "provider-path": {
          "type": "string"
        }
      }
    },
    "if_overrides": {
      "type": "object",
      "minProperties": 1,
      "additionalProperties": false,
      "properties": {
        "scikit-build-version": {
          "type": "string",
          "description": "The version of scikit-build-version. Takes a specifier set."
        },
        "python-version": {
          "type": "string",
          "description": "The two-digit Python version. Takes a specifier set."
        },
        "implementation-name": {
          "type": "string",
          "description": "The value of `sys.implementation.name`. Takes a regex"
        },
        "implementation-version": {
          "type": "string",
          "description": "Derived from `sys.implementation.version`, following PEP 508. Takes a specifier set."
        },
        "platform-system": {
          "type": "string",
          "description": "The value of `sys.platform`. Takes a regex."
        },
        "platform-machine": {
          "type": "string",
          "description": "The value of `platform.machine()`. Takes a regex."
        },
        "platform-node": {
          "type": "string",
          "description": "The value of `platform.node()`. Takes a regex."
        },
        "state": {
          "type": "string",
          "description": "The state of the build, one of `sdist`, `wheel`, `editable`, `metadata_wheel`, and `metadata_editable`. Takes a regex."
        },
        "from-sdist": {
          "type": "boolean",
          "description": "Whether the build is from an sdist."
        },
        "failed": {
          "type": "boolean",
          "description": "Matches if the build fails. A build will be retried if there is at least one matching override with this set to true."
        },
        "system-cmake": {
          "type": "string",
          "description": "The version of CMake found on the system. Takes a specifier set."
        },
        "cmake-wheel": {
          "type": "boolean",
          "description": "Whether a cmake wheel is known to be provided for this system."
        },
        "abi-flags": {
          "type": "string",
          "description": "A sorted string of the abi flags. Takes a regex."
        },
        "env": {
          "type": "object",
          "patternProperties": {
            ".*": {
              "oneOf": [
                {
                  "type": "string"
                },
                {
                  "type": "boolean"
                }
              ]
            }
          },
          "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."
        }
      }
    },
    "inherit": {
      "enum": [
        "none",
        "append",
        "prepend"
      ],
      "default": "none"
    }
  }
}