Commit 482a3bf3 authored by Brad King's avatar Brad King

Help: Document explicitly that policy OLD behavior is deprecated

The most likely documentation page a project author will read in
response to a policy warning is the page for the policy itself.
Add to every policy documentation page a note explicitly stating
that the OLD behavior is deprecated.  Also mention this in the
cmake_policy() command documentation that explains how to set a
policy to OLD.
Suggested-by: default avatarFraser Hutchison <fraser.hutchison@gmail.com>
parent a6916a6c
......@@ -53,6 +53,8 @@ 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``.
.. include:: ../policy/DEPRECATED.txt
Checking Policy Settings
^^^^^^^^^^^^^^^^^^^^^^^^
......
......@@ -20,11 +20,11 @@ for a policy, also avoiding the warning. Each policy can also be set to
either ``NEW`` or ``OLD`` behavior explicitly on the command line with the
:variable:`CMAKE_POLICY_DEFAULT_CMP<NNNN>` variable.
Note that policies are not reliable feature toggles. 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. The ``OLD`` behavior of each policy is undesirable and will be
replaced with an error condition in a future release.
A policy is a deprecation mechanism and not a reliable feature toggle.
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. The ``OLD`` behavior of each policy is undesirable
and will be replaced with an error condition in a future release.
The :command:`cmake_minimum_required` command does more than report an
error if a too-old version of CMake is used to build a project. It
......
......@@ -28,3 +28,5 @@ a warning. An included file may set CMP0000 explicitly to affect how
this policy is enforced for the main CMakeLists.txt file.
This policy was introduced in CMake version 2.6.0.
.. include:: DEPRECATED.txt
......@@ -17,3 +17,5 @@ below.
This policy was introduced in CMake version 2.6.0. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt
......@@ -24,3 +24,5 @@ property ALLOW_DUPLICATE_CUSTOM_TARGETS with a Makefiles generator).
This policy was introduced in CMake version 2.6.0. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt
......@@ -100,3 +100,5 @@ when setting the policy once will probably fix all targets.
This policy was introduced in CMake version 2.6.0. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt
......@@ -21,3 +21,5 @@ target is created by an add_executable or add_library command.
This policy was introduced in CMake version 2.6.0. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt
......@@ -22,3 +22,5 @@ limitations of the escaping implementation.
This policy was introduced in CMake version 2.6.0. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt
......@@ -20,3 +20,5 @@ without a BUNDLE DESTINATION.
This policy was introduced in CMake version 2.6.0. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt
......@@ -13,3 +13,5 @@ empty elements in a list.
This policy was introduced in CMake version 2.6.0. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt
......@@ -30,3 +30,5 @@ pass it directly to the native build tool unchanged.
This policy was introduced in CMake version 2.6.1. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt
......@@ -17,3 +17,5 @@ as an additional argument to the FILE command.
This policy was introduced in CMake version 2.6.2. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt
......@@ -16,3 +16,5 @@ and is treated as always being ``NEW``.
This policy was introduced in CMake version 2.6.3. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt
......@@ -20,3 +20,5 @@ cmake_policy PUSH and POP.
This policy was introduced in CMake version 2.6.3. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt
......@@ -23,3 +23,5 @@ dereferencing variables with such names.
This policy was introduced in CMake version 2.8.0. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt
......@@ -17,3 +17,5 @@ with an error.
This policy was introduced in CMake version 2.8.0. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt
......@@ -13,3 +13,5 @@ behavior for this policy is to report an error.
This policy was introduced in CMake version 2.8.0. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt
......@@ -15,3 +15,5 @@ paths by appending the relative path to CMAKE_CURRENT_SOURCE_DIR.
This policy was introduced in CMake version 2.8.1. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt
......@@ -11,3 +11,5 @@ in this case.
This policy was introduced in CMake version 2.8.3. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt
......@@ -17,3 +17,5 @@ from the CMake modules directory.
This policy was introduced in CMake version 2.8.4. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt
......@@ -30,3 +30,5 @@ honor the POSITION_INDEPENDENT_CODE target property.
This policy was introduced in CMake version 2.8.9. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt
......@@ -18,3 +18,5 @@ the values untouched.
This policy was introduced in CMake version 2.8.11. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt
......@@ -23,3 +23,5 @@ automatically when they link to QtCore IMPORTED target.
This policy was introduced in CMake version 2.8.11. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt
......@@ -16,3 +16,5 @@ relative path.
This policy was introduced in CMake version 2.8.12. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt
......@@ -35,3 +35,5 @@ property for in-build targets, and ignore the old properties matching
This policy was introduced in CMake version 2.8.12. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt
......@@ -31,3 +31,5 @@ signatures.
This policy was introduced in CMake version 2.8.12. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt
......@@ -20,3 +20,5 @@ allow including the result of an export() command.
This policy was introduced in CMake version 3.0. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt
......@@ -25,3 +25,5 @@ by default when this policy is not set and simply uses OLD behavior.
See documentation of the
:variable:`CMAKE_POLICY_WARNING_CMP0025 <CMAKE_POLICY_WARNING_CMP<NNNN>>`
variable to control the warning.
.. include:: DEPRECATED.txt
......@@ -24,3 +24,5 @@ not to allow reading the LOCATION properties from build-targets.
This policy was introduced in CMake version 3.0. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt
......@@ -23,3 +23,5 @@ conditionally linked IMPORTED target does not exist.
This policy was introduced in CMake version 3.0. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt
......@@ -21,3 +21,5 @@ double-colons but is not an IMPORTED target or an ALIAS target.
This policy was introduced in CMake version 3.0. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt
......@@ -8,3 +8,5 @@ but was kept in CMake for compatibility for a long time.
.. |disallowed_version| replace:: 3.0
.. include:: DISALLOWED_COMMAND.txt
.. include:: DEPRECATED.txt
......@@ -9,3 +9,5 @@ not used it in years.
.. |disallowed_version| replace:: 3.0
.. include:: DISALLOWED_COMMAND.txt
.. include:: DEPRECATED.txt
......@@ -11,3 +11,5 @@ the CMake process. It has been mostly superseded by the
.. |disallowed_version| replace:: 3.0
.. include:: DISALLOWED_COMMAND.txt
.. include:: DEPRECATED.txt
......@@ -11,3 +11,5 @@ functionality is better achieved through dedicated outside tools.
.. |disallowed_version| replace:: 3.0
.. include:: DISALLOWED_COMMAND.txt
.. include:: DEPRECATED.txt
......@@ -12,3 +12,5 @@ The functionality has been superseded by the :command:`export` and
.. |disallowed_version| replace:: 3.0
.. include:: DISALLOWED_COMMAND.txt
.. include:: DEPRECATED.txt
......@@ -9,3 +9,5 @@ generate other files. This approach has long been replaced by
.. |disallowed_version| replace:: 3.0
.. include:: DISALLOWED_COMMAND.txt
.. include:: DEPRECATED.txt
......@@ -8,3 +8,5 @@ logic. It has long been replaced by the :command:`if` command.
.. |disallowed_version| replace:: 3.0
.. include:: DISALLOWED_COMMAND.txt
.. include:: DEPRECATED.txt
......@@ -10,3 +10,5 @@ and :variable:`CMAKE_<LANG>_COMPILER` variables.
.. |disallowed_version| replace:: 3.0
.. include:: DISALLOWED_COMMAND.txt
.. include:: DEPRECATED.txt
......@@ -24,3 +24,5 @@ if an add_* command is used with an invalid target name.
This policy was introduced in CMake version 3.0. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt
......@@ -14,3 +14,5 @@ report an error if a target attempts to link to itself.
This policy was introduced in CMake version 3.0. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt
......@@ -15,3 +15,5 @@ utility target.
This policy was introduced in CMake version 3.0. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt
......@@ -14,3 +14,5 @@ if the target referenced in :command:`add_custom_command` is unknown.
This policy was introduced in CMake version 3.0. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt
......@@ -23,3 +23,5 @@ relative.
This policy was introduced in CMake version 3.0. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt
......@@ -17,3 +17,5 @@ variables.
This policy was introduced in CMake version 3.0. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt
......@@ -43,3 +43,5 @@ of the :prop_tgt:`COMPILE_DEFINITIONS_<CONFIG>` target property .
This policy was introduced in CMake version 3.0. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt
......@@ -17,3 +17,5 @@ the ``<LANG>_COMPILER_ID`` expression.
This policy was introduced in CMake version 3.0. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt
......@@ -15,3 +15,5 @@ non-existent target.
This policy was introduced in CMake version 3.0. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
.. include:: DEPRECATED.txt
......@@ -15,3 +15,5 @@ This policy was introduced in CMake version 3.0.
CMake version |release| warns when the policy is not set and uses
OLD behavior. Use the cmake_policy command to set it to OLD or
NEW explicitly.
.. include:: DEPRECATED.txt
......@@ -26,3 +26,5 @@ by default when this policy is not set and simply uses OLD behavior.
See documentation of the
:variable:`CMAKE_POLICY_WARNING_CMP0047 <CMAKE_POLICY_WARNING_CMP<NNNN>>`
variable to control the warning.
.. include:: DEPRECATED.txt
......@@ -20,3 +20,5 @@ This policy was introduced in CMake version 3.0.
CMake version |release| warns when the policy is not set and uses
OLD behavior. Use the cmake_policy command to set it to OLD or
NEW explicitly.
.. include:: DEPRECATED.txt
......@@ -21,3 +21,5 @@ This policy was introduced in CMake version 3.0.
CMake version |release| warns when the policy is not set and uses
OLD behavior. Use the cmake_policy command to set it to OLD or
NEW explicitly.
.. include:: DEPRECATED.txt
......@@ -16,3 +16,5 @@ This policy was introduced in CMake version 3.0.
CMake version |release| warns when the policy is not set and uses
OLD behavior. Use the cmake_policy command to set it to OLD or
NEW explicitly.
.. include:: DEPRECATED.txt
......@@ -22,3 +22,5 @@ This policy was introduced in CMake version 3.1.
CMake version |release| warns when the policy is not set and uses
``OLD`` behavior. Use the :command:`cmake_policy` command to set it
to ``OLD`` or ``NEW`` explicitly.
.. include:: DEPRECATED.txt
......@@ -22,3 +22,5 @@ This policy was introduced in CMake version 3.1.
CMake version |release| warns when the policy is not set and uses
``OLD`` behavior. Use the :command:`cmake_policy` command to set it
to ``OLD`` or ``NEW`` explicitly.
.. include:: DEPRECATED.txt
......@@ -42,3 +42,5 @@ This policy was introduced in CMake version 3.1.
CMake version |release| warns when the policy is not set and uses
``OLD`` behavior. Use the :command:`cmake_policy` command to set
it to ``OLD`` or ``NEW`` explicitly.
.. include:: DEPRECATED.txt
......@@ -48,3 +48,5 @@ This policy was introduced in CMake version 3.1.
CMake version |release| warns when the policy is not set and uses
``OLD`` behavior. Use the :command:`cmake_policy` command to set
it to ``OLD`` or ``NEW`` explicitly.
.. include:: DEPRECATED.txt
......@@ -15,3 +15,5 @@ This policy was introduced in CMake version 3.2.
CMake version |release| warns when the policy is not set and uses
OLD behavior. Use the cmake_policy command to set it to OLD or
NEW explicitly.
.. include:: DEPRECATED.txt
......@@ -30,3 +30,5 @@ CMake version |release| does *not* warn by default when this policy
is not set and simply uses OLD behavior. See documentation of the
:variable:`CMAKE_POLICY_WARNING_CMP0056 <CMAKE_POLICY_WARNING_CMP<NNNN>>`
variable to control the warning.
.. include:: DEPRECATED.txt
......@@ -12,3 +12,5 @@ This policy was introduced in CMake version 3.3.
CMake version |release| warns when the policy is not set and uses
``OLD`` behavior. Use the :command:`cmake_policy` command to set
it to ``OLD`` or ``NEW`` explicitly.
.. include:: DEPRECATED.txt
......@@ -106,3 +106,5 @@ out-of-source build trees if the policy is not set and then uses
the policy to ``OLD`` or ``NEW`` explicitly. The policy setting
must be in scope at the end of the top-level ``CMakeLists.txt``
file of the project and has global effect.
.. include:: DEPRECATED.txt
......@@ -15,3 +15,5 @@ This policy was introduced in CMake version 3.3.
CMake version |release| warns when the policy is not set and uses
``OLD`` behavior. Use the :command:`cmake_policy` command to set
it to ``OLD`` or ``NEW`` explicitly.
.. include:: DEPRECATED.txt
......@@ -61,3 +61,5 @@ CMake version |release| does *not* warn by default when this policy
is not set and simply uses OLD behavior. See documentation of the
:variable:`CMAKE_POLICY_WARNING_CMP0060 <CMAKE_POLICY_WARNING_CMP<NNNN>>`
variable to control the warning.
.. include:: DEPRECATED.txt
......@@ -22,3 +22,5 @@ add ``-i``.
This policy was introduced in CMake version 3.3. Unlike most policies,
CMake version |release| does *not* warn when this policy is not set and
simply uses OLD behavior.
.. include:: DEPRECATED.txt
......@@ -25,3 +25,5 @@ This policy was introduced in CMake version 3.3. CMake version
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy()` command to set it to ``OLD`` or ``NEW``
explicitly.
.. include:: DEPRECATED.txt
......@@ -24,3 +24,5 @@ This policy was introduced in CMake version 3.3. CMake version
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy()` command to set it to ``OLD`` or ``NEW``
explicitly.
.. include:: DEPRECATED.txt
.. note::
The ``OLD`` behavior of a policy is
:manual:`deprecated by definition <cmake-policies(7)>`
and may be removed in a future version of CMake.
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment