scikit-build-core

The scikit_build_core package is the primary entry point for the build backend. It is organized into several subpackages that handle specific aspects of the build process, such as AST manipulation, build orchestration, metadata generation, and settings management.

Key subpackages include:

• scikit_build_core.build: Core build logic.
• scikit_build_core.builder: Logic for constructing the build environment.
• scikit_build_core.metadata: Handling of package metadata.
• scikit_build_core.settings: Configuration and settings management.
• scikit_build_core.utils: General utility functions.

SDists and wheels are produced via a standardized hook sequence defined in pyproject.toml:

1. Read Configuration: The build system reads the [build-system] table in pyproject.toml.
2. Environment Setup: An isolated environment is created containing the packages listed in build-system.requires.
3. Dynamic Dependency Resolution: The backend runs .get_requires_for_build_sdist(...) or .get_requires_for_build_wheel(...). If this returns a list, those packages are installed in the environment.
4. File Production: The backend runs .build_sdist(...) or .build_wheel(...) to produce the final file.

Note on Isolation: If you use --no-isolation (in build) or --no-build-isolation (in pip), steps 2 and 3 are skipped, and the build runs in the current environment.

The scikit_build_core.setuptools.wrapper.setup shim is a compatibility layer designed to behave as closely as possible to the classic skbuild.setup.

When using this shim, you can use the following environment variables to pass configuration:

• SKBUILD_CONFIGURE_OPTIONS: Extra arguments appended during configuration (analogous to SKBUILD_CMAKE_ARGS).
• SKBUILD_BUILD_OPTIONS: Extra arguments forwarded to cmake --build. Use a leading -- to pass native build-tool options (e.g., SKBUILD_BUILD_OPTIONS="-- -l4").

Note: These environment variables have no effect if you are using the standard scikit_build_core.setuptools.build_meta backend or setuptools.build_meta directly.

An SDist is a tarfile containing all the source code required to build the project and a PKG-INFO metadata file.

Best Practices:

• Include all files required for the build (including files from git submodules).
• Omit CI-related files that aren't needed for the build.
• Ensure the SDist can be installed without an internet connection if possible.

Manual Build (without isolation): You can manually trigger an SDist build using the scikit_build_core API:

python -c "from scikit_build_core.build import build_sdist; build_sdist('dist')"

You can control when overrides are applied using conditional logic:

• if: All conditions provided must be true (logical AND).
• if.any: At least one condition provided must be true (logical OR).
• Combined: If you use both if and if.any, all if conditions AND at least one if.any condition must match.

Condition Types:

• bool: Matches a specific boolean value.
• string: Matches a regular expression (regex). For environment variables, a boolean matches any non-false-like value (non-empty/non-unset).
• version: Matches a PEP 508 specifier set (e.g., " >=1.0").

[tool.scikit-build]
wheel.cmake = false

[[tool.scikit-build.overrides]]
# Matches if EITHER CIBUILDWHEEL or BUILD_MY_LIB is truthy
if.any.env.CIBUILDWHEEL = true
if.any.env.BUILD_MY_LIB = true
wheel.cmake = true

The crossenv tool can be used with scikit-build-core to simplify cross-compilation. crossenv creates a fake virtual environment where configuration hints (such as EXT_SUFFIX) are overwritten with the target's values.

Using crossenv typically removes the need to manually overwrite wheel.tags.

scikit-build-core automatically populates CMake search paths to allow projects to find other CMake projects installed in the same environment. To make a project discoverable, it must define one or more cmake.* entry-points in its pyproject.toml.

To ensure your CMakeLists.txt works both when driven by scikit-build-core and when run standalone, use the ${SKBUILD} variable.

• ${SKBUILD} is set to 2 when using scikit-build-core.
• ${SKBUILD} is set to 1 when using classic scikit-build.
• ${SKBUILD_CORE_VERSION} provides the version of scikit-build-core being used.

if(${SKBUILD} STREQUAL "2")
    message("Running under scikit-build-core version ${SKBUILD_CORE_VERSION}")
endif()