hatch-cpp

Hatch plugin for C++ builds

Overview

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

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.

Library Arguments

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 use

CMake Arguments

hatch-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 -D

Linking an extension against a library

A generic library can ship next to the extension that links it, in the layout pyarrow uses. List the library first and name it in the extension's depends:

[[tool.hatch.build.hooks.hatch-cpp.libraries]]
name = "project/lib/libdemo"
sources = ["cpp/demo.c"]
language = "c"
binding = "generic"
include-dirs = ["cpp/include"]
define-macros = ["DEMO_BUILD"]

[[tool.hatch.build.hooks.hatch-cpp.libraries]]
name = "project/extension"
sources = ["cpp/extension.c"]
language = "c"
include-dirs = ["cpp/include"]
depends = ["project/lib/libdemo"]

The library builds first. On Linux it gets -soname libdemo.so and on macOS the install name @rpath/libdemo.dylib, unless extra-link-args already set one. The extension links the built file and gets an rpath to its directory ($ORIGIN/lib, @loader_path/lib), so the wheel works wherever it is installed. On Windows the extension links the import library project/lib/libdemo.lib, which is packaged next to the DLL. Windows has no rpath, so the package __init__.py must call os.add_dll_directory on lib/ before importing the extension, and the library's header must mark its functions __declspec(dllexport) when building it and __declspec(dllimport) otherwise. depends is not supported for Emscripten builds.

library-source (or HATCH_CPP_LIBRARY_SOURCE, which wins) picks how libraries named in depends are provided:

bundled (default): built and shipped in the wheel as above.
external: not built. Each one is found under library-root (or HATCH_CPP_LIBRARY_ROOT) with lib/ and include/, through pkg-config = "demo", or under $PREFIX/$CONDA_PREFIX (Library/ on Windows), by its name without the lib prefix. The extension links it with -L/-l and gets no rpath, so the packager supplies the runtime path; this is the mode a conda recipe uses. Validation fields on the entry check the external library.
direct: not built. Its sources, include directories, and macros are compiled into each entry that depends on it, and no library ships. Use this for Pyodide.

static and python-package are not supported yet.

Wheel repair tools need to leave the bundled library in place: auditwheel repair --exclude 'libdemo.so', delocate-wheel --exclude libdemo, delvewheel repair --exclude libdemo.dll.

C ABI validation

A library that other code links against can be checked after it is built. Validation reads the export table from the binary, so it also works for cross builds and Pyodide. The field names match hatch-rs and come from hatch-native.

Set the fields on a libraries entry:

[[tool.hatch.build.hooks.hatch-cpp.libraries]]
name = "project/lib/libdemo"
sources = ["cpp/demo.c"]
language = "c"
binding = "generic"
include-dirs = ["cpp/include"]
expected-headers = ["cpp/include/demo/demo.h"]
header-symbol-prefix = "demo_"           # every demo_* function in the headers must be exported
expected-abi-strings = ["DEMO_ABI_VERSION 1"]
expected-symbols = []                    # extra symbols to require
validate = false                         # also load the library with ctypes

Or list artifacts to validate files that libraries does not name, such as the output of a CMake install. Each entry takes the same fields plus name and an optional path relative to the project root. Without path, name matches a libraries entry, or else the one packaged file called lib<name>.so, lib<name>.dylib, or <name>.dll:

[[tool.hatch.build.hooks.hatch-cpp.artifacts]]
name = "demo"
expected-headers = ["project/include/demo/demo.h"]
header-symbol-prefix = "demo_"

validation-commands run after the checks, with {name}, {path}, and {header} substituted and HATCH_CPP_ARTIFACT_NAME and HATCH_CPP_ARTIFACT_PATH in the environment.

To record what was packaged, set artifact-manifest = true and artifact-manifest-destination = "project/lib/hatch-cpp-artifacts.json". The JSON lists each packaged binary with its role (python-extension or library), platform, and profile, and is added to the wheel.

CLI

hatch-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-dir

This CLI is aware of your pyproject.toml-configured setup. To display help for this, run (note the passthrough --):

hatch-build -- --help

For 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

Environment Variables

hatch-cpp will respect standard environment variables for compiler control, e.g. CC, CXX, LD, CMAKE_GENERATOR, OSX_DEPLOYMENT_TARGET, etc.

Pyodide

Pyodide builds are detected from PYODIDE_ABI_VERSION. The hook preserves Pyodide's Emscripten compiler wrappers, gives extension modules CPython's Emscripten suffix, and emits the corresponding pyemscripten wheel platform tag. No project-specific build hook is required.

[tool.hatch.build.hooks.hatch-cpp]
libraries = [
    {name = "project/extension", sources = ["cpp/extension.cpp"], binding = "pybind11"},
]

[tool.cibuildwheel.pyodide]
test-command = "python -c 'from project.extension import answer; assert answer() == 42'"

When a vcpkg.json manifest is active, Emscripten builds use vcpkg's wasm32-emscripten community triplet. Package support varies by port.

Note

This library was generated using copier from the Base Python Project Template repository.

Name		Name	Last commit message	Last commit date
.github		.github
hatch_cpp		hatch_cpp
.copier-answers.yaml		.copier-answers.yaml
.gitattributes		.gitattributes
.gitignore		.gitignore
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
pyproject.toml		pyproject.toml

Navigation Menu

Repository navigation

About

Repository files navigation

hatch-cpp

Overview

Configuration

Library Arguments

CMake Arguments

Linking an extension against a library

C ABI validation

CLI

Environment Variables

Pyodide

About

Releases

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

hatch-cpp

Overview

Configuration

Library Arguments

CMake Arguments

Linking an extension against a library

C ABI validation

CLI

Environment Variables

Pyodide

About

Topics

Resources

Code of conduct

Stars

Watchers

Forks

Releases

Contributors

Languages