In CMake, why can cmake -DRENDER_BACKEND=metal seem ignored when CMakeLists.txt also calls set(RENDER_BACKEND vulkan)?
answer
- two kinds of variable, one name
- normal binding is looked up first
- cache is the fallback
- $CACHE{NAME} skips the normal one
- CMP0126 and first-run surprises
basics
~10 sset(RENDER_BACKEND vulkan) creates a normal variable, and ${RENDER_BACKEND} looks up normal variables before the cache. The -D value still sits in the cache, but the normal binding hides it.
solid answer
~40 sCMake keeps **normal variables** (bound in a directory, function or block scope) apart from **cache entries** (persistent, global). A `${NAME}` reference first searches the normal bindings and falls back to the cache only when none is set. `-DRENDER_BACKEND=metal` writes the cache entry; `set(RENDER_BACKEND vulkan)` binds a normal variable of the same name, so every later `${RENDER_BACKEND}` reads `vulkan`. `$CACHE{RENDER_BACKEND}` still returns `metal`, and `unset(RENDER_BACKEND)` exposes it again. The fix is to declare user-settable values as cache entries, `set(RENDER_BACKEND vulkan CACHE STRING "...")` or `option()`, which leave an existing `-D` value alone. Policy CMP0126 matters too: under its OLD behaviour `set(CACHE)` can delete a same-named normal variable, typically on the first run only.
code
cmake · 10 linescmake_minimum_required(VERSION 3.25)
project(renderer NONE)
set(RENDER_BACKEND "vulkan") # normal variable: hides any -D value
set(TEX_CACHE_MB "256" CACHE STRING "Texture cache size")
message(STATUS "RENDER_BACKEND=${RENDER_BACKEND} cache=$CACHE{RENDER_BACKEND}")
message(STATUS "TEX_CACHE_MB=${TEX_CACHE_MB}")
unset(RENDER_BACKEND)
message(STATUS "after unset: RENDER_BACKEND=${RENDER_BACKEND}")go deeper
Recall that set(NAME value) and set(NAME value CACHE ...) create two different kinds of variable that can share a name.
Explain the lookup order, normal bindings first and then the cache, and why unset() exposes a cached value instead of clearing it.
Diagnose a value that differs between the first and second configure as policy CMP0126 under an old minimum version, and fix the declaration.
Set the convention that user-settable values are cache entries and computed values are normal variables, and enforce it in review.
## Two stores behind one name The CMake language has two kinds of variable that can share a name: - **Normal variables** are bound with `set(NAME value)` in the current **scope**: a directory (each `CMakeLists.txt`), a function call, or a `block()`. They vanish when their scope ends and are never saved between runs. - **Cache entries** live in `CMakeCache.txt`, are global to the build tree, and persist across runs. `cmake -D`, `option()`, and `set(NAME value CACHE TYPE "doc")` write them. All values are strings. What decides which one you get is the lookup rule. ## The lookup rule The `cmake-language(7)` manual states it precisely: when evaluating `${NAME}`, CMake searches the function call stack, then the current directory scope, for a binding. If a **set** binding is found, its value is used. If an **unset** binding is found, or no binding at all, CMake then searches the cache. Two consequences: 1. A normal variable **shadows** a cache entry of the same name for every reference in its scope and the scopes that inherit it. 2. `unset(NAME)` on the normal variable does not make `${NAME}` empty: it **exposes** the cache entry again. To get an empty value while a cache entry exists, use `set(NAME "")`. The `$CACHE{NAME}` reference bypasses the normal bindings and reads the cache entry directly. ## The scenario, reproduced ```cmake set(RENDER_BACKEND "vulkan") message(STATUS "RENDER_BACKEND=${RENDER_BACKEND} cache=$CACHE{RENDER_BACKEND}") unset(RENDER_BACKEND) message(STATUS "after unset: RENDER_BACKEND=${RENDER_BACKEND}") ``` Configured with `-DRENDER_BACKEND=metal`, CMake 4.4.4 prints `RENDER_BACKEND=vulkan cache=metal`, then `after unset: RENDER_BACKEND=metal`. The user's value was never lost; it was hidden. ## Fixing it | Project code | What a -D value does | |---|---| | `set(RENDER_BACKEND vulkan)` | Hidden for the rest of the scope | | `set(RENDER_BACKEND vulkan CACHE STRING "Renderer")` | Kept: a non-`FORCE` cache set does not overwrite an existing entry | | `option(USE_VULKAN "Vulkan renderer" ON)` | Kept: `option()` does nothing if the variable is already set | | `set(RENDER_BACKEND vulkan CACHE STRING "Renderer" FORCE)` | Overwritten on every configure | | `if(NOT DEFINED RENDER_BACKEND)` then `set(RENDER_BACKEND vulkan)` | Kept, though the default never appears in the cache | The general rule: anything a user is meant to override is declared as a cache entry; normal variables hold values the project computes. ## CMP0126: the first-run trap What if the project sets both, a normal variable followed by a cache declaration of the same name? The answer depends on policy **CMP0126**, introduced in CMake 3.21: - **NEW**: `set(CACHE)` never removes a normal variable of the same name. - **OLD**: `set(CACHE)` removes the normal variable when no cache entry existed before, when the existing entry had no type (an untyped `-D`), or when `FORCE` or `INTERNAL` was used. Under OLD, the result differs between the first and later runs of the same build tree. With `set(MAX_PLAYERS 8)` followed by `set(MAX_PLAYERS 16 CACHE STRING "...")`, a project declaring `cmake_minimum_required(VERSION 3.20)` printed `16` on the first configure and `8` on the second under CMake 4.4.4; with `VERSION 3.21` it printed `8` both times. A policy introduced after the version a project declares is left unset, and an unset CMP0126 uses OLD behaviour, so older minimum versions keep the trap. ## Where the shadowing normal variable comes from In real projects the stray `set()` is rarely next to the `-D` you are debugging. Typical sources: - a parent directory's `CMakeLists.txt`, whose normal variables every subdirectory inherits as a copy; - a file pulled in with `include()`, which runs in the includer's scope, so its plain `set()` calls land there; - a function that writes the name back with `set(... PARENT_SCOPE)`; - a toolchain file or a find module that sets a result variable with the same name as a user setting. ## How to debug it - Print both views: `message(STATUS "${NAME} / $CACHE{NAME}")`. - Grep the project for `set(NAME` without `CACHE`; one stray normal `set` in a parent directory is enough. - Check the cache with `cmake -LAH` to confirm the `-D` value actually landed. - Check the policy version in `cmake_minimum_required` when a value changes between the first and second configure.
- Why does unset(NAME) not give an empty value when a cache entry of that name exists?`unset(NAME)` removes the normal binding, and the lookup rule then falls back to the cache, so `${NAME}` returns the cached value. To force an empty result in the current scope, write `set(NAME "")`: that keeps a normal binding whose value is the empty string, which still shadows the cache entry.
- What does policy CMP0126 change, and why does it make the first configure differ from the second?Under OLD behaviour, `set(CACHE)` deletes a same-named normal variable when the entry is new, untyped, or written with `FORCE` or `INTERNAL`. On a fresh build tree the entry is new, so the normal variable disappears and the cache value is read; on the next run the entry exists, the normal variable survives and shadows it. NEW, the default for projects declaring 3.21 or later, never removes it.
- Believes a -D value always overrides set() in CMakeLists.txt
- Thinks unset(NAME) leaves ${NAME} empty even with a cache entry
- Assumes normal and cache variables are the same storage
- Expects $ENV{NAME} to read the cache entry
- Treats a value that changes between first and second configure as random