Clarification: Interaction between CMAKE_POLICY_VERSION_MINIMUM and cmake_minimum_required()

Usage
1

Hi CMake team,

Conan member here!

I’d like to clarify the intended behavior of CMAKE_POLICY_VERSION_MINIMUM when it is set to a version lower than the one explicitly specified by cmake_minimum_required().

Given the following example:

cmake_minimum_required(VERSION 3.25)
project(example)

message(STATUS "CMAKE_VERSION = ${CMAKE_VERSION}")
message(STATUS "CMAKE_MINIMUM_REQUIRED_VERSION = ${CMAKE_MINIMUM_REQUIRED_VERSION}")
message(STATUS "CMAKE_POLICY_VERSION = ${CMAKE_POLICY_VERSION}")
message(STATUS "CMAKE_POLICY_VERSION_MINIMUM = ${CMAKE_POLICY_VERSION_MINIMUM}")

foreach(p CMP0048 CMP0077 CMP0127)
    cmake_policy(GET ${p} val)
    message(STATUS "${p} = ${val}")
endforeach()

Configured with:

$ cmake -DCMAKE_POLICY_VERSION_MINIMUM=3.5 ..

I get the following output:

-- CMAKE_VERSION = 4.1.1
-- CMAKE_MINIMUM_REQUIRED_VERSION = 3.25
-- CMAKE_POLICY_VERSION =
-- CMAKE_POLICY_VERSION_MINIMUM = 3.5
-- CMP0048 = NEW
-- CMP0077 = NEW
-- CMP0127 = NEW

From the docs, I understand:

  • cmake_minimum_required(VERSION X.Y) sets all policies up to X.Y to NEW.

  • CMAKE_POLICY_VERSION_MINIMUM only takes effect when no explicit minimum is given.

But in this case, even though I explicitly set CMAKE_POLICY_VERSION_MINIMUM=3.5, the cmake_minimum_required(3.25) call seems to completely override it, resulting in all policies up to 3.25 being set to NEW.

Is this the intended behavior, i.e. that CMAKE_POLICY_VERSION_MINIMUM is ignored whenever cmake_minimum_required() is called, even if it specifies a higher version?

Or should CMAKE_POLICY_VERSION_MINIMUM still constrain the effective minimum (e.g. lower it back down to 3.5)?

Use case

I’m experimenting with always setting -DCMAKE_POLICY_VERSION_MINIMUM=3.5 when building external projects (to ensure future CMake 4.x compatibility).

I’d like to confirm that this does not unexpectedly “downgrade” the policies if the project has already declared a higher cmake_minimum_required().

Thanks for clarifying!

2

CMAKE_POLICY_VERSION_MINIMUM doesn’t unilaterally override the minimum policy version specified by a project. It only raises the project’s minimum if it is less than the version specified by CMAKE_POLICY_VERSION_MINIMUM. You can find the relevant code here.

I think you might be misunderstanding what the CMAKE_POLICY_VERSION_MINIMUM variable is intended to do. It does NOT ensure future CMake 4.x compatibility. All it does is force projects to use a higher minimum policy version than what the project itself says is safe to use. When you set CMAKE_POLICY_VERSION_MINIMUM, you are accepting the risk that the project you are applying it to might not actually handle the NEW policy settings correctly, and things can break in subtle and arbitrary ways. By using CMAKE_POLICY_VERSION_MINIMUM, you’re not ensuring CMake 4.x compatibility, you’re blindly forcing projects to use newer policy settings whether they are ready for it or not.

3

Greetings @craig.scott

Thank you very much for your quick response.

This is exactly the clarification we were hoping to receive.

It only raises the project’s minimum if it is less than the version specified by CMAKE_POLICY_VERSION_MINIMUM

I think this same phrase could be added to CMake docs here:

https://cmake.org/cmake/help/latest/variable/CMAKE_POLICY_VERSION_MINIMUM.html

On the other side,

By using CMAKE_POLICY_VERSION_MINIMUM, you’re not ensuring CMake 4.x compatibility, you’re blindly forcing projects to use newer policy settings whether they are ready for it or not.

We are aware of the situation. When we raise the minimum CMake version, we first check for any incompatibilities with the existing policies. If there are some, we proceed to apply any necessary patching.

Thank you very much for your time and clarification.