cmake-pip

CMake bindings to pip made simple.

This project makes easy the creation and distribution of python packages with extensions built with CMake and with complex set of dependencies through its integration with conan.

Why using cmake-pip

Python extension system through setuptools is simple and effective, but hardly scales up beyond a few source files, and does not handle dependencies that are outside the python ecosystem well: linking the python extension to eg. a system library makes the packaging less portable and harder to maintain.

CMake is a mature tool for defining C/C++ projects with more than 2 decades of updates and running, it is widely accepted as an industry standard for building simple or complex projects, in a platform agnostic way. It provides a wide spectrum of features and integration with libraries and compilers.

Your own C/C++ library is just one side of the story: a common case is when a project needs to integrate with features provided by libraries that are external to your project. CMake usually integrates well with this, but performs not so well when several projects, each with their own build infrastructure, variables, options... are involved. And this is where conan shines: its simplicity for injecting external projects to yours and its great community support provides you the missing piece in the C/C++ world for constructing software with complex dependencies.

Documentation

The full documentation of cmake-pip is available online — start with the worked examples, each of which is a fixture of the test suite and installs end-to-end.

Features

• one declaration in setup.py, plain modern CMake on the project side
• wheels, source distributions and PEP 660 editable installs
• version injection into the cmake configuration (setuptools_scm friendly)
• relocatable packages: rpath rewriting, runtime dependency collection, and linux soname mangling of the vendored libraries
• conan integration: dependencies declared in setup.py, recipes pulled from conan-center-index at a pinned revision, self-provisioned CONAN_HOME
• build only what the wheel needs (the cmake_pip_target umbrella target) and optionally run the project's ctest suite before anything is staged

How to use

The interface is made very simple:

1. on the setup.py/pyproject.toml side, use a specific extension to instruct the python packaging system about CMake and conan dependencies.

   For your pyproject.toml, you just need to specify a build dependency:

   [build-system]
      requires = ["setuptools", "cmake-pip"]
   

   On the setup.py, declare your CMake project and instruct setuptools as follow:

   # setup.py -- everything else lives in pyproject.toml
   from setuptools import setup
   from cmake_pip.cmake_extension import ExtensionCMake
   
   my_cmake_extensions = ExtensionCMake(
    "my_package.my_extensions",
    "my_cmake_project/CMakeLists.txt",
    cmake_install_component="python_ext_component")
   
   setup(ext_modules=[my_cmake_extensions])
   

2. on the cmake side: use directives to declare the content of a python package,

   # this declares "python_package_add_target" and is provided
   # by cmake-pip
   find_package(cmakepip)
   
   python3_add_library(my_module1 MODULE
       src/my_module1.cpp)
   python3_add_library(my_module2 MODULE
       src/my_module2.cpp)
   
   python_package_add_target(TARGET my_module1
                             DESTINATION my_extensions/
                             PYTHON_PACKAGE python_ext_component)
   python_package_add_target(TARGET my_module2
                             DESTINATION my_extensions/
                             PYTHON_PACKAGE python_ext_component)
   

Et voilà! With very little changes to your CMake and python package side, you can define a python package with many python extensions. No need to specify those in the python package, cmake-pip takes care of it. No need also to package the shared libraries your extensions depend on, neither complicated renaming: cmake-pip is there for this.