find_package: Add support for CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY

Extend the change from commit 1d00ba9ccf (Find: find_package prefers
variable CMAKE_FIND_USE_REGISTRY, 2018-11-13, v3.16.0-rc1~461^2~1)
to cover the system package registry too.

Fixes: #19890

12 files changed, 65 insertions, 6 deletions

diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst
index 546b00ff8e..64a16f3211 100644
--- a/Help/command/find_package.rst
+++ b/Help/command/find_package.rst
@@ -353,8 +353,10 @@ enabled.
 
 8. Search paths stored in the CMake :ref:`System Package Registry`.
    This can be skipped if ``NO_CMAKE_SYSTEM_PACKAGE_REGISTRY`` is passed
-   or by setting the
+   or by setting the :variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY`
+   variable to ``FALSE`` or the deprecated variable
    :variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY` to ``TRUE``.
+
    See the :manual:`cmake-packages(7)` manual for details on the system
    package registry.
 
diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst
index 0442d8930d..360140c41a 100644
--- a/Help/manual/cmake-variables.7.rst
+++ b/Help/manual/cmake-variables.7.rst
@@ -191,6 +191,7 @@ Variables that Change Behavior
    /variable/CMAKE_FIND_USE_PACKAGE_REGISTRY
    /variable/CMAKE_FIND_USE_PACKAGE_ROOT_PATH
    /variable/CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH
+   /variable/CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY
    /variable/CMAKE_FRAMEWORK_PATH
    /variable/CMAKE_IGNORE_PATH
    /variable/CMAKE_INCLUDE_DIRECTORIES_BEFORE
diff --git a/Help/release/3.16.rst b/Help/release/3.16.rst
index 570f536cdc..3f198ca025 100644
--- a/Help/release/3.16.rst
+++ b/Help/release/3.16.rst
@@ -95,7 +95,9 @@ Commands
 
 * The :command:`find_package` command has learned to check the
   :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` variable to control the default
-  behavior of searching the CMake user package registry.
+  behavior of searching the CMake user package registry and to check the
+  :variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY` variable to control
+  the default behavior of searching the CMake system package registry.
 
 * The :command:`message` command learned indentation control with the new
   :variable:`CMAKE_MESSAGE_INDENT` variable.
diff --git a/Help/variable/CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY.rst b/Help/variable/CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY.rst
index 44588b17ab..107c183eb8 100644
--- a/Help/variable/CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY.rst
+++ b/Help/variable/CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY.rst
@@ -1,12 +1,23 @@
 CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY
 ---------------------------------------------
 
-Skip :ref:`System Package Registry` in :command:`find_package` calls.
+.. deprecated:: 3.16
+
+  Use the :variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY` variable instead.
+
+By default this variable is not set. If neither
+:variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY` nor
+``CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY`` is set, then
+:command:`find_package()` will use the :ref:`System Package Registry`
+unless the ``NO_CMAKE_SYSTEM_PACKAGE_REGISTRY`` option is provided.
+
+``CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY`` is ignored if
+:variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY` is set.
 
 In some cases, it is not desirable to use the
 :ref:`System Package Registry` when searching for packages. If the
 :variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY` variable is
-enabled, all the :command:`find_package` commands will skip
+``TRUE``, all the :command:`find_package` commands will skip
 the :ref:`System Package Registry` as if they were called with the
 ``NO_CMAKE_SYSTEM_PACKAGE_REGISTRY`` argument.
 
diff --git a/Help/variable/CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH.rst b/Help/variable/CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH.rst
index 9ebf672e1b..957e956f35 100644
--- a/Help/variable/CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH.rst
+++ b/Help/variable/CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH.rst
@@ -19,5 +19,6 @@ take precedence over this variable.
 See also the :variable:`CMAKE_FIND_USE_CMAKE_PATH`,
 :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`,
 :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`,
+:variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY`,
 :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY`,
 and :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` variables.
diff --git a/Help/variable/CMAKE_FIND_USE_CMAKE_PATH.rst b/Help/variable/CMAKE_FIND_USE_CMAKE_PATH.rst
index 62ae3cbdbb..d2bdb09b5a 100644
--- a/Help/variable/CMAKE_FIND_USE_CMAKE_PATH.rst
+++ b/Help/variable/CMAKE_FIND_USE_CMAKE_PATH.rst
@@ -19,5 +19,6 @@ take precedence over this variable.
 See also the :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`,
 :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`,
 :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`,
+:variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY`,
 :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY`,
 and :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` variables.
diff --git a/Help/variable/CMAKE_FIND_USE_CMAKE_SYSTEM_PATH.rst b/Help/variable/CMAKE_FIND_USE_CMAKE_SYSTEM_PATH.rst
index b484a6ab4e..b99081d3ea 100644
--- a/Help/variable/CMAKE_FIND_USE_CMAKE_SYSTEM_PATH.rst
+++ b/Help/variable/CMAKE_FIND_USE_CMAKE_SYSTEM_PATH.rst
@@ -19,5 +19,6 @@ take precedence over this variable.
 See also the :variable:`CMAKE_FIND_USE_CMAKE_PATH`,
 :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`,
 :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`,
+:variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY`,
 :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY`,
 and :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` variables.
diff --git a/Help/variable/CMAKE_FIND_USE_PACKAGE_REGISTRY.rst b/Help/variable/CMAKE_FIND_USE_PACKAGE_REGISTRY.rst
index a9c8469647..7c7ca3618d 100644
--- a/Help/variable/CMAKE_FIND_USE_PACKAGE_REGISTRY.rst
+++ b/Help/variable/CMAKE_FIND_USE_PACKAGE_REGISTRY.rst
@@ -26,4 +26,5 @@ See also :ref:`Disabling the Package Registry` and the
 :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`,
 :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`,
 :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`,
+:variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY`,
 and :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` variables.
diff --git a/Help/variable/CMAKE_FIND_USE_PACKAGE_ROOT_PATH.rst b/Help/variable/CMAKE_FIND_USE_PACKAGE_ROOT_PATH.rst
index 25a25f3ba0..e7f5b0ff83 100644
--- a/Help/variable/CMAKE_FIND_USE_PACKAGE_ROOT_PATH.rst
+++ b/Help/variable/CMAKE_FIND_USE_PACKAGE_ROOT_PATH.rst
@@ -18,4 +18,5 @@ See also the :variable:`CMAKE_FIND_USE_CMAKE_PATH`,
 :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`,
 :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`,
 :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`,
+:variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY`,
 and :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` variables.
diff --git a/Help/variable/CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH.rst b/Help/variable/CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH.rst
index 0713709b7f..fbaba5a73a 100644
--- a/Help/variable/CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH.rst
+++ b/Help/variable/CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH.rst
@@ -20,4 +20,5 @@ See also the :variable:`CMAKE_FIND_USE_CMAKE_PATH`,
 :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`,
 :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`,
 :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY`,
-and :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` variables.
+:variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH`,
+and :variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY` variables.
diff --git a/Help/variable/CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY.rst b/Help/variable/CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY.rst
new file mode 100644
index 0000000000..cb4eec5d17
--- /dev/null
+++ b/Help/variable/CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY.rst
@@ -0,0 +1,31 @@
+CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY
+--------------------------------------
+
+Controls searching the :ref:`System Package Registry` by the
+:command:`find_package` command.
+
+By default this variable is not set and the behavior will fall back
+to that determined by the deprecated
+:variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY` variable.
+If that is also not set, then :command:`find_package()` will use the
+:ref:`System Package Registry` unless the ``NO_CMAKE_SYSTEM_PACKAGE_REGISTRY``
+option is provided.
+
+This variable takes precedence over
+:variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY` when both are set.
+
+In some cases, for example to locate only user specific installations, it
+is not desirable to use the :ref:`System Package Registry` when searching
+for packages. If the ``CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY``
+variable is ``FALSE``, all the :command:`find_package` commands will skip
+the :ref:`System Package Registry` as if they were called with the
+``NO_CMAKE_SYSTEM_PACKAGE_REGISTRY`` argument.
+
+See also :ref:`Disabling the Package Registry`.
+
+See also the :variable:`CMAKE_FIND_USE_CMAKE_PATH`,
+:variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`,
+:variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`,
+:variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`,
+:variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY`,
+and :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` variables.
diff --git a/Source/cmFindPackageCommand.cxx b/Source/cmFindPackageCommand.cxx
index ea936cfd95..2b11b62a21 100644
--- a/Source/cmFindPackageCommand.cxx
+++ b/Source/cmFindPackageCommand.cxx
@@ -201,7 +201,13 @@ bool cmFindPackageCommand::InitialPass(std::vector<std::string> const& args)
   }
 
   // Check if System Package Registry should be disabled
-  if (this->Makefile->IsOn("CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY")) {
+  // The `CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY` has
+  // priority over the deprecated CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY
+  if (const char* def = this->Makefile->GetDefinition(
+        "CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY")) {
+    this->NoSystemRegistry = !cmIsOn(def);
+  } else if (this->Makefile->IsOn(
+               "CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY")) {
     this->NoSystemRegistry = true;
   }