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:
pyproject.toml
file in cmeel specific keys of the[tool.cmeel]
section$XDG_CONFIG_HOME/cmeel/cmeel.toml
(if$XDG_CONFIG_HOME
is not set, fallback to~/.config
)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:
Cmeel defaults
-DBUILD_TESTING=OFF
ifrun-tests
is off.configure-args
key in the[tool.cmeel]
section of localpyproject.toml
configure-args
key in globalcmeel.toml
configure-args
key in the project section in globalcmeel.toml
CMEEL_CMAKE_ARGS
environment variable, splitted
This configuration step is done in the environment defined by:
The environment of the calling process
If installed cmeel packages are detected, prepend
CMAKE_PREFIX_PATH
with their installation path, andPKG_CONFIG_PATH
if relevant.
Test step#
This configuration step is done in the environment defined by:
The environment of the calling process
CTEST_OUTPUT_ON_FAILURE=1
CTEST_PARALLEL_LEVEL
set totest-jobs
global configuration, orCMEEL_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:
building in a
build-editable
directory in the sourceadding a
.pth
file to that directoly in the wheelsetting
CMAKE_INSTALL_MODE
toABS_SYMLINK
.