As a C++ team lead, how would you standardize CMake presets and the cmake_minimum_required range across developers and CI?
answer
- one committed file, one personal file
- CI runs a workflow preset
- oldest supported versus newest tested
- presets must not be required
- upgrade cadence and ownership
basics
~20 sCommit a small CMakePresets.json whose hidden bases define the standard generator, build directories and options, make CI run the same presets, and pin cmake_minimum_required to the oldest supported CMake with policy_max at the newest tested; personal variants go in CMakeUserPresets.json.
solid answer
~50 sThe goal is that a developer's build, an IDE's build and CI's build are the same configuration by construction. I would commit `CMakePresets.json` with hidden bases for generator, `binaryDir` and the team's options, concrete debug, release and sanitizer presets, and build, test and a workflow preset that CI calls with `cmake --workflow --preset ci`; individual tweaks live in an ignored `CMakeUserPresets.json`. I would keep the project configurable without presets, because packagers and projects embedding ours will not use them. For versions, `cmake_minimum_required(VERSION <oldest supported>...<newest tested>)`, a presets `version` that the oldest supported CMake reads, and a CI job on each end of that range. Raising either bound is a scheduled change with an owner: fix policy warnings, raise `policy_max`, and drop temporary `OLD` settings. The trade-off is between users on older CMake and the cost of carrying old behaviours.
go deeper
Use the team's presets rather than your own command lines, and put personal variants in CMakeUserPresets.json.
Explain how hidden bases, build and test presets and a workflow preset let developers and CI run the same configuration.
Keep presets optional for consumers, choose a presets schema the oldest supported CMake reads, and run CI at both ends of the supported range.
Decide the supported CMake range from platform and user constraints, assign ownership and cadence for raising it, and treat the shared presets file as reviewed build policy.
## The decision Two things in a CMake project are really **team agreements** rather than code: - **how the project is configured**: generator, build directories, build types, warning and sanitizer options, toolchains; - **which CMake releases the project supports**: the `cmake_minimum_required` range and, with it, the policy behaviours the code relies on. Left alone, the first drifts into personal shell aliases and CI scripts that differ from both, and the second stays at whatever version someone typed years ago. A lead's job is to make both explicit, cheap to follow and easy to change. ## Standardizing configuration with presets A structure that scales: 1. **Hidden bases** in the committed `CMakePresets.json` hold what everyone shares: generator, `binaryDir` of `${sourceDir}/build/${presetName}`, the project's standard options. 2. **Concrete configure presets** inherit those bases: `debug`, `release`, `asan`, perhaps a `cross-arm` that adds `toolchainFile`. 3. **Build and test presets** with the same names point at their configure presets, so `cmake --build --preset debug` and `ctest --preset debug` need no directories. 4. **A workflow preset** (schema 6, CMake 3.25 or newer) named `ci` chains configure, build and test. The CI job becomes `cmake --workflow --preset ci`, so a developer reproduces CI with the same command. 5. **`CMakeUserPresets.json`** is listed in `.gitignore`; developers inherit shared presets there for local paths, extra checks or experiments. What stays out of the committed file: absolute machine paths, credentials, and settings only one person needs. ## Presets must remain optional `CMakeLists.txt` must still configure with a plain `cmake -S . -B build`. Distribution packagers, projects consuming ours through `FetchContent` or `add_subdirectory`, and anyone on an older CMake will not run our presets. Presets record **defaults and conventions**; requirements belong in the project, for example as `target_compile_features` or checks that fail clearly. ## Choosing the supported CMake range The `cmake_minimum_required(VERSION <min>...<policy_max>)` line is a support statement with costs on both sides: | Lower `<min>` | Higher `<min>` | |---|---| | more users can build without upgrading CMake | newer commands, presets schemas and fixes available | | more `if(POLICY ...)` guards and older behaviours to test | users on older platforms must install a newer CMake | | CI must cover an older release | fewer combinations to test | Inputs that usually decide it: the CMake shipped with the oldest platform the team supports, what IDEs and CI images provide, and which features the build needs (for example, workflow presets need 3.25). CMake 4 removed compatibility below 3.5 and deprecated below 3.10, which sets a hard floor and a soft one. Keep `<policy_max>` at the newest CMake the team actually tests, and keep the presets `version` at a schema the oldest supported CMake can read, since a newer schema makes the file unreadable there. ## Keeping it current A standard that is never updated becomes the next legacy. Practices that keep it alive: - **A CI matrix at both ends** of the supported range, so a feature or policy dependency on either end is caught. - **Treat policy warnings as work items.** `Policy CMPxxxx is not set` warnings predict what breaks when `policy_max` is raised. - **A cadence and an owner** for raising `policy_max`, and for raising `<min>` when the oldest platform drops out. - **Temporary `OLD` settings carry a ticket** and are removed on the next upgrade. - **Review changes to `CMakePresets.json`** like build code: a new cache variable in a shared preset changes every developer's build. ## Where teams disagree There is no universal answer, which is why this is a lead's call: - A library with many external users leans to a low `<min>` and minimal presets. - An application team with controlled build images can require a recent CMake, use workflow presets heavily and drop guards. - A monorepo with many projects benefits from one shared base presets file pulled in with `include` (schema 4), at the cost of coupling all projects to its schema version. Whatever the choice, write it down beside the presets file: the supported range, who changes it, and how a developer adds a personal variant without touching the shared file.
- A developer wants extra sanitizer flags only on their machine. Where should they go?In their own `CMakeUserPresets.json`, as a preset that inherits a shared configure preset and adds the cache variables they need. The user file implicitly includes `CMakePresets.json`, is ignored by version control, and leaves the shared presets unchanged for everyone else.
- Why test CI at both ends of the cmake_minimum_required range?The minimum end catches uses of commands, presets fields or policies the oldest supported CMake lacks; the maximum end catches code that relies on an OLD policy behaviour the newest CMake has turned to NEW. Testing only the CMake on developers' machines verifies neither promise.
- Once presets exist, CMakeLists.txt no longer needs to configure without them
- The minimum CMake version should be whatever the lead has installed
- CI scripts should keep their own -D flags separate from the presets
- Raising policy_max is free because newer CMake is always backward compatible
- Every developer's local presets belong in the shared CMakePresets.json