skip to content

In CMakePresets.json, how do hidden presets, inherits, and build, test and workflow presets combine into one repeatable configure-build-test flow?

level: middleimportance: should knowfreq 40%

answer

  1. a hidden base nobody runs
  2. earlier parent wins conflicts
  3. build preset names its configure preset
  4. schema version gates fields
  5. cmake --workflow

basics

~20 s

Shared settings go into a hidden configure preset that concrete presets inherit; build and test presets point at a configure preset and reuse its build directory; a workflow preset chains configure, build, test and package steps so cmake --workflow runs them all.

solid answer

~40 s

A `hidden: true` configure preset cannot be run but can hold the common `generator`, `binaryDir` and `cacheVariables`. Concrete presets list it in `inherits`; they receive every field except `name`, `hidden`, `inherits`, `description` and `displayName`, `cacheVariables` are merged as a union, the earlier parent wins a conflict, and a `null` value unsets an inherited variable. A build preset's `configurePreset` field ties it to a configure preset and its `binaryDir`; test presets add CTest options such as `output.outputOnFailure`. Workflow presets (schema 6, CMake 3.25) list steps, and `cmake --workflow --preset ci` runs them in order. Two rules bite: presets in `CMakePresets.json` may not inherit from `CMakeUserPresets.json`, and a field newer than the file's `version` is rejected, as CMake 4.4 does with `$comment` in a version 6 file.

code

json · 22 lines
json
{
  "version": 6,
  "configurePresets": [
    { "name": "base", "hidden": true, "generator": "Ninja",
      "binaryDir": "${sourceDir}/build/${presetName}" },
    { "name": "release", "inherits": "base",
      "cacheVariables": { "CMAKE_BUILD_TYPE": "Release" } }
  ],
  "buildPresets": [
    { "name": "release", "configurePreset": "release" }
  ],
  "testPresets": [
    { "name": "release", "configurePreset": "release",
      "output": { "outputOnFailure": true } }
  ],
  "workflowPresets": [
    { "name": "ci", "steps": [
      { "type": "configure", "name": "release" },
      { "type": "build", "name": "release" },
      { "type": "test", "name": "release" } ] }
  ]
}

go deeper

for a junior

Recall that presets can inherit from a hidden base and that build and test presets point at a configure preset by name.

for a middle

Explain which fields inherit, that the earlier parent wins, that cacheVariables merge and null unsets, and how a workflow preset chains the steps.

for a senior

Read schema-version and unreachable-preset errors correctly, and lay presets out so CI runs one workflow preset while developers extend shared bases in their own file.

for a principal

Choose the presets schema version as a deliberate statement of the oldest CMake the team supports, and keep the preset graph small enough that everyone can read it.

## Building presets from parts A real project wants several presets that share most settings: debug and release, with and without sanitizers, native and cross. Copying the generator and build directory into each is the same drift presets were meant to stop, so the format offers **inheritance**. - **`hidden: true`** marks a preset as a base. It cannot be used with `--preset` (CMake 4.4 reports `Cannot use hidden configure preset`), does not appear in `--list-presets`, and need not have a valid `generator` or `binaryDir`. - **`inherits`** is a string or an array of preset names. The child receives every field of its parents **except** `name`, `hidden`, `inherits`, `description` and `displayName`, and may override any of them. - When several parents set the same field, **the earlier entry in the `inherits` array wins**. - `cacheVariables` and `environment` merge: the child's map is the union of its own and its parents'. Setting a variable to `null` removes an inherited one. ```json { "version": 6, "configurePresets": [ { "name": "base", "hidden": true, "generator": "Ninja", "binaryDir": "${sourceDir}/build/${presetName}", "cacheVariables": { "PR_WARNINGS_AS_ERRORS": true } }, { "name": "debug", "inherits": "base", "cacheVariables": { "CMAKE_BUILD_TYPE": "Debug" } }, { "name": "release", "inherits": "base", "cacheVariables": { "CMAKE_BUILD_TYPE": "Release" } } ] } ``` Because `binaryDir` uses the `${presetName}` macro, `debug` builds in `build/debug` and `release` in `build/release` from a single definition. ## Build and test presets Configure presets only cover `cmake --preset`. Two more arrays (schema version 2, CMake 3.20) cover the next steps: | Preset kind | Run with | Key fields | |---|---|---| | Configure | `cmake --preset <name>` | `generator`, `binaryDir`, `cacheVariables`, `toolchainFile` | | Build | `cmake --build --preset <name>` | `configurePreset`, `configuration`, `targets`, `jobs` | | Test | `ctest --preset <name>` | `configurePreset`, `output`, `filter`, `execution` | | Workflow | `cmake --workflow --preset <name>` | `steps` | A build preset's **`configurePreset`** names the configure preset it belongs to; the build happens in that preset's `binaryDir`, so nobody repeats the directory. A test preset does the same and adds CTest options such as `"output": {"outputOnFailure": true}`. ## Workflow presets Workflow presets (schema 6, CMake 3.25) chain the other kinds. Each step has a `type` (`configure`, `build`, `test` or `package`) and a `name`; the first step must be a configure step, and the other steps must refer to presets of that same configure preset. CI then needs one line: ```bash cmake --workflow --preset ci ``` ## Schema versions are a contract The root `version` field selects the schema, and each schema is tied to the CMake release that introduced it. A few landmarks: 1. version 1 (3.19): configure presets; 2. version 2 (3.20): build and test presets; 3. version 3 (3.21): `condition`, `toolchainFile`, `installDir`, and `binaryDir` and `generator` became optional; 4. version 4 (3.23): `include` of other preset files; 5. version 6 (3.25): package and workflow presets; 6. version 10 (3.31): `$comment` fields; 7. version 12 (4.4): the latest in CMake 4.4. CMake validates the file against the declared version. With `"version": 6` and a `$comment` field, CMake 4.4 refuses the file (path shortened): ```plaintext CMake Error: Could not read presets from /work/pr: CMakePresets.json:25: Invalid extra field "$comment" in Preset ``` Raising `version` fixes that error but stops older CMake releases from reading the file at all, so the version is effectively the minimum CMake the presets support. The optional root `cmakeMinimumRequired` object states the same minimum explicitly. ## The rules that cause most errors - **Direction of inheritance.** `CMakeUserPresets.json` implicitly includes `CMakePresets.json`, so user presets may inherit shared ones, never the reverse. A shared preset that inherits a user preset fails with `Inherited configure preset "release" is unreachable from preset's file`. - **Unique names per kind.** Two configure presets in the union of both files may not share a name, but a build preset may share a configure preset's name, which is the usual convention. - **Hidden presets are bases only.** `cmake --preset base` on a hidden preset fails, so every setting a developer should run needs a concrete, non-hidden child.

  • Two parents in an inherits array set CMAKE_BUILD_TYPE differently. Which value does the child get?
    The value from the parent listed first in `inherits`. The child's own `cacheVariables` beat both, and setting the variable to `null` in the child removes it entirely.
  • Why can't a preset in CMakePresets.json inherit from one in CMakeUserPresets.json?
    A preset may only inherit from presets in its own file or in files that file includes. `CMakeUserPresets.json` includes `CMakePresets.json`, not the other way round, so a shared preset cannot see user presets; CMake reports the inherited preset as unreachable from the preset's file.

  • A child preset inherits its parent's name and description too
  • When two parents conflict, the last one in inherits wins
  • Build presets must repeat the binaryDir of their configure preset
  • The version field is informational and does not limit which fields are allowed
  • Shared presets may inherit from presets in CMakeUserPresets.json

Assumes CMake 4.4, which reads presets schema versions 1 to 12; build and test presets need schema 2 (3.20), workflow presets schema 6 (3.25).