Add deprecation warnings for policies CMP0036 and below

The OLD behaviors of all policies are deprecated, but only by
documentation.  Add an explicit deprecation diagnostic for some policies
to encourage projects to port away from setting policies to OLD.

14 files changed, 133 insertions, 1 deletions

diff --git a/Help/release/dev/deprecate-policy-old.rst b/Help/release/dev/deprecate-policy-old.rst
new file mode 100644
index 0000000..9ae30e6
--- /dev/null
+++ b/Help/release/dev/deprecate-policy-old.rst
@@ -0,0 +1,7 @@
+deprecate-policy-old
+--------------------
+
+* An explicit deprecation diagnostic was added for policies ``CMP0036``
+  and below.  The :manual:`cmake-policies(7)` manual explains that the
+  OLD behaviors of all policies are deprecated and that projects should
+  port to the NEW behaviors.
diff --git a/Source/cmMakefile.cxx b/Source/cmMakefile.cxx
index 4ed76c7..b8a5293 100644
--- a/Source/cmMakefile.cxx
+++ b/Source/cmMakefile.cxx
@@ -4002,6 +4002,13 @@ bool cmMakefile::SetPolicy(cmPolicies::PolicyID id,
     return false;
   }
 
+  // Deprecate old policies, especially those that require a lot
+  // of code to maintain the old behavior.
+  if (status == cmPolicies::OLD && id <= cmPolicies::CMP0036) {
+    this->IssueMessage(cmake::DEPRECATION_WARNING,
+                       cmPolicies::GetPolicyDeprecatedWarning(id));
+  }
+
   this->StateSnapshot.SetPolicy(id, status);
   return true;
 }
diff --git a/Source/cmPolicies.cxx b/Source/cmPolicies.cxx
index 837557b..da3edd4 100644
--- a/Source/cmPolicies.cxx
+++ b/Source/cmPolicies.cxx
@@ -275,6 +275,22 @@ std::string cmPolicies::GetPolicyWarning(cmPolicies::PolicyID id)
   return msg.str();
 }
 
+std::string cmPolicies::GetPolicyDeprecatedWarning(cmPolicies::PolicyID id)
+{
+  std::ostringstream msg;
+  /* clang-format off */
+  msg <<
+    "The OLD behavior for policy " << idToString(id) << " "
+    "will be removed from a future version of CMake.\n"
+    "The cmake-policies(7) manual explains that the OLD behaviors of all "
+    "policies are deprecated and that a policy should be set to OLD only "
+    "under specific short-term circumstances.  Projects should be ported "
+    "to the NEW behavior and not rely on setting a policy to OLD."
+    ;
+  /* clang-format on */
+  return msg.str();
+}
+
 ///! return an error string for when a required policy is unspecified
 std::string cmPolicies::GetRequiredPolicyError(cmPolicies::PolicyID id)
 {
diff --git a/Source/cmPolicies.h b/Source/cmPolicies.h
index 120beb6..69cbc18 100644
--- a/Source/cmPolicies.h
+++ b/Source/cmPolicies.h
@@ -279,6 +279,7 @@ public:
 
   ///! return a warning string for a given policy
   static std::string GetPolicyWarning(cmPolicies::PolicyID id);
+  static std::string GetPolicyDeprecatedWarning(cmPolicies::PolicyID id);
 
   ///! return an error string for when a required policy is unspecified
   static std::string GetRequiredPolicyError(cmPolicies::PolicyID id);
diff --git a/Tests/RunCMake/CMP0019/CMP0019-OLD-stderr.txt b/Tests/RunCMake/CMP0019/CMP0019-OLD-stderr.txt
new file mode 100644
index 0000000..048762d
--- /dev/null
+++ b/Tests/RunCMake/CMP0019/CMP0019-OLD-stderr.txt
@@ -0,0 +1,10 @@
+^CMake Deprecation Warning at CMP0019-OLD.cmake:[0-9]+ \(cmake_policy\):
+  The OLD behavior for policy CMP0019 will be removed from a future version
+  of CMake.
+
+  The cmake-policies\(7\) manual explains that the OLD behaviors of all
+  policies are deprecated and that a policy should be set to OLD only under
+  specific short-term circumstances.  Projects should be ported to the NEW
+  behavior and not rely on setting a policy to OLD.
+Call Stack \(most recent call first\):
+  CMakeLists.txt:[0-9]+ \(include\)$
diff --git a/Tests/RunCMake/CMP0026/CMP0026-CONFIG-LOCATION-OLD-stderr.txt b/Tests/RunCMake/CMP0026/CMP0026-CONFIG-LOCATION-OLD-stderr.txt
new file mode 100644
index 0000000..edeb337
--- /dev/null
+++ b/Tests/RunCMake/CMP0026/CMP0026-CONFIG-LOCATION-OLD-stderr.txt
@@ -0,0 +1,10 @@
+^CMake Deprecation Warning at CMP0026-CONFIG-LOCATION-OLD.cmake:[0-9]+ \(cmake_policy\):
+  The OLD behavior for policy CMP0026 will be removed from a future version
+  of CMake.
+
+  The cmake-policies\(7\) manual explains that the OLD behaviors of all
+  policies are deprecated and that a policy should be set to OLD only under
+  specific short-term circumstances.  Projects should be ported to the NEW
+  behavior and not rely on setting a policy to OLD.
+Call Stack \(most recent call first\):
+  CMakeLists.txt:[0-9]+ \(include\)$
diff --git a/Tests/RunCMake/CMP0026/CMP0026-LOCATION-CONFIG-OLD-stderr.txt b/Tests/RunCMake/CMP0026/CMP0026-LOCATION-CONFIG-OLD-stderr.txt
new file mode 100644
index 0000000..32ff698
--- /dev/null
+++ b/Tests/RunCMake/CMP0026/CMP0026-LOCATION-CONFIG-OLD-stderr.txt
@@ -0,0 +1,10 @@
+^CMake Deprecation Warning at CMP0026-LOCATION-CONFIG-OLD.cmake:[0-9]+ \(cmake_policy\):
+  The OLD behavior for policy CMP0026 will be removed from a future version
+  of CMake.
+
+  The cmake-policies\(7\) manual explains that the OLD behaviors of all
+  policies are deprecated and that a policy should be set to OLD only under
+  specific short-term circumstances.  Projects should be ported to the NEW
+  behavior and not rely on setting a policy to OLD.
+Call Stack \(most recent call first\):
+  CMakeLists.txt:[0-9]+ \(include\)$
diff --git a/Tests/RunCMake/CMP0026/CMP0026-OLD-stderr.txt b/Tests/RunCMake/CMP0026/CMP0026-OLD-stderr.txt
new file mode 100644
index 0000000..b3f79fc
--- /dev/null
+++ b/Tests/RunCMake/CMP0026/CMP0026-OLD-stderr.txt
@@ -0,0 +1,10 @@
+^CMake Deprecation Warning at CMP0026-OLD.cmake:[0-9]+ \(cmake_policy\):
+  The OLD behavior for policy CMP0026 will be removed from a future version
+  of CMake.
+
+  The cmake-policies\(7\) manual explains that the OLD behaviors of all
+  policies are deprecated and that a policy should be set to OLD only under
+  specific short-term circumstances.  Projects should be ported to the NEW
+  behavior and not rely on setting a policy to OLD.
+Call Stack \(most recent call first\):
+  CMakeLists.txt:[0-9]+ \(include\)$
diff --git a/Tests/RunCMake/CMP0026/clear-cached-information-stderr.txt b/Tests/RunCMake/CMP0026/clear-cached-information-stderr.txt
new file mode 100644
index 0000000..157a046
--- /dev/null
+++ b/Tests/RunCMake/CMP0026/clear-cached-information-stderr.txt
@@ -0,0 +1,10 @@
+^CMake Deprecation Warning at clear-cached-information.cmake:[0-9]+ \(cmake_policy\):
+  The OLD behavior for policy CMP0026 will be removed from a future version
+  of CMake.
+
+  The cmake-policies\(7\) manual explains that the OLD behaviors of all
+  policies are deprecated and that a policy should be set to OLD only under
+  specific short-term circumstances.  Projects should be ported to the NEW
+  behavior and not rely on setting a policy to OLD.
+Call Stack \(most recent call first\):
+  CMakeLists.txt:[0-9]+ \(include\)$
diff --git a/Tests/RunCMake/CMP0028/CMP0028-OLD-iface-stderr.txt b/Tests/RunCMake/CMP0028/CMP0028-OLD-iface-stderr.txt
new file mode 100644
index 0000000..b7a0755
--- /dev/null
+++ b/Tests/RunCMake/CMP0028/CMP0028-OLD-iface-stderr.txt
@@ -0,0 +1,10 @@
+^CMake Deprecation Warning at CMP0028-OLD-iface.cmake:[0-9]+ \(cmake_policy\):
+  The OLD behavior for policy CMP0028 will be removed from a future version
+  of CMake.
+
+  The cmake-policies\(7\) manual explains that the OLD behaviors of all
+  policies are deprecated and that a policy should be set to OLD only under
+  specific short-term circumstances.  Projects should be ported to the NEW
+  behavior and not rely on setting a policy to OLD.
+Call Stack \(most recent call first\):
+  CMakeLists.txt:[0-9]+ \(include\)$
diff --git a/Tests/RunCMake/CMP0028/CMP0028-OLD-stderr.txt b/Tests/RunCMake/CMP0028/CMP0028-OLD-stderr.txt
new file mode 100644
index 0000000..586a876
--- /dev/null
+++ b/Tests/RunCMake/CMP0028/CMP0028-OLD-stderr.txt
@@ -0,0 +1,10 @@
+^CMake Deprecation Warning at CMP0028-OLD.cmake:[0-9]+ \(cmake_policy\):
+  The OLD behavior for policy CMP0028 will be removed from a future version
+  of CMake.
+
+  The cmake-policies\(7\) manual explains that the OLD behaviors of all
+  policies are deprecated and that a policy should be set to OLD only under
+  specific short-term circumstances.  Projects should be ported to the NEW
+  behavior and not rely on setting a policy to OLD.
+Call Stack \(most recent call first\):
+  CMakeLists.txt:[0-9]+ \(include\)$
diff --git a/Tests/RunCMake/DisallowedCommands/CMP0029-OLD-stderr.txt b/Tests/RunCMake/DisallowedCommands/CMP0029-OLD-stderr.txt
new file mode 100644
index 0000000..430c865
--- /dev/null
+++ b/Tests/RunCMake/DisallowedCommands/CMP0029-OLD-stderr.txt
@@ -0,0 +1,10 @@
+^CMake Deprecation Warning at CMP0029-OLD.cmake:[0-9]+ \(cmake_policy\):
+  The OLD behavior for policy CMP0029 will be removed from a future version
+  of CMake.
+
+  The cmake-policies\(7\) manual explains that the OLD behaviors of all
+  policies are deprecated and that a policy should be set to OLD only under
+  specific short-term circumstances.  Projects should be ported to the NEW
+  behavior and not rely on setting a policy to OLD.
+Call Stack \(most recent call first\):
+  CMakeLists.txt:[0-9]+ \(include\)$
diff --git a/Tests/RunCMake/DisallowedCommands/CMP0030-OLD-stderr.txt b/Tests/RunCMake/DisallowedCommands/CMP0030-OLD-stderr.txt
index e95e16f..d00b827 100644
--- a/Tests/RunCMake/DisallowedCommands/CMP0030-OLD-stderr.txt
+++ b/Tests/RunCMake/DisallowedCommands/CMP0030-OLD-stderr.txt
@@ -1,4 +1,15 @@
-^CMake Error at CMP0030-OLD.cmake:2 \(use_mangled_mesa\):
+^CMake Deprecation Warning at CMP0030-OLD.cmake:[0-9]+ \(cmake_policy\):
+  The OLD behavior for policy CMP0030 will be removed from a future version
+  of CMake.
+
+  The cmake-policies\(7\) manual explains that the OLD behaviors of all
+  policies are deprecated and that a policy should be set to OLD only under
+  specific short-term circumstances.  Projects should be ported to the NEW
+  behavior and not rely on setting a policy to OLD.
+Call Stack \(most recent call first\):
+  CMakeLists.txt:[0-9]+ \(include\)
++
+CMake Error at CMP0030-OLD.cmake:2 \(use_mangled_mesa\):
   use_mangled_mesa called with incorrect number of arguments
 Call Stack \(most recent call first\):
   CMakeLists.txt:3 \(include\)$
diff --git a/Tests/RunCMake/TargetSources/CMP0026-LOCATION-stderr.txt b/Tests/RunCMake/TargetSources/CMP0026-LOCATION-stderr.txt
new file mode 100644
index 0000000..d7ccedb
--- /dev/null
+++ b/Tests/RunCMake/TargetSources/CMP0026-LOCATION-stderr.txt
@@ -0,0 +1,10 @@
+^CMake Deprecation Warning at CMP0026-LOCATION.cmake:[0-9]+ \(cmake_policy\):
+  The OLD behavior for policy CMP0026 will be removed from a future version
+  of CMake.
+
+  The cmake-policies\(7\) manual explains that the OLD behaviors of all
+  policies are deprecated and that a policy should be set to OLD only under
+  specific short-term circumstances.  Projects should be ported to the NEW
+  behavior and not rely on setting a policy to OLD.
+Call Stack \(most recent call first\):
+  CMakeLists.txt:[0-9]+ \(include\)$