Metadata-Version: 2.5
Name: hatch-cpp
Version: 0.6.0
Summary: Hatch plugin for C++ builds
Project-URL: Repository, https://github.com/python-project-templates/hatch-cpp
Project-URL: Homepage, https://github.com/python-project-templates/hatch-cpp
Author-email: the hatch-cpp authors <t.paine154@gmail.com>
License: Apache-2.0
License-File: LICENSE
Keywords: build,c++,cmake,cpp,hatch,python
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.10
Requires-Dist: hatch-build<0.6,>=0.5
Requires-Dist: hatch-native<0.2,>=0.1.0
Requires-Dist: hatchling
Requires-Dist: pkn
Requires-Dist: pydantic
Provides-Extra: develop
Requires-Dist: build; extra == 'develop'
Requires-Dist: bump-my-version; extra == 'develop'
Requires-Dist: check-dist; extra == 'develop'
Requires-Dist: codespell; extra == 'develop'
Requires-Dist: hatch-build>=0.3.2; extra == 'develop'
Requires-Dist: hatchling; extra == 'develop'
Requires-Dist: mdformat; extra == 'develop'
Requires-Dist: mdformat-myst; extra == 'develop'
Requires-Dist: mdformat-tables>=1; extra == 'develop'
Requires-Dist: nanobind; extra == 'develop'
Requires-Dist: pybind11; extra == 'develop'
Requires-Dist: pytest; extra == 'develop'
Requires-Dist: pytest-cov; extra == 'develop'
Requires-Dist: ruff; extra == 'develop'
Requires-Dist: toml; extra == 'develop'
Requires-Dist: twine; extra == 'develop'
Requires-Dist: ty; extra == 'develop'
Requires-Dist: uv; extra == 'develop'
Requires-Dist: wheel; extra == 'develop'
Description-Content-Type: text/markdown

# hatch-cpp

Hatch plugin for C++ builds

[![Build Status](https://github.com/python-project-templates/hatch-cpp/actions/workflows/build.yaml/badge.svg?branch=main&event=push)](https://github.com/python-project-templates/hatch-cpp/actions/workflows/build.yaml)
[![codecov](https://codecov.io/gh/python-project-templates/hatch-cpp/branch/main/graph/badge.svg)](https://codecov.io/gh/python-project-templates/hatch-cpp)
[![License](https://img.shields.io/github/license/python-project-templates/hatch-cpp)](https://github.com/python-project-templates/hatch-cpp)
[![PyPI](https://img.shields.io/pypi/v/hatch-cpp.svg)](https://pypi.python.org/pypi/hatch-cpp)

## Overview

A simple, extensible C++ build plugin for [hatch](https://hatch.pypa.io/latest/).

```toml
[tool.hatch.build.hooks.hatch-cpp]
libraries = [
    {name = "project/extension", sources = ["cpp/project/basic.cpp"], include-dirs = ["cpp"]}
]
```

For more complete systems, see:

- [scikit-build-core](https://github.com/scikit-build/scikit-build-core)
- [setuptools](https://setuptools.pypa.io/en/latest/userguide/ext_modules.html)

## 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.

```toml
verbose = true
libraries = { Library Args }
cmake = { CMake Args }
platform = { Platform, either "linux", "darwin", or "win32" }
```

See the [test cases](./hatch_cpp/tests/) for more concrete examples.

`hatch-cpp` is driven by [pydantic](https://docs.pydantic.dev/latest/) models for configuration and execution of the build.
These models can themselves be overridden by setting `build-config-class` / `build-plan-class`.

### Library Arguments

```toml
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.

```toml
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`:

```toml
[[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](https://github.com/python-project-templates/hatch-rs) and come from [hatch-native](https://github.com/python-project-templates/hatch-native).

Set the fields on a `libraries` entry:

```toml
[[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`:

```toml
[[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`](https://github.com/python-project-templates/hatch-build) to allow easy configuration of options via command line:

```bash
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 `--`):

```bash
hatch-build -- --help
```

For example, for the `test_project_basic` in this project's `tests` folder:

```raw
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.

```toml
[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](https://copier.readthedocs.io/en/stable/) from the [Base Python Project Template repository](https://github.com/python-project-templates/base).
