TCPM: (the) Cmake Preset Matrix

Build status Supported Python Versions PyPI Release Version GitHub deployments

TCPM is a CMakePresets.json transformation tool that generates presets for the cartesian product of a set of parameters. For example, given two toolchains :

"toolchain": [
    "gcc",
    "clang"
],

and two different c++ language standards:

"standard": [
    "cpp-20",
    "cpp-23"
],

the tcpm tool will generate four (4) configuration presets:

{
    "name": "configure-gcc-cpp-20"
},
{
    "name": "configure-gcc-cpp-23"
},
{
    "name": "configure-clang-cpp-20"
},
{
    "name": "configure-clang-cpp-23"
},

If you added a third parameter list with two items then TCPM would generate eight (8) configurations, the cartesian product producing \(|A| \times |B| = |A| * |B|\) items.

TCPM also provides a template language to allow generation of various preset fields like "cacheVariables". These templates, called “shapes” in the json, are given contextual tokens to use in string expansion and, for more complex logic, the pQuery DSL embedded in TCPM allows procedural expansion of fields based on the state of a presets document at the time a given preset is generated.

There’s a lot more to it, of course, and TCPM provides a complete JSON transformation language for presets json in in addition to other features. To get started we reccommend starting with the Try Me exercise.

Note

This is alpha software. A lot will change before 1.0. Your input is required to get there. Thanks for helping ❤️

This project is an experiment, a proposal, a tool. One of these three things will become the roadmap for it over time. As an experiment, this tool will explore the utility of CMakePresets.json which makes direct integration of cmake with CI worflows possible. As a proposal, this project demonstrates certain functionality not available in the current version of CMakePresets.json as a suggestion to Kitware when evolving this part of their product. Finally, this is a tool that will continue to aid complex projects in the management of their preset files whether or not Kitware adds similar features supporting matrix builds in the future.

Key Features

  • Matrix Builds – Provides a way to manage large matrices of build types for complex projects that doesn’t require copy-and-paste or a lot of typing 😩

  • Idempotent – The tool will continue to produce the same output given the same parameters as inputs. This allows automated generation of CMakePresets.json files from themselves or using separate template files.

  • Preserves Existing Presets – Any presets that are manually added to a CMakePresets.json file will be maintained when using the “expand-in-place” features of this tool.