Build Python Wheels from your CMake project#

Get Started#

Cmeel follows PEP 621, so packaging a CMake project with cmeel to build Wheels mostly consist of writing a pyproject.toml file with corrects [project] and [build-system] sections, eg.:

[project]
name = "cmeel-example"
version = "0.2.3"
description = "This is an example project, to show how to use cmeel"
readme = "README.md"
requires-python = ">= 3.8"
license = "BSD-2-Clause"
authors = [{name = "Guilhem Saurel", email = "guilhem.saurel@laas.fr"}]

[project.urls]
homepage = "https://github.com/cmake-wheel/cmeel-example"
repository = "https://github.com/cmake-wheel/cmeel-example.git"
changelog = "https://github.com/cmake-wheel/cmeel-example/CHANGELOG.md"

[build-system]
requires = ["cmeel[build]"]
build-backend = "cmeel.build"

PEP 621 Configuration#

Everything required to configure a project is in its pyproject.toml file, especially:

  • in [project] section:

    • name

    • version

    • description

    • keywords

    • license

    • license-files (["LICEN[CS]E*", "COPYING*", "NOTICE*", "AUTHORS*"] are found by default)

    • requires-python (cmeel will set >=3.8 by default if this is omitted)

  • in [project.urls] section:

    • homepage

Build System#

The [build-system] section of pyproject.toml is the way to indicate that cmeel is to be used by python standard build tools:

  • requires must at least contain "cmeel[build]"

  • build-backend must be "cmeel.build"

Dependencies#

Cmeel packages can have dependencies on other python packages, cmeel or not. They have to be declared in the standard dependencies key of the [project] section as a list of strings.

cmeel is automatically added.

Cmeel also accepts an optional-dependencies table for extras.

Readme#

Built wheels will ship the README file in their metadata. The provided content-type for this file will be detected as:

  • markdown if the filename ends with .md (case insensitive),

  • reStructuredText if it ends with .rst (also case insensitive),

  • plain text otherwise.

If this field is not present, Cmeel will try to find a README.md, README.rst, README.txt or a README.

Content-type can also be specified manually with eg. readme = {content-type = "something", file = "readme.sth"}

Cmeel specific Configuration#

Cmeel configuration can be provided by:

  1. pyproject.toml file in cmeel specific keys of the [tool.cmeel] section

  2. $XDG_CONFIG_HOME/cmeel/cmeel.toml (if $XDG_CONFIG_HOME is not set, fallback to ~/.config)

  3. environment variables

Working directories#

Cmeel works in $CMEEL_TEMP_DIR (default to a temporary directory), which contains a bld configure and build directory, and a pfx install directory.

If you want to use build cache, you’ll probably need to set this to a fixed location.

Patch step#

Cmeel will automatically apply a cmeel.patch provided at the root of the project if it exists. If cmeel try to apply this patch, and detect that it was already applied, it shouldn’t complain about it.

CMake configure step#

CMake arguments is a list of strings generated by concatenation of:

  1. Cmeel defaults

  2. -DBUILD_TESTING=OFF if run-tests is off.

  3. configure-args key in the [tool.cmeel] section of local pyproject.toml

  4. configure-args key in global cmeel.toml

  5. configure-args key in the project section in global cmeel.toml

  6. CMEEL_CMAKE_ARGS environment variable, splitted

This configuration step is done in the environment defined by:

  1. The environment of the calling process

  2. If installed cmeel packages are detected, prepend CMAKE_PREFIX_PATH with their installation path, and PKG_CONFIG_PATH if relevant.

Test step#

This configuration step is done in the environment defined by:

  1. The environment of the calling process

  2. CTEST_OUTPUT_ON_FAILURE=1

  3. CTEST_PARALLEL_LEVEL set to test-jobs global configuration, or CMEEL_TEST_JOBS environment variable, or 4

Other options in [tool.cmeel] section of pyproject.toml#

source#

String providing the main CMake source directory for this project. "." by default.

run-tests#

Boolean setting to run tests. true by default. Can be overrided by CMEEL_RUN_TESTS environment variable.

run-tests-after-install#

Boolean setting to run tests after the installation instead of before, if they run. false by default.

build-number#

Integer which acts as a tie-breaker if two wheel file names are the same. 0 by default.

test-cmd#

List of string providing the test command and its arguments. ["cmake", "--build", "BUILD_DIR", "-t", "test"] by default. BUILD_DIR is replaced by the current path to the build directory.

has-binaries#

Boolean setting to build wheels with architecture-dependent binaries. true by default.

has-sitelib#

Boolean setting to build wheels which include content in python sitelib. true by default.

any#

⚠️ DEPRECATED: Please use has-binaries = false and has-sitelib = false

Boolean setting to build a wheel for py3-none-any.

A package with this setting must not provide any binary library or executable, nor anything in a python sitelib. false by default.

pyver-any#

⚠️ DEPRECATED: Please use has-binaries = false

Boolean setting to build a wheel for py3x-none-any where x is the current python 3 minor version.

A package with this setting must not provide any binary library or executable. false by default.

py3-none#

⚠️ DEPRECATED: Please use has-sitelib = false

Boolean setting to build a wheel for py3-none-{platform}.

A package with this setting must not provide anything in a python sitelib. false by default.

check-relocatable#

Boolean setting to check generated *.cmake files for wrong absolute paths. true by default.

fix-pkg-config#

Boolean setting to fix generated *.pc files with wrong absolute paths. true by default.

upstream-version#

Document upstream version.

Global config file#

Users can have a cmeel/cmeel.toml file in their $XDG_CONFIG_HOME directory (usually ~/.config).

In the main section of this files, one can configure some global options for cmeel.

default-env#

By default, cmeel take the caller environment as a basis for the configure, build and test steps of the packaging.

If default-env is set to False, we only keep the PATH and PYTHONPATH variables, filtering everything else.

jobs#

Number of jobs for the build step. $CMEEL_JOBS by default, or 4.

test-jobs#

Number of jobs for the test step. $CMEEL_TEST_JOBS by default, or 4.

temp-dir#

ref. “Working directories” above.

configure-args#

ref. “CMake configure step” above.

log-level#

Logging level. $CMEEL_LOG_LEVEL by default, or WARNING.

Editable builds#

Cmeel implement PEP 660, and python -m pip install --editable option by:

  1. building in a build-editable directory in the source

  2. adding a .pth file to that directoly in the wheel

  3. setting CMAKE_INSTALL_MODE to ABS_SYMLINK.