CMake Presets

Throughout the last few chapters, our build commands have been getting progressively more complex. We've added toolchain files for package managers, specified build types, and configured cross-compilation.

This has led to a new problem: our command-line invocations have become long, hard to remember, and difficult to share with others using our project who may find them useful.

This is where CMake Presets come in. Presets are a modern, standardized way to define and share common build configurations in a simple JSON file. They allow you to replace a long, error-prone command with a single, memorable name.

In this lesson, we'll learn the fundamentals of presets. We'll start by encapsulating a complex command into our first configure preset, then add a corresponding build preset, and finally understand the distinction between shared team presets and personal user presets.

In these examples, we'll use our vcpkg project from the previous chapter. The code is provided below if you want to follow along. Note that the include() command in the toolchain file (highlighted) may need updated to point to your vcpkg location. We'll learn how to make this portable soon.

Support for presets were first introduced in version 3.19 of CMake, and were expanded in subsequent versions. Later in the chapter, we'll use features added in 3.21 so, if you want to follow along, having at least that version is recommended.

Remember, you can check the installed cmake version using the command:

1cmake --version

Using a recent addition to the cmake executable doesn't necessarily require us to update the cmake_minimum_requirements() for our project. Someone on an older version could still use our project without using our presets.

However, if our project is designed around the use of presets, and our documentation recommends using them, bumping the cmake_minimum_required() version is a reasonable choice anyway. This signals to users that a more modern version of CMake is expected in order to use the project as designed.

1cmake_minimum_required(VERSION 3.21) 
2project(Greeter)
3
4// ...

Let's revisit the command we used to cross-compile our Greeter application for Windows from a macOS or Linux host. It required setting the source and build directories, the toolchain file, and the build type.

For example, if our terminal was in our project root, and we wanted to configure a vcpkg project in /build/windows-debug, our command to provide all of the required arguments might look like this:

1cmake -S . -B ./build/windows-debug \                      
2  -DCMAKE_TOOLCHAIN_FILE=./toolchains/mingw-windows-x64.cmake \
3  -DCMAKE_BUILD_TYPE=Debug

And after that, we still need to repeat the correct build directory for the build command:

1cmake --build ./build/windows-debug

This is a lot to type correctly every time. If a new developer joins the team, you have to document this command precisely. If you need to change a flag, you have to tell everyone to update their personal scripts.

CMakePresets.json is the solution. It's a file you create in the root of your project that lets you give names to these complex configurations.

Let's create this file and define our first preset to encapsulate the command above.

1{
2  "version": 3,
3  "configurePresets": [{
4    "name": "windows-x64-debug",
5    "displayName": "Windows x64 Debug",
6    "description": "Build for 64-bit Windows with MinGW (Debug)",
7    "binaryDir": "${sourceDir}/build/windows-x64-debug",
8    "cacheVariables": {
9      "CMAKE_BUILD_TYPE": "Debug",
10      "CMAKE_TOOLCHAIN_FILE": "${sourceDir}/toolchains/mingw-windows-x64.cmake"
11    }
12  }]
13}

Let's break down this JSON file:

• "version": The schema version for the presets file. CMake adds support for new keys and features in presets over time. Version 3 is a relatively common baseline and is supported by CMake versions 3.21 and later.
• "configurePresets": An array containing one or more configure preset objects.
• "name": The unique, machine-readable ID for the preset. This is what you'll use on the command line to declare that you want to use this preset. It's best to use a simple, consistent naming scheme like os-arch-config.
• "displayName" and "description": Human-readable strings that GUI tools such as an IDE can use to present the preset in a friendly way.
• "binaryDir": The output directory for the build. This corresponds to the -B argument we'd pass on the command line. The ${sourceDir} variable is automatically provided by CMake and points to the directory containing the CMakePresets.json file.
• "cacheVariables": An object containing key-value pairs that will be passed as -D arguments to the cmake command. This is where we can set things like CMAKE_BUILD_TYPE and CMAKE_TOOLCHAIN_FILE.

Listing Presets

We can ask CMake to list all of the available presets using the following command:

1cmake --list-presets

The output should list our new preset as an option:

1Available configure presets:
2  "windows-x64-debug" - Windows x64 Debug

1cmake --preset=windows-x64-debug

1cmake --preset=windows-x64-debug -B "./output"

1{
2  "version": 3,
3  "configurePresets": [{
4    "name": "windows-x64-debug",
5    "displayName": "Windows x64 Debug",
6    "description": "Build for 64-bit Windows with MinGW (Debug)",
7    "binaryDir": "${sourceDir}/build/windows-x64-debug",
8    "cacheVariables": {
9      "CMAKE_BUILD_TYPE": "Debug",
10      "CMAKE_TOOLCHAIN_FILE": "${sourceDir}/toolchains/mingw-windows-x64.cmake"
11    }
12  }],
13  "buildPresets": [{
14    "name": "windows-x64-debug",
15    "displayName": "Build Windows x64 (Debug)",
16    "configurePreset": "windows-x64-debug"
17  }]
18}

1cmake --build --preset=windows-x64-debug