In CMake, what problem do CMakePresets.json and CMakeUserPresets.json solve, and which one belongs in version control?
answer
- the -D flags everyone types
- shared file versus personal file
- cmake --preset <name>
- command line still overrides
basics
~20 sThey record named configure, build and test settings, such as generator, build directory and cache variables, so everyone runs cmake --preset <name> instead of retyping -D flags. CMakePresets.json is committed for the project; CMakeUserPresets.json holds personal presets and stays out of version control.
solid answer
~40 sWithout presets, each developer and each CI job reconstructs the configure line by hand: generator, `-B` directory, `-DCMAKE_BUILD_TYPE`, toolchain file, project options. They drift. `CMakePresets.json`, supported since CMake 3.19 and placed beside the top-level `CMakeLists.txt`, names those settings once: a configure preset carries `generator`, `binaryDir`, `cacheVariables`, `environment` and more, and `cmake --preset debug` applies them. Build and test presets let `cmake --build --preset debug` and `ctest --preset debug` reuse the same build directory. `CMakePresets.json` is meant to be committed; `CMakeUserPresets.json` has the same format, is for one developer's local variants, should be ignored by version control, and automatically sees the presets of `CMakePresets.json`. Anything given on the command line still wins: `cmake --preset debug -DMYVAR=2` overrides the preset's value. `cmake --list-presets` shows what is available.
code
console · 19 lines$ cmake --list-presets=all
Available configure presets:
"my-debug"
"debug"
"release"
Available build presets:
"debug"
"release"
Available test presets:
"debug"
Available workflow presets:
"ci"go deeper
Know that CMakePresets.json holds named configure, build and test settings, that cmake --preset <name> applies them, and that the user file stays out of git.
Explain the fields of a configure preset, how -D on the command line overrides a preset, and how build and test presets reuse the configure preset's build directory.
Use presets to make developer, CI and IDE configurations identical, keep machine-specific paths in user presets, and keep CMakeLists.txt usable without any preset.
Treat the shared presets file as the team's build contract, deciding which options are standard and how far each developer may diverge.
## The problem presets solve A CMake project is configured with a command line, and that command line tends to grow: ```bash cmake -S . -B build/debug -G Ninja \ -DCMAKE_BUILD_TYPE=Debug \ -DCMAKE_TOOLCHAIN_FILE=cmake/arm.cmake \ -DLEDGER_WARNINGS_AS_ERRORS=ON ``` When every developer and every CI job types its own version, the builds quietly differ: one person forgets the warnings option, CI uses a different generator, a new team member does not know the toolchain file exists. The settings live in people's shell history instead of in the repository. **CMake presets** (introduced in CMake 3.19) move those settings into JSON files that CMake itself reads. A preset is a **named** bundle of options, and the command line shrinks to the name: ```bash cmake --preset debug cmake --build --preset debug ctest --preset debug ``` ## The two files | | `CMakePresets.json` | `CMakeUserPresets.json` | |---|---|---| | Purpose | project-wide presets the team shares | one developer's local presets | | Version control | committed | not committed, listed in `.gitignore` | | Location | beside the top-level `CMakeLists.txt` | the same directory | | Can use the other file's presets | no | yes, it implicitly includes `CMakePresets.json` | Both files have exactly the same format, both are optional, and at least one must exist for `--preset` to work (CMake 4.4 also adds `--presets-file` to read a different file instead). Because `CMakeUserPresets.json` includes `CMakePresets.json`, a developer can write a personal preset that **inherits** a shared one and changes a single option. ## What a configure preset holds A configure preset is an object in the `configurePresets` array. Common fields: - `name`, the identifier passed to `--preset`; - `generator`, such as `Ninja`; - `binaryDir`, the build directory, often `${sourceDir}/build/${presetName}`; - `cacheVariables`, the values you would otherwise pass with `-D`; - `environment`, environment variables for the configure step; - `toolchainFile`, the equivalent of `CMAKE_TOOLCHAIN_FILE`; - `inherits` and `hidden`, to build presets out of shared bases. A minimal shared file: ```json { "version": 6, "configurePresets": [ { "name": "debug", "generator": "Ninja", "binaryDir": "${sourceDir}/build/${presetName}", "cacheVariables": { "CMAKE_BUILD_TYPE": "Debug" } } ] } ``` The required `version` field names the schema version of the file; each newer schema needs a newer CMake (6 needs 3.25, for example), so a team picks the lowest version that has the fields it uses. ## How presets interact with the command line `cmake --preset debug` reads the presets before any other option, then applies the command line on top. The CMake manual is explicit: if a preset sets a variable to `1` and the user passes `-D` with `2`, the value `2` is used. You can also pass `-B` to build somewhere other than the preset's `binaryDir`. Presets therefore standardize the default without taking away a developer's ability to experiment. ## Macros keep the file portable Hard-coded paths would make a shared presets file useless on other machines, so string fields support **macro expansion**: - `${sourceDir}` expands to the project's source directory and `${presetName}` to the preset's own name, which is why `${sourceDir}/build/${presetName}` gives each preset its own build tree; - `$env{NAME}` reads an environment variable, with the preset's own `environment` applied, and `$penv{NAME}` reads the parent environment only; - `${hostSystemName}` (schema 3) names the host system, and a `condition` object (schema 3) can use it so a Windows-only preset is neither listed nor usable on other hosts. With these, one committed file serves every developer's checkout location and operating system. ## Useful commands 1. `cmake --list-presets` lists configure presets; `--list-presets=all` lists every kind. 2. `cmake --preset <name>` configures. 3. `cmake --build --preset <name>` builds in the directory the matching configure preset used. 4. `ctest --preset <name>` runs the tests with a test preset's options. Presets are also read by the CMake GUI and by IDEs that support the format, so the same file drives the command line, CI and editors. ## What presets are not - They do not replace `CMakeLists.txt`: the project must still configure correctly with a plain command line, for packagers and for anyone embedding it. - They are not a place for secrets or machine-specific paths in the committed file; those belong in `CMakeUserPresets.json` or the environment.
- A preset sets PR_WARNINGS_AS_ERRORS to ON; how do you turn it off for one configure without editing the file?Pass it on the command line: `cmake --preset debug -DPR_WARNINGS_AS_ERRORS=OFF`. Presets are read first and command-line options are applied on top, so the explicit `-D` wins. For a permanent personal variant, write a preset in `CMakeUserPresets.json` that inherits `debug` and overrides that variable.
- Why should CMakeUserPresets.json stay out of version control?It exists for one developer's local choices, such as a scratch build directory, a local dependency path or extra debugging options. Committing it would push those choices on everyone, and the CMake presets manual says it should not be checked in, while `CMakePresets.json` may be.
- Presets replace CMakeLists.txt, so the project no longer needs to configure without them
- A preset's cacheVariables cannot be overridden from the command line
- CMakeUserPresets.json should be committed so everyone shares the same presets
- Presets only work inside IDEs, not with the cmake command line
- CMakePresets.json can be placed in any subdirectory of the project