Skip to main content

hatch-cpp

Hatch plugin for C++ builds

Build Status codecov License PyPI

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.

Metadata

Release files for hatch-cpp 0.6.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for hatch-cpp 0.6.1
File Size Uploaded Provenance Actions
hatch_cpp-0.6.1.tar.gz 38.9 kB Without provenance Details for hatch_cpp-0.6.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for hatch-cpp 0.6.1
File Interpreter ABI Platform Actions
hatch_cpp-0.6.1-py3-none-any.whl Python 3 none any Details for hatch_cpp-0.6.1-py3-none-any.whl

Total release size: 105.9 kB

Release files / hatch_cpp-0.6.1.tar.gz

Download URL hatch_cpp-0.6.1.tar.gz
Size 38.9 kB
Tags Source
SHA-256 checksum
How to use checksums
16b885a39649b6c3cb2b39410bac97e094c7e474ac78d9c9d8d15a3e3fb8b715
BLAKE2b-256 checksum
How to use checksums
f55ad86c2252477b22ccbaef30570521490b853994eb438a385eb39e00dd8bb8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.13

Release files / hatch_cpp-0.6.1-py3-none-any.whl

Download URL hatch_cpp-0.6.1-py3-none-any.whl
Size 67.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
de558dc058275bc6bbf907713edb66e05650fbd294d6f06f802ccdf357a52ab1
BLAKE2b-256 checksum
How to use checksums
e55d5dbc18fec7213e3b83e233dde4ef2cab193ce5945e338b5925115ac0c860
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.13

Security for hatch-cpp 0.6.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page