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

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

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.

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.

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.

Source/cmGlobalGenerator.cxx

@@ -765,7 +765,8 @@ void cmGlobalGenerator::CheckCompilerIdCompatibility(cmMakefile* mf,
     switch(mf->GetPolicyStatus(cmPolicies::CMP0025))
       {
       case cmPolicies::WARN:
-        if(!this->CMakeInstance->GetIsInTryCompile())
+        if(!this->CMakeInstance->GetIsInTryCompile() &&
+           mf->PolicyOptionalWarningEnabled("CMAKE_POLICY_WARNING_CMP0025"))
           {
           cmOStringStream w;
           w << policies->GetPolicyWarning(cmPolicies::CMP0025) << "\n"
@@ -796,7 +797,8 @@ void cmGlobalGenerator::CheckCompilerIdCompatibility(cmMakefile* mf,
     switch(mf->GetPolicyStatus(cmPolicies::CMP0047))
       {
       case cmPolicies::WARN:
-        if(!this->CMakeInstance->GetIsInTryCompile())
+        if(!this->CMakeInstance->GetIsInTryCompile() &&
+           mf->PolicyOptionalWarningEnabled("CMAKE_POLICY_WARNING_CMP0047"))
           {
           cmOStringStream w;
           w << policies->GetPolicyWarning(cmPolicies::CMP0047) << "\n"

Source/cmMakefile.cxx

@@ -4330,6 +4330,22 @@ cmMakefile::GetPolicyStatusInternal(cmPolicies::PolicyID id) const
   return this->GetPolicies()->GetPolicyStatus(id);
 }
 
+//----------------------------------------------------------------------------
+bool cmMakefile::PolicyOptionalWarningEnabled(std::string const& var)
+{
+  // Check for an explicit CMAKE_POLICY_WARNING_CMP<NNNN> setting.
+  if(!var.empty())
+    {
+    if(const char* val = this->GetDefinition(var))
+      {
+      return cmSystemTools::IsOn(val);
+      }
+    }
+  // Enable optional policy warnings with --debug-output or --trace.
+  cmake* cm = this->GetCMakeInstance();
+  return cm->GetDebugOutput() || cm->GetTrace();
+}
+
 bool cmMakefile::SetPolicy(const char *id,
                            cmPolicies::PolicyStatus status)
 {

Source/cmMakefile.h

@@ -880,6 +880,8 @@ public:
   std::set<std::string> const & GetSystemIncludeDirectories() const
     { return this->SystemIncludeDirectories; }
 
+  bool PolicyOptionalWarningEnabled(std::string const& var);
+
 protected:
   // add link libraries and directories to the target
   void AddGlobalLinkInformation(const std::string& name, cmTarget& target);