Merge topic 'revise-compiler-id-policies'

13684e2b cmMakefile: Port PolicyOptionalWarningEnabled to string APIs
8018fcca Merge branch 'master' into revise-compiler-id-policies
a41c0a9d Do not warn by default when policy CMP0025 or CMP0047 is not set
d339653e Help: Revise and format policy CMP0025 and CMP0047 docs

4 files changed, 60 insertions, 24 deletions

diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst
index 8b4ce26..4fac6a5 100644
--- a/Help/manual/cmake-variables.7.rst
+++ b/Help/manual/cmake-variables.7.rst
@@ -131,6 +131,7 @@ Variables that Change Behavior
    /variable/CMAKE_MODULE_PATH
    /variable/CMAKE_NOT_USING_CONFIG_FLAGS
    /variable/CMAKE_POLICY_DEFAULT_CMPNNNN
+   /variable/CMAKE_POLICY_WARNING_CMPNNNN
    /variable/CMAKE_PREFIX_PATH
    /variable/CMAKE_PROGRAM_PATH
    /variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE
diff --git a/Help/policy/CMP0025.rst b/Help/policy/CMP0025.rst
index f3b39e3..8d19edf 100644
--- a/Help/policy/CMP0025.rst
+++ b/Help/policy/CMP0025.rst
@@ -1,21 +1,27 @@
 CMP0025
 -------
 
-Compiler id for Apple Clang is now AppleClang.
+Compiler id for Apple Clang is now ``AppleClang``.
 
-CMake >= 3.0 recognize that Apple Clang is a different compiler
+CMake 3.0 and above recognize that Apple Clang is a different compiler
 than upstream Clang and that they have different version numbers.
-CMake now prefers to present this to projects by setting
-CMAKE_<LANG>_COMPILER_ID to "AppleClang" instead of "Clang".  However,
-existing projects may assume the compiler id for Apple Clang is just
-"Clang" as it was in CMake < 3.0.  Therefore this policy determines
-for Apple Clang which compiler id to report in
-CMAKE_<LANG>_COMPILER_ID after <LANG> is enabled by the project() or
-enable_language() command.
+CMake now prefers to present this to projects by setting the
+:variable:`CMAKE_<LANG>_COMPILER_ID` variable to ``AppleClang`` instead
+of ``Clang``.  However, existing projects may assume the compiler id for
+Apple Clang is just ``Clang`` as it was in CMake versions prior to 3.0.
+Therefore this policy determines for Apple Clang which compiler id to
+report in the :variable:`CMAKE_<LANG>_COMPILER_ID` variable after
+language ``<LANG>`` is enabled by the :command:`project` or
+:command:`enable_language` command.  The policy must be set prior
+to the invocation of either command.
 
-The OLD behavior for this policy is to use compiler id "Clang".  The
-NEW behavior for this policy is to use compiler id "AppleClang".
+The OLD behavior for this policy is to use compiler id ``Clang``.  The
+NEW behavior for this policy is to use compiler id ``AppleClang``.
 
-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.
+This policy was introduced in CMake version 3.0.  Use the
+:command:`cmake_policy` command to set this policy to OLD or NEW explicitly.
+Unlike most policies, 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_CMP0025 <CMAKE_POLICY_WARNING_CMP<NNNN>>`
+variable to control the warning.
diff --git a/Help/policy/CMP0047.rst b/Help/policy/CMP0047.rst
index c2d951b..26ae439 100644
--- a/Help/policy/CMP0047.rst
+++ b/Help/policy/CMP0047.rst
@@ -1,16 +1,28 @@
 CMP0047
 -------
 
-Use QCC compiler id for the qcc drivers on QNX.
+Use ``QCC`` compiler id for the qcc drivers on QNX.
 
-CMake 2.8.12 and lower assigned the QNX qcc and QCC compiler drivers the "GNU"
-compiler id.
+CMake 3.0 and above recognize that the QNX qcc compiler driver is
+different from the GNU compiler.
+CMake now prefers to present this to projects by setting the
+:variable:`CMAKE_<LANG>_COMPILER_ID` variable to ``QCC`` instead
+of ``GNU``.  However, existing projects may assume the compiler id for
+QNX qcc is just ``GNU`` as it was in CMake versions prior to 3.0.
+Therefore this policy determines for QNX qcc which compiler id to
+report in the :variable:`CMAKE_<LANG>_COMPILER_ID` variable after
+language ``<LANG>`` is enabled by the :command:`project` or
+:command:`enable_language` command.  The policy must be set prior
+to the invocation of either command.
 
-The OLD behavior for this policy is to use the "GNU" compiler id for the qcc
-and QCC compiler drivers. The NEW behavior for this policy is to use the "QCC"
-compiler id for those drivers.
+The OLD behavior for this policy is to use the ``GNU`` compiler id
+for the qcc and QCC compiler drivers. The NEW behavior for this policy
+is to use the ``QCC`` compiler id for those drivers.
 
-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.
+This policy was introduced in CMake version 3.0.  Use the
+:command:`cmake_policy` command to set this policy to OLD or NEW explicitly.
+Unlike most policies, 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_CMP0047 <CMAKE_POLICY_WARNING_CMP<NNNN>>`
+variable to control the warning.
diff --git a/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst
new file mode 100644
index 0000000..b563aea
--- /dev/null
+++ b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst
@@ -0,0 +1,17 @@
+CMAKE_POLICY_WARNING_CMP<NNNN>
+------------------------------
+
+Explicitly enable or disable the warning when CMake Policy ``CMP<NNNN>``
+is not set.  This is meaningful only for the few policies that do not
+warn by default:
+
+* ``CMAKE_POLICY_WARNING_CMP0025`` controls the warning for
+  policy :policy:`CMP0025`.
+* ``CMAKE_POLICY_WARNING_CMP0047`` controls the warning for
+  policy :policy:`CMP0047`.
+
+This variable should not be set by a project in CMake code.  Project
+developers running CMake may set this variable in their cache to
+enable the warning (e.g. ``-DCMAKE_POLICY_WARNING_CMP<NNNN>=ON``).
+Alternatively, running :manual:`cmake(1)` with the ``--debug-output``
+or ``--trace`` option will also enable the warning.