cmake: Add filtered debug-find options

Add a `--debug-find-pkg=` option to debug find calls for specific
packages.

Add a `--debug-find-var=` option to debug find calls for specific
return variables.

Fixes: #21880

Help/manual/cmake.1.rst

@@ -250,6 +250,20 @@ Options
  See also the :variable:`CMAKE_FIND_DEBUG_MODE` variable for debugging
  a more local part of the project.
 
+``--debug-find=<pkg>[,...]``
+ Put cmake find commands in a debug mode when running under calls
+ to ``find_package(<pkg>)``, where ``<pkg>`` is an entry in the given
+ comma-separated list of case-sensitive package names.
+
+ Like ``--debug-find``, but limiting scope to the specified packages.
+
+``--debug-find-var=<var>[,...]``
+ Put cmake find commands in a debug mode when called with ``<var>``
+ as the return variable, where ``<var>`` is an entry in the given
+ comma-separated list.
+
+ Like ``--debug-find``, but limiting scope to the specified variable names.
+
 ``--trace``
  Put cmake in trace mode.
 

Help/release/dev/filter-debug-find.rst

@@ -0,0 +1,10 @@
+filter-debug-find
+-----------------
+
+* The :manual:`cmake(1)` command line tool's gained a
+  ``--debug-find-pkg=`` option to enable debug messages under specific
+  :command:`find_package` calls.
+
+* The :manual:`cmake(1)` command line tool gained a ``--debug-find-var=``
+  option to enable debug messages for ``find_*`` calls that use specific
+  result variables.

Source/cmFindCommon.cxx

@@ -77,6 +77,12 @@ bool cmFindCommon::ComputeIfDebugModeWanted()
     this->Makefile->GetCMakeInstance()->GetDebugFindOutput();
 }
 
+bool cmFindCommon::ComputeIfDebugModeWanted(std::string const& var)
+{
+  return this->ComputeIfDebugModeWanted() ||
+    this->Makefile->GetCMakeInstance()->GetDebugFindOutput(var);
+}
+
 void cmFindCommon::InitializeSearchPathGroups()
 {
   std::vector<PathLabel>* labels;

Source/cmFindCommon.h

@@ -99,8 +99,9 @@ protected:
   void SelectDefaultSearchModes();
 
   /** The `InitialPass` functions of the child classes should set
-      this->DebugMode to the result of this.  */
+      this->DebugMode to the result of these.  */
   bool ComputeIfDebugModeWanted();
+  bool ComputeIfDebugModeWanted(std::string const& var);
 
   // Path arguments prior to path manipulation routines
   std::vector<std::string> UserHintsArgs;

Source/cmFindLibraryCommand.cxx

@@ -32,13 +32,14 @@ cmFindLibraryCommand::cmFindLibraryCommand(cmExecutionStatus& status)
 // cmFindLibraryCommand
 bool cmFindLibraryCommand::InitialPass(std::vector<std::string> const& argsIn)
 {
-  this->DebugMode = this->ComputeIfDebugModeWanted();
   this->CMakePathName = "LIBRARY";
 
   if (!this->ParseArguments(argsIn)) {
     return false;
   }
 
+  this->DebugMode = this->ComputeIfDebugModeWanted(this->VariableName);
+
   if (this->AlreadyDefined) {
     this->NormalizeFindResult();
     return true;

Source/cmFindPackageCommand.cxx

@@ -33,6 +33,7 @@
 #include "cmSystemTools.h"
 #include "cmValue.h"
 #include "cmVersion.h"
+#include "cmake.h"
 
 #if defined(__HAIKU__)
 #  include <FindDirectory.h>
@@ -144,9 +145,6 @@ bool cmFindPackageCommand::InitialPass(std::vector<std::string> const& args)
     this->RequiredCMakeVersion = CMake_VERSION_ENCODE(v[0], v[1], v[2]);
   }
 
-  this->DebugMode = this->ComputeIfDebugModeWanted();
-  this->DebugBuffer.clear();
-
   // Lookup target architecture, if any.
   if (cmValue arch =
         this->Makefile->GetDefinition("CMAKE_LIBRARY_ARCHITECTURE")) {
@@ -236,6 +234,10 @@ bool cmFindPackageCommand::InitialPass(std::vector<std::string> const& args)
   // Always search directly in a generated path.
   this->SearchPathSuffixes.emplace_back();
 
+  // Process debug mode
+  this->DebugMode = this->ComputeIfDebugModeWanted(this->Name);
+  this->DebugBuffer.clear();
+
   // Parse the arguments.
   enum Doing
   {
@@ -619,6 +621,12 @@ bool cmFindPackageCommand::InitialPass(std::vector<std::string> const& args)
   return loadedPackage;
 }
 
+bool cmFindPackageCommand::ComputeIfDebugModeWanted(std::string const& var)
+{
+  return this->ComputeIfDebugModeWanted() ||
+    this->Makefile->GetCMakeInstance()->GetDebugFindPkgOutput(var);
+}
+
 bool cmFindPackageCommand::FindPackageUsingModuleMode()
 {
   bool foundModule = false;

Source/cmFindPackageCommand.h

@@ -40,6 +40,7 @@ class cmSearchPath;
 class cmFindPackageCommand : public cmFindCommon
 {
 public:
+  using cmFindCommon::ComputeIfDebugModeWanted;
   /*! A sorting order strategy to be applied to recovered package folders (see
    * FIND_PACKAGE_SORT_ORDER)*/
   enum /*class*/ SortOrderType
@@ -120,6 +121,7 @@ private:
   bool ReadListFile(const std::string& f, PolicyScopeRule psr);
   void StoreVersionFound();
 
+  bool ComputeIfDebugModeWanted(std::string const& var);
   void ComputePrefixes();
   void FillPrefixesPackageRoot();
   void FillPrefixesCMakeEnvironment();

Source/cmFindPathCommand.cxx

@@ -29,13 +29,14 @@ cmFindPathCommand::cmFindPathCommand(cmExecutionStatus& status)
 // cmFindPathCommand
 bool cmFindPathCommand::InitialPass(std::vector<std::string> const& argsIn)
 {
-  this->DebugMode = this->ComputeIfDebugModeWanted();
   this->CMakePathName = "INCLUDE";
 
   if (!this->ParseArguments(argsIn)) {
     return false;
   }
 
+  this->DebugMode = this->ComputeIfDebugModeWanted(this->VariableName);
+
   if (this->AlreadyDefined) {
     this->NormalizeFindResult();
     return true;

Source/cmFindProgramCommand.cxx

@@ -177,13 +177,14 @@ cmFindProgramCommand::cmFindProgramCommand(cmExecutionStatus& status)
 // cmFindProgramCommand
 bool cmFindProgramCommand::InitialPass(std::vector<std::string> const& argsIn)
 {
-  this->DebugMode = this->ComputeIfDebugModeWanted();
+
   this->CMakePathName = "PROGRAM";
 
   // call cmFindBase::ParseArguments
   if (!this->ParseArguments(argsIn)) {
     return false;
   }
+  this->DebugMode = this->ComputeIfDebugModeWanted(this->VariableName);
 
   if (this->AlreadyDefined) {
     this->NormalizeFindResult();

Source/cmake.cxx

@@ -968,7 +968,34 @@ void cmake::SetArgs(const std::vector<std::string>& args)
       "--debug-find", CommandArgument::Values::Zero,
       [](std::string const&, cmake* state) -> bool {
         std::cout << "Running with debug output on for the `find` commands.\n";
-        state->SetDebugFindOutputOn(true);
+        state->SetDebugFindOutput(true);
+        return true;
+      } },
+    CommandArgument{
+      "--debug-find-pkg", "Provide a package argument for --debug-find-pkg",
+      CommandArgument::Values::One, CommandArgument::RequiresSeparator::Yes,
+      [](std::string const& value, cmake* state) -> bool {
+        std::vector<std::string> find_pkgs(cmTokenize(value, ","));
+        std::cout << "Running with debug output on for the 'find' commands "
+                     "for package(s)";
+        for (auto const& v : find_pkgs) {
+          std::cout << " " << v;
+          state->SetDebugFindOutputPkgs(v);
+        }
+        std::cout << ".\n";
+        return true;
+      } },
+    CommandArgument{
+      "--debug-find-var", CommandArgument::Values::One,
+      CommandArgument::RequiresSeparator::Yes,
+      [](std::string const& value, cmake* state) -> bool {
+        std::vector<std::string> find_vars(cmTokenize(value, ","));
+        std::cout << "Running with debug output on for the variable(s)";
+        for (auto const& v : find_vars) {
+          std::cout << " " << v;
+          state->SetDebugFindOutputVars(v);
+        }
+        std::cout << ".\n";
         return true;
       } },
     CommandArgument{ "--trace-expand", CommandArgument::Values::Zero,
@@ -1325,7 +1352,7 @@ void cmake::SetArgs(const std::vector<std::string>& args)
       this->DebugTryCompileOn();
     }
     if (expandedPreset->DebugFind == true) {
-      this->SetDebugFindOutputOn(true);
+      this->SetDebugFindOutput(true);
     }
   }
 #endif
@@ -3619,6 +3646,26 @@ void cmake::SetDeprecatedWarningsAsErrors(bool b)
                       cmStateEnums::INTERNAL);
 }
 
+void cmake::SetDebugFindOutputPkgs(std::string const& args)
+{
+  this->DebugFindPkgs.emplace(args);
+}
+
+void cmake::SetDebugFindOutputVars(std::string const& args)
+{
+  this->DebugFindVars.emplace(args);
+}
+
+bool cmake::GetDebugFindOutput(std::string const& var) const
+{
+  return this->DebugFindVars.count(var);
+}
+
+bool cmake::GetDebugFindPkgOutput(std::string const& pkg) const
+{
+  return this->DebugFindPkgs.count(pkg);
+}
+
 #if !defined(CMAKE_BOOTSTRAP)
 cmMakefileProfilingData& cmake::GetProfilingOutput()
 {

Source/cmake.h

@@ -486,7 +486,11 @@ public:
 
   //! Do we want debug output from the find commands during the cmake run.
   bool GetDebugFindOutput() const { return this->DebugFindOutput; }
-  void SetDebugFindOutputOn(bool b) { this->DebugFindOutput = b; }
+  bool GetDebugFindOutput(std::string const& var) const;
+  bool GetDebugFindPkgOutput(std::string const& var) const;
+  void SetDebugFindOutput(bool b) { this->DebugFindOutput = b; }
+  void SetDebugFindOutputPkgs(std::string const& args);
+  void SetDebugFindOutputVars(std::string const& args);
 
   //! Do we want trace output during the cmake run.
   bool GetTrace() const { return this->Trace; }
@@ -704,6 +708,9 @@ private:
 
   std::vector<std::string> TraceOnlyThisSources;
 
+  std::set<std::string> DebugFindPkgs;
+  std::set<std::string> DebugFindVars;
+
   LogLevel MessageLogLevel = LogLevel::LOG_STATUS;
   bool LogLevelWasSetViaCLI = false;
   bool LogContext = false;

Source/cmakemain.cxx

@@ -90,6 +90,10 @@ const char* cmDocumentationOptions[][2] = {
     "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." },
+  { "--debug-find-pkg=<pkg-name>[,...]",
+    "Limit cmake debug-find to the comma-separated list of packages" },
+  { "--debug-find-var=<var-name>[,...]",
+    "Limit cmake debug-find to the comma-separated list of result variables" },
   { "--trace", "Put cmake in trace mode." },
   { "--trace-expand", "Put cmake in trace mode with variable expansion." },
   { "--trace-format=<human|json-v1>", "Set the output format of the trace." },

Tests/RunCMake/find_file/FromPATHEnvDebugVar-stderr.txt

@@ -0,0 +1,25 @@
+  find_file called with the following settings:.*
+    VAR: PrefixInPATH_File
+    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_file considered the following locations:.*
+  The item was not found.*
+  find_file called with the following settings:.*
+    VAR: PrefixInPATH_File
+    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_file considered the following locations:.*

Tests/RunCMake/find_file/FromPATHEnvDebugVar-stdout-cygwin.txt

@@ -0,0 +1,9 @@
+-- PrefixInPATH_File='PrefixInPATH_File-NOTFOUND'
+-- PrefixInPATH_File='.*/Tests/RunCMake/find_file/include/PrefixInPATH.h'
+-- PrefixInPATH_File='.*/Tests/RunCMake/find_file/include/PrefixInPATH.h'
+-- PrefixInPATH_File='PrefixInPATH_File-NOTFOUND'
+-- PrefixInPATH_File='PrefixInPATH_File-NOTFOUND'
+-- PrefixInPATH_File='PrefixInPATH_File-NOTFOUND'
+-- PrefixInPATH_File='PrefixInPATH_File-NOTFOUND'
+-- PrefixInPATH_File='PrefixInPATH_File-NOTFOUND'
+-- PrefixInPATH_File='PrefixInPATH_File-NOTFOUND'

Tests/RunCMake/find_file/FromPATHEnvDebugVar-stdout-msys.txt

@@ -0,0 +1,9 @@
+-- PrefixInPATH_File='PrefixInPATH_File-NOTFOUND'
+-- PrefixInPATH_File='.*/Tests/RunCMake/find_file/include/PrefixInPATH.h'
+-- PrefixInPATH_File='.*/Tests/RunCMake/find_file/include/PrefixInPATH.h'
+-- PrefixInPATH_File='PrefixInPATH_File-NOTFOUND'
+-- PrefixInPATH_File='PrefixInPATH_File-NOTFOUND'
+-- PrefixInPATH_File='PrefixInPATH_File-NOTFOUND'
+-- PrefixInPATH_File='PrefixInPATH_File-NOTFOUND'
+-- PrefixInPATH_File='PrefixInPATH_File-NOTFOUND'
+-- PrefixInPATH_File='PrefixInPATH_File-NOTFOUND'

Tests/RunCMake/find_file/FromPATHEnvDebugVar-stdout-windows.txt

@@ -0,0 +1,9 @@
+-- PrefixInPATH_File='PrefixInPATH_File-NOTFOUND'
+-- PrefixInPATH_File='.*/Tests/RunCMake/find_file/include/PrefixInPATH.h'
+-- PrefixInPATH_File='.*/Tests/RunCMake/find_file/include/PrefixInPATH.h'
+-- PrefixInPATH_File='PrefixInPATH_File-NOTFOUND'
+-- PrefixInPATH_File='PrefixInPATH_File-NOTFOUND'
+-- PrefixInPATH_File='PrefixInPATH_File-NOTFOUND'
+-- PrefixInPATH_File='PrefixInPATH_File-NOTFOUND'
+-- PrefixInPATH_File='PrefixInPATH_File-NOTFOUND'
+-- PrefixInPATH_File='PrefixInPATH_File-NOTFOUND'

Tests/RunCMake/find_file/FromPATHEnvDebugVar-stdout.txt

@@ -0,0 +1,9 @@
+-- PrefixInPATH_File='PrefixInPATH_File-NOTFOUND'
+-- PrefixInPATH_File='.*/Tests/RunCMake/find_file/include/PrefixInPATH.h'
+-- PrefixInPATH_File='PrefixInPATH_File-NOTFOUND'
+-- PrefixInPATH_File='PrefixInPATH_File-NOTFOUND'
+-- PrefixInPATH_File='PrefixInPATH_File-NOTFOUND'
+-- PrefixInPATH_File='PrefixInPATH_File-NOTFOUND'
+-- PrefixInPATH_File='PrefixInPATH_File-NOTFOUND'
+-- PrefixInPATH_File='PrefixInPATH_File-NOTFOUND'
+-- PrefixInPATH_File='PrefixInPATH_File-NOTFOUND'

Tests/RunCMake/find_file/FromPATHEnvDebugVar.cmake

@@ -0,0 +1,24 @@
+set(ENV_PATH "$ENV{PATH}")
+foreach(path "/does_not_exist" "/include" "")
+  unset(PrefixInPATH_File CACHE)
+  set(ENV{PATH} "${CMAKE_CURRENT_SOURCE_DIR}${path}")
+  find_file(PrefixInPATH_File NAMES PrefixInPATH.h)
+  message(STATUS "PrefixInPATH_File='${PrefixInPATH_File}'")
+endforeach()
+
+set(CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH OFF)
+foreach(path "/does_not_exist" "/include" "")
+  unset(PrefixInPATH_File CACHE)
+  set(ENV{PATH} "${CMAKE_CURRENT_SOURCE_DIR}${path}")
+  find_file(PrefixInPATH_File NAMES PrefixInPATH.h)
+  message(STATUS "PrefixInPATH_File='${PrefixInPATH_File}'")
+endforeach()
+
+set(CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH ON)
+foreach(path "/does_not_exist" "/include" "")
+  unset(PrefixInPATH_File CACHE)
+  set(ENV{PATH} "${CMAKE_CURRENT_SOURCE_DIR}${path}")
+  find_file(PrefixInPATH_File NAMES PrefixInPATH.h NO_SYSTEM_ENVIRONMENT_PATH)
+  message(STATUS "PrefixInPATH_File='${PrefixInPATH_File}'")
+endforeach()
+set(ENV{PATH} "${ENV_PATH}")

Tests/RunCMake/find_file/RunCMakeTest.cmake

@@ -5,3 +5,5 @@ run_cmake(FromPrefixPath)
 run_cmake(PrefixInPATH)
 run_cmake(Required)
 run_cmake(NO_CACHE)
+
+run_cmake_with_options(FromPATHEnvDebugVar --debug-find-var=PrefixInPATH_File)

Tests/RunCMake/find_library/FromPATHEnvDebugVar-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

Tests/RunCMake/find_library/FromPATHEnvDebugVar-stdout-cygwin.txt

@@ -0,0 +1,6 @@
+-- CREATED_LIBRARY='CREATED_LIBRARY-NOTFOUND'
+-- CREATED_LIBRARY='[^']*/Tests/RunCMake/find_library/FromPATHEnvDebugVar-build/lib/libcreated.a'
+-- CREATED_LIBRARY='[^']*/Tests/RunCMake/find_library/FromPATHEnvDebugVar-build/lib/libcreated.a'
+-- CREATED_LIBRARY='CREATED_LIBRARY-NOTFOUND'
+-- CREATED_LIBRARY='CREATED_LIBRARY-NOTFOUND'
+-- CREATED_LIBRARY='CREATED_LIBRARY-NOTFOUND'

Tests/RunCMake/find_library/FromPATHEnvDebugVar-stdout-msys.txt

@@ -0,0 +1,6 @@
+-- CREATED_LIBRARY='CREATED_LIBRARY-NOTFOUND'
+-- CREATED_LIBRARY='[^']*/Tests/RunCMake/find_library/FromPATHEnvDebugVar-build/lib/libcreated.a'
+-- CREATED_LIBRARY='[^']*/Tests/RunCMake/find_library/FromPATHEnvDebugVar-build/lib/libcreated.a'
+-- CREATED_LIBRARY='CREATED_LIBRARY-NOTFOUND'
+-- CREATED_LIBRARY='CREATED_LIBRARY-NOTFOUND'
+-- CREATED_LIBRARY='CREATED_LIBRARY-NOTFOUND'

Tests/RunCMake/find_library/FromPATHEnvDebugVar-stdout-windows.txt

@@ -0,0 +1,6 @@
+-- CREATED_LIBRARY='CREATED_LIBRARY-NOTFOUND'
+-- CREATED_LIBRARY='[^']*/Tests/RunCMake/find_library/FromPATHEnvDebugVar-build/lib/libcreated.a'
+-- CREATED_LIBRARY='[^']*/Tests/RunCMake/find_library/FromPATHEnvDebugVar-build/lib/libcreated.a'
+-- CREATED_LIBRARY='CREATED_LIBRARY-NOTFOUND'
+-- CREATED_LIBRARY='CREATED_LIBRARY-NOTFOUND'
+-- CREATED_LIBRARY='CREATED_LIBRARY-NOTFOUND'

Tests/RunCMake/find_library/FromPATHEnvDebugVar-stdout.txt

@@ -0,0 +1,6 @@
+-- CREATED_LIBRARY='CREATED_LIBRARY-NOTFOUND'
+-- CREATED_LIBRARY='[^']*/Tests/RunCMake/find_library/FromPATHEnvDebugVar-build/lib/libcreated.a'
+-- CREATED_LIBRARY='CREATED_LIBRARY-NOTFOUND'
+-- CREATED_LIBRARY='CREATED_LIBRARY-NOTFOUND'
+-- CREATED_LIBRARY='CREATED_LIBRARY-NOTFOUND'
+-- CREATED_LIBRARY='CREATED_LIBRARY-NOTFOUND'

Tests/RunCMake/find_library/FromPATHEnvDebugVar.cmake

@@ -0,0 +1,35 @@
+list(APPEND CMAKE_FIND_LIBRARY_PREFIXES lib)
+list(APPEND CMAKE_FIND_LIBRARY_SUFFIXES .a)
+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}")
+  find_library(CREATED_LIBRARY NAMES created)
+  message(STATUS "CREATED_LIBRARY='${CREATED_LIBRARY}'")
+endforeach()
+
+set(CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH OFF)
+foreach(path "/does_not_exist" "/lib" "")
+  unset(CREATED_LIBRARY CACHE)
+  set(ENV{PATH} "${CMAKE_CURRENT_BINARY_DIR}${path}")
+  find_library(CREATED_LIBRARY NAMES created)
+  message(STATUS "CREATED_LIBRARY='${CREATED_LIBRARY}'")
+endforeach()
+set(CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH ON)
+set(ENV{PATH} "${ENV_PATH}")

Tests/RunCMake/find_library/RunCMakeTest.cmake

@@ -12,3 +12,5 @@ run_cmake(Required)
 run_cmake(NO_CACHE)
 
 run_cmake_script(FromScriptMode "-DTEMP_DIR=${RunCMake_BINARY_DIR}/FromScriptMode-temp")
+
+run_cmake_with_options(FromPATHEnvDebugVar --debug-find-var=CREATED_LIBRARY)

Tests/RunCMake/find_package/FromPATHEnvDebugPkg-stderr.txt

@@ -0,0 +1,21 @@
+CMake Debug Log at FromPATHEnvDebugPkg.cmake:4 \(find_package\):
+  find_package considered the following paths for Resolved.cmake.*
+.*/Modules/FindResolved.cmake.*
+  The file was not found.*
+  <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.*
+  CMAKE_FRAMEWORK_PATH and CMAKE_APPBUNDLE_PATH env variables.*
+  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.*
+  find_package considered the following locations for the Config module:.*
+.*Tests/RunCMake/find_package/PackageRoot/ResolvedConfig\.cmake.*
+  The file was found at.*
+.*Tests/RunCMake/find_package/PackageRoot/ResolvedConfig\.cmake

Tests/RunCMake/find_package/FromPATHEnvDebugPkg-stdout.txt

@@ -0,0 +1,9 @@
+-- Resolved_FOUND='0'
+-- Resolved_FOUND='0'
+-- Resolved_FOUND='0'
+-- Resolved_FOUND='0'
+-- Resolved_FOUND='0'
+-- Resolved_FOUND='0'
+-- Resolved_FOUND='0'
+-- Resolved_FOUND='0'
+-- Resolved_FOUND='0'

Tests/RunCMake/find_package/FromPATHEnvDebugPkg.cmake

@@ -0,0 +1,31 @@
+set(ENV_PATH "$ENV{PATH}")
+
+set(ENV{PATH} "${CMAKE_CURRENT_SOURCE_DIR}/PackageRoot")
+find_package(Resolved QUIET)
+
+foreach(path "/does_not_exist" "/PackageRoot" "")
+  unset(ResolvedA_FOUND CACHE)
+  set(ResolvedA_DIR "")
+  set(ENV{PATH} "${CMAKE_CURRENT_SOURCE_DIR}${path}")
+  find_package(ResolvedA QUIET)
+  message(STATUS "Resolved_FOUND='${ResolvedA_FOUND}'")
+endforeach()
+
+set(CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH OFF)
+foreach(path "/does_not_exist" "/PackageRoot" "")
+  unset(Resolved_FOUND CACHE)
+  set(Resolved_DIR "")
+  set(ENV{PATH} "${CMAKE_CURRENT_SOURCE_DIR}${path}")
+  find_package(ResolvedB QUIET)
+  message(STATUS "Resolved_FOUND='${ResolvedB_FOUND}'")
+endforeach()
+
+set(CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH ON)
+foreach(path "/does_not_exist" "/PackageRoot" "")
+  unset(Resolved_FOUND CACHE)
+  set(Resolved_DIR "")
+  set(ENV{PATH} "${CMAKE_CURRENT_SOURCE_DIR}${path}")
+  find_package(ResolvedC NO_SYSTEM_ENVIRONMENT_PATH QUIET)
+  message(STATUS "Resolved_FOUND='${ResolvedC_FOUND}'")
+endforeach()
+set(ENV{PATH} "${ENV_PATH}")

Tests/RunCMake/find_package/MissingConfigDebugPkg-stderr.txt

@@ -0,0 +1,20 @@
+  <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.*
+  CMAKE_FRAMEWORK_PATH and CMAKE_APPBUNDLE_PATH env variables.*
+  Paths specified by the find_package HINTS option.*
+  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.*
+.*
+    .*NotHereConfig.cmake
+    .*nothere-config.cmake
+.*
+CMake Warning at MissingConfigDebugPkg.cmake:2 \(message\):
+  This warning must be reachable.
+Call Stack \(most recent call first\):
+  CMakeLists.txt:3 \(include\)$

Tests/RunCMake/find_package/MissingConfigDebugPkg.cmake

@@ -0,0 +1,2 @@
+find_package(NotHere CONFIG)
+message(WARNING "This warning must be reachable.")

Tests/RunCMake/find_package/RunCMakeTest.cmake

@@ -49,3 +49,6 @@ if(UNIX
     )
   run_cmake(SetFoundResolved)
 endif()
+
+run_cmake_with_options(MissingConfigDebugPkg --debug-find-pkg=NotHere)
+run_cmake_with_options(FromPATHEnvDebugPkg --debug-find-pkg=Resolved)

Tests/RunCMake/find_path/FromPATHEnvDebugVar-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.*

Tests/RunCMake/find_path/FromPATHEnvDebugVar-stdout-cygwin.txt

@@ -0,0 +1,9 @@
+-- PATH_IN_ENV_PATH='PATH_IN_ENV_PATH_A-NOTFOUND'
+-- PATH_IN_ENV_PATH='.*/Tests/RunCMake/find_path/include'
+-- PATH_IN_ENV_PATH='.*/Tests/RunCMake/find_path/include'
+-- PATH_IN_ENV_PATH='PATH_IN_ENV_PATH_A-NOTFOUND'
+-- PATH_IN_ENV_PATH='PATH_IN_ENV_PATH_A-NOTFOUND'
+-- PATH_IN_ENV_PATH='PATH_IN_ENV_PATH_A-NOTFOUND'
+-- PATH_IN_ENV_PATH=''
+-- PATH_IN_ENV_PATH=''
+-- PATH_IN_ENV_PATH=''

Tests/RunCMake/find_path/FromPATHEnvDebugVar-stdout-msys.txt

@@ -0,0 +1,9 @@
+-- PATH_IN_ENV_PATH='PATH_IN_ENV_PATH_A-NOTFOUND'
+-- PATH_IN_ENV_PATH='.*/Tests/RunCMake/find_path/include'
+-- PATH_IN_ENV_PATH='.*/Tests/RunCMake/find_path/include'
+-- PATH_IN_ENV_PATH='PATH_IN_ENV_PATH_A-NOTFOUND'
+-- PATH_IN_ENV_PATH='PATH_IN_ENV_PATH_A-NOTFOUND'
+-- PATH_IN_ENV_PATH='PATH_IN_ENV_PATH_A-NOTFOUND'
+-- PATH_IN_ENV_PATH=''
+-- PATH_IN_ENV_PATH=''
+-- PATH_IN_ENV_PATH=''

Tests/RunCMake/find_path/FromPATHEnvDebugVar-stdout-windows.txt

@@ -0,0 +1,9 @@
+-- PATH_IN_ENV_PATH='PATH_IN_ENV_PATH_A-NOTFOUND'
+-- PATH_IN_ENV_PATH='.*/Tests/RunCMake/find_path/include'
+-- PATH_IN_ENV_PATH='.*/Tests/RunCMake/find_path/include'
+-- PATH_IN_ENV_PATH='PATH_IN_ENV_PATH_A-NOTFOUND'
+-- PATH_IN_ENV_PATH='PATH_IN_ENV_PATH_A-NOTFOUND'
+-- PATH_IN_ENV_PATH='PATH_IN_ENV_PATH_A-NOTFOUND'
+-- PATH_IN_ENV_PATH=''
+-- PATH_IN_ENV_PATH=''
+-- PATH_IN_ENV_PATH=''

Tests/RunCMake/find_path/FromPATHEnvDebugVar-stdout.txt

@@ -0,0 +1,9 @@
+-- PATH_IN_ENV_PATH='PATH_IN_ENV_PATH_A-NOTFOUND'
+-- PATH_IN_ENV_PATH='.*/Tests/RunCMake/find_path/include'
+-- PATH_IN_ENV_PATH='PATH_IN_ENV_PATH_A-NOTFOUND'
+-- PATH_IN_ENV_PATH='PATH_IN_ENV_PATH_A-NOTFOUND'
+-- PATH_IN_ENV_PATH='PATH_IN_ENV_PATH_A-NOTFOUND'
+-- PATH_IN_ENV_PATH='PATH_IN_ENV_PATH_A-NOTFOUND'
+-- PATH_IN_ENV_PATH=''
+-- PATH_IN_ENV_PATH=''
+-- PATH_IN_ENV_PATH=''

Tests/RunCMake/find_path/FromPATHEnvDebugVar.cmake

@@ -0,0 +1,35 @@
+set(ENV_PATH "$ENV{PATH}")
+
+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)
+
+
+foreach(path "/does_not_exist" "/include" "")
+  unset(PATH_IN_ENV_PATH_A CACHE)
+  set(ENV{PATH} "${CMAKE_CURRENT_SOURCE_DIR}${path}")
+  find_path(PATH_IN_ENV_PATH_A NAMES PrefixInPATH.h)
+  message(STATUS "PATH_IN_ENV_PATH='${PATH_IN_ENV_PATH_A}'")
+endforeach()
+
+set(CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH OFF)
+foreach(path "/does_not_exist" "/include" "")
+  unset(PATH_IN_ENV_PATH_A CACHE)
+  set(ENV{PATH} "${CMAKE_CURRENT_SOURCE_DIR}${path}")
+  find_path(PATH_IN_ENV_PATH_A NAMES PrefixInPATH.h)
+  message(STATUS "PATH_IN_ENV_PATH='${PATH_IN_ENV_PATH_A}'")
+endforeach()
+
+set(CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH ON)
+foreach(path "/does_not_exist" "/include" "")
+  unset(PATH_IN_ENV_PATH_A CACHE)
+  set(ENV{PATH} "${CMAKE_CURRENT_SOURCE_DIR}${path}")
+  find_path(PATH_IN_ENV_PAT_H_A NAMES PrefixInPATH.h NO_SYSTEM_ENVIRONMENT_PATH)
+  message(STATUS "PATH_IN_ENV_PATH='${PATH_IN_ENV_PATH_A}'")
+endforeach()
+
+set(ENV{PATH} "${ENV_PATH}")

Tests/RunCMake/find_path/RunCMakeTest.cmake

@@ -9,3 +9,5 @@ run_cmake(NO_CACHE)
 if(APPLE)
   run_cmake(FrameworksWithSubdirs)
 endif()
+
+run_cmake_with_options(FromPATHEnvDebugVar --debug-find-var=PATH_IN_ENV_PATH)

Tests/RunCMake/find_program/EnvAndHintsDebugVar-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.*

Tests/RunCMake/find_program/EnvAndHintsDebugVar-stdout.txt

@@ -0,0 +1,4 @@
+-- PROG='[^']*/Tests/RunCMake/find_program/A/testAandB'
+-- PROG='PROG-NOTFOUND'
+-- PROG='[^']*/Tests/RunCMake/find_program/B/testAandB'
+-- PROG='[^']*/Tests/RunCMake/find_program/A/testAandB'

Tests/RunCMake/find_program/EnvAndHintsDebugVar.cmake

@@ -0,0 +1,31 @@
+
+set(ENV_PATH "$ENV{PATH}")
+set(ENV{PATH} ${CMAKE_CURRENT_SOURCE_DIR}/A)
+find_program(PROG
+  NAMES testAandB
+  )
+message(STATUS "PROG='${PROG}'")
+unset(PROG CACHE)
+
+set(CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH OFF)
+find_program(PROG
+  NAMES testAandB
+  )
+message(STATUS "PROG='${PROG}'")
+unset(PROG CACHE)
+
+find_program(PROG_A
+  NAMES testAandB
+  HINTS ${CMAKE_CURRENT_SOURCE_DIR}/B ${CMAKE_CURRENT_SOURCE_DIR}/A
+  )
+message(STATUS "PROG='${PROG_A}'")
+unset(PROG_A CACHE)
+set(ENV{PATH} "${ENV_PATH}")
+
+find_program(PROG_A
+  NAMES testAandB
+  HINTS ${CMAKE_CURRENT_SOURCE_DIR}/A ${CMAKE_CURRENT_SOURCE_DIR}/B
+  )
+message(STATUS "PROG='${PROG_A}'")
+unset(PROG_A CACHE)
+set(ENV{PATH} "${ENV_PATH}")

Tests/RunCMake/find_program/RunCMakeTest.cmake

@@ -27,3 +27,5 @@ endif()
 if(APPLE)
   run_cmake(BundleSpaceInName)
 endif()
+
+run_cmake_with_options(EnvAndHintsDebugVar --debug-find-var=PROG)