cmake-policies(7)

Introduction

CMake policies introduce behavior changes while preserving compatibility for existing project releases. Policies are deprecation mechanisms, not feature toggles. Each policy documents a deprecated OLD behavior and a preferred NEW behavior. Projects must be updated over time to use the NEW behavior, but their existing releases will continue to work with the OLD behavior.

Updating Projects

When policies are newly introduced by a version of CMake, their OLD behaviors are immediately deprecated by that version of CMake and later. Projects should be updated to use the NEW behaviors of the policies as soon as possible.

Use the cmake_minimum_required() command to record the latest version of CMake for which a project has been updated. For example:

cmake_minimum_required(VERSION 3.10...4.0)

This uses the <min>...<max> syntax to enable the NEW behaviors of policies introduced in CMake 4.0 and earlier while only requiring a minimum version of CMake 3.10. The project is expected to work with both the OLD and NEW behaviors of policies introduced between those versions.

Transition Schedule

To help projects port to the NEW behaviors of policies on their own schedule, CMake offers a transition period:

  • If a policy is not set by a project, CMake uses its OLD behavior, but may warn that the policy has not been set.

    • Users running CMake may silence the warning without modifying a project by setting the CMAKE_POLICY_DEFAULT_CMP<NNNN> variable as a cache entry on the cmake(1) command line:

      cmake -DCMAKE_POLICY_DEFAULT_CMP0990=OLD ...

    • Projects may silence the warning by using the cmake_policy() command to explicitly set the policy to OLD or NEW behavior:

      if(POLICY CMP0990)
  cmake_policy(SET CMP0990 NEW)
endif()

      Note

      A policy should almost never be set to OLD, except to silence warnings in an otherwise frozen or stable codebase, or temporarily as part of a larger migration path.

  • If a policy is set to OLD by a project, CMake versions released at least 2 years after the version that introduced a policy may issue a warning that the policy's OLD behavior will be removed from a future version of CMake.

  • If a policy is not set to NEW by a project, CMake versions released at least 6 years after the version that introduced a policy, and whose major version number is higher, may issue an error that the policy's OLD behavior has been removed.

Supported Policies

The following policies are supported.

Policies Introduced by CMake 4.1

Policies Introduced by CMake 4.0

Policies Introduced by CMake 3.31

Policies Introduced by CMake 3.30

Policies Introduced by CMake 3.29

Policies Introduced by CMake 3.28

Policies Introduced by CMake 3.27

Policies Introduced by CMake 3.26

Policies Introduced by CMake 3.25

Policies Introduced by CMake 3.24

Policies Introduced by CMake 3.23

Policies Introduced by CMake 3.22

Policies Introduced by CMake 3.21

Policies Introduced by CMake 3.20

Policies Introduced by CMake 3.19

Policies Introduced by CMake 3.18

Policies Introduced by CMake 3.17

Policies Introduced by CMake 3.16

Policies Introduced by CMake 3.15

Policies Introduced by CMake 3.14

Policies Introduced by CMake 3.13

Policies Introduced by CMake 3.12

Policies Introduced by CMake 3.11

Policies Introduced by CMake 3.10

Policies Introduced by CMake 3.9

Policies Introduced by CMake 3.8

Policies Introduced by CMake 3.7

Unsupported Policies

The following policies are no longer supported. Projects' calls to cmake_minimum_required(VERSION) or cmake_policy(VERSION) must set them to NEW. Their OLD behaviors have been removed from CMake.

Policies Introduced by CMake 3.4, Removed by CMake 4.0

Policies Introduced by CMake 3.3, Removed by CMake 4.0

Policies Introduced by CMake 3.2, Removed by CMake 4.0

Policies Introduced by CMake 3.1, Removed by CMake 4.0

Policies Introduced by CMake 3.0, Removed by CMake 4.0

Policies Introduced by CMake 2.8, Removed by CMake 4.0

Policies Introduced by CMake 2.6, Removed by CMake 4.0