skip to content

In CMake, why does changing an option() default from ON to OFF in CMakeLists.txt not affect an existing build directory?

level: middleimportance: must knowfreq 62%

answer

  1. defaults apply to a fresh cache
  2. option() leaves existing entries alone
  3. CI builds from scratch, laptops do not
  4. FORCE overrides the user too
  5. -U NAME or --fresh

basics

~20 s

option() and set(... CACHE ...) only write an entry that does not exist yet. An existing build tree already holds the old value in CMakeCache.txt, so the new default is ignored until that entry is removed or overwritten.

solid answer

~40 s

A project default lands in the cache only when the entry does not exist. `option(ENABLE_SIMD "..." OFF)` does nothing if `ENABLE_SIMD` is already set, and `set(... CACHE ...)` without `FORCE` does not overwrite an existing entry. The first configure of a build tree wrote `ENABLE_SIMD:BOOL=ON` into `CMakeCache.txt`; every later run reloads it, so editing the default changes nothing there. A fresh CI build tree sees the new default, which is why CI and a developer's machine can disagree. Fixes: `cmake -U ENABLE_SIMD`, `cmake --fresh`, deleting `CMakeCache.txt`, or passing `-DENABLE_SIMD=OFF`. Adding `FORCE` is the wrong fix: it overwrites the user's own choice on every configure, so the value stops being an option at all.

code

cmake · 8 lines
cmake
cmake_minimum_required(VERSION 3.25)
project(engine NONE)

# Edited from ON to OFF after build/ was first configured.
option(ENABLE_SIMD "Use SIMD kernels" OFF)
set(LOG_LEVEL "debug" CACHE STRING "Default log level")

message(STATUS "ENABLE_SIMD=${ENABLE_SIMD} LOG_LEVEL=${LOG_LEVEL}")

go deeper

for a junior

Recall that a project's option() default only applies the first time a build directory is configured.

for a middle

Explain that option() and non-FORCE cache sets never overwrite an existing entry, and list -U, --fresh and -D as the ways to pick up a change.

for a senior

Diagnose CI-versus-laptop differences by comparing caches, and argue why FORCE on a user option is a defect rather than a fix.

for a principal

Set a team rule for changing defaults: rename options whose meaning changes, announce resets, and keep CI configuring from scratch.

## The scenario A developer changes one line of `CMakeLists.txt`, from `option(ENABLE_SIMD "Use SIMD kernels" ON)` to `OFF`, reruns `cmake` in an existing build directory and the binary is still built with SIMD. CI, which configures a new build directory each time, builds without it. Nothing is broken: this is how the **cache** is meant to work. ## Defaults only fill empty slots A CMake build tree keeps its user-settable values in `CMakeCache.txt`. The commands a project uses to declare those values are deliberately polite: - **`option(<variable> "<help_text>" [value])`**: if the variable is already set as a normal or cache variable, the command does nothing. - **`set(<variable> <value> CACHE <type> <docstring>)`** without `FORCE`: the CMake documentation says that because cache entries are meant to provide user-settable values, this does not overwrite existing entries. So the default written in `CMakeLists.txt` is used exactly once: on the first configure of a build tree, when the entry does not exist yet. Every later run reloads the cached value, and the declaration sees an existing entry and steps aside. CMake prints no warning that the cached value differs from the default in the source. ## Reproducing it With CMake 4.4.4: ```console $ cmake -S . -B build # option(... ON), set(LOG_LEVEL "info" CACHE ...) -- ENABLE_SIMD=ON LOG_LEVEL=info # edit CMakeLists.txt: option default OFF, LOG_LEVEL default "debug" $ cmake -S . -B build -- ENABLE_SIMD=ON LOG_LEVEL=info $ cmake -U ENABLE_SIMD -S . -B build -- ENABLE_SIMD=OFF LOG_LEVEL=info $ cmake --fresh -S . -B build -- ENABLE_SIMD=OFF LOG_LEVEL=debug ``` ## Why the automatic re-run does not help After you edit `CMakeLists.txt`, running the build tool (`ninja`, `make`, or `cmake --build build`) notices the change and re-runs the configure step on its own. That is why the edit seems to be ignored even though CMake visibly ran: the re-run reuses the same build tree and therefore the same `CMakeCache.txt`. To confirm what a build tree really holds, list it with its help strings: ```console $ cmake -LH -B build | grep -B1 ENABLE_SIMD // Use SIMD kernels ENABLE_SIMD:BOOL=ON ``` ## Ways to pick up the new default | Action | Effect | |---|---| | `cmake -U ENABLE_SIMD -B build` | Removes that entry; the next configure re-creates it from the current default. Globs such as `-U 'ENABLE_*'` work. | | `cmake --fresh -B build` (CMake 3.24 and later) | Deletes `CMakeCache.txt` and `CMakeFiles/` and configures from scratch, so every default is re-read. | | Delete `build/CMakeCache.txt` or the whole build directory | Same as `--fresh`, by hand. | | `cmake -DENABLE_SIMD=OFF -B build` | Sets the value explicitly; the default is still not what produced it. | | `ccmake build` or `cmake-gui` | Edit the entry interactively. | None of these is `cmake --build build --clean-first`: that cleans build outputs, not the cache. Touching `CMakeLists.txt` re-runs the configure step too, but the cached entry still wins. ## Why FORCE is the wrong fix The tempting project-side fix is `set(ENABLE_SIMD OFF CACHE BOOL "Use SIMD kernels" FORCE)`. It does make every build tree follow the source, but it also overwrites whatever the user passed with `-DENABLE_SIMD=ON` on **every** configure. The entry still shows up in `cmake-gui` as if it were editable, yet any edit is silently undone. `FORCE` belongs to values the project computes and owns, such as an `INTERNAL` entry used as persistent storage (the `INTERNAL` type implies `FORCE`), not to a user's option. ## Handling a default change on a team 1. **Announce it with the fix**: tell people to run `cmake -U NAME` or `--fresh`, since nothing in the build will tell them. 2. **Rename the option** when the meaning changed (for example `ENABLE_SIMD` to `ENABLE_SIMD_KERNELS`): the new name has no cached entry anywhere, so every tree picks up the new default, and the old entry becomes harmless clutter. 3. **Keep CI honest**: CI that reuses a build directory between jobs has the same stale-cache problem, so either configure fresh or pass every option explicitly. 4. **Print the effective values** with `message(STATUS ...)` for the handful of options that change binaries, so a log shows what was really used. The diagnosis habit that pays off: when a build ignores a change to a default, read `CMakeCache.txt` (or `cmake -LH`) before reading the code.

  • When is set(... CACHE ... FORCE) the right tool?
    When the project, not the user, owns the value: a computed result it wants to persist across runs, often with type `INTERNAL`, which implies `FORCE` and hides the entry from `cmake-gui`. For a user-facing option it is wrong, because it discards the user's `-D` on every configure while still presenting the entry as editable.
  • Why can CI and a developer's machine build different binaries from the same commit?
    CI usually configures a new build directory, so every `option()` and cache default is read from the source. A developer's long-lived build tree keeps the values from its first configure, plus any `-D` they passed months ago. Same source, different caches; comparing `cmake -LH` output from both is the quickest way to see it.

A cache default is like a form field's pre-filled text: it fills an empty box once, and once someone has typed in the box, changing the pre-filled text on the blank form does nothing to forms already filled in.

  • Assumes the newest option() default always wins on reconfigure
  • Adds FORCE to a user option to make a new default stick
  • Thinks cmake --build --clean-first resets cached option values
  • Expects CMake to warn when a cached value differs from the default
  • Believes touching CMakeLists.txt makes CMake re-read every default