py-build-cmake

A modern, PEP 517 compliant build backend for creating Python packages with extensions built using CMake.

Features

• Building and packaging C, C++ or Fortran extension modules for Python using CMake
• Declarative configuration using pyproject.toml (PEP 621)
• Editable/development installations for Python modules (PEP 660)
• Easy integration with pybind11, nanobind and SWIG, with stable ABI support
• Stub generation for type checking and autocompletion
• Customizable CMake configuration, build, and installation options
• Support for installation of multiple configurations and components, across different Wheel packages
• First-class cross-compilation support
• Reproducible Wheels and source distributions
• No dependency on setuptools
• Compatible with cibuildwheel for building Wheels

Installation

The py-build-cmake package is available on PyPI:

pip install py-build-cmake

Documentation

The documentation can be found on https://tttapa.github.io/py-build-cmake.

The format of the configuration file is explained in Config.md.

Alternatively, use the command-line interface to get the documentation for all supported options:

py-build-cmake config format

To get started quickly, have a look at the following section and the README in examples/minimal, which goes over the project structure and the configuration files you'll need.

Usage

If you don't have one already, add a pyproject.toml configuration file to your project's repository. Specify the mandatory project metadata (PyPA: Declaring project metadata), and tell py-build-cmake how to build your CMake project. For example:

[project] # Project metadata
name = "example-project"
requires-python = ">=3.8"
readme = "README.md"
license = "MIT"
license-files = ["LICENSE"]
dependencies = ["numpy"]
dynamic = ["version", "description"]

[build-system] # How pip and other frontends should build this project
requires = ["py-build-cmake~=0.5.1"]
build-backend = "py_build_cmake.build"

[tool.py-build-cmake.module] # Where to find the Python module to package
directory = "src-python"

[tool.py-build-cmake.sdist] # What to include in source distributions
include = ["CMakeLists.txt", "src/*"]

[tool.py-build-cmake.cmake] # How to build the CMake project
build_type = "RelWithDebInfo"
source_path = "src"
build_args = ["-j"]
install_components = ["python_modules"]

[tool.py-build-cmake.stubgen] # Whether and how to generate typed stub files

The README of examples/minimal describes this configuration file in much more detail.

Then use pip, build or another PEP 517 compatible frontend to build and/or install the package.

Build sdist and wheel packages you can upload to PyPI:

python -m pip install -U build
python -m build . # find the sdist and wheel file in the 'dist' folder

Install the package in the current environment:

pip install .    # normal installation
pip install -e . # editable installation

Examples

As an introduction to py-build-cmake, see examples/minimal for a detailed overview of the configuration files and the directory structure, using a very simple Python module as an example.
For a more advanced, real-world example, see examples/pybind11-project and examples/nanobind-project.
Alternatively, SWIG can also be used instead of pybind11 or nanobind, as demonstrated in examples/swig-project.
If you are interested in packaging C/C++/Fortran programs using py-build-cmake, have a look at examples/minimal-program.
See the examples folder for a full list of examples.

A full example that uses the Conan package manager for C++ dependencies, and that uses GitHub Actions to deploy the Wheel packages built by py-build-cmake to PyPI can be found in tttapa/py-build-cmake-example.

Projects using py-build-cmake

If you need more examples, you can look at the following projects using py-build-cmake as their Python build backend:

• alpaqa
• QPALM

Alternatives and related tools

• scikit-build-core: alternative CMake build backend, successor of scikit-build
• meson-python: Meson build backend
• flit: pure-Python packaging tool and build backend
• hatchling: build backend of the Hatch project manager, supports build hooks
• poetry-core: pure-Python build backend for the Poetry package manager
• crossenv: tool to trick setuptools into cross-compiling by monkey patching the sysconfig and distutils modules