CMake Presets

This page describes CMake presets and how they can be used with VisualGDB projects.

Contents

Overview
Internal Format
Editing Presets
Tweaking
Importing Existing Projects

Overview

CMake Presets are essentially instructions how to build CMake projects stored in a consistent IDE-independent way. A project using presets can be opened and built using any preset-capable IDE with exactly the same results:

Presets store parameters that would be otherwise passed to CMake via command line: toolchain to use, target system type, debug/release configuration type, etc.

Internal Format

Presets are stored in the CMakePresets.json file in the project directory. A simplified example of this file is provided below:

{
    "configurePresets": [
        {
            "name": "RaspberryPi",
            "environment": {
                "TOOLCHAIN_ROOT": "C:/SysGCC/raspberry",
            },
            "cacheVariables": {
                "CMAKE_C_COMPILER": "$env{TOOLCHAIN_ROOT}/bin/arm-linux-gnueabihf-gcc.exe",
            },
            "binaryDir": "${sourceDir}/build/${presetName}",
            "generator": "Ninja",
            "hidden": true
        }
    ]
}

Instead of manually setting TOOLCHAIN_ROOT via the environment and passing -DCMAKE_C_COMPILER=[…] to CMake, you can simply run CMake as follows:

cmake.exe --preset=RaspberryPi
cmake.exe --build build/RaspberryPi

Editing Presets

VisualGDB automatically translates CMake presets into solution configurations (replacing the normal Debug/Release) and provides GUI for managing them. You can switch between the classic configurations and CMake presets via the VisualGDB Project Properties -> CMake Build Settings -> Store build settings in setting (1):If you have enabled preset-based mode (you would need to click ‘Apply’ (2)), the Manage button (3) in the top right corner of the window will open the preset editor:The editor allows creating (1) and deleting (2) presets, as well as editing settings within each preset.

Note that the presets can be inherited. E.g. it could be convenient to define a base RaspberryPi preset containing all toolchain settings, and then derive separate debug/release presets from it:

 {
    "name": "RaspberryPi-Debug",
    "inherits": "RaspberryPi",
    "cacheVariables": {
        "CMAKE_BUILD_TYPE": "Debug"
    }
},
{
    "name": "RaspberryPi-Release",
    "inherits": "RaspberryPi",
    "cacheVariables": {
        "CMAKE_BUILD_TYPE": "RelWithDebInfo"
    }
}

VisualGDB fully supports preset inheritance, allowing you to select one or more base presets (3). The inherited settings for each preset are initially grayed out, but can be easily copied into the currently edited preset and edited using the edit button (5). Overridden settings can be reverted back to the inherited value via the revert button (4).

You can create new presets completely from scratch, inherit other presets, or let VisualGDB pre-fill the new preset with common values:
Selecting the “reference current toolchain” option (1) when creating a preset will automatically set variables like TOOLCHAIN_ROOT, CMAKE_SYSROOT, CMAKE_C_COMPILER, etc. based on the current toolchain. This is convenient when converting existing CMake projects to the preset model.

The “create a pair of debug/release presets” checkbox (2) will automatically mark the newly created preset as hidden and will create Debug and RelWithDebInfo presets inheriting it. This way, the actual toolchain settings will be shared between the debug and release presets instead of being duplicated between them.

Tweaking

VisualGDB only displays the most commonly used preset options. If you would like to set an option that is not shown in the list, you can manually edit CMakePresets.json file (VisualGDB will show the manually added setting) or edit the preset schema in the C:\Program Files (x86)\Sysprogs\VisualGDB\Rules\CMakeData.xml file. The schema file simply lists all displayed properties for each preset type. E.g. the following element defines the “Installation directory” property for configuration presets:

<PresetEntry xsi:type="String">
    <Key>installDir</Key>
    <Name>Installation Directory</Name>
</PresetEntry>

Importing Existing Projects

If you already have a project that uses CMake presets, VisualGDB will automatically detect it, suggesting to reuse existing presets: As long as this option is enabled during importing, VisualGDB will immediately map existing presets to solution configurations without the need to change anything in VisualGDB Project Properties.