Skip to main content

CMake Presets Exploder

PyPI version Python versions Tests status License: MIT

A simple Python tool to automatically generate combinations of different CMake Presets options.

Table of contents

  1. Motivation and basic usage
  2. Other tools
  3. Pre-commit hook
  4. Installation

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)

Source distribution for cmake-presets-exploder 0.3.3
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)

Table of built distributions (wheels) for cmake-presets-exploder 0.3.3
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page