skip to content

Presets and Policies

CMakePresets.json records configure, build and test settings for a team, and modern CMake replaces directory-wide commands with targets. Interviewers check which habits you have.

on this pageshow

explore

questions

6

In CMake, what does cmake_minimum_required(VERSION 3.25...4.4) actually set, and what does CMake 4 do with a minimum below 3.5?

level: middleimportance: must knowfreq 55%

answer

  1. two numbers, two meanings
  2. the policy version
  3. NEW up to the max
  4. compatibility below 3.5 removed
  5. CMAKE_POLICY_VERSION_MINIMUM

basics

~20 s

It refuses CMake releases older than 3.25 and sets the policy version to 4.4, so every policy introduced up to 4.4 uses NEW behaviour. CMake 4 rejects a policy version below 3.5 with an error unless CMAKE_POLICY_VERSION_MINIMUM raises it.

solid answer

~40 s

`cmake_minimum_required(VERSION <min>...<policy_max>)` does two jobs. It stops with an error if the running CMake is older than `<min>`, and it sets the **policy version**: `<policy_max>` when given, otherwise `<min>`. Every policy introduced in that version or earlier is set to `NEW`; later policies stay unset, so they use their `OLD` behaviour and may warn. The range form (since 3.12) says: works with 3.25, tested and updated through 4.4; it does not forbid newer CMake. The call belongs at the top of the top-level `CMakeLists.txt`, before `project()`. CMake 4.0 removed compatibility with versions below 3.5: a policy version under 3.5 is a configure error, and since 3.31 one below 3.10 draws a deprecation warning. A user building an unmaintained project can pass `-DCMAKE_POLICY_VERSION_MINIMUM=3.5` (since 4.0) to try anyway.

go deeper

for a junior

Know that cmake_minimum_required is the first line of the top-level CMakeLists.txt and that CMake refuses to run when it is older than the stated minimum.

for a middle

Explain the policy version: NEW for policies up to it, unset and OLD for later ones, and what the <min>...<policy_max> range changes.

for a senior

Fix projects that CMake 4 rejects for a minimum below 3.5, know when CMAKE_POLICY_VERSION_MINIMUM is acceptable, and raise policy_max deliberately with each CMake upgrade.

for a principal

Set the supported CMake range as a team policy, balancing users on older distributions against the cost of carrying OLD behaviours.

## Two numbers with different jobs `cmake_minimum_required(VERSION 3.25...4.4)` looks like a single requirement, but the two numbers mean different things: | Part | Meaning | Effect | |---|---|---| | `<min>` (`3.25`) | the oldest CMake that may process the project | an older CMake stops with an error; `CMAKE_MINIMUM_REQUIRED_VERSION` is set to it | | `<policy_max>` (`4.4`) | the newest CMake the project has been updated for | sets the **policy version** | The `...` is literal and the range form exists since CMake 3.12; older releases read the dots as version separators and ignore the second part. The `FATAL_ERROR` keyword is still accepted but ignored by every release since 2.6. ## Policies and the policy version CMake changes behaviour carefully. When a release fixes or tightens something, it introduces a **policy** named `CMP<NNNN>` with an `OLD` behaviour (the historical one) and a `NEW` behaviour. The `cmake-policies` manual describes policies as deprecation mechanisms, not feature toggles. The **policy version** decides which ones a project gets: 1. every policy introduced in the policy version or earlier is set to **`NEW`**; 2. every policy introduced later is left **unset**; an unset policy uses its `OLD` behaviour, and CMake may warn that it is not set; 3. a `CMAKE_POLICY_DEFAULT_CMP<NNNN>` variable can give an unset policy a default from outside the project. So the second number is a promise about behaviour, not a ceiling on the tool. In the words of the documentation, `...<policy_max>` does not forbid later CMake versions; it records the newest version for which the project has been actively updated. ## What CMake 4 removed Old policies do not stay forever. The schedule documented in `cmake-policies` allows a warning about an `OLD` behaviour two years after the policy appears, and removal of the `OLD` behaviour in a later major version at least six years after. CMake 4.0 exercised that: - compatibility with CMake older than **3.5** is **removed**: a `cmake_minimum_required` or `cmake_policy(VERSION)` whose policy version is below 3.5 is an error; - since 3.31, a policy version below **3.10** draws a deprecation warning. Configuring a project that still says `cmake_minimum_required(VERSION 3.0)` with CMake 4.4 prints: ```plaintext CMake Error at CMakeLists.txt:1 (cmake_minimum_required): Compatibility with CMake < 3.5 has been removed from CMake. Update the VERSION argument <min> value. Or, use the <min>...<max> syntax to tell CMake that the project requires at least <min> but has been updated to work with policies introduced by <max> or earlier. Or, add -DCMAKE_POLICY_VERSION_MINIMUM=3.5 to try configuring anyway. ``` `CMAKE_POLICY_VERSION_MINIMUM` (new in 4.0) raises the policy version from outside, so a user can build an unmaintained third-party project. The variable's documentation says projects should not set it themselves; the real fix is to update the project's call. ## Where the call goes - **First line of the top-level `CMakeLists.txt`**, before `project()`, so the policy settings are in force before any command whose behaviour they affect. Policy `CMP0000` exists because projects once omitted it. - **Not inside a `function()`**: some effects stay in the function scope while policy settings leak to the caller, and the documentation discourages it. - **Subdirectories** get their own entry on the policy stack, so a `cmake_minimum_required` there affects that directory and below, not the parent. ## Choosing the numbers - Set `<min>` to the oldest CMake you test and support, not to whatever was installed when the file was written. Raising it is a compatibility decision for your users. - Set `<policy_max>` to the newest CMake you have actually tested, and raise it when you upgrade, after fixing whatever the new `NEW` behaviours break. - Prefer the range over a lone `<min>`: a lone `3.25` leaves every policy from 3.26 onward unset, so newer CMake releases keep warning and apply old behaviours you did not ask for. - Check the effective setting of one policy with `cmake_policy(GET CMP0115 var)`, which yields `NEW`, `OLD` or an empty string when unset.

  • What is the practical difference between cmake_minimum_required(VERSION 3.25) and cmake_minimum_required(VERSION 3.25...4.4) when run by CMake 4.4?
    Both refuse CMake older than 3.25. The first sets the policy version to 3.25, so policies added in 3.26 through 4.4 stay unset, keep their OLD behaviour and may warn. The second sets the policy version to 4.4, so all of those policies use NEW behaviour.
  • Should a project set CMAKE_POLICY_VERSION_MINIMUM in its own CMakeLists.txt to silence the CMake 4 error?
    No. Its documentation says projects should not set it as a way to choose their own policy version; it is meant for a user building a project they cannot edit. A maintained project fixes the `cmake_minimum_required` call, ideally with a range.

  • The second number in VERSION 3.25...4.4 forbids running with CMake newer than 4.4
  • cmake_minimum_required only checks the CMake version and changes no behaviour
  • An unset policy uses its NEW behaviour automatically
  • cmake_minimum_required can go anywhere, even after project() and add_subdirectory()
  • CMake 4 still accepts cmake_minimum_required(VERSION 2.8) with only a warning

Assumes CMake 4.4; compatibility below 3.5 was removed in 4.0, below 3.10 is deprecated since 3.31, and CMAKE_POLICY_VERSION_MINIMUM exists since 4.0.

open as a page

In CMake, why is target_compile_options preferred over directory-wide commands such as add_compile_options and include_directories?

level: middleimportance: must knowfreq 55%

basics

~20 s

Directory-wide commands affect every target in a directory and its subdirectories, depending on call order, and never reach consumers in other directories. target_* commands state each target's requirements explicitly and let PUBLIC and INTERFACE requirements propagate to whoever links it.

open as a page

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

level: juniorimportance: should knowfreq 45%

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.

open as a page

In CMakePresets.json, how do hidden presets, inherits, and build, test and workflow presets combine into one repeatable configure-build-test flow?

level: middleimportance: should knowfreq 40%

basics

~20 s

Shared settings go into a hidden configure preset that concrete presets inherit; build and test presets point at a configure preset and reuse its build directory; a workflow preset chains configure, build, test and package steps so cmake --workflow runs them all.

open as a page

After a CMake project raises its policy version, add_executable(app main) fails with Cannot find source file; why, and how do you migrate policies safely?

level: seniorimportance: should knowfreq 35%

basics

~20 s

Raising the policy version set CMP0115 to NEW, so CMake stopped guessing the .cpp extension. Fix the code to name main.cpp; migrate by reading each 'Policy CMPxxxx is not set' warning first and only using cmake_policy(SET ... OLD) temporarily.

open as a page

As a C++ team lead, how would you standardize CMake presets and the cmake_minimum_required range across developers and CI?

level: principalimportance: should knowfreq 35%

basics

~20 s

Commit a small CMakePresets.json whose hidden bases define the standard generator, build directories and options, make CI run the same presets, and pin cmake_minimum_required to the oldest supported CMake with policy_max at the newest tested; personal variants go in CMakeUserPresets.json.

open as a page