find_package: Use PackageName_ROOT variables as search prefixes

This feature was originally added by commit v3.9.0-rc1~71^2~2 (find_*:
Add a new PackageRoot search path group, 2017-05-03) and documented by
commit v3.9.0-rc1~71^2 (find_*: Add docs for PackageRoot search path
group, 2017-05-03).  However, we had to disable the feature and remove
the documentation in commit v3.9.1~2^2 (find_*: Disable the PACKAGE_ROOT
search path group for CMake 3.9, 2017-08-08) due to breaking projects
that used `PackageName_ROOT` variables themselves.

Add policy `CMP0074` to restore the `PackageName_ROOT` variable behavior
in a compatible way.  Also revise the stack of root paths to store the
paths themselves rather than the package names.  This way the policy can
be considered at the `find_package` call site instead of individual
`find_` calls inside a find module.

Co-Author: Chuck Atkins <chuck.atkins@kitware.com>
Issue: #17144

1 files changed, 20 insertions, 0 deletions

diff --git a/Source/cmMakefile.cxx b/Source/cmMakefile.cxx
index 9e53579..1191490 100644
--- a/Source/cmMakefile.cxx
+++ b/Source/cmMakefile.cxx
@@ -158,6 +158,26 @@ bool cmMakefile::CheckCMP0037(std::string const& targetName,
   return true;
 }
 
+void cmMakefile::MaybeWarnCMP0074(std::string const& pkg)
+{
+  // Warn if a <pkg>_ROOT variable we may use is set.
+  std::string const varName = pkg + "_ROOT";
+  bool const haveVar = this->GetDefinition(varName) != nullptr;
+  bool const haveEnv = cmSystemTools::HasEnv(varName);
+  if ((haveVar || haveEnv) && this->WarnedCMP0074.insert(varName).second) {
+    std::ostringstream w;
+    w << cmPolicies::GetPolicyWarning(cmPolicies::CMP0074) << "\n";
+    if (haveVar) {
+      w << "CMake variable " << varName << " is set.\n";
+    }
+    if (haveEnv) {
+      w << "Environment variable " << varName << " is set.\n";
+    }
+    w << "For compatibility, CMake is ignoring the variable.";
+    this->IssueMessage(cmake::AUTHOR_WARNING, w.str());
+  }
+}
+
 cmStringRange cmMakefile::GetIncludeDirectoriesEntries() const
 {
   return this->StateSnapshot.GetDirectory().GetIncludeDirectoriesEntries();