CMake Presets Exploder
A simple Python tool to automatically generate combinations of different CMake Presets options.
Table of contents
Motivation and basic usage
CMake Presets are a useful tool for specifying and sharing configuration, build, and test settings for CMake Projects. Many editors and IDEs, such as Visual Studio Code, can integrate with presets files.
However, some projects have a large number of different configuration and build
options, and CMake
currently doesn't support
specifying multiple presets. For example, suppose you have a project with a
compile-time option called ENABLE_FEATURE_X, and you need to support
compilation with both GCC and Clang toolchains. You would need to create a
separate preset for each combination of feature and toolchain:
{
"version": 5,
"configurePresets": [
{
"name": "base-config",
"generator": "Ninja"
},
{
"name": "configure-feature-x-on-gcc",
"inherits": ["base-config"],
"cacheVariables": {
"ENABLE_FEATURE_X": "on"
},
"toolchainFile": "gcc"
},
{
"name": "configure-feature-x-off-gcc",
"inherits": ["base-config"],
"cacheVariables": {
"ENABLE_FEATURE_X": "off"
},
"toolchainFile": "gcc"
},
{
"name": "configure-feature-x-on-clang",
"inherits": ["base-config"],
"cacheVariables": {
"ENABLE_FEATURE_X": "on"
},
"toolchainFile": "clang"
},
{
"name": "configure-feature-x-off-clang",
"inherits": ["base-config"],
"cacheVariables": {
"ENABLE_FEATURE_X": "off"
},
"toolchainFile": "clang"
}
]
}
Now, suppose you add a new feature ENABLE_FEATURE_Y, or want to configure
different build configurations such as Debug, Release, or support different
config generators (such as Ninja and Visual Studio). The number of presets
increases exponentially, which would be tedious and error-prone to maintain
manually.
This tool automates the 'combinatorial explosion' of presets given a template
file. For example, the above config file could be generated by creating a file
named CMakePresetsMatrixTemplate.json:
{
"version": 5,
"configurePresets": [
{
"name": "base-config",
"generator": "Ninja",
"hidden": true
}
],
"vendor": {
"exploder": {
"version": 0,
"presetGroups": {
"configure": {
"type": "configure",
"inherits": ["base-config"],
"parameters": {
"feature-x": {
"feature-x-on": "on",
"feature-x-off": "off"
},
"toolchainFile": ["gcc", "clang"]
},
"templates": {
"feature-x": {
"cacheVariables": {
"ENABLE_FEATURE_X": "$value"
}
}
}
}
}
}
}
}
And then running
cmake-presets-exploder --output CMakePresets.json
Which will generate the following CMakePresets.json:
{
"version": 5,
"configurePresets": [
{
"name": "base-config",
"generator": "Ninja",
"hidden": true
},
{
"name": "configure-feature-x-feature-x-on",
"hidden": true,
"cacheVariables": {
"ENABLE_FEATURE_X": "on"
}
},
{
"name": "configure-feature-x-feature-x-off",
"hidden": true,
"cacheVariables": {
"ENABLE_FEATURE_X": "off"
}
},
{
"name": "configure-toolchainFile-gcc",
"hidden": true,
"toolchainFile": "gcc"
},
{
"name": "configure-toolchainFile-clang",
"hidden": true,
"toolchainFile": "clang"
},
{
"name": "configure-feature-x-on-gcc",
"inherits": [
"base-config",
"configure-feature-x-feature-x-on",
"configure-toolchainFile-gcc"
]
},
{
"name": "configure-feature-x-on-clang",
"inherits": [
"base-config",
"configure-feature-x-feature-x-on",
"configure-toolchainFile-clang"
]
},
{
"name": "configure-feature-x-off-gcc",
"inherits": [
"base-config",
"configure-feature-x-feature-x-off",
"configure-toolchainFile-gcc"
]
},
{
"name": "configure-feature-x-off-clang",
"inherits": [
"base-config",
"configure-feature-x-feature-x-off",
"configure-toolchainFile-clang"
]
}
]
}
The template file can also be written in YAML or TOML if YAML or TOML support is
installed and yaml or toml are passed to the --loader option on the CLI.
Jinja2 templating is also optionally supported. As a contrived example, the
ENABLE_FEATURE_X option above could be capitalised with the following:
{
"templates": {
"feature-x": {
"cacheVariables": {
"ENABLE_FEATURE_X": "{jinja}{{ value | upper }}"
}
}
}
}
(See Installation for how to install optional dependencies.)
Run cmake-presets-exploder --help for more information on the different CLI
options.
(More documentation to follow...)
Other tools
This tool was directly inspired by Scott Dixon's TCPM (The CMake Preset Matrix), which supports more complex configuration generation. The project is still under active development, so if you find you have more complex needs, check out that project!
Pre-commit hook
A pre-commit hook is provided for running the tool
when changes to the CMakePresets.json or CMakePresetsMatrixTemplate.json
files are committed, preventing the files from going out of sync from one
another. To use it, add the following to your .pre-commit-config.yaml:
repos:
- repo: https://github.com/harrymander/cmake-presets-exploder
rev: v0.3.2 # replace with desired tag (must be at least v0.3.1)
hooks:
- id: cmake-presets-exploder
Installation
Available from PyPI under cmake-presets-exploder, which provides a script with
the same name for running the tool. I recommend using a tool such as
pipx or
uv to install the
script into an isolated environment.
pipx install cmake-presets-exploder
# or
uv tool install cmake-presets-exploder
You can also just run the script directly without installing it to PATH with
pipx run cmake-presets-exploder or uvx cmake-presets-exploder.
To install optional YAML, TOML, and/or Jinja2 support, install with the yaml
and jinja2 extras. E.g.
pipx install cmake-presets-exploder[yaml,toml,jinja2]
# or
uv tool install cmake-presets-exploder[yaml,toml,jinja2]
(Note that Python 3.11 and higher has built-in TOML support, so installing the
toml extra on those versions has no effect.)
To install the latest development version, pass the Git URL, e.g.
uv tool install git+https://github.com/harrymander/cmake-presets-exploder.git
Metadata
Release files for cmake-presets-exploder 0.3.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| cmake_presets_exploder-0.3.3.tar.gz | 47.5 kB | Without provenance | Details for cmake_presets_exploder-0.3.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| cmake_presets_exploder-0.3.3-py3-none-any.whl | Python 3 | none | any | Details for cmake_presets_exploder-0.3.3-py3-none-any.whl |
Total release size: 60.4 kB
Release files / cmake_presets_exploder-0.3.3.tar.gz
| Download URL | cmake_presets_exploder-0.3.3.tar.gz |
|---|---|
| Size | 47.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1ae339e777b448a384b3a79a639465f60346482ef9124d02295ded6922f3579e
|
|
BLAKE2b-256 checksum How to use checksums |
cb74e04e42e05374af01f86f042066f642589ca2f7e29785299ae89c7704fd01
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.6.12
|
Release files / cmake_presets_exploder-0.3.3-py3-none-any.whl
| Download URL | cmake_presets_exploder-0.3.3-py3-none-any.whl |
|---|---|
| Size | 13.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
78a3d66f078b828434b8a0487d1a1e60e33c87375da20a8d2f9f6f8d6bbb4288
|
|
BLAKE2b-256 checksum How to use checksums |
a626feb52324344a1313c3caccd65b12dd0cd1fc7d4ffd5a5061468d151876cf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.6.12
|
Security for cmake-presets-exploder 0.3.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.