cmake --preset: Reproducible Configure in CI
cmake --preset <name> applies a configuration recorded in CMakePresets.json, so CI and local builds use identical settings.
Presets (CMake 3.19+) move generator, cache variables, and paths out of shell scripts and into a versioned JSON file. That makes CI runs reproducible and self-documenting.
What it does
cmake --preset selects a configure preset from CMakePresets.json (or CMakeUserPresets.json), applying its generator, binary dir, and cache variables in one command. Build and test presets extend the same idea to cmake --build --preset and ctest --preset.
Common usage
cmake --list-presets
cmake --preset ci-release
cmake --build --preset ci-release
ctest --preset ci-releaseOptions
| Flag | What it does |
|---|---|
| --preset <name> | Use the named configure preset |
| --list-presets | List available presets and exit |
| --build --preset <name> | Use a build preset (references a configure preset) |
| ctest --preset <name> | Use a test preset for the run |
| CMakePresets.json | Committed presets shared by the team and CI |
| CMakeUserPresets.json | Local overrides, usually gitignored |
In CI
Commit CMakePresets.json and have both developers and CI call the same preset name, eliminating "works on my machine" configure drift. Presets require CMake 3.19+ (schema versions add features in later releases); pin a recent CMake in your runner image.
Common errors in CI
"No such preset in ...: ci-release" means a name typo or a preset defined only in CMakeUserPresets.json that CI does not have. "Could not read presets ... unsupported version" means CMake is older than the presets schema version; upgrade CMake. "Invalid preset" usually points at a JSON syntax error or a missing referenced configurePreset.