find_package: Optionally warn when implicitly using Config mode

Define variable CMAKE_FIND_PACKAGE_WARN_NO_MODULE for use by a project
that wants to use an explicit mode in every call to find_package in
order to generate more specific failure messages.  Word the warning
using the new CONFIG and MODULE mode keywords when the minimum required
version of CMake is new enough to have them.  Otherwise word the warning
using the old NO_MODULE mode keyword.

Inspired-by: Alex Neundorf <neundorf@kde.org>

Source/cmDocumentVariables.cxx

@@ -745,6 +745,26 @@ void cmDocumentVariables::DefineVariables(cmake* cm)
      "this package from the cache using the cache editor or cmake -U", false,
      "Variables That Change Behavior");
 
+  cm->DefineProperty
+    ("CMAKE_FIND_PACKAGE_WARN_NO_MODULE", cmProperty::VARIABLE,
+     "Tell find_package to warn if called without an explicit mode.",
+     "If find_package is called without an explicit mode option "
+     "(MODULE, CONFIG or NO_MODULE) and no Find<pkg>.cmake module is "
+     "in CMAKE_MODULE_PATH then CMake implicitly assumes that the "
+     "caller intends to search for a package configuration file.  "
+     "If no package configuration file is found then the wording "
+     "of the failure message must account for both the case that the "
+     "package is really missing and the case that the project has a "
+     "bug and failed to provide the intended Find module.  "
+     "If instead the caller specifies an explicit mode option then "
+     "the failure message can be more specific."
+     "\n"
+     "Set CMAKE_FIND_PACKAGE_WARN_NO_MODULE to TRUE to tell find_package "
+     "to warn when it implicitly assumes Config mode.  "
+     "This helps developers enforce use of an explicit mode in all calls "
+     "to find_package within a project.", false,
+     "Variables That Change Behavior");
+
   cm->DefineProperty
     ("CMAKE_USER_MAKE_RULES_OVERRIDE", cmProperty::VARIABLE,
      "Specify a CMake file that overrides platform information.",

Source/cmFindPackageCommand.cxx

@@ -73,6 +73,7 @@ cmFindPackageCommand::cmFindPackageCommand()
   this->VersionFoundPatch = 0;
   this->VersionFoundTweak = 0;
   this->VersionFoundCount = 0;
+  this->RequiredCMakeVersion = 0;
 }
 
 //----------------------------------------------------------------------------
@@ -372,6 +373,15 @@ bool cmFindPackageCommand
     return false;
     }
 
+  // Lookup required version of CMake.
+  if(const char* rv =
+     this->Makefile->GetDefinition("CMAKE_MINIMUM_REQUIRED_VERSION"))
+    {
+    unsigned int v[3] = {0,0,0};
+    sscanf(rv, "%u.%u.%u", &v[0], &v[1], &v[2]);
+    this->RequiredCMakeVersion = CMake_VERSION_ENCODE(v[0],v[1],v[2]);
+    }
+
   // Check for debug mode.
   this->DebugMode = this->Makefile->IsOn("CMAKE_FIND_DEBUG_MODE");
 
@@ -691,6 +701,37 @@ bool cmFindPackageCommand
       }
     }
 
+  if(this->UseFindModules && this->UseConfigFiles &&
+     this->Makefile->IsOn("CMAKE_FIND_PACKAGE_WARN_NO_MODULE"))
+    {
+    cmOStringStream aw;
+    if(this->RequiredCMakeVersion >= CMake_VERSION_ENCODE(2,8,8))
+      {
+      aw << "find_package called without either MODULE or CONFIG option and "
+        "no Find" << this->Name << ".cmake module is in CMAKE_MODULE_PATH.  "
+        "Add MODULE to exclusively request Module mode and fail if "
+        "Find" << this->Name << ".cmake is missing.  "
+        "Add CONFIG to exclusively request Config mode and search for a "
+        "package configuration file provided by " << this->Name <<
+        " (" << this->Name << "Config.cmake or " <<
+        cmSystemTools::LowerCase(this->Name) << "-config.cmake).  ";
+      }
+    else
+      {
+      aw << "find_package called without NO_MODULE option and no "
+        "Find" << this->Name << ".cmake module is in CMAKE_MODULE_PATH.  "
+        "Add NO_MODULE to exclusively request Config mode and search for a "
+        "package configuration file provided by " << this->Name <<
+        " (" << this->Name << "Config.cmake or " <<
+        cmSystemTools::LowerCase(this->Name) << "-config.cmake).  "
+        "Otherwise make Find" << this->Name << ".cmake available in "
+        "CMAKE_MODULE_PATH.";
+      }
+    aw << "\n"
+      "(Variable CMAKE_FIND_PACKAGE_WARN_NO_MODULE enabled this warning.)";
+    this->Makefile->IssueMessage(cmake::AUTHOR_WARNING, aw.str());
+    }
+
   // No find module.  Assume the project has a CMake config file.  Use
   // a <package>_DIR cache variable to locate it.
   this->Variable = this->Name;

Source/cmFindPackageCommand.h

@@ -130,6 +130,7 @@ private:
   unsigned int VersionFoundPatch;
   unsigned int VersionFoundTweak;
   unsigned int VersionFoundCount;
+  unsigned int RequiredCMakeVersion;
   bool Quiet;
   bool Required;
   bool Compatibility_1_6;