Modern, PEP 517 compliant build backend for creating Python packages with
Project description
py-build-cmake
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 and nanobind, with stable ABI support
- Stub generation for type checking and autocompletion
- Customizable CMake configuration, build, and installation options
- Support for multiple installation configurations and components, across different Wheel packages
- First-class cross-compilation support
- Reproducible 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"
readme = "README.md"
requires-python = ">=3.7"
license = { "file" = "LICENSE" }
authors = [{ "name" = "Pieter P", "email" = "pieter.p.dev@outlook.com" }]
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.2.0a1"]
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
.
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.
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:
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 thesysconfig
anddistutils
modules
Planned features
-
macOS support -
Entry point support - Namespace package support (PEP 420)
- Doxygen and Sphinx support
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for py_build_cmake-0.2.0a1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | e8bcd25c983e8230a7f85052392c7d7f2f94b9cb0b87e66607a69ca70cb2fe28 |
|
MD5 | caf900a0dff8125dea5ce1937f0b5a6c |
|
BLAKE2b-256 | 5663966ff64bd1edd9fdd8ccd140503b1b74713946a6b3ad201c3529354f5239 |