find_package: add support for a <package>_NOT_FOUND_MESSAGE variable

If a config-file sets <package>_FOUND to FALSE, it can now give a reason
using the variable <package>_NOT_FOUND_MESSAGE, which is used by cmFindPackage
and FPHSA.

Alex

Modules/FindPackageHandleStandardArgs.cmake

@@ -120,6 +120,9 @@ macro(_FPHSA_HANDLE_FAILURE_CONFIG_MODE)
         list(GET ${_NAME}_CONSIDERED_VERSIONS ${currentConfigIndex} version)
         set(configsText "${configsText}    ${filename} (version ${version})\n")
       endforeach()
+      if (${_NAME}_NOT_FOUND_MESSAGE)
+        set(configsText "${configsText}    Reason given by package: ${${_NAME}_NOT_FOUND_MESSAGE}\n")
+      endif()
       _FPHSA_FAILURE_MESSAGE("${FPHSA_FAIL_MESSAGE} ${VERSION_MSG}, checked the following files:\n${configsText}")
 
     else()

Modules/readme.txt

@@ -18,6 +18,9 @@ XXX_VERSION_YY          Expect Version YY if true. Make sure at most one of thes
 XXX_WRAP_YY             If False, do not try to use the relevent CMake wrapping command.
 XXX_YY_FOUND            If False, optional YY part of XXX sytem is not available.
 XXX_FOUND               Set to false, or undefined, if we haven't found, or don't want to use XXX.
+XXX_NOT_FOUND_MESSAGE   Should be set by config-files in the case that it has set XXX_FOUND to FALSE.
+                        The contained message will be printed by the find_package() command and by
+                        find_package_handle_standard_args() to inform the user about the problem.
 XXX_RUNTIME_LIBRARY_DIRS Optionally, the runtime library search path for use when running an executable linked to shared libraries.
                          The list should be used by user code to create the PATH on windows or LD_LIBRARY_PATH on unix.
                          This should not be a cache entry.

Source/cmFindPackageCommand.cxx

@@ -1016,6 +1016,9 @@ bool cmFindPackageCommand::HandlePackageMode()
 
   std::string foundVar = this->Name;
   foundVar += "_FOUND";
+  std::string notFoundMessageVar = this->Name;
+  notFoundMessageVar += "_NOT_FOUND_MESSAGE";
+  std::string notFoundMessage;
 
   // If the directory for the config file was found, try to read the file.
   bool result = true;
@@ -1033,6 +1036,7 @@ bool cmFindPackageCommand::HandlePackageMode()
       // has set Foo_FOUND to FALSE itself:
       this->Makefile->RemoveDefinition(foundVar.c_str());
       }
+    this->Makefile->RemoveDefinition(notFoundMessageVar.c_str());
 
     // Set the version variables before loading the config file.
     // It may override them.
@@ -1051,6 +1055,8 @@ bool cmFindPackageCommand::HandlePackageMode()
         // we get here if the Config file has set Foo_FOUND actively to FALSE
         found = false;
         configFileSetFOUNDFalse = true;
+        notFoundMessage = this->Makefile->GetSafeDefinition(
+                                                   notFoundMessageVar.c_str());
         }
       }
     else
@@ -1071,6 +1077,10 @@ bool cmFindPackageCommand::HandlePackageMode()
         "  " << this->FileFound << "\n"
         "but it set " << foundVar << " to FALSE so package \"" <<
         this->Name << "\" is considered to be NOT FOUND.";
+      if (!notFoundMessage.empty())
+        {
+        e << " Reason given by package: \n" << notFoundMessage << "\n";
+        }
       }
     // If there are files in ConsideredConfigs, it means that FooConfig.cmake
     // have been found, but they didn't have appropriate versions.