Building the CMake Python wheel#

Overview#

This project has been designed to work with scikit-build-core.

This is done ensuring source files and build artifacts are copied and/or generated in expected locations.

Prerequisites#

In addition of Git, Python and CMake, building the wheel with BUILD_CMAKE_FROM_SOURCE set to ON also requires a C++ Compiler.

Quick start#

Build the CMake Python wheel with the following command:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements-dev.txt build
python -m build --wheel

Source distribution (sdist)#

CMake sources will always be downloaded in the <ROOT>/src directory.

This will ensure that the rules specified in <ROOT>/MANIFEST.in can successfully glob the source files.

The source distribution is generated using the following command:

python -m build --sdist

Binary distribution (build, bdist, bdist_wheel)#

The project has two mode of operations:

  1. build CMake from source (BUILD_CMAKE_FROM_SOURCE set to ON)

  2. download CMake binaries (BUILD_CMAKE_FROM_SOURCE set to OFF)

The binary distribution is generated using the following command:

python -m build --wheel

Changing the default mode is achieved by explicitly passing the option to CMake:

python -m build --wheel -Ccmake.define.BUILD_CMAKE_FROM_SOURCE=ON

Default value for BUILD_CMAKE_FROM_SOURCE#

Depending on the platform, option BUILD_CMAKE_FROM_SOURCE has different default:

  • Linux: ON

  • MacOSX: OFF

  • Windows: OFF

Controlling verbosity#

configure and build output#

By default, the output associated to the configure and build steps of the CMakeProject-build external project are logged into files. This can be changed by setting the BUILD_VERBOSE option:

python -m build --wheel -Ccmake.define.BUILD_VERBOSE=ON

Optimizations#

On a given platform, when building different “flavor” of CMake python wheels (one for each <python tag>-<abi> tag), the whole process can be made faster in two ways.

Caching downloads#

To avoid the re-download of CMake sources and/or binary packages, passing the option -Ccmake.define.CMakePythonDistributions_ARCHIVE_DOWNLOAD_DIR=/path/to/cache enables successive build to re-use existing archives instead of re-downloading them.

Re-using build tree#

And finally, on a given platform, to avoid rebuilding CMake, the idea is to first create a standalone build of the CMake project and then building the wheel using it.

Step 1: Standalone build:

mkdir -p standalone-build && cd $_
cmake -DCMakePythonDistributions_ARCHIVE_DOWNLOAD_DIR:PATH=/path/to/cache -G Ninja ../

Step 2: Faster build reusing download and build directories:

python -m build -Ccmake.define.CMakePythonDistributions_ARCHIVE_DOWNLOAD_DIR=/path/to/cache
                -Ccmake.define.CMakeProject_BINARY_DIR=/path/to/standalone-build