Registry / devops / cmake-build-extension

cmake-build-extension

library0.6.1pypypi✓ verified 24d ago

cmake-build-extension is a Setuptools extension designed to simplify the integration of C++ projects based on CMake with Python packaging tools. It enables configuring and building CMake projects directly from `setup.py`, installing their artifacts into the resulting Python package, and passing custom CMake options. The library also provides a context manager for reliable CPython module imports across operating systems. It is currently at version 0.6.1, with releases occurring on an as-needed basis for features and bug fixes.

devops

pip install cmake-build-extension

github ↗package ↗changelog ↗

INSTALL

IMPORT

SIG · CMAKE-BUILD-EXTENS

cmake-build-extension

devopspythonv0.6.1

Install

3.9s avg

Import

699ms

Disk

123MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.6.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.744s · 135MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 3.9s · import 0.654s · 111MB

123MB installed

● package 123MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

BuildExtension

✓ from cmake_build_extension import BuildExtension

CMakeExtension

✓ from cmake_build_extension import CMakeExtension

To use `cmake-build-extension`, you typically define `CMakeExtension` objects within the `ext_modules` list in your `setup.py` and register `BuildExtension` in `cmdclass`. The `CMakeExtension` points to your CMake project and specifies installation details. Ensure your `CMakeLists.txt` is configured to build and install the necessary artifacts.

from setuptools import setup, find_packages from cmake_build_extension import BuildExtension, CMakeExtension # --- Minimal Example setup.py --- # This assumes a C++ project structured like: # myproject/ # |-- CMakeLists.txt # |-- src/my_cpp_lib.cpp # |-- python/ # `-- my_python_package/ # `-- __init__.py setup( name="my-hybrid-package", version="0.1.0", packages=find_packages(where="python"), package_dir={'': "python"}, ext_modules=[ CMakeExtension( name="MyProject", # Corresponds to a CMake target or project name install_prefix="my_python_package", # Where to install CMake artifacts within the Python package cmake_configure_options=[ "-DBUILD_SHARED_LIBS=ON", # Additional CMake options can be passed here ], # Optional: Specify a CMake component to install # cmake_install_component="my_component", ), ], cmdclass=dict(build_ext=BuildExtension), zip_safe=False, # Often required for packages containing C extensions )

Debug

Known issues

breakingSupport for Python 3.6 was removed in version 0.6.0. Projects targeting Python 3.6 will need to stay on an older version of cmake-build-extension or upgrade their Python environment.

fix

Upgrade Python to 3.7+ or pin cmake-build-extension to <0.6.0.

affects: >=0.6.0

gotchaWhen developing with C++ extensions, ensure your CMake project configuration (e.g., `CMAKE_BUILD_TYPE`, generator selection) is correctly handled. Version 0.6.0 improved how users can specify the desired CMake generator, which might affect existing setups.

fix

Review your `setup.py` and any `CMAKE_ARGS` environment variables for generator specification. Utilize the `cmake_configure_options` in `CMakeExtension` for explicit control.

affects: >=0.6.0

gotchaIt is crucial for CMake-based projects to perform out-of-source builds to avoid polluting the source directory and prevent build issues. While `cmake-build-extension` handles this, accidentally running CMake directly in the source directory can lead to problems.

fix

Always use a dedicated build directory for CMake, and ensure your `setup.py` configuration respects this. Consider adding a check to your `CMakeLists.txt` to enforce out-of-source builds.

affects: All versions

gotchaIf your CMake project exports targets or has complex C++ dependencies, downstream Python projects might need to extend their `CMAKE_MODULE_PATH` or use `cmake-build-extension`'s `cmake_depends_on` option. Packaging shared C++ libraries also needs careful consideration for `manylinux` compatibility on Linux.

fix

Thoroughly test package installation and import in isolated environments. For `manylinux` wheels, use tools like `auditwheel` or CI solutions like `cibuildwheel`.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'cmake_build_extension'

The 'cmake-build-extension' Python package is not installed or not accessible in the current Python environment where 'setup.py' is being run, or there's a conflict with a separate 'cmake' Python package.

fix

Install the package using `pip install cmake-build-extension` within your active Python environment. If issues persist, ensure no conflicting 'cmake' Python package is installed, or try installing in a clean virtual environment.

CMake Error: Could not find CMAKE_ROOT !!! CMake has most likely not been installed correctly.

The CMake build tool executable is either not installed on your system, not included in your system's PATH environment variable, or its installation is corrupted.

fix

Install CMake globally on your system (e.g., via your system's package manager, Homebrew on macOS, or the official CMake website) and ensure its binary directory is added to your system's PATH.

command 'cmake' failed: No such file or directory

The 'cmake' command-line tool, which 'cmake-build-extension' relies on, cannot be found by the shell due to it not being installed or not being in the system's PATH.

fix

Install CMake on your operating system and verify that the `cmake` executable is available in your system's PATH. On Linux, this might be `sudo apt-get install cmake`; on macOS, `brew install cmake`; on Windows, install from the official CMake website and ensure 'Add CMake to the system PATH' is selected during installation.

ImportError: cannot import name 'my_cpp_module' from 'my_python_package'

The C++ extension module (e.g., a .so or .pyd file) built by CMake was not correctly installed into the Python package directory, preventing the Python interpreter from finding it at import time.

fix

Ensure your `CMakeExtension` in `setup.py` correctly specifies the output directory for the compiled C++ module, typically within your Python package. `cmake-build-extension` usually handles this by default, but check `CMAKE_RUNTIME_OUTPUT_DIRECTORY` or `CMAKE_LIBRARY_OUTPUT_DIRECTORY` settings in your CMakeLists.txt or custom `CMakeExtension` logic to ensure binaries are placed where Setuptools expects them (e.g., alongside your Python source files or in the appropriate site-packages subdirectory).

Upgrade

Version history

0.6.1latest on PyPI · released Sep 9, 2024

Audit

Dependencies

pythonrequiredRequired Python version.

setuptoolsrequiredThis library is a setuptools extension, hence setuptools is a core dependency for its functionality.

cmakerequiredCMake must be installed and available in the system's PATH for the build process. Version 3.15 or newer is generally recommended for modern CMake features and stability, although 3.4 is cited as a minimum for general stability.

Agent activity

13 hits · last 30 days

node

Resources

githubhttps://github.com/diegoferigo/cmake-build-extension ↗

packagehttps://pypi.org/project/cmake-build-extension/ ↗

changeloghttps://github.com/diegoferigo/cmake-build-extension/releases ↗