Help/command/cmake_policy.rst

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