User Presets and Inheritance

Inheritance isn't just for user presets; it's the key to creating a scalable and maintainable CMakePresets.json for the whole team.

As a project grows, the number of build configurations can explode. You might need:

• Windows, Linux, and macOS builds.
• Debug and Release configurations for each.
• Maybe a special "Address Sanitizer" build for debugging memory errors.

A flat list of presets for every combination quickly becomes a maintenance nightmare, full of duplicated JSON.

1{
2  "version": 3,
3  "configurePresets": [{
4    "name": "windows-debug",
5    "binaryDir": "${sourceDir}/build/win-dbg",
6    "cacheVariables": {
7      "CMAKE_BUILD_TYPE": "Debug",
8      "CMAKE_TOOLCHAIN_FILE":
9        "${sourceDir}/toolchains/mingw-windows-x64.cmake"
10    }
11  }, {
12    "name": "windows-release",
13    "binaryDir": "${sourceDir}/build/win-rel",
14    "cacheVariables": {
15      "CMAKE_BUILD_TYPE": "Release",
16      "CMAKE_TOOLCHAIN_FILE":
17        "${sourceDir}/toolchains/mingw-windows-x64.cmake"
18    }
19  }, {
20    "name": "linux-debug",
21    "binaryDir": "${sourceDir}/build/linux-dbg",
22    "cacheVariables": {
23      "CMAKE_BUILD_TYPE": "Debug",
24      "CMAKE_TOOLCHAIN_FILE":
25        "${sourceDir}/toolchains/linux.cmake"
26    }
27  }, {
28    "name": "linux-release",
29    "binaryDir": "${sourceDir}/build/linux-rel",
30    "cacheVariables": {
31      "CMAKE_BUILD_TYPE": "Release",
32      "CMAKE_TOOLCHAIN_FILE":
33        "${sourceDir}/toolchains/linux.cmake"
34    }
35  }]
36}

The solution is to think in layers. We can create abstract "base" presets that define a common set of options, and then compose them together to create our final, user-visible presets.

A common convention is to create abstract presets that are not meant to be used directly by a developer. We can signal this by setting the "hidden" property to true. By convention, hidden presets also have their names prefixed with an underscore (e.g., "_base") but this is not strictly necessary.

Let's start refactoring our "bad" example by creating a base preset that defines a standard directory structure for all our builds.

1{
2  "version": 3,
3  "configurePresets": [{
4    "name": "_base",
5    "hidden": true,
6    "binaryDir": "${sourceDir}/build/${presetName}"
7  }]
8}

The ${presetName} variable automatically expanded by CMake to the name of the final, user-visible preset. So, when we create a windows-debug preset that inherits from this, the binaryDir will automatically become ".../build/windows-debug".

1{
2  "version": 3,
3  "configurePresets": [{
4    "name": "_base",
5    "hidden": true,
6    "binaryDir": "${sourceDir}/build/${presetName}"
7  }, {
8    "name": "windows-debug",
9    "inherits": "_base",
10    "cacheVariables": {
11      "CMAKE_TOOLCHAIN_FILE":
12        "${sourceDir}/toolchains/mingw-windows-x64.cmake"
13    }
14  }]
15}

This single base preset has already eliminated the binaryDir duplication from all our final presets. If we list our presets, our hidden preset should not be listed:

1cmake --list-presets

1Available configure presets:
2  "windows-debug"

Inheritance becomes even more useful when we realize that the inherits key can take an array of strings. This allows a preset to inherit from multiple parents.

1inherits: ["_parent1", "_parent2", "_parent3"]

Settings from presets that appear later in the array will override settings from earlier ones. This lets us build up our final configuration by layering a series of base presets.

Let's complete our refactor. We'll create base presets for the OS and for the build type, and then compose them.

1{
2  "version": 3,
3  "configurePresets": [{
4    "name": "_base",
5    "hidden": true,
6    "binaryDir": "${sourceDir}/build/${presetName}"
7  }, {
8    "name": "_windows",
9    "hidden": true,
10    "cacheVariables": {
11      "CMAKE_TOOLCHAIN_FILE":
12        "${sourceDir}/toolchains/mingw-windows-x64.cmake"
13    }
14  }, {
15    "name": "_linux",
16    "hidden": true,
17    "cacheVariables": {
18      "CMAKE_TOOLCHAIN_FILE":
19        "${sourceDir}/toolchains/linux.cmake"
20    }
21  }, {
22    "name": "_debug",
23    "hidden": true,
24    "cacheVariables": {
25      "CMAKE_BUILD_TYPE": "Debug"
26    }
27  }, {
28    "name": "_release",
29    "hidden": true,
30    "cacheVariables": {
31      "CMAKE_BUILD_TYPE": "Release"
32    }
33  }, {
34    "name": "windows-debug",
35    "inherits": ["_base", "_windows", "_debug"]
36  }, {
37    "name": "windows-release",
38    "inherits": ["_base", "_windows", "_release"]
39  }, {
40    "name": "linux-debug",
41    "inherits": ["_base", "_linux", "_debug"]
42  }, {
43    "name": "linux-release",
44    "inherits": ["_base", "_linux", "_release"]
45  }]
46}

Each piece of configuration (binaryDir, toolchain, build type) is now defined in exactly one place.

The final, user-visible presets are just simple one-liners that compose these building blocks

1cmake --list-presets

1Available configure presets:
2  "windows-debug"
3  "windows-release"
4  "linux-debug"
5  "linux-release"

Defining a new configuration is now trivial:

1{
2  "name": "windows-asan",
3  "inherits": ["_base", "_windows", "_debug"],
4  "cacheVariables": {
5    "ENABLE_ASAN": "ON"
6  }
7}

This ENABLE_ASAN variable enables AddressSanitizer, which we'll cover in more detail later in the course.

This layered approach fits perfectly with the CMakeUserPresets.json file we saw earlier. The shared CMakePresets.json defines the team-wide standard configurations. The user presets file acts as the final, outermost layer for personal, machine-specific overrides.

This is the standard solution to a very common problem: how to handle paths to external tools that might be installed in different locations on different machines.

Let's imagine we were using vcpkg, and our build expects the location of vcpkg toolchain file to be provided in a variable called VCPKG_TOOLCHAIN_FILE:

1# 1. Set the target system
2set(CMAKE_SYSTEM_NAME Windows)
3set(CMAKE_SYSTEM_PROCESSOR x86_64)
4
5# 2. Specify the cross-compilers
6set(CMAKE_C_COMPILER x86_64-w64-mingw32-gcc)
7set(CMAKE_C_FLAGS_INIT "-static -static-libgcc")
8
9set(CMAKE_CXX_COMPILER x86_64-w64-mingw32-g++)
10set(CMAKE_CXX_FLAGS_INIT
11  "-static -static-libgcc -static-libstdc++")
12set(CMAKE_EXE_LINKER_FLAGS_INIT
13  "-static-libgcc -static-libstdc++")
14
15# 3. Configure search for external dependencies
16set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
17set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
18set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
19
20set(MINGW TRUE)
21set(VCPKG_TARGET_TRIPLET x64-mingw-static)
22include("${VCPKG_TOOLCHAIN_FILE}")

The team's standard convention might be to install vcpkg in C:/vcpkg, and the shared CMakePresets.json could reflect this:

1{
2  "version": 3,
3  "configurePresets": [{
4    "name": "_base",
5    "hidden": true,
6    "binaryDir": "${sourceDir}/build/${presetName}"
7    "cacheVariables": {
8      "VCPKG_TOOLCHAIN_FILE":
9        "C:/vcpkg/scripts/buildsystems/vcpkg.cmake"
10    }
11  }]
12}

However, on our machine, we've installed vcpkg to D:/vcpkg. Remember, we can still override preset values on the command line as needed:

1cmake \
2  --preset=windows-vcpkg-debug \
3  -DVCPKG_TOOLCHAIN_FILE= \
4    "D:/vcpkg/scripts/buildsystems/vcpkg.cmake"

But always remembering to do this can get annoying, so we'd prefer to use a preset instead. Instead of modifying the shared CMakePresets.json and causing issues for the rest of the team, we can create a personal preset in CMakeUserPresets.json:

1{
2  "version": 3,
3  "configurePresets": [{
4    "name": "user-windows-debug",
5    "inherits": ["windows-debug"],
6    "cacheVariables": {
7      "VCPKG_TOOLCHAIN_FILE":
8        "D:/vcpkg/scripts/buildsystems/vcpkg.cmake"
9    }
10  }]
11}

By using inherits, we keep all the other settings from the shared preset and only change the one thing we needs to: the path to the toolchain file.

Hardcoded Paths are Still not Ideal

While this pattern works, hardcoding paths, even in a user preset, is not the most robust solution. Creating a load of new presets to handle variations in a single variable is quite a lot of work. This is particularly true when working with build servers, which we'll cover later.

A more flexible and standard approach is to use environment variables. In the next lesson, we'll see how to use the $env{...} syntax in our presets to read paths from the system environment, making our configurations even simpler.

In this lesson, we expanded our understanding of CMake Presets from a simple shortcuts to an architectural tool for managing build complexity.

• Shared vs. User Presets: Use CMakePresets.json for team-wide configurations that go into version control. Use CMakeUserPresets.json for personal, machine-specific overrides.
• Inheritance is Key: Use the inherits key to avoid duplication. This is the fundamental mechanism for creating maintainable presets.
• Layered Architecture: Structure your presets by creating hidden base presets (e.g., _base, _windows, _debug) that are responsible for small, discrete blocks of configuration. Then, compose them into final, user-visible presets using multi-inheritance.
• User Presets as the Final Override: A user can create a personal preset just for themselves. User presets can inherit from shared presets.