CMakePresets.json: Reproducible Configure Presets
CMakePresets.json stores named configure presets so the same generator, cache variables, and paths are used everywhere.
Presets (CMake 3.19+) replace long, error-prone command lines with a versioned JSON file. CI and developers run cmake --preset <name> and get identical configuration, which removes a whole class of "works on my machine" build differences.
What it does
CMakePresets.json defines configurePresets that fix the generator, binaryDir, cacheVariables, and environment for a named configuration. cmake --preset <name> configures using it. Presets can inherit from each other, and CMakeUserPresets.json holds developer-local overrides that are not committed.
Common usage
cmake --preset ci-release # configure using a preset
cmake --list-presets # list available configure presets
# CMakePresets.json (excerpt)
# {
# "version": 3,
# "configurePresets": [{
# "name": "ci-release",
# "generator": "Ninja",
# "binaryDir": "build",
# "cacheVariables": {
# "CMAKE_BUILD_TYPE": "Release",
# "CMAKE_CXX_COMPILER_LAUNCHER": "ccache"
# }
# }]
# }Options
| Field / Command | What it does |
|---|---|
| cmake --preset <name> | Configure with the named preset |
| cmake --list-presets | List configure presets |
| "generator" | Generator the preset uses (e.g. Ninja) |
| "binaryDir" | Build directory the preset writes to |
| "cacheVariables" | Cache variables (build type, launchers, flags) |
| "inherits" | Base preset(s) to inherit settings from |
In CI
Commit CMakePresets.json with a ci preset that pins the generator (Ninja), build type, and the ccache/sccache launcher, so the pipeline and contributors configure identically. Keep machine-specific paths out of the committed file and in CMakeUserPresets.json. Reference the same preset name from your build and test presets to avoid drift.
Common errors in CI
"No such preset in this project: 'X'" means a name typo or the preset lives in an uncommitted CMakeUserPresets.json. "Could not read presets ... version not specified" or a version error means the version field is missing or higher than the runner's CMake supports; raise CMake or lower the version. A schema error names the offending field.