From a7ea20649d4593bbad70b8a99aab4c2bf6294b79 Mon Sep 17 00:00:00 2001
From: Robert Maynard <robert.maynard@kitware.com>
Date: Fri, 4 Oct 2019 17:18:26 -0400
Subject: find_*: Add debug logging infrastructure

Enable debug messages a new `--find-debug` command-line option or via
the `CMAKE_FIND_DEBUG_MODE` variable.

This work was started by Chris Wilson, continued by Ray Donnelly, and
then refactored by Robert Maynard to collect information into a single
message per find query.

Co-Author: Ray Donnelly <mingw.android@gmail.com>
Co-Author: Chris Wilson <chris+github@qwirx.com>
---
 Help/manual/cmake.1.rst |   6 +++
 Source/cmFindBase.cxx   | 131 +++++++++++++++++++++++++++++++++++-------------
 Source/cmFindBase.h     |  32 +++++++++++-
 Source/cmFindCommon.cxx |  17 +++++++
 Source/cmFindCommon.h   |   9 ++++
 Source/cmMakefile.cxx   |   9 +++-
 Source/cmMakefile.h     |  15 +++++-
 Source/cmSearchPath.h   |   2 +
 Source/cmake.cxx        |   3 ++
 Source/cmake.h          |  11 ++--
 Source/cmakemain.cxx    |   1 +
 11 files changed, 193 insertions(+), 43 deletions(-)

diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst
index 6f33866..f8847f1 100644
--- a/Help/manual/cmake.1.rst
+++ b/Help/manual/cmake.1.rst
@@ -241,6 +241,12 @@ Options
  Print extra information during the cmake run like stack traces with
  :command:`message(SEND_ERROR)` calls.
 
+``--debug-find``
+ Put cmake find in a debug mode.
+
+ Print extra find call information during the cmake run to standard
+ error. Output is designed for human consumption and not for parsing.
+
 ``--trace``
  Put cmake in trace mode.
 
diff --git a/Source/cmFindBase.cxx b/Source/cmFindBase.cxx
index 7d74118..d5fa610 100644
--- a/Source/cmFindBase.cxx
+++ b/Source/cmFindBase.cxx
@@ -4,8 +4,8 @@
 
 #include <cstddef>
 #include <deque>
-#include <iostream>
 #include <map>
+#include <utility>
 
 #include "cmAlgorithms.h"
 #include "cmMakefile.h"
@@ -116,17 +116,19 @@ bool cmFindBase::ParseArguments(std::vector<std::string> const& argsIn)
       this->NoDefaultPath = true;
     } else if (this->CheckCommonArgument(args[j])) {
       doing = DoingNone;
+    } else {
       // Some common arguments were accidentally supported by CMake
       // 2.4 and 2.6.0 in the short-hand form of the command, so we
       // must support it even though it is not documented.
-    } else if (doing == DoingNames) {
-      this->Names.push_back(args[j]);
-    } else if (doing == DoingPaths) {
-      this->UserGuessArgs.push_back(args[j]);
-    } else if (doing == DoingHints) {
-      this->UserHintsArgs.push_back(args[j]);
-    } else if (doing == DoingPathSuffixes) {
-      this->AddPathSuffix(args[j]);
+      if (doing == DoingNames) {
+        this->Names.push_back(args[j]);
+      } else if (doing == DoingPaths) {
+        this->UserGuessArgs.push_back(args[j]);
+      } else if (doing == DoingHints) {
+        this->UserHintsArgs.push_back(args[j]);
+      } else if (doing == DoingPathSuffixes) {
+        this->AddPathSuffix(args[j]);
+      }
     }
   }
 
@@ -288,33 +290,6 @@ void cmFindBase::FillUserGuessPath()
   paths.AddSuffixes(this->SearchPathSuffixes);
 }
 
-void cmFindBase::PrintFindStuff()
-{
-  std::cerr << "SearchFrameworkLast: " << this->SearchFrameworkLast << "\n";
-  std::cerr << "SearchFrameworkOnly: " << this->SearchFrameworkOnly << "\n";
-  std::cerr << "SearchFrameworkFirst: " << this->SearchFrameworkFirst << "\n";
-  std::cerr << "SearchAppBundleLast: " << this->SearchAppBundleLast << "\n";
-  std::cerr << "SearchAppBundleOnly: " << this->SearchAppBundleOnly << "\n";
-  std::cerr << "SearchAppBundleFirst: " << this->SearchAppBundleFirst << "\n";
-  std::cerr << "VariableName " << this->VariableName << "\n";
-  std::cerr << "VariableDocumentation " << this->VariableDocumentation << "\n";
-  std::cerr << "NoDefaultPath " << this->NoDefaultPath << "\n";
-  std::cerr << "NoCMakeEnvironmentPath " << this->NoCMakeEnvironmentPath
-            << "\n";
-  std::cerr << "NoCMakePath " << this->NoCMakePath << "\n";
-  std::cerr << "NoSystemEnvironmentPath " << this->NoSystemEnvironmentPath
-            << "\n";
-  std::cerr << "NoCMakeSystemPath " << this->NoCMakeSystemPath << "\n";
-  std::cerr << "EnvironmentPath " << this->EnvironmentPath << "\n";
-  std::cerr << "CMakePathName " << this->CMakePathName << "\n";
-  std::cerr << "Names  " << cmJoin(this->Names, " ") << "\n";
-  std::cerr << "\n";
-  std::cerr << "SearchPathSuffixes  ";
-  std::cerr << cmJoin(this->SearchPathSuffixes, "\n") << "\n";
-  std::cerr << "SearchPaths\n";
-  std::cerr << cmWrap("[", this->SearchPaths, "]", "\n") << "\n";
-}
-
 bool cmFindBase::CheckForVariableInCache()
 {
   if (const char* cacheValue =
@@ -343,3 +318,87 @@ bool cmFindBase::CheckForVariableInCache()
   }
   return false;
 }
+
+cmFindBaseDebugState::cmFindBaseDebugState(std::string commandName,
+                                           cmFindBase const* findBase)
+  : FindCommand(findBase)
+  , CommandName(std::move(commandName))
+{
+}
+
+cmFindBaseDebugState::~cmFindBaseDebugState()
+{
+  if (this->FindCommand->DebugMode) {
+    std::string buffer =
+      cmStrCat(this->CommandName, " called with the following settings:\n");
+    buffer += cmStrCat("  VAR: ", this->FindCommand->VariableName, "\n");
+    buffer += cmStrCat(
+      "  NAMES: ", cmWrap("\"", this->FindCommand->Names, "\"", "\n         "),
+      "\n");
+    buffer += cmStrCat(
+      "  Documentation: ", this->FindCommand->VariableDocumentation, "\n");
+    buffer += "  Framework\n";
+    buffer += cmStrCat("    Only Search Frameworks: ",
+                       this->FindCommand->SearchFrameworkOnly, "\n");
+
+    buffer += cmStrCat("    Search Frameworks Last: ",
+                       this->FindCommand->SearchFrameworkLast, "\n");
+    buffer += cmStrCat("    Search Frameworks First: ",
+                       this->FindCommand->SearchFrameworkFirst, "\n");
+    buffer += "  AppBundle\n";
+    buffer += cmStrCat("    Only Search AppBundle: ",
+                       this->FindCommand->SearchAppBundleOnly, "\n");
+    buffer += cmStrCat("    Search AppBundle Last: ",
+                       this->FindCommand->SearchAppBundleLast, "\n");
+    buffer += cmStrCat("    Search AppBundle First: ",
+                       this->FindCommand->SearchAppBundleFirst, "\n");
+
+    if (this->FindCommand->NoDefaultPath) {
+      buffer += "  NO_DEFAULT_PATH Enabled\n";
+    } else {
+      buffer += cmStrCat(
+        "  CMAKE_FIND_USE_CMAKE_PATH: ", !this->FindCommand->NoCMakePath, "\n",
+        "  CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH: ",
+        !this->FindCommand->NoCMakeEnvironmentPath, "\n",
+        "  CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH: ",
+        !this->FindCommand->NoSystemEnvironmentPath, "\n",
+        "  CMAKE_FIND_USE_CMAKE_SYSTEM_PATH: ",
+        !this->FindCommand->NoCMakeSystemPath, "\n");
+    }
+
+    buffer +=
+      cmStrCat(this->CommandName, " considered the following locations:\n");
+    for (auto const& state : this->FailedSearchLocations) {
+      std::string path = cmStrCat("  ", state.path);
+      if (!state.regexName.empty()) {
+        path = cmStrCat(path, "/", state.regexName);
+      }
+      buffer += cmStrCat(path, "\n");
+    }
+
+    if (!this->FoundSearchLocation.path.empty()) {
+      buffer += cmStrCat("The item was found at\n  ",
+                         this->FoundSearchLocation.path, "\n");
+    } else {
+      buffer += "The item was not found.\n";
+    }
+
+    this->FindCommand->DebugMessage(buffer);
+  }
+}
+
+void cmFindBaseDebugState::FoundAt(std::string const& path,
+                                   std::string regexName)
+{
+  if (this->FindCommand->DebugMode) {
+    this->FoundSearchLocation = DebugLibState{ std::move(regexName), path };
+  }
+}
+
+void cmFindBaseDebugState::FailedAt(std::string const& path,
+                                    std::string regexName)
+{
+  if (this->FindCommand->DebugMode) {
+    this->FailedSearchLocations.emplace_back(std::move(regexName), path);
+  }
+}
diff --git a/Source/cmFindBase.h b/Source/cmFindBase.h
index f75db5f..fce0b11 100644
--- a/Source/cmFindBase.h
+++ b/Source/cmFindBase.h
@@ -6,6 +6,7 @@
 #include "cmConfigure.h" // IWYU pragma: keep
 
 #include <string>
+#include <utility>
 #include <vector>
 
 #include "cmFindCommon.h"
@@ -31,7 +32,7 @@ public:
   virtual bool ParseArguments(std::vector<std::string> const& args);
 
 protected:
-  void PrintFindStuff();
+  friend class cmFindBaseDebugState;
   void ExpandPaths();
 
   // see if the VariableName is already set in the cache,
@@ -63,4 +64,33 @@ private:
   void FillUserGuessPath();
 };
 
+class cmFindBaseDebugState
+{
+public:
+  explicit cmFindBaseDebugState(std::string name, cmFindBase const* findBase);
+  ~cmFindBaseDebugState();
+
+  void FoundAt(std::string const& path, std::string regexName = std::string());
+  void FailedAt(std::string const& path,
+                std::string regexName = std::string());
+
+private:
+  struct DebugLibState
+  {
+    DebugLibState() = default;
+    DebugLibState(std::string&& n, std::string p)
+      : regexName(n)
+      , path(std::move(p))
+    {
+    }
+    std::string regexName;
+    std::string path;
+  };
+
+  cmFindBase const* FindCommand;
+  std::string CommandName;
+  std::vector<DebugLibState> FailedSearchLocations;
+  DebugLibState FoundSearchLocation;
+};
+
 #endif
diff --git a/Source/cmFindCommon.cxx b/Source/cmFindCommon.cxx
index badec55..92317bb 100644
--- a/Source/cmFindCommon.cxx
+++ b/Source/cmFindCommon.cxx
@@ -10,8 +10,10 @@
 #include "cmAlgorithms.h"
 #include "cmExecutionStatus.h"
 #include "cmMakefile.h"
+#include "cmMessageType.h"
 #include "cmStringAlgorithms.h"
 #include "cmSystemTools.h"
+#include "cmake.h"
 
 cmFindCommon::PathGroup cmFindCommon::PathGroup::All("ALL");
 cmFindCommon::PathLabel cmFindCommon::PathLabel::PackageRoot(
@@ -52,6 +54,8 @@ cmFindCommon::cmFindCommon(cmExecutionStatus& status)
   this->SearchAppBundleLast = false;
 
   this->InitializeSearchPathGroups();
+
+  this->DebugMode = false;
 }
 
 void cmFindCommon::SetError(std::string const& e)
@@ -59,6 +63,19 @@ void cmFindCommon::SetError(std::string const& e)
   this->Status.SetError(e);
 }
 
+void cmFindCommon::DebugMessage(std::string const& msg) const
+{
+  if (this->Makefile) {
+    this->Makefile->IssueMessage(MessageType::LOG, msg);
+  }
+}
+
+bool cmFindCommon::ComputeIfDebugModeWanted()
+{
+  return this->Makefile->IsOn("CMAKE_FIND_DEBUG_MODE") ||
+    this->Makefile->GetCMakeInstance()->GetDebugFindOutput();
+}
+
 void cmFindCommon::InitializeSearchPathGroups()
 {
   std::vector<PathLabel>* labels;
diff --git a/Source/cmFindCommon.h b/Source/cmFindCommon.h
index 8177eac..916f3bc 100644
--- a/Source/cmFindCommon.h
+++ b/Source/cmFindCommon.h
@@ -30,8 +30,11 @@ public:
 
   void SetError(std::string const& e);
 
+  bool DebugModeEnabled() const { return this->DebugMode; }
+
 protected:
   friend class cmSearchPath;
+  friend class cmFindBaseDebugState;
 
   /** Used to define groups of path labels */
   class PathGroup : public cmPathLabel
@@ -96,6 +99,10 @@ protected:
   /** Compute the current default search modes based on global variables.  */
   void SelectDefaultSearchModes();
 
+  /** The `InitialPass` functions of the child classes should set
+      this->DebugMode to the result of this.  */
+  bool ComputeIfDebugModeWanted();
+
   // Path arguments prior to path manipulation routines
   std::vector<std::string> UserHintsArgs;
   std::vector<std::string> UserGuessArgs;
@@ -106,6 +113,8 @@ protected:
   bool CheckCommonArgument(std::string const& arg);
   void AddPathSuffix(std::string const& arg);
 
+  void DebugMessage(std::string const& msg) const;
+  bool DebugMode;
   bool NoDefaultPath;
   bool NoPackageRootPath;
   bool NoCMakePath;
diff --git a/Source/cmMakefile.cxx b/Source/cmMakefile.cxx
index 74cc831..0ad482c 100644
--- a/Source/cmMakefile.cxx
+++ b/Source/cmMakefile.cxx
@@ -3728,7 +3728,8 @@ void cmMakefile::DisplayStatus(const std::string& message, float s) const
 }
 
 std::string cmMakefile::GetModulesFile(const std::string& filename,
-                                       bool& system) const
+                                       bool& system, bool debug,
+                                       std::string& debugBuffer) const
 {
   std::string result;
 
@@ -3759,6 +3760,9 @@ std::string cmMakefile::GetModulesFile(const std::string& filename,
         moduleInCMakeModulePath = itempl;
         break;
       }
+      if (debug) {
+        debugBuffer = cmStrCat(debugBuffer, "  ", itempl, "\n");
+      }
     }
   }
 
@@ -3767,6 +3771,9 @@ std::string cmMakefile::GetModulesFile(const std::string& filename,
     cmStrCat(cmSystemTools::GetCMakeRoot(), "/Modules/", filename);
   cmSystemTools::ConvertToUnixSlashes(moduleInCMakeRoot);
   if (!cmSystemTools::FileExists(moduleInCMakeRoot)) {
+    if (debug) {
+      debugBuffer = cmStrCat(debugBuffer, "  ", moduleInCMakeRoot, "\n");
+    }
     moduleInCMakeRoot.clear();
   }
 
diff --git a/Source/cmMakefile.h b/Source/cmMakefile.h
index 672244e..085c1d6 100644
--- a/Source/cmMakefile.h
+++ b/Source/cmMakefile.h
@@ -766,10 +766,21 @@ public:
   std::string GetModulesFile(const std::string& name) const
   {
     bool system;
-    return this->GetModulesFile(name, system);
+    std::string debugBuffer;
+    return this->GetModulesFile(name, system, false, debugBuffer);
   }
 
-  std::string GetModulesFile(const std::string& name, bool& system) const;
+  /**
+   * Return a location of a file in cmake or custom modules directory
+   */
+  std::string GetModulesFile(const std::string& name, bool& system) const
+  {
+    std::string debugBuffer;
+    return this->GetModulesFile(name, system, false, debugBuffer);
+  }
+
+  std::string GetModulesFile(const std::string& name, bool& system, bool debug,
+                             std::string& debugBuffer) const;
 
   //! Set/Get a property of this directory
   void SetProperty(const std::string& prop, const char* value);
diff --git a/Source/cmSearchPath.h b/Source/cmSearchPath.h
index 2a576ed..3ecc73b 100644
--- a/Source/cmSearchPath.h
+++ b/Source/cmSearchPath.h
@@ -5,6 +5,7 @@
 
 #include "cmConfigure.h" // IWYU pragma: keep
 
+#include <cstddef>
 #include <set>
 #include <string>
 #include <vector>
@@ -27,6 +28,7 @@ public:
   ~cmSearchPath();
 
   const std::vector<std::string>& GetPaths() const { return this->Paths; }
+  std::size_t size() const { return this->Paths.size(); }
 
   void ExtractWithout(const std::set<std::string>& ignore,
                       std::vector<std::string>& outPaths,
diff --git a/Source/cmake.cxx b/Source/cmake.cxx
index 684ab3b..3642a0f 100644
--- a/Source/cmake.cxx
+++ b/Source/cmake.cxx
@@ -749,6 +749,9 @@ void cmake::SetArgs(const std::vector<std::string>& args)
       this->LogLevelWasSetViaCLI = true;
     } else if (arg == "--log-context") {
       this->SetShowLogContext(true);
+    } else if (arg.find("--debug-find", 0) == 0) {
+      std::cout << "Running with debug output on for the `find` commands.\n";
+      this->SetDebugFindOutputOn(true);
     } else if (arg.find("--trace-expand", 0) == 0) {
       std::cout << "Running with expanded trace output on.\n";
       this->SetTrace(true);
diff --git a/Source/cmake.h b/Source/cmake.h
index 02de4c1..cb959ef 100644
--- a/Source/cmake.h
+++ b/Source/cmake.h
@@ -409,13 +409,17 @@ public:
     this->CheckInProgressMessages.emplace(std::move(message));
   }
 
+  //! Should `message` command display context.
+  bool GetShowLogContext() const { return this->LogContext; }
+  void SetShowLogContext(bool b) { this->LogContext = b; }
+
   //! Do we want debug output during the cmake run.
   bool GetDebugOutput() { return this->DebugOutput; }
   void SetDebugOutputOn(bool b) { this->DebugOutput = b; }
 
-  //! Should `message` command display context.
-  bool GetShowLogContext() const { return this->LogContext; }
-  void SetShowLogContext(bool b) { this->LogContext = b; }
+  //! Do we want debug output from the find commands during the cmake run.
+  bool GetDebugFindOutput() { return this->DebugFindOutput; }
+  void SetDebugFindOutputOn(bool b) { this->DebugFindOutput = b; }
 
   //! Do we want trace output during the cmake run.
   bool GetTrace() { return this->Trace; }
@@ -577,6 +581,7 @@ private:
   ProgressCallbackType ProgressCallback;
   WorkingMode CurrentWorkingMode = NORMAL_MODE;
   bool DebugOutput = false;
+  bool DebugFindOutput = false;
   bool Trace = false;
   bool TraceExpand = false;
   cmGeneratedFileStream TraceFile;
diff --git a/Source/cmakemain.cxx b/Source/cmakemain.cxx
index d817971..253191a 100644
--- a/Source/cmakemain.cxx
+++ b/Source/cmakemain.cxx
@@ -78,6 +78,7 @@ const char* cmDocumentationOptions[][2] = {
     "Do not delete the try_compile build tree. Only "
     "useful on one try_compile at a time." },
   { "--debug-output", "Put cmake in a debug mode." },
+  { "--debug-find", "Put cmake find in a debug mode." },
   { "--trace", "Put cmake in trace mode." },
   { "--trace-expand", "Put cmake in trace mode with variable expansion." },
   { "--trace-source=<file>",
-- 
cgit v0.12


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 20221b1..d5a4bde 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 2b11b62..9eb256b 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 85fe7b6..a65a292 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 f5e2631..908f0c1 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 8d1ea8b..18bfb7d 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 e0a3fbf..3e49172 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 0000000..0d77571
--- /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 1e33c08..c334d89 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 0000000..a690eec
--- /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 fec041d..c24e640 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 0000000..1d24c84
--- /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 f1b8b18..e27d362 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 0000000..5856d56
--- /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 4822b13..ceb79b6 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 0000000..8ff04a9
--- /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 0000000..4e3bb22
--- /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 208f83c..5186297 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 0000000..088efd5
--- /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 af13d09..535e624 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 0000000..8951345
--- /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 0f12eff..beed873 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 v0.12


From f3c93962609f19ababd58b48db313f836bd8f0e7 Mon Sep 17 00:00:00 2001
From: Robert Maynard <robert.maynard@kitware.com>
Date: Tue, 17 Dec 2019 10:53:35 -0500
Subject: Help: Document CMAKE_FIND_DEBUG_MODE

---
 Help/manual/cmake-variables.7.rst       |  1 +
 Help/variable/CMAKE_FIND_DEBUG_MODE.rst | 22 ++++++++++++++++++++++
 2 files changed, 23 insertions(+)
 create mode 100644 Help/variable/CMAKE_FIND_DEBUG_MODE.rst

diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst
index d0eaa31..74dd1fb 100644
--- a/Help/manual/cmake-variables.7.rst
+++ b/Help/manual/cmake-variables.7.rst
@@ -53,6 +53,7 @@ Variables that Provide Information
    /variable/CMAKE_EXECUTABLE_SUFFIX
    /variable/CMAKE_EXTRA_GENERATOR
    /variable/CMAKE_EXTRA_SHARED_LIBRARY_SUFFIXES
+   /variable/CMAKE_FIND_DEBUG_MODE
    /variable/CMAKE_FIND_PACKAGE_NAME
    /variable/CMAKE_FIND_PACKAGE_SORT_DIRECTION
    /variable/CMAKE_FIND_PACKAGE_SORT_ORDER
diff --git a/Help/variable/CMAKE_FIND_DEBUG_MODE.rst b/Help/variable/CMAKE_FIND_DEBUG_MODE.rst
new file mode 100644
index 0000000..33ffdd6
--- /dev/null
+++ b/Help/variable/CMAKE_FIND_DEBUG_MODE.rst
@@ -0,0 +1,22 @@
+CMAKE_FIND_DEBUG_MODE
+---------------------
+
+Print extra find call information for the following commands to standard
+error:
+* :command:`find_program`
+* :command:`find_library`
+* :command:`find_file`
+* :command:`find_path`
+* :command:`find_package`
+
+Output is designed for human consumption and not for parsing.
+Enabling this variable is equivalent to using :manual:`cmake <cmake(1)>` ``--debug-find``
+with the added ability to enable debugging for a subset of find calls.
+
+.. code-block:: cmake
+
+  set(CMAKE_FIND_DEBUG_MODE TRUE)
+  find_program(...)
+  set(CMAKE_FIND_DEBUG_MODE FALSE)
+
+Default is unset.
-- 
cgit v0.12