TopolearnPresets replace long, error-prone command lines and are understood by VS Code, CLion and Visual Studio.
Instead of documenting cmake -S . -B build/release -G Ninja -DCMAKE_BUILD_TYPE=Release -D... in a README, put it in `CMakePresets.json` at the project root and commit it.
- configurePresets set the generator,
binaryDir, cache variables, environment and toolchain file. Presets caninheritsfrom others, and hidden ones act as shared bases. - buildPresets and testPresets reference a configure preset and add build targets, jobs or test filters.
- workflowPresets (schema version 6, CMake 3.25+) chain configure, build and test into one command.
Use them with cmake --preset release, cmake --build --preset release, ctest --preset release or cmake --workflow --preset ci. cmake --list-presets shows what's available.
Macros like ${sourceDir}, ${presetName} and $env{HOME} keep paths portable. A condition can restrict presets to a host OS.
`CMakeUserPresets.json` has the same format for personal settings (local compiler paths, extra flags) and should be in .gitignore. It may inherit from the project's presets.
IDEs read both files and offer the presets in their UI, so the command line, CI and every developer's editor configure the project identically.
Example
{
"version": 6,
"configurePresets": [
{ "name": "base", "hidden": true, "generator": "Ninja",
"binaryDir": "${sourceDir}/build/${presetName}",
"cacheVariables": { "CMAKE_EXPORT_COMPILE_COMMANDS": "ON" } },
{ "name": "debug", "inherits": "base",
"cacheVariables": { "CMAKE_BUILD_TYPE": "Debug" } },
{ "name": "release", "inherits": "base",
"cacheVariables": { "CMAKE_BUILD_TYPE": "Release" } }
],
"buildPresets": [ { "name": "release", "configurePreset": "release" } ],
"testPresets": [
{ "name": "release", "configurePreset": "release",
"output": { "outputOnFailure": true }, "execution": { "jobs": 8 } }
],
"workflowPresets": [
{ "name": "ci", "steps": [
{ "type": "configure", "name": "release" },
{ "type": "build", "name": "release" },
{ "type": "test", "name": "release" } ] }
]
}Remember
- CMakePresets.json holds shared configure, build, test and workflow presets
- Run with cmake --preset, cmake --build --preset, ctest --preset or cmake --workflow
- Personal settings go in CMakeUserPresets.json, not committed
Watch out for
- Committing machine-specific paths into CMakePresets.json instead of CMakeUserPresets.json.