skip to content

In CMake, a game adds a vendored physics library with add_subdirectory; how do you turn off its option(PHYSICS_BUILD_TESTS ... ON) without editing its files?

level: seniorimportance: should knowfreq 42%

answer

  1. set a normal variable first
  2. option() honours normal variables
  3. policy CMP0077, since 3.13
  4. OLD: first run differs from second
  5. CMAKE_POLICY_DEFAULT_CMP0077, not FORCE

basics

~10 s

Set a normal variable, set(PHYSICS_BUILD_TESTS OFF), before add_subdirectory. With policy CMP0077 NEW, option() then does nothing. If the library's minimum version predates 3.13, also set CMAKE_POLICY_DEFAULT_CMP0077 to NEW.

solid answer

~40 s

Write `set(PHYSICS_BUILD_TESTS OFF)` before `add_subdirectory(third_party/physics)`. The child directory inherits that normal variable, and since CMake 3.13, under policy **CMP0077** NEW, `option()` does nothing when a normal variable of that name exists: no cache entry is created and the subproject reads `OFF`. The trap is a library whose `cmake_minimum_required` predates 3.13. CMP0077 is then unset and behaves as OLD: on the first configure `option()` creates the cache entry and deletes the normal variable, so tests build, and on the second run the override wins. Fix that from the parent with `set(CMAKE_POLICY_DEFAULT_CMP0077 NEW)` before `add_subdirectory`, or, in CMake 4.0 and later, `CMAKE_POLICY_VERSION_MINIMUM`. Avoid `set(... CACHE BOOL "" FORCE)`: it overrides the user's `-D` every run.

code

cmake · 14 lines
cmake
# game/CMakeLists.txt
cmake_minimum_required(VERSION 3.25)
project(game NONE)

# The library declares cmake_minimum_required(VERSION 3.10),
# so CMP0077 would otherwise be unset (OLD) inside it.
set(CMAKE_POLICY_DEFAULT_CMP0077 NEW)
set(PHYSICS_BUILD_TESTS OFF)
add_subdirectory(third_party/physics)

# third_party/physics/CMakeLists.txt (untouched):
#   cmake_minimum_required(VERSION 3.10)
#   project(physics NONE)
#   option(PHYSICS_BUILD_TESTS "Build physics tests" ON)

go deeper

for a junior

Recall that a normal variable set before add_subdirectory is visible inside that subdirectory.

for a middle

Explain that option() does nothing when a normal variable exists, and that this is policy CMP0077, introduced in CMake 3.13.

for a senior

Diagnose first-run-versus-second-run differences as CMP0077 OLD in an old subproject, and fix it with CMAKE_POLICY_DEFAULT_CMP0077 rather than FORCE.

for a principal

Weigh vendoring with add_subdirectory against installed packages, given how much policy and option plumbing each embedded project costs.

## The scenario A game repository vendors a physics library under `third_party/physics` and pulls it in with `add_subdirectory()`. The library's `CMakeLists.txt` declares `option(PHYSICS_BUILD_TESTS "Build physics tests" ON)`, so every configure of the game also builds the library's test suite. Editing the vendored file is off the table, because the next update would overwrite it. ## The intended mechanism: a normal variable plus CMP0077 Two rules combine: - **Directory scope inheritance**: `add_subdirectory()` initialises the child's scope with a copy of the parent's normal variables, so a value set beforehand in the parent is visible in the child. - **`option()` honours normal variables**: the `option` documentation says that if the variable is already set as a normal or cache variable, the command does nothing. That is policy **CMP0077**'s NEW behaviour, introduced in CMake 3.13. ```cmake set(PHYSICS_BUILD_TESTS OFF) # normal variable, parent scope add_subdirectory(third_party/physics) # option() sees it and does nothing ``` Under NEW, CMake 4.4.4 reports `PHYSICS_BUILD_TESTS=OFF` on every run, and no `PHYSICS_BUILD_TESTS` entry appears in `CMakeCache.txt`. The override stays a project decision rather than a user setting. ## The trap: CMP0077 OLD A policy is set by `cmake_minimum_required(VERSION ...)` in the subproject. If the library declares a version older than 3.13, CMP0077 is **unset**, which means OLD behaviour plus a warning. Under OLD, when the cache entry does not exist or has no type, `option()` creates the cache entry, gives it type `BOOL`, and **removes** the normal variable. On later runs the typed entry exists, so `option()` changes nothing and the normal variable survives. The result is a build that changes between runs. With the library declaring `cmake_minimum_required(VERSION 3.10)`, CMake 4.4.4 produced: | Run | Subproject sees | Cache | |---|---|---| | First configure | `ON` (plus a CMP0077 warning) | `PHYSICS_BUILD_TESTS:BOOL=ON` | | Second configure | `OFF` | `PHYSICS_BUILD_TESTS:BOOL=ON`, now shadowed | A CI job that always configures fresh would build the tests every time, while developers' second runs would not. ## Fixing OLD from the parent, without editing the library 1. **`set(CMAKE_POLICY_DEFAULT_CMP0077 NEW)`** before `add_subdirectory()`. `CMAKE_POLICY_DEFAULT_CMP<NNNN>` supplies the setting for a policy that the subproject's version leaves unset; its documentation names exactly this use, a project adding a third-party subdirectory. With it, the 3.10 library reported `OFF` from the first run, with no warning and no cache entry. 2. **`CMAKE_POLICY_VERSION_MINIMUM`**, added in CMake 4.0, raises the policy version of projects that declare an older one, turning on every policy up to that version. It is broader: it changes many policies, not one. 3. **Prefer the library's own switch** when it has one. Many projects gate their tests on the standard `BUILD_TESTING` variable, or on `PROJECT_IS_TOP_LEVEL` (CMake 3.21), so they skip tests automatically when embedded. ## What not to do - **`set(PHYSICS_BUILD_TESTS OFF CACHE BOOL "" FORCE)`**: it works under either policy, but it writes the user-visible cache on every configure, so a developer who passes `-DPHYSICS_BUILD_TESTS=ON` to debug the library is silently overruled. - **A plain `-DPHYSICS_BUILD_TESTS=OFF` in a README**: it relies on every developer and every CI job remembering the flag. - **Setting the variable after `add_subdirectory()`**: the child has already run, and it copied the parent's scope before your `set()`. ## Checking what actually happened - Search the configure log for `Policy CMP0077 is not set`: that warning means the library is running OLD behaviour. - Read the library's `cmake_minimum_required` line: a version below 3.13 leaves CMP0077 unset unless the parent supplies a default. - Grep `CMakeCache.txt` for the option name: under NEW with the override in place there is **no** entry; a `BOOL` entry means `option()` ran without seeing your variable. - `cmake --help-policy CMP0077` prints the exact OLD and NEW rules for the CMake version you are running. ## Scope hygiene The normal variable stays set in the parent directory, so every later `add_subdirectory()` inherits it too. When several vendored projects need different values for similarly named options, wrap each pair in `block()` (CMake 3.25) so the overrides do not leak. The same pattern applies to a dependency that `FetchContent_MakeAvailable` builds from source, because it adds that dependency with `add_subdirectory()`.

  • Why does CMake create no cache entry for the option when the normal-variable override works?
    Under CMP0077 NEW, `option()` does nothing at all when a normal variable of that name exists: it neither creates nor updates the cache entry. The value is therefore a project decision, invisible in `cmake-gui`, and a later `-D` for that name is hidden by the parent's normal variable for as long as it is set.
  • How does CMP0126 differ from CMP0077?
    Both stop a cache declaration from deleting a same-named normal variable. The difference is what happens to the entry: under CMP0126 NEW, `set(CACHE)` still creates the entry if it did not exist, while under CMP0077 NEW, `option()` creates nothing when a normal variable exists.

  • Overrides a vendored option with CACHE FORCE in the parent project
  • Sets the override after add_subdirectory has already run
  • Assumes option() always wins inside the subdirectory that declares it
  • Treats a value that flips on the second configure as a CMake bug
  • Edits the vendored CMakeLists.txt and loses it on the next update

Assumes CMake 4.x: CMP0077 dates from 3.13, CMAKE_POLICY_VERSION_MINIMUM was added in 4.0, and 4.0 rejects policy versions below 3.5.