skip to content

In CMake, what does passing -DNAME=VALUE to the cmake command do, and why does the value persist on later runs?

level: juniorimportance: must knowfreq 64%

answer

  1. a file in the build tree
  2. CMakeCache.txt holds NAME:TYPE=VALUE
  3. project defaults never overwrite it
  4. typed or UNINITIALIZED entries
  5. -U, --fresh, cmake -L

basics

~20 s

cmake -DNAME=VALUE creates or updates a cache entry in the build tree's CMakeCache.txt. The cache survives between runs, so later configures of that build directory keep the value until someone changes or removes the entry.

solid answer

~40 s

`cmake -DNAME=VALUE` creates or updates a **cache entry**, which CMake stores in `CMakeCache.txt` inside the build directory. Every later `cmake` run on that build tree reloads the cache, so the value sticks even when you stop passing `-D`. Because `option()` and `set(... CACHE ...)` without `FORCE` never overwrite an existing entry, the `-D` value beats the project's default. The typed form `-DNAME:BOOL=OFF` records a type; the untyped form leaves the type `UNINITIALIZED` until the project declares the entry. A misspelt name is not rejected: it becomes a stray entry and CMake prints a `Manually-specified variables were not used by the project` warning. You inspect the cache with `cmake -L` (or `-LAH`), `ccmake` or `cmake-gui`, and remove entries with `-U <glob>` or start over with `--fresh`.

code

console · 14 lines
console
$ cmake -S . -B build -DENABLE_SMID=OFF
...
CMake Warning (unused-cli):
  Manually-specified variables were not used by the project:

    ENABLE_SMID

$ grep ENABLE_S build/CMakeCache.txt
ENABLE_SIMD:BOOL=ON
ENABLE_SMID:UNINITIALIZED=OFF
$ cmake -B build -DENABLE_SIMD=OFF
$ cmake -B build
$ grep ENABLE_SIMD build/CMakeCache.txt
ENABLE_SIMD:BOOL=OFF

go deeper

for a junior

Recall that -D writes a cache entry into CMakeCache.txt in the build directory and that the entry persists across later configure runs.

for a middle

Explain why option() and non-FORCE cache sets lose to -D, what an UNINITIALIZED entry is, and how -U, --fresh and cmake -L help.

for a senior

Show you diagnose builds by reading the cache first, and catch typo'd -D names through the unused-cli warning before they waste a day.

for a principal

Decide where cache values come from on a team, so configure lines are reproducible and nobody depends on a hand-edited cache.

## What -D does on the cmake command line When you configure a project, CMake runs the project's `CMakeLists.txt` files and writes a **build tree**: the build files for the chosen generator plus a file called `CMakeCache.txt`. That file is the **cache**: a flat list of entries of the form `NAME:TYPE=VALUE` that CMake reloads every time it configures that build tree again. `cmake -DNAME=VALUE` (or `-D NAME=VALUE`) does one thing: it **creates or updates a cache entry** before the project's own code runs. The CMake manual describes it as specifying "a setting that takes priority over the project's default value". Note the vocabulary trap: this is not the compiler's `-D` that defines a preprocessor macro. CMake's `-D` sets a CMake variable; whether that variable ever reaches the compiler depends on what the project does with it. ## Why the value persists The cache belongs to the **build directory**, not to the source tree and not to one command invocation. A typical session looks like this: 1. `cmake -S . -B build -DENABLE_SIMD=OFF` creates `build/CMakeCache.txt` with `ENABLE_SIMD:BOOL=OFF`. 2. A later `cmake -B build` (no `-D` at all) reloads the cache, so `ENABLE_SIMD` is still `OFF`. 3. The value changes only when someone passes another `-D`, edits it in `ccmake` or `cmake-gui`, removes it, or deletes the build tree. That persistence is by design: the cache is how a developer's choices survive the automatic re-runs of CMake that the build triggers whenever a `CMakeLists.txt` changes. ## Why -D beats the project's default Projects declare user-settable values with `option(NAME "help" ON)` or `set(NAME value CACHE TYPE "help")`. Neither overwrites an entry that already exists: - `option()` does nothing if the name is already set as a normal or cache variable. - `set(... CACHE ...)` without `FORCE` sets the entry only if it did not exist before. Because `-D` is applied first, the project's call finds the entry already present and leaves it alone. (A plain `set(NAME value)` in the project is a different story: it creates a **normal** variable that hides the cache entry. That precedence rule is its own topic.) ## Types and the UNINITIALIZED entry The typed form `-DNAME:TYPE=VALUE` records one of the cache types `BOOL`, `FILEPATH`, `PATH`, `STRING` or `INTERNAL`. The untyped form creates the entry with no type, which `CMakeCache.txt` shows as `UNINITIALIZED`. When the project later declares the entry with a type, CMake adds the type; for `PATH` and `FILEPATH` it also turns a relative command-line value into an absolute path. | Command line | Cache line after configure | |---|---| | `-DENABLE_SIMD:BOOL=OFF` | `ENABLE_SIMD:BOOL=OFF` | | `-DENABLE_SIMD=OFF`, project calls `option(ENABLE_SIMD ...)` | `ENABLE_SIMD:BOOL=OFF` | | `-DENABLE_SMID=OFF` (typo), nothing declares it | `ENABLE_SMID:UNINITIALIZED=OFF` | ## The typo trap CMake accepts any name after `-D`. A misspelt name does not fail the configure: it adds a stray entry and the option you meant keeps its default. CMake 4.4.4 does flag it at the end of that run: ```plaintext CMake Warning (unused-cli): Manually-specified variables were not used by the project: ENABLE_SMID ``` The warning appears only on the run that received the `-D`, so it is easy to scroll past, and the stray entry stays in the cache afterwards. ## Inspecting and resetting the cache - `cmake -L -B build` lists non-advanced cache entries; add `A` for advanced ones and `H` for their help strings (`-LAH`). - `ccmake build` (a terminal UI) and `cmake-gui` let you edit entries interactively. - `cmake -U 'ENABLE_*' -B build` removes matching entries; the next configure re-creates them from the project's defaults. - `cmake --fresh -B build` (added in CMake 3.24) deletes `CMakeCache.txt` and `CMakeFiles/` and configures from scratch. - `-C <file>` pre-loads a script of `set(... CACHE ...)` calls; when `-C` and `-D` touch the same entry, the manual says they apply in command-line order, and a non-`FORCE` `set` in the `-C` file always loses to `-D`. The practical habit: when a build behaves as if an option were set differently from what you believe, read the cache before reading the code.

  • What is the difference between -DNAME=VALUE and -DNAME:STRING=VALUE?
    Both create or update a cache entry. The typed form records the type immediately; the untyped form leaves it `UNINITIALIZED` until the project declares the entry with `option()` or `set(... CACHE <type> ...)`, which then adds the type. For `PATH` and `FILEPATH` declarations, CMake converts a relative command-line value to an absolute path at that point.
  • How do you reset a single cached value without deleting the whole build tree?
    Run `cmake -U NAME -B build` (it accepts `*` and `?` globs), then configure again: the project's `option()` or `set(... CACHE ...)` re-creates the entry with its current default. Editing the entry in `ccmake` or `cmake-gui`, or passing a new `-D`, also works. `cmake --fresh` resets everything, not just one entry.

  • Thinks cmake -D defines a preprocessor macro for the compiler
  • Expects a -D value to apply only to that one cmake invocation
  • Believes the project's option() default overrides an existing -D value
  • Assumes CMake rejects a misspelt -D name with an error
  • Edits CMakeLists.txt defaults and expects old build trees to follow