skip to content

In CMake, what problem do CMakePresets.json and CMakeUserPresets.json solve, and which one belongs in version control?

level: juniorimportance: should knowfreq 45%

answer

  1. the -D flags everyone types
  2. shared file versus personal file
  3. cmake --preset <name>
  4. command line still overrides

basics

~20 s

They 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 s

Without 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
console
$ 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

for a junior

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.

for a middle

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.

for a senior

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.

for a principal

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