Welcome to CMake Python Distributions’s documentation!¶

CMake is used to control the software compilation process using simple platform and compiler independent configuration files, and generate native makefiles and workspaces that can be used in the compiler environment of your choice.

The suite of CMake tools were created by Kitware in response to the need for a powerful, cross-platform build environment for open-source projects such as ITK and VTK.

The CMake python wheels provide CMake 3.27.5.

Installation¶

Install package with pip¶

To install with pip:

$ pip install cmake

Install from source¶

See Building the CMake Python wheel

Dependencies¶

Python Packages¶

The development dependencies (for testing and coverage) are:

-r requirements-test.txt
-r requirements-repair.txt

Usage¶

After installing the package using pip, the executables cmake, cpack and ctest will be available in the PATH and can be used to configure and build any projects.

Building the CMake Python wheel¶

Overview¶

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

It provides a setup.py and allows to create both source and binary distributions of CMake.

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:

mkvirtualenv build-cmake
pip install -r requirements-dev.txt
python setup.py bdist_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 setup.py sdist

Binary distribution (build, bdist, bdist_wheel)¶

The project has two mode of operations:

build CMake from source (BUILD_CMAKE_FROM_SOURCE set to ON)
download CMake binaries (BUILD_CMAKE_FROM_SOURCE set to OFF)

The binary distribution is generated using the following command:

python setup.py bdist_wheel

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

python setup.py bdist_wheel -- -DBUILD_CMAKE_FROM_SOURCE:BOOL=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 setup.py bdist_wheel -- -DBUILD_VERBOSE:BOOL=1

list of files copied into the distributions¶

By default, the complete list of files copied into the distributions are reported. This can be changed passing the --hide-listing option:

python setup.py --hide-listing sdist
python setup.py --hide-listing bdist_wheel

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 -DCMakePythonDistributions_ARCHIVE_DOWNLOAD_DIR:PATH=/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 setup.py bdist_wheel -- \
   -DCMakePythonDistributions_ARCHIVE_DOWNLOAD_DIR:PATH=/path/to/cache \
   -DCMakeProject_BINARY_DIR:PATH=/path/to/standalone-build

Understanding the Build-system¶

CMakeLists.txt¶

The build system is described by the CMakeLists.txt and is composed of few projects each responsible for a specific task. Once configured, the Outer Project is responsible for driving the overall build composed of multiple project called external project. Here is the list of external project:

CMakeProject-src-download
CMakeProject-binary-download
CMakeProject-build
CMakePythonDistributions: This corresponds to the Inner Project represented below.

The flow chart represented below illustrates which external projects are included based on the configure options and describes the role of each one:

Name	Description
CMakeLists	See CMakeLists.txt
Download source ?	If option `CMakeProject_SOURCE_DIR` is set, skip source download.
Download Source archive	External project downloading archives from https://cmake.org/files/.
Re-use source directory	Empty external project.
Build from Source ?	Answer based on option `BUILD_CMAKE_FROM_SOURCE`
CMakeProject-binary-download	External project downloading pre-built binary archives from https://cmake.org/files/.
CMakeProject-build	External project building CMake from source.
Strip executables	If possible, reduce wheel size stripping cmake, cpack and ctest executables
Which files to install?	Answer based on option `BUILD_CMAKE_FROM_SOURCE`
Install prebuilt binaries	Recursively glob all files and explicitly add install rules.
Install CMake project	Achieved by including `${CMakeProject_BINARY_DIR}/cmake_install.cmake`.

Contributing¶

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.

Types of Contributions¶

You can contribute in many ways:

Report Bugs¶

Report bugs at https://github.com/scikit-build/cmake-python-distributions/issues.

If you are reporting a bug, please include:

Your operating system name and version.
Any details about your local setup that might be helpful in troubleshooting.
Detailed steps to reproduce the bug.

Fix Bugs¶

Look through the GitHub issues for bugs. Anything tagged with “bug” is open to whoever wants to implement it.

Implement Features¶

Look through the GitHub issues for features. Anything tagged with “feature” is open to whoever wants to implement it.

Write Documentation¶

The cmake-python-distributions project could always use more documentation. We welcome help with the official cmake-python-distributions docs, in docstrings, or even on blog posts and articles for the web.

Submit Feedback¶

The best way to send feedback is to file an issue at https://github.com/scikit-build/cmake-python-distributions/issues.

If you are proposing a new feature:

Explain in detail how it would work.
Keep the scope as narrow as possible, to make it easier to implement.
Remember that this is a volunteer-driven project, and that contributions are welcome :)

Get Started¶

Ready to contribute? Here’s how to set up cmake-python-distributions for local development.

Fork the cmake-python-distributions repo on GitHub.

Clone your fork locally:

$ git clone git@github.com:your_name_here/cmake-python-distributions.git

Make sure you have nox installed (preferably use pipx or brew (macOS) if you have those):
```
$ pip install nox
$ cd cmake-python-distributions/
```
Create a branch for local development:
```
$ git checkout -b name-of-your-bugfix-or-feature
```
Now you can make your changes locally.
When you’re done making changes, check that your changes pass linters and the tests:
```
$ nox
```

Commit your changes and push your branch to GitHub:

$ git add .
$ git commit -m "Your detailed description of your changes."
$ git push origin name-of-your-bugfix-or-feature

Submit a pull request through the GitHub website.

Pull Request Guidelines¶

Before you submit a pull request, check that it meets these guidelines:

The pull request should include tests.
If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.rst.
The pull request should work for Python 2.7, and 3.6+. Check `GitHub Actions https://github.com/scikit-build/cmake-python-distributions/actions/workflows/build.yml`_ and make sure that the tests pass for all supported Python versions.

Tips¶

To run a subset of tests:

    $ pytest tests/test_cmake.py
# OR
$ nox -s tests -- tests/test_cmake.py

Credits¶

Please see the GitHub project page at https://github.com/scikit-build/cmake-python-distributions/graphs/contributors

History¶

cmake-python-distributions was initially developed in September 2016 by Jean-Christophe Fillion-Robin to facilitate the distribution of project using scikit-build and depending on CMake.

Updating the CMake version¶

A developer should use the following steps to update the version X.Y.Z of CMake associated with the current CMake python distributions.

Available CMake archives can be found at https://cmake.org/files.

Nox procedure¶

If using nox, run:

nox -s bump -- <version>

And follow the instructions it gives you. Leave off the version to bump to the latest version. Add –commit to run the commit procedure.

Classic procedure:¶

Install requests:
```
$ pip install requests
```

Execute scripts/update_cmake_version.py command line tool with the desired X.Y.Z CMake version available for download. For example:

$ release=3.27.5
$ ./scripts/update_cmake_version.py $release
Collecting URLs and SHA256s from 'https://api.github.com/repos/Kitware/CMake/releases/tags/v3.27.5'
[...]
Collecting URLs and SHA256s from 'https://api.github.com/repos/Kitware/CMake/releases/tags/v3.27.5' - done
Updating 'CMakeUrls.cmake' with CMake version 3.27.5
Updating 'CMakeUrls.cmake' with CMake version 3.27.5 - done
Updating docs/index.rst
Updating docs/index.rst - done
Updating README.rst
Updating README.rst - done
Updating tests/test_distribution.py
Updating tests/test_distribution.py - done

Create a topic named update-to-cmake-X.Y.Z and commit the changes. For example:

release=3.27.5
git switch -c update-to-cmake-$release
git add -u CMakeUrls.cmake docs/index.rst README.rst tests/test_distribution.py docs/update_cmake_version.rst
git commit -m "Update to CMake $release"

Push the topic and create a Pull Request.
If all CI tests are passing, merge the topic and consider making a new release.

Making a release¶

A core developer should use the following steps to create a release X.Y.Z of cmake-python-distributions on PyPI.

This is usually done after Updating the CMake version.

Prerequisites¶

All CI tests are passing on GitHub Actions.
You have a GPG signing key.

Documentation conventions¶

The commands reported below should be evaluated in the same terminal session.

Commands to evaluate starts with a dollar sign. For example:

$ echo "Hello"
Hello

means that echo "Hello" should be copied and evaluated in the terminal.

PyPI: Step-by-step¶

Make sure that all CI tests are passing on GitHub Actions.
Download the latest sources

$ cd /tmp && \
  git clone git@github.com:scikit-build/cmake-python-distributions cmake-python-distributions-release && \
  cd cmake-python-distributions-release

List all tags sorted by version

$ git fetch --tags && \
  git tag -l | sort -V

Choose the next release version number

$ release=X.Y.Z
Warning

To ensure the packages are uploaded on PyPI, tags must match this regular expression: ^[0-9]+(\.[0-9]+)*(\.post[0-9]+)?$.

Tag the release

$ git tag --sign -m "cmake-python-distributions $release" $release master
Warning

We recommend using a GPG signing key to sign the tag.

Publish the release tag

$ git push origin $release
Note

This will trigger builds on each CI services and automatically upload the wheels and source distribution on PyPI.

Check the status of the builds on GitHub Actions.
Once the builds are completed, check that the distributions are available on PyPI.
Make a GitHub release based on the tag. This will display the latest version in the GitHub sidebar, and will notify release watchers of the release. Title it Version X.Y.Z and add a little note about what changed (Python only).
Create a clean testing environment to test the installation

$ pushd $(mktemp -d) && \
  mkvirtualenv cmake-$release-install-test && \
  pip install cmake && \
  cmake --version
Note

If the mkvirtualenv command is not available, this means you do not have virtualenvwrapper installed, in that case, you could either install it or directly use virtualenv or venv.

Cleanup

$ popd && \
  deactivate  && \
  rm -rf dist/* && \
  rmvirtualenv cmake-$release-install-test

Indices and tables¶

Resources¶

This project is maintained by Jean-Christophe Fillion-Robin from Kitware Inc. It is covered by the Apache License, Version 2.0.

CMake is distributed under the OSI-approved BSD 3-clause License. For more information about CMake, visit http://cmake.org

Documentation: http://cmake-python-distributions.readthedocs.io/en/latest/
Source code: https://github.com/scikit-build/cmake-python-distributions
Mailing list: https://groups.google.com/forum/#!forum/scikit-build

Welcome to CMake Python Distributions’s documentation!¶

Installation¶

Install package with pip¶

Install from source¶

Dependencies¶

Python Packages¶

Usage¶

Building the CMake Python wheel¶

Overview¶

Prerequisites¶

Quick start¶

Source distribution (sdist)¶

Binary distribution (build, bdist, bdist_wheel)¶

Default value for BUILD_CMAKE_FROM_SOURCE¶

Controlling verbosity¶

configure and build output¶

list of files copied into the distributions¶

Optimizations¶

Caching downloads¶

Re-using build tree¶

Understanding the Build-system¶

CMakeLists.txt¶

Contributing¶

Types of Contributions¶

Report Bugs¶

Fix Bugs¶

Implement Features¶

Write Documentation¶

Submit Feedback¶

Get Started¶

Pull Request Guidelines¶

Tips¶

Credits¶

History¶

Updating the CMake version¶

Nox procedure¶

Classic procedure:¶

Making a release¶

Prerequisites¶

Documentation conventions¶

PyPI: Step-by-step¶

Indices and tables¶

Resources¶

Default value for `BUILD_CMAKE_FROM_SOURCE`¶