Hatch plugin for C++ builds
A simple, extensible C++ build plugin for hatch.
[tool.hatch.build.hooks.hatch-cpp] libraries = [ {name = "project/extension", sources = ["cpp/project/basic.cpp"], include-dirs = ["cpp"]} ]For more complete systems, see:
Configuration is driven from the [tool.hatch.build.hooks.hatch-cpp] hatch hook configuration field in a pyproject.toml. It is designed to closely match existing Python/C/C++ packaging tools.
verbose = true libraries = { Library Args } cmake = { CMake Args } platform = { Platform, either "linux", "darwin", or "win32" }See the test cases for more concrete examples.
hatch-cpp is driven by pydantic models for configuration and execution of the build. These models can themselves be overridden by setting build-config-class / build-plan-class.
name = "mylib" sources = [ "path/to/file.cpp", ] language = "c++" binding = "cpython" # or "pybind11", "nanobind", "generic" std = "" # Passed to -std= or /std: include_dirs = ["paths/to/add/to/-I"] library_dirs = ["paths/to/add/to/-L"] libraries = ["-llibraries_to_link"] extra_compile_args = ["--extra-compile-args"] extra_link_args = ["--extra-link-args"] extra_objects = ["extra_objects"] define_macros = ["-Ddefines_to_use"] undef_macros = ["-Uundefines_to_use"] py_limited_api = "cp39" # limited API to usehatch-cpp has some convenience integration with CMake. Though this is not designed to be as full-featured as e.g. scikit-build, it should be satisfactory for many small projects.
root = "path/to/cmake/root" build = "path/to/cmake/build/folder" install = "path/to/cmake/install/folder" cmake_arg_prefix = "MYPROJECT_" cmake_args = {} # any other cmake args to pass cmake_env_args = {} # env-specific cmake args to pass include_flags = {} # include flags to pass -Dhatch-cpp is integrated with hatch-build to allow easy configuration of options via command line:
hatch-build \ -- \ --verbose \ --platform linux \ --vcpkg.vcpkg a/path/to/vcpkg.json \ --libraries.0.binding pybind11 \ --libraries.0.include-dirs cpp,another-dirThis CLI is aware of your pyproject.toml-configured setup. To display help for this, run (note the passthrough --):
hatch-build -- --helpFor example, for the test_project_basic in this project's tests folder:
hatch-build --hooks-only -- --help [sdist] [wheel] [2025-11-11T17:31:06-0500][p2a][WARNING]: Only dicts with str, int, float, bool, or enum values are supported - field `cmake_env_args` got value type typing.Dict[str, str] usage: hatch-build-extras-model [-h] [--verbose] [--name NAME] [--libraries.0.name LIBRARIES.0.NAME] [--libraries.0.sources.0 LIBRARIES.0.SOURCES.0] [--libraries.0.sources LIBRARIES.0.SOURCES] [--libraries.0.language LIBRARIES.0.LANGUAGE] [--libraries.0.binding LIBRARIES.0.BINDING] [--libraries.0.std LIBRARIES.0.STD] [--libraries.0.include-dirs.0 LIBRARIES.0.INCLUDE_DIRS.0] [--libraries.0.include-dirs LIBRARIES.0.INCLUDE_DIRS] [--libraries.0.library-dirs LIBRARIES.0.LIBRARY_DIRS] [--libraries.0.libraries LIBRARIES.0.LIBRARIES] [--libraries.0.extra-compile-args LIBRARIES.0.EXTRA_COMPILE_ARGS] [--libraries.0.extra-link-args LIBRARIES.0.EXTRA_LINK_ARGS] [--libraries.0.extra-objects LIBRARIES.0.EXTRA_OBJECTS] [--libraries.0.define-macros LIBRARIES.0.DEFINE_MACROS] [--libraries.0.undef-macros LIBRARIES.0.UNDEF_MACROS] [--libraries.0.export-symbols LIBRARIES.0.EXPORT_SYMBOLS] [--libraries.0.depends LIBRARIES.0.DEPENDS] [--libraries.0.py-limited-api LIBRARIES.0.PY_LIMITED_API] [--cmake.root CMAKE.ROOT] [--cmake.build CMAKE.BUILD] [--cmake.install CMAKE.INSTALL] [--cmake.cmake-arg-prefix CMAKE.CMAKE_ARG_PREFIX] [--cmake.cmake-args CMAKE.CMAKE_ARGS] [--cmake.include-flags CMAKE.INCLUDE_FLAGS] [--platform.cc PLATFORM.CC] [--platform.cxx PLATFORM.CXX] [--platform.ld PLATFORM.LD] [--platform.platform PLATFORM.PLATFORM] [--platform.toolchain PLATFORM.TOOLCHAIN] [--platform.disable-ccache] [--vcpkg.vcpkg VCPKG.VCPKG] [--vcpkg.vcpkg-root VCPKG.VCPKG_ROOT] [--vcpkg.vcpkg-repo VCPKG.VCPKG_REPO] [--vcpkg.vcpkg-triplet VCPKG.VCPKG_TRIPLET] [--build-type BUILD_TYPE] [--commands COMMANDS] options: -h, --help show this help message and exit --verbose --name NAME --libraries.0.name LIBRARIES.0.NAME --libraries.0.sources.0 LIBRARIES.0.SOURCES.0 --libraries.0.sources LIBRARIES.0.SOURCES --libraries.0.language LIBRARIES.0.LANGUAGE --libraries.0.binding LIBRARIES.0.BINDING --libraries.0.std LIBRARIES.0.STD --libraries.0.include-dirs.0 LIBRARIES.0.INCLUDE_DIRS.0 --libraries.0.include-dirs LIBRARIES.0.INCLUDE_DIRS --libraries.0.library-dirs LIBRARIES.0.LIBRARY_DIRS --libraries.0.libraries LIBRARIES.0.LIBRARIES --libraries.0.extra-compile-args LIBRARIES.0.EXTRA_COMPILE_ARGS --libraries.0.extra-link-args LIBRARIES.0.EXTRA_LINK_ARGS --libraries.0.extra-objects LIBRARIES.0.EXTRA_OBJECTS --libraries.0.define-macros LIBRARIES.0.DEFINE_MACROS --libraries.0.undef-macros LIBRARIES.0.UNDEF_MACROS --libraries.0.export-symbols LIBRARIES.0.EXPORT_SYMBOLS --libraries.0.depends LIBRARIES.0.DEPENDS --libraries.0.py-limited-api LIBRARIES.0.PY_LIMITED_API --cmake.root CMAKE.ROOT --cmake.build CMAKE.BUILD --cmake.install CMAKE.INSTALL --cmake.cmake-arg-prefix CMAKE.CMAKE_ARG_PREFIX --cmake.cmake-args CMAKE.CMAKE_ARGS --cmake.include-flags CMAKE.INCLUDE_FLAGS --platform.cc PLATFORM.CC --platform.cxx PLATFORM.CXX --platform.ld PLATFORM.LD --platform.platform PLATFORM.PLATFORM --platform.toolchain PLATFORM.TOOLCHAIN --platform.disable-ccache --vcpkg.vcpkg VCPKG.VCPKG --vcpkg.vcpkg-root VCPKG.VCPKG_ROOT --vcpkg.vcpkg-repo VCPKG.VCPKG_REPO --vcpkg.vcpkg-triplet VCPKG.VCPKG_TRIPLET --build-type BUILD_TYPE --commands COMMANDS hatch-cpp will respect standard environment variables for compiler control, e.g. CC, CXX, LD, CMAKE_GENERATOR, OSX_DEPLOYMENT_TARGET, etc.
Note
This library was generated using copier from the Base Python Project Template repository.