Modern, PEP 517 compliant build backend for creating Python packages with extensions built using CMake.
Modern, PEP 517 compliant build backend for creating Python packages with extensions built using CMake.
pyproject.toml
(PEP 621), compatible with
flit
The py-build-cmake package is available on PyPI:
pip install py-build-cmake
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
If you don't have one already, add a pyproject.toml
configuration file to your
project's repository. Specify the metadata required by PEP 621,
and tell py-build-cmake how to build your project. For example:
[project] # Project metadata
name = "example-project"
readme = "README.md"
requires-python = ">=3.7"
license = { "file" = "LICENSE" }
authors = [{ "name" = "Pieter P", "email" = "[email protected]" }]
keywords = ["some", "keywords"]
classifiers = ["Topic :: Scientific/Engineering"]
urls = { "Documentation" = "https://tttapa.github.io/py-build-cmake" }
dependencies = ["numpy"]
dynamic = ["version", "description"]
[build-system] # How pip and other frontends should build this project
requires = ["py-build-cmake~=0.1.8"]
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
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
.
If you are interested in packaging C/C++/Fortran programs using py-build-cmake,
have a look at examples/minimal-program
.
If you need more examples, you can look at the following projects using py-build-cmake as their Python build backend: