1cmake_policy
2------------
3
4Manage CMake Policy settings.  See the :manual:`cmake-policies(7)`
5manual for defined policies.
6
7As CMake evolves it is sometimes necessary to change existing behavior
8in order to fix bugs or improve implementations of existing features.
9The CMake Policy mechanism is designed to help keep existing projects
10building as new versions of CMake introduce changes in behavior.  Each
11new policy (behavioral change) is given an identifier of the form
12``CMP<NNNN>`` where ``<NNNN>`` is an integer index.  Documentation
13associated with each policy describes the ``OLD`` and ``NEW`` behavior
14and the reason the policy was introduced.  Projects may set each policy
15to select the desired behavior.  When CMake needs to know which behavior
16to use it checks for a setting specified by the project.  If no
17setting is available the ``OLD`` behavior is assumed and a warning is
18produced requesting that the policy be set.
19
20Setting Policies by CMake Version
21^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
22
23The ``cmake_policy`` command is used to set policies to ``OLD`` or ``NEW``
24behavior.  While setting policies individually is supported, we
25encourage projects to set policies based on CMake versions:
26
27.. code-block:: cmake
28
29  cmake_policy(VERSION <min>[...<max>])
30
31.. versionadded:: 3.12
32  The optional ``<max>`` version.
33
34``<min>`` and the optional ``<max>`` are each CMake versions of the form
35``major.minor[.patch[.tweak]]``, and the ``...`` is literal.  The ``<min>``
36version must be at least ``2.4`` and at most the running version of CMake.
37The ``<max>`` version, if specified, must be at least the ``<min>`` version
38but may exceed the running version of CMake.  If the running version of
39CMake is older than 3.12, the extra ``...`` dots will be seen as version
40component separators, resulting in the ``...<max>`` part being ignored and
41preserving the pre-3.12 behavior of basing policies on ``<min>``.
42
43This specifies that the current CMake code is written for the given
44range of CMake versions.  All policies known to the running version of CMake
45and introduced in the ``<min>`` (or ``<max>``, if specified) version
46or earlier will be set to use ``NEW`` behavior.  All policies
47introduced in later versions will be unset (unless the
48:variable:`CMAKE_POLICY_DEFAULT_CMP<NNNN>` variable sets a default).
49This effectively requests behavior preferred as of a given CMake
50version and tells newer CMake versions to warn about their new policies.
51
52Note that the :command:`cmake_minimum_required(VERSION)`
53command implicitly calls ``cmake_policy(VERSION)`` too.
54
55Setting Policies Explicitly
56^^^^^^^^^^^^^^^^^^^^^^^^^^^
57
58.. code-block:: cmake
59
60  cmake_policy(SET CMP<NNNN> NEW)
61  cmake_policy(SET CMP<NNNN> OLD)
62
63Tell CMake to use the ``OLD`` or ``NEW`` behavior for a given policy.
64Projects depending on the old behavior of a given policy may silence a
65policy warning by setting the policy state to ``OLD``.  Alternatively
66one may fix the project to work with the new behavior and set the
67policy state to ``NEW``.
68
69.. include:: ../policy/DEPRECATED.txt
70
71Checking Policy Settings
72^^^^^^^^^^^^^^^^^^^^^^^^
73
74.. code-block:: cmake
75
76  cmake_policy(GET CMP<NNNN> <variable>)
77
78Check whether a given policy is set to ``OLD`` or ``NEW`` behavior.
79The output ``<variable>`` value will be ``OLD`` or ``NEW`` if the
80policy is set, and empty otherwise.
81
82CMake Policy Stack
83^^^^^^^^^^^^^^^^^^
84
85CMake keeps policy settings on a stack, so changes made by the
86``cmake_policy`` command affect only the top of the stack.  A new entry on
87the policy stack is managed automatically for each subdirectory to
88protect its parents and siblings.  CMake also manages a new entry for
89scripts loaded by :command:`include` and :command:`find_package` commands
90except when invoked with the ``NO_POLICY_SCOPE`` option
91(see also policy :policy:`CMP0011`).
92The ``cmake_policy`` command provides an interface to manage custom
93entries on the policy stack:
94
95.. code-block:: cmake
96
97  cmake_policy(PUSH)
98  cmake_policy(POP)
99
100Each ``PUSH`` must have a matching ``POP`` to erase any changes.
101This is useful to make temporary changes to policy settings.
102Calls to the :command:`cmake_minimum_required(VERSION)`,
103``cmake_policy(VERSION)``, or ``cmake_policy(SET)`` commands
104influence only the current top of the policy stack.
105
106Commands created by the :command:`function` and :command:`macro`
107commands record policy settings when they are created and
108use the pre-record policies when they are invoked.  If the function or
109macro implementation sets policies, the changes automatically
110propagate up through callers until they reach the closest nested
111policy stack entry.
112