kolan
/
CMake
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Merge topic 'policy-doc-updates' 

b1f4e620 Help: Reference cmake_minimum_required from cmake_policy docs
69a23cb2 Help: Format cmake_policy command documentation
0c4835a3 Help: Add missing space in policy CMP0020 description
This commit is contained in:
Brad King 2014-06-02 10:44:25 -04:00 committed by CMake Topic Stage
parent 2ebeaa2c97 b1f4e6206b
commit a0c0abb457
2 changed files with 52 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

86
Help/command/cmake_policy.rst
View File

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

2
Help/policy/CMP0020.rst
View File

@ -16,7 +16,7 @@ this automatic linking will need to be disabled as per the
documentation. documentation.
The OLD behavior for this policy is not to link executables to The OLD behavior for this policy is not to link executables to
qtmain.lib automatically when they link to the QtCore IMPORTEDtarget. qtmain.lib automatically when they link to the QtCore IMPORTED target.
The NEW behavior for this policy is to link executables to qtmain.lib The NEW behavior for this policy is to link executables to qtmain.lib
automatically when they link to QtCore IMPORTED target. automatically when they link to QtCore IMPORTED target.