From 204b8d9f4e9c5a64e1fa6a0ee4e6dc2911694bae Mon Sep 17 00:00:00 2001
From: Robert Maynard <robert.maynard@kitware.com>
Date: Wed, 11 Dec 2019 13:01:09 -0500
Subject: find_*: Use debug logging infrastructure

Teach the find_package, find_library, find_program, find_path, and
find_file commands to print debug log messages when enabled by the
`--debug-find` command-line option or `CMAKE_FIND_DEBUG_MODE` variable.
---
 Source/cmFindLibraryCommand.cxx                    |  68 ++++++++++-
 Source/cmFindPackageCommand.cxx                    | 133 +++++++++++++++++++--
 Source/cmFindPackageCommand.h                      |   1 -
 Source/cmFindPathCommand.cxx                       |  17 ++-
 Source/cmFindPathCommand.h                         |   4 +-
 Source/cmFindProgramCommand.cxx                    |  19 ++-
 Tests/RunCMake/find_file/PrefixInPATH-stderr.txt   |  13 ++
 Tests/RunCMake/find_file/PrefixInPATH.cmake        |   6 +
 Tests/RunCMake/find_library/FromPATHEnv-stderr.txt |  28 +++++
 Tests/RunCMake/find_library/FromPATHEnv.cmake      |  13 ++
 .../RunCMake/find_library/PrefixInPATH-stderr.txt  |  14 +++
 Tests/RunCMake/find_library/PrefixInPATH.cmake     |   6 +
 Tests/RunCMake/find_package/FromPATHEnv-stderr.txt |  16 +++
 Tests/RunCMake/find_package/FromPATHEnv.cmake      |   6 +
 .../find_package/MissingConfigDebug-stderr.txt     |  17 +++
 .../RunCMake/find_package/MissingConfigDebug.cmake |   4 +
 Tests/RunCMake/find_package/RunCMakeTest.cmake     |   1 +
 Tests/RunCMake/find_path/FromPATHEnv-stderr.txt    |  27 +++++
 Tests/RunCMake/find_path/FromPATHEnv.cmake         |  12 ++
 Tests/RunCMake/find_program/EnvAndHints-stderr.txt |  28 +++++
 Tests/RunCMake/find_program/EnvAndHints.cmake      |   2 +
 21 files changed, 404 insertions(+), 31 deletions(-)
 create mode 100644 Tests/RunCMake/find_file/PrefixInPATH-stderr.txt
 create mode 100644 Tests/RunCMake/find_library/FromPATHEnv-stderr.txt
 create mode 100644 Tests/RunCMake/find_library/PrefixInPATH-stderr.txt
 create mode 100644 Tests/RunCMake/find_package/FromPATHEnv-stderr.txt
 create mode 100644 Tests/RunCMake/find_package/MissingConfigDebug-stderr.txt
 create mode 100644 Tests/RunCMake/find_package/MissingConfigDebug.cmake
 create mode 100644 Tests/RunCMake/find_path/FromPATHEnv-stderr.txt
 create mode 100644 Tests/RunCMake/find_program/EnvAndHints-stderr.txt

diff --git a/Source/cmFindLibraryCommand.cxx b/Source/cmFindLibraryCommand.cxx
index 20221b12e0..d5a4bde97e 100644
--- a/Source/cmFindLibraryCommand.cxx
+++ b/Source/cmFindLibraryCommand.cxx
@@ -29,6 +29,7 @@ cmFindLibraryCommand::cmFindLibraryCommand(cmExecutionStatus& status)
 // cmFindLibraryCommand
 bool cmFindLibraryCommand::InitialPass(std::vector<std::string> const& argsIn)
 {
+  this->DebugMode = ComputeIfDebugModeWanted();
   this->VariableDocumentation = "Path to a library.";
   this->CMakePathName = "LIBRARY";
   if (!this->ParseArguments(argsIn)) {
@@ -92,6 +93,13 @@ void cmFindLibraryCommand::AddArchitecturePaths(const char* suffix)
   original.swap(this->SearchPaths);
   for (std::string const& o : original) {
     this->AddArchitecturePath(o, 0, suffix);
+    if (this->DebugMode) {
+      std::string msg = cmStrCat(
+        "find_library(", this->VariableName, ") removed original suffix ", o,
+        " from PATH_SUFFIXES while adding architecture paths for suffix '",
+        suffix, "'");
+      this->DebugMessage(msg);
+    }
   }
 }
 
@@ -153,11 +161,23 @@ void cmFindLibraryCommand::AddArchitecturePath(
 
     if (use_dirX) {
       dirX += "/";
+      if (this->DebugMode) {
+        std::string msg = cmStrCat(
+          "find_library(", this->VariableName, ") added replacement path ",
+          dirX, " to PATH_SUFFIXES for architecture suffix '", suffix, "'");
+        this->DebugMessage(msg);
+      }
       this->SearchPaths.push_back(std::move(dirX));
     }
 
     if (use_dir) {
       this->SearchPaths.push_back(dir);
+      if (this->DebugMode) {
+        std::string msg = cmStrCat(
+          "find_library(", this->VariableName, ") added replacement path ",
+          dir, " to PATH_SUFFIXES for architecture suffix '", suffix, "'");
+        this->DebugMessage(msg);
+      }
     }
   }
 }
@@ -179,7 +199,7 @@ std::string cmFindLibraryCommand::FindLibrary()
 
 struct cmFindLibraryHelper
 {
-  cmFindLibraryHelper(cmMakefile* mf);
+  cmFindLibraryHelper(cmMakefile* mf, cmFindBase const* findBase);
 
   // Context information.
   cmMakefile* Makefile;
@@ -198,6 +218,8 @@ struct cmFindLibraryHelper
   // Support for OpenBSD shared library naming: lib<name>.so.<major>.<minor>
   bool OpenBSD;
 
+  bool DebugMode;
+
   // Current names under consideration.
   struct Name
   {
@@ -227,10 +249,33 @@ struct cmFindLibraryHelper
   void SetName(std::string const& name);
   bool CheckDirectory(std::string const& path);
   bool CheckDirectoryForName(std::string const& path, Name& name);
+
+  cmFindBaseDebugState DebugSearches;
+
+  void DebugLibraryFailed(std::string const& name, std::string const& path)
+  {
+    if (this->DebugMode) {
+      auto regexName =
+        cmStrCat(this->PrefixRegexStr, name, this->SuffixRegexStr);
+      this->DebugSearches.FailedAt(path, regexName);
+    }
+  };
+
+  void DebugLibraryFound(std::string const& name, std::string const& path)
+  {
+    if (this->DebugMode) {
+      auto regexName =
+        cmStrCat(this->PrefixRegexStr, name, this->SuffixRegexStr);
+      this->DebugSearches.FoundAt(path, regexName);
+    }
+  };
 };
 
-cmFindLibraryHelper::cmFindLibraryHelper(cmMakefile* mf)
+cmFindLibraryHelper::cmFindLibraryHelper(cmMakefile* mf,
+                                         cmFindBase const* base)
   : Makefile(mf)
+  , DebugMode(base->DebugModeEnabled())
+  , DebugSearches("find_library", base)
 {
   this->GG = this->Makefile->GetGlobalGenerator();
 
@@ -350,7 +395,12 @@ bool cmFindLibraryHelper::CheckDirectoryForName(std::string const& path,
   // library or an import library).
   if (name.TryRaw) {
     this->TestPath = cmStrCat(path, name.Raw);
-    if (cmSystemTools::FileExists(this->TestPath, true)) {
+
+    const bool exists = cmSystemTools::FileExists(this->TestPath, true);
+    if (!exists) {
+      this->DebugLibraryFailed(name.Raw, path);
+    } else {
+      this->DebugLibraryFound(name.Raw, path);
       this->BestPath = cmSystemTools::CollapseFullPath(this->TestPath);
       cmSystemTools::ConvertToUnixSlashes(this->BestPath);
       return true;
@@ -376,6 +426,8 @@ bool cmFindLibraryHelper::CheckDirectoryForName(std::string const& path,
     if (name.Regex.find(testName)) {
       this->TestPath = cmStrCat(path, origName);
       if (!cmSystemTools::FileIsDirectory(this->TestPath)) {
+        this->DebugLibraryFound(name.Raw, dir);
+
         // This is a matching file.  Check if it is better than the
         // best name found so far.  Earlier prefixes are preferred,
         // followed by earlier suffixes.  For OpenBSD, shared library
@@ -402,6 +454,12 @@ bool cmFindLibraryHelper::CheckDirectoryForName(std::string const& path,
     }
   }
 
+  if (this->BestPath.empty()) {
+    this->DebugLibraryFailed(name.Raw, dir);
+  } else {
+    this->DebugLibraryFound(name.Raw, this->BestPath);
+  }
+
   // Use the best candidate found in this directory, if any.
   return !this->BestPath.empty();
 }
@@ -417,7 +475,7 @@ std::string cmFindLibraryCommand::FindNormalLibrary()
 std::string cmFindLibraryCommand::FindNormalLibraryNamesPerDir()
 {
   // Search for all names in each directory.
-  cmFindLibraryHelper helper(this->Makefile);
+  cmFindLibraryHelper helper(this->Makefile, this);
   for (std::string const& n : this->Names) {
     helper.AddName(n);
   }
@@ -434,7 +492,7 @@ std::string cmFindLibraryCommand::FindNormalLibraryNamesPerDir()
 std::string cmFindLibraryCommand::FindNormalLibraryDirsPerName()
 {
   // Search the entire path for each name.
-  cmFindLibraryHelper helper(this->Makefile);
+  cmFindLibraryHelper helper(this->Makefile, this);
   for (std::string const& n : this->Names) {
     // Switch to searching for this name.
     helper.SetName(n);
diff --git a/Source/cmFindPackageCommand.cxx b/Source/cmFindPackageCommand.cxx
index 2b11b62a21..9eb256b7a3 100644
--- a/Source/cmFindPackageCommand.cxx
+++ b/Source/cmFindPackageCommand.cxx
@@ -160,8 +160,7 @@ bool cmFindPackageCommand::InitialPass(std::vector<std::string> const& args)
     this->RequiredCMakeVersion = CMake_VERSION_ENCODE(v[0], v[1], v[2]);
   }
 
-  // Check for debug mode.
-  this->DebugMode = this->Makefile->IsOn("CMAKE_FIND_DEBUG_MODE");
+  this->DebugMode = ComputeIfDebugModeWanted();
 
   // Lookup target architecture, if any.
   if (const char* arch =
@@ -695,8 +694,23 @@ void cmFindPackageCommand::RestoreFindDefinitions()
 bool cmFindPackageCommand::FindModule(bool& found)
 {
   std::string module = cmStrCat("Find", this->Name, ".cmake");
+
   bool system = false;
-  std::string mfile = this->Makefile->GetModulesFile(module, system);
+  std::string debugBuffer =
+    cmStrCat("find_package considered the following paths for ", this->Name,
+             ".cmake\n");
+  std::string mfile = this->Makefile->GetModulesFile(
+    module, system, this->DebugMode, debugBuffer);
+  if (this->DebugMode) {
+    if (mfile.empty()) {
+      debugBuffer = cmStrCat(debugBuffer, "The file was not found.");
+    } else {
+      debugBuffer =
+        cmStrCat(debugBuffer, "The file was found at\n  ", mfile, "\n");
+    }
+    this->DebugMessage(debugBuffer);
+  }
+
   if (!mfile.empty()) {
     if (system) {
       auto it = this->DeprecatedFindModules.find(this->Name);
@@ -1164,6 +1178,21 @@ void cmFindPackageCommand::AppendSuccessInformation()
   this->Makefile->FindPackageRootPathStack.pop_back();
 }
 
+inline std::size_t collectPathsForDebug(std::string& buffer,
+                                        cmSearchPath const& searchPath,
+                                        std::size_t startIndex = 0)
+{
+  const auto& paths = searchPath.GetPaths();
+  if (paths.empty()) {
+    buffer += "  none";
+    return 0;
+  }
+  for (std::size_t i = startIndex; i < paths.size(); i++) {
+    buffer += "  " + paths[i] + "\n";
+  }
+  return paths.size();
+}
+
 void cmFindPackageCommand::ComputePrefixes()
 {
   if (!this->NoDefaultPath) {
@@ -1177,7 +1206,9 @@ void cmFindPackageCommand::ComputePrefixes()
       this->FillPrefixesCMakeEnvironment();
     }
   }
+
   this->FillPrefixesUserHints();
+
   if (!this->NoDefaultPath) {
     if (!this->NoSystemEnvironmentPath) {
       this->FillPrefixesSystemEnvironment();
@@ -1209,29 +1240,72 @@ void cmFindPackageCommand::FillPrefixesPackageRoot()
       paths.AddPath(path);
     }
   }
+  if (this->DebugMode) {
+    std::string debugBuffer = "<PackageName>_ROOT CMake variable "
+                              "[CMAKE_FIND_USE_PACKAGE_ROOT_PATH].\n";
+    collectPathsForDebug(debugBuffer, paths);
+    this->DebugMessage(debugBuffer);
+  }
 }
 
 void cmFindPackageCommand::FillPrefixesCMakeEnvironment()
 {
   cmSearchPath& paths = this->LabeledPaths[PathLabel::CMakeEnvironment];
+  std::string debugBuffer;
+  std::size_t debugOffset = 0;
 
   // Check the environment variable with the same name as the cache
   // entry.
   paths.AddEnvPath(this->Variable);
+  if (this->DebugMode) {
+    debugBuffer = cmStrCat("Env variable ", this->Variable,
+                           " [CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH].\n");
+    debugOffset = collectPathsForDebug(debugBuffer, paths);
+  }
 
   // And now the general CMake environment variables
   paths.AddEnvPath("CMAKE_PREFIX_PATH");
+  if (this->DebugMode) {
+    debugBuffer = cmStrCat(debugBuffer,
+                           "\nCMAKE_PREFIX_PATH env variable "
+                           "[CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH].\n");
+    debugOffset = collectPathsForDebug(debugBuffer, paths, debugOffset);
+  }
+
   paths.AddEnvPath("CMAKE_FRAMEWORK_PATH");
   paths.AddEnvPath("CMAKE_APPBUNDLE_PATH");
+  if (this->DebugMode) {
+    debugBuffer =
+      cmStrCat(debugBuffer,
+               "\nCMAKE_FRAMEWORK_PATH and CMAKE_APPBUNDLE_PATH env "
+               "variables [CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH].\n");
+    collectPathsForDebug(debugBuffer, paths, debugOffset);
+    this->DebugMessage(debugBuffer);
+  }
 }
 
 void cmFindPackageCommand::FillPrefixesCMakeVariable()
 {
   cmSearchPath& paths = this->LabeledPaths[PathLabel::CMake];
+  std::string debugBuffer;
+  std::size_t debugOffset = 0;
 
   paths.AddCMakePath("CMAKE_PREFIX_PATH");
+  if (this->DebugMode) {
+    debugBuffer = "CMAKE_PREFIX_PATH variable [CMAKE_FIND_USE_CMAKE_PATH].\n";
+    debugOffset = collectPathsForDebug(debugBuffer, paths);
+  }
+
   paths.AddCMakePath("CMAKE_FRAMEWORK_PATH");
   paths.AddCMakePath("CMAKE_APPBUNDLE_PATH");
+  if (this->DebugMode) {
+    debugBuffer =
+      cmStrCat(debugBuffer,
+               "\nCMAKE_FRAMEWORK_PATH and CMAKE_APPBUNDLE_PATH variables "
+               "[CMAKE_FIND_USE_CMAKE_PATH].\n");
+    collectPathsForDebug(debugBuffer, paths, debugOffset);
+    this->DebugMessage(debugBuffer);
+  }
 }
 
 void cmFindPackageCommand::FillPrefixesSystemEnvironment()
@@ -1251,6 +1325,12 @@ void cmFindPackageCommand::FillPrefixesSystemEnvironment()
       paths.AddPath(i);
     }
   }
+  if (this->DebugMode) {
+    std::string debugBuffer = "Standard system environment variables "
+                              "[CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH].\n";
+    collectPathsForDebug(debugBuffer, paths);
+    this->DebugMessage(debugBuffer);
+  }
 }
 
 void cmFindPackageCommand::FillPrefixesUserRegistry()
@@ -1274,6 +1354,13 @@ void cmFindPackageCommand::FillPrefixesUserRegistry()
                                  this->LabeledPaths[PathLabel::UserRegistry]);
   }
 #endif
+  if (this->DebugMode) {
+    std::string debugBuffer =
+      "CMake User Package Registry [CMAKE_FIND_USE_PACKAGE_REGISTRY].\n";
+    collectPathsForDebug(debugBuffer,
+                         this->LabeledPaths[PathLabel::UserRegistry]);
+    this->DebugMessage(debugBuffer);
+  }
 }
 
 void cmFindPackageCommand::FillPrefixesSystemRegistry()
@@ -1285,6 +1372,15 @@ void cmFindPackageCommand::FillPrefixesSystemRegistry()
 #if defined(_WIN32) && !defined(__CYGWIN__)
   this->LoadPackageRegistryWinSystem();
 #endif
+
+  if (this->DebugMode) {
+    std::string debugBuffer =
+      "CMake System Package Registry "
+      "[CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY].\n";
+    collectPathsForDebug(debugBuffer,
+                         this->LabeledPaths[PathLabel::SystemRegistry]);
+    this->DebugMessage(debugBuffer);
+  }
 }
 
 #if defined(_WIN32) && !defined(__CYGWIN__)
@@ -1457,6 +1553,13 @@ void cmFindPackageCommand::FillPrefixesCMakeSystemVariable()
   paths.AddCMakePath("CMAKE_SYSTEM_PREFIX_PATH");
   paths.AddCMakePath("CMAKE_SYSTEM_FRAMEWORK_PATH");
   paths.AddCMakePath("CMAKE_SYSTEM_APPBUNDLE_PATH");
+
+  if (this->DebugMode) {
+    std::string debugBuffer = "CMake variables defined in the Platform file "
+                              "[CMAKE_FIND_USE_CMAKE_SYSTEM_PATH].\n";
+    collectPathsForDebug(debugBuffer, paths);
+    this->DebugMessage(debugBuffer);
+  }
 }
 
 void cmFindPackageCommand::FillPrefixesUserGuess()
@@ -1466,6 +1569,12 @@ void cmFindPackageCommand::FillPrefixesUserGuess()
   for (std::string const& p : this->UserGuessArgs) {
     paths.AddUserPath(p);
   }
+  if (this->DebugMode) {
+    std::string debugBuffer =
+      "Paths specified by the find_package PATHS option.\n";
+    collectPathsForDebug(debugBuffer, paths);
+    this->DebugMessage(debugBuffer);
+  }
 }
 
 void cmFindPackageCommand::FillPrefixesUserHints()
@@ -1475,6 +1584,12 @@ void cmFindPackageCommand::FillPrefixesUserHints()
   for (std::string const& p : this->UserHintsArgs) {
     paths.AddUserPath(p);
   }
+  if (this->DebugMode) {
+    std::string debugBuffer =
+      "Paths specified by the find_package HINTS option.\n";
+    collectPathsForDebug(debugBuffer, paths);
+    this->DebugMessage(debugBuffer);
+  }
 }
 
 bool cmFindPackageCommand::SearchDirectory(std::string const& dir)
@@ -1519,7 +1634,8 @@ bool cmFindPackageCommand::FindConfigFile(std::string const& dir,
   for (std::string const& c : this->Configs) {
     file = cmStrCat(dir, '/', c);
     if (this->DebugMode) {
-      fprintf(stderr, "Checking file [%s]\n", file.c_str());
+      std::string msg = "Checking file [" + file + "]\n";
+      this->DebugMessage(msg);
     }
     if (cmSystemTools::FileExists(file, true) && this->CheckVersion(file)) {
       // Allow resolving symlinks when the config file is found through a link
@@ -2032,9 +2148,6 @@ private:
 bool cmFindPackageCommand::SearchPrefix(std::string const& prefix_in)
 {
   assert(!prefix_in.empty() && prefix_in.back() == '/');
-  if (this->DebugMode) {
-    fprintf(stderr, "Checking prefix [%s]\n", prefix_in.c_str());
-  }
 
   // Skip this if the prefix does not exist.
   if (!cmSystemTools::FileIsDirectory(prefix_in)) {
@@ -2188,9 +2301,6 @@ bool cmFindPackageCommand::SearchPrefix(std::string const& prefix_in)
 bool cmFindPackageCommand::SearchFrameworkPrefix(std::string const& prefix_in)
 {
   assert(!prefix_in.empty() && prefix_in.back() == '/');
-  if (this->DebugMode) {
-    fprintf(stderr, "Checking framework prefix [%s]\n", prefix_in.c_str());
-  }
 
   // Strip the trailing slash because the path generator is about to
   // add one.
@@ -2249,9 +2359,6 @@ bool cmFindPackageCommand::SearchFrameworkPrefix(std::string const& prefix_in)
 bool cmFindPackageCommand::SearchAppBundlePrefix(std::string const& prefix_in)
 {
   assert(!prefix_in.empty() && prefix_in.back() == '/');
-  if (this->DebugMode) {
-    fprintf(stderr, "Checking bundle prefix [%s]\n", prefix_in.c_str());
-  }
 
   // Strip the trailing slash because the path generator is about to
   // add one.
diff --git a/Source/cmFindPackageCommand.h b/Source/cmFindPackageCommand.h
index 85fe7b6e51..a65a2924c6 100644
--- a/Source/cmFindPackageCommand.h
+++ b/Source/cmFindPackageCommand.h
@@ -174,7 +174,6 @@ private:
   bool UseFindModules;
   bool NoUserRegistry;
   bool NoSystemRegistry;
-  bool DebugMode;
   bool UseLib32Paths;
   bool UseLib64Paths;
   bool UseLibx32Paths;
diff --git a/Source/cmFindPathCommand.cxx b/Source/cmFindPathCommand.cxx
index f5e2631081..908f0c13c6 100644
--- a/Source/cmFindPathCommand.cxx
+++ b/Source/cmFindPathCommand.cxx
@@ -21,6 +21,7 @@ cmFindPathCommand::cmFindPathCommand(cmExecutionStatus& status)
 // cmFindPathCommand
 bool cmFindPathCommand::InitialPass(std::vector<std::string> const& argsIn)
 {
+  this->DebugMode = ComputeIfDebugModeWanted();
   this->VariableDocumentation = "Path to a file.";
   this->CMakePathName = "INCLUDE";
   if (!this->ParseArguments(argsIn)) {
@@ -55,16 +56,19 @@ bool cmFindPathCommand::InitialPass(std::vector<std::string> const& argsIn)
 
 std::string cmFindPathCommand::FindHeader()
 {
+  std::string debug_name = this->IncludeFileInPath ? "find_file" : "find_path";
+  cmFindBaseDebugState debug(debug_name, this);
   std::string header;
   if (this->SearchFrameworkFirst || this->SearchFrameworkOnly) {
-    header = this->FindFrameworkHeader();
+    header = this->FindFrameworkHeader(debug);
   }
   if (header.empty() && !this->SearchFrameworkOnly) {
-    header = this->FindNormalHeader();
+    header = this->FindNormalHeader(debug);
   }
   if (header.empty() && this->SearchFrameworkLast) {
-    header = this->FindFrameworkHeader();
+    header = this->FindFrameworkHeader(debug);
   }
+
   return header;
 }
 
@@ -116,28 +120,31 @@ std::string cmFindPathCommand::FindHeaderInFramework(std::string const& file,
   return "";
 }
 
-std::string cmFindPathCommand::FindNormalHeader()
+std::string cmFindPathCommand::FindNormalHeader(cmFindBaseDebugState& debug)
 {
   std::string tryPath;
   for (std::string const& n : this->Names) {
     for (std::string const& sp : this->SearchPaths) {
       tryPath = cmStrCat(sp, n);
       if (cmSystemTools::FileExists(tryPath)) {
+        debug.FoundAt(tryPath);
         if (this->IncludeFileInPath) {
           return tryPath;
         }
         return sp;
       }
+      debug.FailedAt(tryPath);
     }
   }
   return "";
 }
 
-std::string cmFindPathCommand::FindFrameworkHeader()
+std::string cmFindPathCommand::FindFrameworkHeader(cmFindBaseDebugState& debug)
 {
   for (std::string const& n : this->Names) {
     for (std::string const& sp : this->SearchPaths) {
       std::string fwPath = this->FindHeaderInFramework(n, sp);
+      fwPath.empty() ? debug.FailedAt(fwPath) : debug.FoundAt(fwPath);
       if (!fwPath.empty()) {
         return fwPath;
       }
diff --git a/Source/cmFindPathCommand.h b/Source/cmFindPathCommand.h
index 8d1ea8b60e..18bfb7dd86 100644
--- a/Source/cmFindPathCommand.h
+++ b/Source/cmFindPathCommand.h
@@ -32,8 +32,8 @@ private:
   std::string FindHeaderInFramework(std::string const& file,
                                     std::string const& dir);
   std::string FindHeader();
-  std::string FindNormalHeader();
-  std::string FindFrameworkHeader();
+  std::string FindNormalHeader(cmFindBaseDebugState& debug);
+  std::string FindFrameworkHeader(cmFindBaseDebugState& debug);
 };
 
 bool cmFindPath(std::vector<std::string> const& args,
diff --git a/Source/cmFindProgramCommand.cxx b/Source/cmFindProgramCommand.cxx
index e0a3fbfcf5..3e4917262c 100644
--- a/Source/cmFindProgramCommand.cxx
+++ b/Source/cmFindProgramCommand.cxx
@@ -15,7 +15,9 @@ class cmExecutionStatus;
 
 struct cmFindProgramHelper
 {
-  cmFindProgramHelper()
+  cmFindProgramHelper(cmMakefile* makefile, cmFindBase const* base)
+    : DebugSearches("find_program", base)
+    , Makefile(makefile)
   {
 #if defined(_WIN32) || defined(__CYGWIN__) || defined(__MINGW32__)
     // Consider platform-specific extensions.
@@ -41,6 +43,10 @@ struct cmFindProgramHelper
   // Current full path under consideration.
   std::string TestPath;
 
+  // Debug state
+  cmFindBaseDebugState DebugSearches;
+  cmMakefile* Makefile;
+
   void AddName(std::string const& name) { this->Names.push_back(name); }
   void SetName(std::string const& name)
   {
@@ -78,8 +84,10 @@ struct cmFindProgramHelper
       this->TestNameExt = cmStrCat(name, ext);
       this->TestPath =
         cmSystemTools::CollapseFullPath(this->TestNameExt, path);
-
-      if (cmSystemTools::FileExists(this->TestPath, true)) {
+      bool exists = cmSystemTools::FileExists(this->TestPath, true);
+      exists ? this->DebugSearches.FoundAt(this->TestPath)
+             : this->DebugSearches.FailedAt(this->TestPath);
+      if (exists) {
         this->BestPath = this->TestPath;
         return true;
       }
@@ -97,6 +105,7 @@ cmFindProgramCommand::cmFindProgramCommand(cmExecutionStatus& status)
 // cmFindProgramCommand
 bool cmFindProgramCommand::InitialPass(std::vector<std::string> const& argsIn)
 {
+  this->DebugMode = ComputeIfDebugModeWanted();
   this->VariableDocumentation = "Path to a program.";
   this->CMakePathName = "PROGRAM";
   // call cmFindBase::ParseArguments
@@ -158,7 +167,7 @@ std::string cmFindProgramCommand::FindNormalProgram()
 std::string cmFindProgramCommand::FindNormalProgramNamesPerDir()
 {
   // Search for all names in each directory.
-  cmFindProgramHelper helper;
+  cmFindProgramHelper helper(this->Makefile, this);
   for (std::string const& n : this->Names) {
     helper.AddName(n);
   }
@@ -181,7 +190,7 @@ std::string cmFindProgramCommand::FindNormalProgramNamesPerDir()
 std::string cmFindProgramCommand::FindNormalProgramDirsPerName()
 {
   // Search the entire path for each name.
-  cmFindProgramHelper helper;
+  cmFindProgramHelper helper(this->Makefile, this);
   for (std::string const& n : this->Names) {
     // Switch to searching for this name.
     helper.SetName(n);
diff --git a/Tests/RunCMake/find_file/PrefixInPATH-stderr.txt b/Tests/RunCMake/find_file/PrefixInPATH-stderr.txt
new file mode 100644
index 0000000000..0d7757103b
--- /dev/null
+++ b/Tests/RunCMake/find_file/PrefixInPATH-stderr.txt
@@ -0,0 +1,13 @@
+  find_file called with the following settings:.*
+    VAR: PrefixInPATH_INCLUDE_DIR
+    NAMES: \"PrefixInPATH\.h\"
+    Documentation.*
+    Framework.*
+    AppBundle.*
+    CMAKE_FIND_USE_CMAKE_PATH: 1
+    CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH: 1
+    CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH: 1
+    CMAKE_FIND_USE_CMAKE_SYSTEM_PATH: 1
+
+  find_file considered the following locations:.*
+.*include/PrefixInPATH.*
diff --git a/Tests/RunCMake/find_file/PrefixInPATH.cmake b/Tests/RunCMake/find_file/PrefixInPATH.cmake
index 1e33c08a61..c334d89345 100644
--- a/Tests/RunCMake/find_file/PrefixInPATH.cmake
+++ b/Tests/RunCMake/find_file/PrefixInPATH.cmake
@@ -1,4 +1,10 @@
 set(ENV_PATH "$ENV{PATH}")
+
+set(CMAKE_FIND_DEBUG_MODE 1)
+set(ENV{PATH} "${CMAKE_CURRENT_SOURCE_DIR}/bin")
+find_file(PrefixInPATH_INCLUDE_DIR NAMES PrefixInPATH.h)
+set(CMAKE_FIND_DEBUG_MODE 0)
+
 foreach(path "/does_not_exist" "" "/bin" "/sbin")
   unset(PrefixInPATH_INCLUDE_DIR CACHE)
   set(ENV{PATH} "${CMAKE_CURRENT_SOURCE_DIR}${path}")
diff --git a/Tests/RunCMake/find_library/FromPATHEnv-stderr.txt b/Tests/RunCMake/find_library/FromPATHEnv-stderr.txt
new file mode 100644
index 0000000000..a690eecdc0
--- /dev/null
+++ b/Tests/RunCMake/find_library/FromPATHEnv-stderr.txt
@@ -0,0 +1,28 @@
+  find_library called with the following settings:.*
+    VAR: CREATED_LIBRARY
+    NAMES: \"created\"
+           \"created_no_exist\"
+    Documentation.*
+    Framework.*
+    AppBundle.*
+    CMAKE_FIND_USE_CMAKE_PATH: 1
+    CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH: 1
+    CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH: 0
+    CMAKE_FIND_USE_CMAKE_SYSTEM_PATH: 1
+
+  find_library considered the following locations:.*
+  The item was not found.*
+  find_library called with the following settings:.*
+    VAR: CREATED_LIBRARY
+    NAMES: \"created\"
+    Documentation.*
+    Framework.*
+    AppBundle.*
+    CMAKE_FIND_USE_CMAKE_PATH: 1
+    CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH: 1
+    CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH: 1
+    CMAKE_FIND_USE_CMAKE_SYSTEM_PATH: 1
+
+  find_library considered the following locations:.*
+  The item was found at.*
+.*lib/libcreated.a
diff --git a/Tests/RunCMake/find_library/FromPATHEnv.cmake b/Tests/RunCMake/find_library/FromPATHEnv.cmake
index fec041d3eb..c24e64019d 100644
--- a/Tests/RunCMake/find_library/FromPATHEnv.cmake
+++ b/Tests/RunCMake/find_library/FromPATHEnv.cmake
@@ -4,6 +4,19 @@ set(ENV_PATH "$ENV{PATH}")
 file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/lib)
 file(WRITE "${CMAKE_CURRENT_BINARY_DIR}/lib/libcreated.a" "created")
 
+set(CMAKE_FIND_DEBUG_MODE 1)
+set(CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH OFF)
+
+set(ENV{PATH} "${CMAKE_CURRENT_BINARY_DIR}/lib")
+find_library(CREATED_LIBRARY NAMES created created_no_exist)
+
+set(CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH ON)
+
+set(ENV{PATH} "${CMAKE_CURRENT_BINARY_DIR}/lib")
+find_library(CREATED_LIBRARY NAMES created)
+set(CMAKE_FIND_DEBUG_MODE 0)
+
+
 foreach(path "/does_not_exist" "/lib" "")
   unset(CREATED_LIBRARY CACHE)
   set(ENV{PATH} "${CMAKE_CURRENT_BINARY_DIR}${path}")
diff --git a/Tests/RunCMake/find_library/PrefixInPATH-stderr.txt b/Tests/RunCMake/find_library/PrefixInPATH-stderr.txt
new file mode 100644
index 0000000000..1d24c84eac
--- /dev/null
+++ b/Tests/RunCMake/find_library/PrefixInPATH-stderr.txt
@@ -0,0 +1,14 @@
+  find_library called with the following settings:.*
+    VAR: PrefixInPATH_LIBRARY
+    NAMES: \"PrefixInPATH\"
+    Documentation.*
+    Framework.*
+    AppBundle.*
+    CMAKE_FIND_USE_CMAKE_PATH: 1
+    CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH: 1
+    CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH: 1
+    CMAKE_FIND_USE_CMAKE_SYSTEM_PATH: 1
+
+  find_library considered the following locations:.*
+.*/does_not_exist.*
+  The item was not found
diff --git a/Tests/RunCMake/find_library/PrefixInPATH.cmake b/Tests/RunCMake/find_library/PrefixInPATH.cmake
index f1b8b187a5..e27d36246f 100644
--- a/Tests/RunCMake/find_library/PrefixInPATH.cmake
+++ b/Tests/RunCMake/find_library/PrefixInPATH.cmake
@@ -2,6 +2,12 @@ list(APPEND CMAKE_FIND_LIBRARY_PREFIXES lib)
 list(APPEND CMAKE_FIND_LIBRARY_SUFFIXES .a)
 
 set(ENV_PATH "$ENV{PATH}")
+
+set(CMAKE_FIND_DEBUG_MODE 1)
+set(ENV{PATH} "${CMAKE_CURRENT_SOURCE_DIR}/does_not_exist")
+find_library(PrefixInPATH_LIBRARY NAMES PrefixInPATH)
+set(CMAKE_FIND_DEBUG_MODE 0)
+
 foreach(path "/does_not_exist" "" "/bin" "/sbin")
   unset(PrefixInPATH_LIBRARY CACHE)
   set(ENV{PATH} "${CMAKE_CURRENT_SOURCE_DIR}${path}")
diff --git a/Tests/RunCMake/find_package/FromPATHEnv-stderr.txt b/Tests/RunCMake/find_package/FromPATHEnv-stderr.txt
new file mode 100644
index 0000000000..5856d567cc
--- /dev/null
+++ b/Tests/RunCMake/find_package/FromPATHEnv-stderr.txt
@@ -0,0 +1,16 @@
+CMake Debug Log at FromPATHEnv.cmake:5 \(find_package\):
+  find_package considered the following paths for Resolved.cmake
+.*
+  <PackageName>_ROOT CMake variable.*
+  CMAKE_PREFIX_PATH variable.*
+  CMAKE_FRAMEWORK_PATH and CMAKE_APPBUNDLE_PATH variables.*
+  Env variable Resolved_DIR.*
+  CMAKE_PREFIX_PATH env variable.*
+  Paths specified by the find_package HINTS option.*
+  Standard system environment variables.*
+.*Tests/RunCMake/find_package/PackageRoot.*
+  CMake User Package Registry.*
+  CMake variables defined in the Platform file.*
+  CMake System Package Registry.*
+  Paths specified by the find_package PATHS option.*
+  Checking file.*\[.*Tests/RunCMake/find_package/PackageRoot/ResolvedConfig\.cmake\]
diff --git a/Tests/RunCMake/find_package/FromPATHEnv.cmake b/Tests/RunCMake/find_package/FromPATHEnv.cmake
index 4822b133d7..ceb79b6829 100644
--- a/Tests/RunCMake/find_package/FromPATHEnv.cmake
+++ b/Tests/RunCMake/find_package/FromPATHEnv.cmake
@@ -1,4 +1,10 @@
 set(ENV_PATH "$ENV{PATH}")
+
+set(CMAKE_FIND_DEBUG_MODE ON)
+set(ENV{PATH} "${CMAKE_CURRENT_SOURCE_DIR}/PackageRoot")
+find_package(Resolved QUIET)
+set(CMAKE_FIND_DEBUG_MODE OFF)
+
 foreach(path "/does_not_exist" "/PackageRoot" "")
   unset(Resolved_FOUND CACHE)
   set(Resolved_DIR "")
diff --git a/Tests/RunCMake/find_package/MissingConfigDebug-stderr.txt b/Tests/RunCMake/find_package/MissingConfigDebug-stderr.txt
new file mode 100644
index 0000000000..8ff04a9b65
--- /dev/null
+++ b/Tests/RunCMake/find_package/MissingConfigDebug-stderr.txt
@@ -0,0 +1,17 @@
+  <PackageName>_ROOT CMake variable.*
+  CMAKE_PREFIX_PATH variable.*
+  CMAKE_FRAMEWORK_PATH and CMAKE_APPBUNDLE_PATH variables.*
+  Env variable NotHere_DIR.*
+  CMAKE_PREFIX_PATH env variable.*
+  Standard system environment variables.*
+  CMake User Package Registry.*
+  CMake variables defined in the Platform file.*
+  CMake System Package Registry.*
+  Paths specified by the find_package PATHS option.*
+.*
+  Checking file \[.*NotHereConfig.cmake\].*
+  Checking file \[.*nothere-config.cmake\].*
+CMake Warning at MissingConfigDebug.cmake:3 \(message\):
+  This warning must be reachable.
+Call Stack \(most recent call first\):
+  CMakeLists.txt:3 \(include\)$
diff --git a/Tests/RunCMake/find_package/MissingConfigDebug.cmake b/Tests/RunCMake/find_package/MissingConfigDebug.cmake
new file mode 100644
index 0000000000..4e3bb22ddb
--- /dev/null
+++ b/Tests/RunCMake/find_package/MissingConfigDebug.cmake
@@ -0,0 +1,4 @@
+set(CMAKE_FIND_DEBUG_MODE ON)
+find_package(NotHere CONFIG)
+message(WARNING "This warning must be reachable.")
+set(CMAKE_FIND_DEBUG_MODE OFF)
diff --git a/Tests/RunCMake/find_package/RunCMakeTest.cmake b/Tests/RunCMake/find_package/RunCMakeTest.cmake
index 208f83c919..5186297dfb 100644
--- a/Tests/RunCMake/find_package/RunCMakeTest.cmake
+++ b/Tests/RunCMake/find_package/RunCMakeTest.cmake
@@ -13,6 +13,7 @@ run_cmake(MissingNormalWarnNoModuleNew)
 run_cmake(MissingModule)
 run_cmake(MissingModuleRequired)
 run_cmake(MissingConfig)
+run_cmake(MissingConfigDebug)
 run_cmake(MissingConfigOneName)
 run_cmake(MissingConfigRequired)
 run_cmake(MissingConfigVersion)
diff --git a/Tests/RunCMake/find_path/FromPATHEnv-stderr.txt b/Tests/RunCMake/find_path/FromPATHEnv-stderr.txt
new file mode 100644
index 0000000000..088efd559c
--- /dev/null
+++ b/Tests/RunCMake/find_path/FromPATHEnv-stderr.txt
@@ -0,0 +1,27 @@
+  find_path called with the following settings:.*
+    VAR: PATH_IN_ENV_PATH
+    NAMES: \"PrefixInPATH\.h\"
+    Documentation.*
+    Framework.*
+    AppBundle.*
+    CMAKE_FIND_USE_CMAKE_PATH: 1
+    CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH: 1
+    CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH: 0
+    CMAKE_FIND_USE_CMAKE_SYSTEM_PATH: 1
+
+  find_path considered the following locations:.*
+  The item was not found.*
+  find_path called with the following settings:.*
+    VAR: PATH_IN_ENV_PATH
+    NAMES: \"PrefixInPATH\.h\"
+    Documentation.*
+    Framework.*
+    AppBundle.*
+    CMAKE_FIND_USE_CMAKE_PATH: 1
+    CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH: 1
+    CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH: 1
+    CMAKE_FIND_USE_CMAKE_SYSTEM_PATH: 1
+
+  find_path considered the following locations:.*
+  The item was found at.*
+.*include/PrefixInPATH.*
diff --git a/Tests/RunCMake/find_path/FromPATHEnv.cmake b/Tests/RunCMake/find_path/FromPATHEnv.cmake
index af13d09fa9..535e62437f 100644
--- a/Tests/RunCMake/find_path/FromPATHEnv.cmake
+++ b/Tests/RunCMake/find_path/FromPATHEnv.cmake
@@ -1,4 +1,16 @@
 set(ENV_PATH "$ENV{PATH}")
+
+set(CMAKE_FIND_DEBUG_MODE 1)
+set(CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH OFF)
+
+set(ENV{PATH} "${CMAKE_CURRENT_SOURCE_DIR}/include")
+find_path(PATH_IN_ENV_PATH NAMES PrefixInPATH.h)
+
+set(CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH ON)
+find_path(PATH_IN_ENV_PATH NAMES PrefixInPATH.h)
+
+set(CMAKE_FIND_DEBUG_MODE 0)
+
 foreach(path "/does_not_exist" "/include" "")
   unset(PATH_IN_ENV_PATH CACHE)
   set(ENV{PATH} "${CMAKE_CURRENT_SOURCE_DIR}${path}")
diff --git a/Tests/RunCMake/find_program/EnvAndHints-stderr.txt b/Tests/RunCMake/find_program/EnvAndHints-stderr.txt
new file mode 100644
index 0000000000..8951345ffd
--- /dev/null
+++ b/Tests/RunCMake/find_program/EnvAndHints-stderr.txt
@@ -0,0 +1,28 @@
+  find_program called with the following settings:.*
+    VAR: PROG
+    NAMES: \"testAandB\"
+    Documentation.*
+    Framework.*
+    AppBundle.*
+    CMAKE_FIND_USE_CMAKE_PATH: 1
+    CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH: 1
+    CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH: 1
+    CMAKE_FIND_USE_CMAKE_SYSTEM_PATH: 1
+
+  find_program considered the following locations:.*
+  The item was found at.*
+.*testAandB
+.*
+  find_program called with the following settings:.*
+    VAR: PROG
+    NAMES: \"testAandB\"
+    Documentation.*
+    Framework.*
+    AppBundle.*
+    CMAKE_FIND_USE_CMAKE_PATH: 1
+    CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH: 1
+    CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH: 0
+    CMAKE_FIND_USE_CMAKE_SYSTEM_PATH: 1
+
+  find_program considered the following locations:.*
+  The item was not found.*
diff --git a/Tests/RunCMake/find_program/EnvAndHints.cmake b/Tests/RunCMake/find_program/EnvAndHints.cmake
index 0f12effc06..beed873caa 100644
--- a/Tests/RunCMake/find_program/EnvAndHints.cmake
+++ b/Tests/RunCMake/find_program/EnvAndHints.cmake
@@ -1,4 +1,5 @@
 
+set(CMAKE_FIND_DEBUG_MODE 1)
 set(ENV_PATH "$ENV{PATH}")
 set(ENV{PATH} ${CMAKE_CURRENT_SOURCE_DIR}/A)
 find_program(PROG
@@ -13,6 +14,7 @@ find_program(PROG
   )
 message(STATUS "PROG='${PROG}'")
 unset(PROG CACHE)
+set(CMAKE_FIND_DEBUG_MODE 0)
 
 find_program(PROG
   NAMES testAandB
-- 
cgit v1.2.1