Hatchling¶

A hatchling plugin is provided by scikit-build-core. Feedback is welcome.

Warning

Use the [hatchling] extra when using this plugin. It will ensure a proper version of hatchling, and will help protect you if the plugin moves to a separate package in the future.

Added in version 0.9.

Changed in version 1.0: The plugin is no longer experimental (the experimental = true toggle is not required), editable installs are supported, and the [hatchling] extra is the recommended way to depend on it (warning shown if missing).

Basic usage¶

To use the plugin, make sure hatchling and scikit-build-core are in your build-system.requires. A recent version of hatchling is best; you need 1.23 to get cmake and ninja auto-added if needed, and 1.24 if you want to write out custom scripts, metadata, or shared data.

You need a tool.hatch.build.targets.wheel.hooks.scikit-build section to activate the plugin.

[build-system]
requires = ["hatchling", "scikit-build-core[hatchling]"]
build-backend = "hatchling.build"

[project]
name = "hatchling_example"
version = "0.1.0"

[tool.hatch.build.targets.wheel.hooks.scikit-build]

Options¶

Most of scikit-build-core’s configuration can be used with hatchling if it is applicable. Things like metadata and wheel options generally are not applicable, unless they pertain to setting the tag (which scikit-build-core controls). You can specify settings in either tool.hatch.build.targets.wheel.hooks.scikit-build or tool.scikit-build or via environment variables. You cannot use config-settings, as that’s not supported by hatchling for plugins.

Key limitations:

You need to leave wheel.cmake on. No wheel.platlib = false builds.
Using cmake in SDist step is not supported yet.
scikit-build.generate and scikit-build.metadata are not supported.
${SKBUILD_HEADER_DIR} is not supported, request support in Hatchling if needed.
Anything in ${SKBUILD_METADATA_DIR} must be placed in an extra_metadata folder.

Writing CMakeLists.txt¶

The hatchling version is available as ${SKBUILD_HATCHLING}.