cmake-build-extension 0.2.dev5

Setuptools extension to build and package CMake projects

cmake-build-extension

Setuptools extension to build and package CMake projects.

A project MyProject with C++ files that can be compiled with CMake (here MyClass.{h,cpp}) and a Python package (here my_python_package) can be structured as follows:

myproject/
|-- CMakeLists.txt
|-- include
|   `-- MyClass.h
|-- python
|   `-- my_python_package
|       `-- __init__.py
|-- setup.py
`-- src
    `-- MyClass.cpp

The C++ and Python could be independent, even though this hybrid setup usually applies to project that want to provide Python bindings of the C++ libraries.

This extension enables the following:

• Streamlines the interaction of Python packaging and CMake.
• Enables building and packaging a generic CMake project through setuptools.
• Simplifies distributing and consuming C++ / Python hybrid projects.

The following lines of the setup.py script add a build_ext step to the pipeline that compiles and installs the CMake project in the root of the resulting Python package:

from setuptools import find_packages, setup
from cmake_build_extension import BuildExtension, CMakeExtension

setup(
    name="my-python-package",
    packages=find_packages("python"),
    package_dir={'': "python"},
    # ...
    ext_modules=[
        CMakeExtension(name="MyProject",
                       install_prefix="my_python_package",
                       cmake_configure_options=[
                           "-DBUILD_SHARED_LIBS:BOOL=OFF",
                       ]),
    ],
    cmdclass=dict(build_ext=BuildExtension),
)

Note: If CMake also exports the targets, downstream projects can import them by adding the directory of the installed Python package to CMAKE_PREFIX_PATH.

The resulting Python install tree will be something similar to what follows:

site-packages/
`-- my_python_package
    |-- __init__.py
    `-- lib
        |-- cmake
        |   |-- MyProject.cmake
        |   |-- MyProjectTargets.cmake
        |   `-- MyProjectVersion.cmake
        `-- libMyProject.so

This way, if the C++ project also includes Python bindings, they can be generated by your favourite tool and handled with CMake. This is often convenient since CMake typically has powerful modules that simplify the building process, especially for big projects.

Check out examples/swig for a minimal working example.

Usage

Once both CMake project and setup.py are correctly configured, the following commands can be used:

# Install with pip
pip install .
pip install --editable .

# Install with setup.py
python setup.py install .
python setup.py develop .

# Install with pip passing custom CMake options
pip install --global-option="build_ext" --global-option="-DBAR=Foo;VAR=TRUE" .

# Install with setup.py passing custom CMake options
python setup.py install build_ext -D"BAR=Foo;VAR=TRUE"

# Create wheel with pip
pip wheel -w dist .

# Create wheel with setup.py
python setup.py bdist_wheel

# Create wheel with setup.py passing custom CMake options
python setup.py bdist_wheel build_ext -D"BAR=Foo;VAR=TRUE"

If the Python project is compliant with PEP517 and PEP518, pip will use an isolated environment. Note that CMake's find_package will still find resources from the filesystem and it will not be isolated.

Caveats

• Beyond distributing a hybrid C++ / Python project through, e.g., PyPI, this extension simplifies including the exported CMake project in the resulting wheel. This is dependent on how the CMake project is configured and whether it installs in the prefix the exported targets alongside to shared libraries and headers. If everything is in place, the manylinux* guidelines could still work against you. In fact, wheels supporting manylinux2010|manylinux2014 are built with gcc4 that does not support the new C++11 ABIs. In few words, this means that the exported libraries bundled with the wheel cannot be imported in a downstream project using relatevely new C++ standards! For more details visit robotology/idyntree#776. Luckily, the situation changed thanks to the finalization of PEP600, i.e. manylinux2_24 :tada: If you build a PEP600 compliant wheel (nowadays compatible with most of the commonly used distributions), your exported CMake project bundled in the wheel can be successfully imported by either standalone C++ downstream projects by simply configuring CMAKE_INSTALL_PREFIX=/path/to/site-packages/<package_name>, or from other projects using cmake_build_extension using the cmake_depends_on option (example).