95 lines
3.8 KiB
ReStructuredText
95 lines
3.8 KiB
ReStructuredText
cmake_policy
|
|
------------
|
|
|
|
Manage CMake Policy settings. See the :manual:`cmake-policies(7)`
|
|
manual for defined policies.
|
|
|
|
As CMake evolves it is sometimes necessary to change existing behavior
|
|
in order to fix bugs or improve implementations of existing features.
|
|
The CMake Policy mechanism is designed to help keep existing projects
|
|
building as new versions of CMake introduce changes in behavior. Each
|
|
new policy (behavioral change) is given an identifier of the form
|
|
``CMP<NNNN>`` where ``<NNNN>`` is an integer index. Documentation
|
|
associated with each policy describes the ``OLD`` and ``NEW`` behavior
|
|
and the reason the policy was introduced. Projects may set each policy
|
|
to select the desired behavior. When CMake needs to know which behavior
|
|
to use it checks for a setting specified by the project. If no
|
|
setting is available the ``OLD`` behavior is assumed and a warning is
|
|
produced requesting that the policy be set.
|
|
|
|
Setting Policies by CMake Version
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
The ``cmake_policy`` command is used to set policies to ``OLD`` or ``NEW``
|
|
behavior. While setting policies individually is supported, we
|
|
encourage projects to set policies based on CMake versions::
|
|
|
|
cmake_policy(VERSION major.minor[.patch[.tweak]])
|
|
|
|
Specify that the current CMake code is written for the given
|
|
version of CMake. All policies introduced in the specified version or
|
|
earlier will be set to use ``NEW`` behavior. All policies introduced
|
|
after the specified version will be unset (unless the
|
|
:variable:`CMAKE_POLICY_DEFAULT_CMP<NNNN>` variable sets a default).
|
|
This effectively requests behavior preferred as of a given CMake
|
|
version and tells newer CMake versions to warn about their new policies.
|
|
The policy version specified must be at least 2.4 or the command will
|
|
report an error.
|
|
|
|
Note that the :command:`cmake_minimum_required(VERSION)`
|
|
command implicitly calls ``cmake_policy(VERSION)`` too.
|
|
|
|
Setting Policies Explicitly
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
::
|
|
|
|
cmake_policy(SET CMP<NNNN> NEW)
|
|
cmake_policy(SET CMP<NNNN> OLD)
|
|
|
|
Tell CMake to use the ``OLD`` or ``NEW`` behavior for a given policy.
|
|
Projects depending on the old behavior of a given policy may silence a
|
|
policy warning by setting the policy state to ``OLD``. Alternatively
|
|
one may fix the project to work with the new behavior and set the
|
|
policy state to ``NEW``.
|
|
|
|
Checking Policy Settings
|
|
^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
::
|
|
|
|
cmake_policy(GET CMP<NNNN> <variable>)
|
|
|
|
Check whether a given policy is set to ``OLD`` or ``NEW`` behavior.
|
|
The output ``<variable>`` value will be ``OLD`` or ``NEW`` if the
|
|
policy is set, and empty otherwise.
|
|
|
|
CMake Policy Stack
|
|
^^^^^^^^^^^^^^^^^^
|
|
|
|
CMake keeps policy settings on a stack, so changes made by the
|
|
cmake_policy command affect only the top of the stack. A new entry on
|
|
the policy stack is managed automatically for each subdirectory to
|
|
protect its parents and siblings. CMake also manages a new entry for
|
|
scripts loaded by :command:`include` and :command:`find_package` commands
|
|
except when invoked with the ``NO_POLICY_SCOPE`` option
|
|
(see also policy :policy:`CMP0011`).
|
|
The ``cmake_policy`` command provides an interface to manage custom
|
|
entries on the policy stack::
|
|
|
|
cmake_policy(PUSH)
|
|
cmake_policy(POP)
|
|
|
|
Each ``PUSH`` must have a matching ``POP`` to erase any changes.
|
|
This is useful to make temporary changes to policy settings.
|
|
Calls to the :command:`cmake_minimum_required(VERSION)`,
|
|
``cmake_policy(VERSION)``, or ``cmake_policy(SET)`` commands
|
|
influence only the current top of the policy stack.
|
|
|
|
Commands created by the :command:`function` and :command:`macro`
|
|
commands record policy settings when they are created and
|
|
use the pre-record policies when they are invoked. If the function or
|
|
macro implementation sets policies, the changes automatically
|
|
propagate up through callers until they reach the closest nested
|
|
policy stack entry.
|