{"id":4907,"library":"cmake-build-extension","title":"Setuptools extension to build and package CMake projects","description":"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.","status":"active","version":"0.6.1","language":"en","source_language":"en","source_url":"https://github.com/diegoferigo/cmake-build-extension","tags":["build-system","cmake","setuptools","cpp-extension","packaging","hybrid-projects","python-bindings"],"install":[{"cmd":"pip install cmake-build-extension","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required Python version.","package":"python","optional":false},{"reason":"This library is a setuptools extension, hence setuptools is a core dependency for its functionality.","package":"setuptools","optional":false},{"reason":"CMake 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.","package":"cmake","optional":false}],"imports":[{"symbol":"BuildExtension","correct":"from cmake_build_extension import BuildExtension"},{"symbol":"CMakeExtension","correct":"from cmake_build_extension import CMakeExtension"}],"quickstart":{"code":"from setuptools import setup, find_packages\nfrom cmake_build_extension import BuildExtension, CMakeExtension\n\n# --- Minimal Example setup.py ---\n# This assumes a C++ project structured like:\n# myproject/\n# |-- CMakeLists.txt\n# |-- src/my_cpp_lib.cpp\n# |-- python/\n#     `-- my_python_package/\n#         `-- __init__.py\n\nsetup(\n    name=\"my-hybrid-package\",\n    version=\"0.1.0\",\n    packages=find_packages(where=\"python\"),\n    package_dir={'': \"python\"},\n    ext_modules=[\n        CMakeExtension(\n            name=\"MyProject\", # Corresponds to a CMake target or project name\n            install_prefix=\"my_python_package\", # Where to install CMake artifacts within the Python package\n            cmake_configure_options=[\n                \"-DBUILD_SHARED_LIBS=ON\",\n                # Additional CMake options can be passed here\n            ],\n            # Optional: Specify a CMake component to install\n            # cmake_install_component=\"my_component\",\n        ),\n    ],\n    cmdclass=dict(build_ext=BuildExtension),\n    zip_safe=False, # Often required for packages containing C extensions\n)","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade Python to 3.7+ or pin cmake-build-extension to <0.6.0.","message":"Support 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.","severity":"breaking","affected_versions":">=0.6.0"},{"fix":"Review your `setup.py` and any `CMAKE_ARGS` environment variables for generator specification. Utilize the `cmake_configure_options` in `CMakeExtension` for explicit control.","message":"When 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.","severity":"gotcha","affected_versions":">=0.6.0"},{"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.","message":"It 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Thoroughly test package installation and import in isolated environments. For `manylinux` wheels, use tools like `auditwheel` or CI solutions like `cibuildwheel`.","message":"If 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}