Merge topic 'add_cmake_find_use_package_registry'

447a96f590 vim: Update cmake.vim to include the CMAKE_FIND_USE variables
1d00ba9ccf Find: find_package prefers variable CMAKE_FIND_USE_REGISTRY
704e3a2ca8 Find: Correct spelling and layout issues in CMAKE_FIND_USE_ docs

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !3487

8 files changed, 108 insertions, 33 deletions

diff --git a/Help/variable/CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY.rst b/Help/variable/CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY.rst
index 9058471..ffb8a2c 100644
--- a/Help/variable/CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY.rst
+++ b/Help/variable/CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY.rst
@@ -1,12 +1,23 @@
 CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY
 --------------------------------------
 
-Skip :ref:`User Package Registry` in :command:`find_package` calls.
+.. deprecated:: 3.16
+
+  Use the :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` variable instead.
+
+By default this variable is not set. If neither
+:variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` nor
+``CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY`` is set, then
+:command:`find_package()` will use the `User Package Registry` unless the
+`NO_CMAKE_PACKAGE_REGISTRY` option is provided.
+
+``CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY`` is ignored if
+:variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` is set.
 
 In some cases, for example to locate only system wide installations, it
 is not desirable to use the :ref:`User Package Registry` when searching
 for packages. If the :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY`
-variable is enabled, all the :command:`find_package` commands will skip
+variable is ``TRUE``, all the :command:`find_package` commands will skip
 the :ref:`User Package Registry` as if they were called with the
 ``NO_CMAKE_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 3db510f..33514a0 100644
--- a/Help/variable/CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH.rst
+++ b/Help/variable/CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH.rst
@@ -1,11 +1,18 @@
 CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH
 -------------------------------------
 
-Controls the searching the cmake-specific environment variables by the :command:`find_program`,
-:command:`find_library`, :command:`find_file`, :command:`find_package`, and :command:`find_path`.
+Controls the searching the cmake-specific environment variables by the
+:command:`find_program`, :command:`find_library`, :command:`find_file`,
+and :command:`find_path` commands.
 This is useful in cross-compiling environments.
 
-By default this this is set to ``TRUE``.
+By default this variable is not set, which is equivalent to it having
+a value of ``TRUE``.  Explicit options given to the :command:`find_program`,
+:command:`find_library`, :command:`find_file`, and :command:`find_path`
+commands 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`, and :variable:`CMAKE_FIND_USE_PACAKGE_ROOT_PATH` variables.
+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_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 86a6186..cefc645 100644
--- a/Help/variable/CMAKE_FIND_USE_CMAKE_PATH.rst
+++ b/Help/variable/CMAKE_FIND_USE_CMAKE_PATH.rst
@@ -1,11 +1,18 @@
 CMAKE_FIND_USE_CMAKE_PATH
 -------------------------
 
-Controls the searching the cmake-specific cache variables by the :command:`find_program`,
-:command:`find_library`, :command:`find_file`, :command:`find_package`, and :command:`find_path`.
+Controls the searching the cmake-specific cache variables by the
+:command:`find_program`, :command:`find_library`, :command:`find_file`,
+and :command:`find_path` commands.
 This is useful in cross-compiling environments.
 
-By default this this is set to ``TRUE``.
+By default this variable is not set, which is equivalent to it having
+a value of ``TRUE``.  Explicit options given to the :command:`find_program`,
+:command:`find_library`, :command:`find_file`, and :command:`find_path`
+commands 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`, and :variable:`CMAKE_FIND_USE_PACAKGE_ROOT_PATH` variables.
+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_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 b4171c0..2aa544d 100644
--- a/Help/variable/CMAKE_FIND_USE_CMAKE_SYSTEM_PATH.rst
+++ b/Help/variable/CMAKE_FIND_USE_CMAKE_SYSTEM_PATH.rst
@@ -1,11 +1,18 @@
 CMAKE_FIND_USE_CMAKE_SYSTEM_PATH
 --------------------------------
 
-Controls the searching cmake platform specific variables by the :command:`find_program`,
-:command:`find_library`, :command:`find_file`, :command:`find_package`, and :command:`find_path`.
+Controls the searching cmake platform specific variables by the
+:command:`find_program`, :command:`find_library`, :command:`find_file`,
+and :command:`find_path` commands.
 This is useful in cross-compiling environments.
 
-By default this this is set to ``TRUE``.
+By default this variable is not set, which is equivalent to it having
+a value of ``TRUE``.  Explicit options given to the :command:`find_program`,
+:command:`find_library`, :command:`find_file`, and :command:`find_path`
+commands 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`, and :variable:`CMAKE_FIND_USE_PACAKGE_ROOT_PATH` variables.
+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_PACKAGE_REGISTRY`,
+and :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` variables.
diff --git a/Help/variable/CMAKE_FIND_USE_PACAKGE_ROOT_PATH.rst b/Help/variable/CMAKE_FIND_USE_PACAKGE_ROOT_PATH.rst
deleted file mode 100644
index ac25ec9..0000000
--- a/Help/variable/CMAKE_FIND_USE_PACAKGE_ROOT_PATH.rst
+++ /dev/null
@@ -1,11 +0,0 @@
-CMAKE_FIND_USE_PACAKGE_ROOT_PATH
---------------------------------
-
-Controls the searching of :variable:`<PackageName>_ROOT` variables by the :command:`find_program`,
-:command:`find_library`, :command:`find_file`, :command:`find_package`, and :command:`find_path`.
-This is useful in cross-compiling environments.
-
-By default this this is set to ``TRUE``.
-
-See also the :variable:`CMAKE_FIND_USE_CMAKE_PATH`, :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`,
-:variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`, and :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH` variables.
diff --git a/Help/variable/CMAKE_FIND_USE_PACKAGE_REGISTRY.rst b/Help/variable/CMAKE_FIND_USE_PACKAGE_REGISTRY.rst
new file mode 100644
index 0000000..75e910f
--- /dev/null
+++ b/Help/variable/CMAKE_FIND_USE_PACKAGE_REGISTRY.rst
@@ -0,0 +1,29 @@
+CMAKE_FIND_USE_PACKAGE_REGISTRY
+-------------------------------
+
+Controls the searching the :ref:`User 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_PACKAGE_REGISTRY`
+variable.  If that is also not set, then `find_package()` will use the
+`User Package Registry` unless the `NO_CMAKE_PACKAGE_REGISTRY` option
+is provided.
+
+This variable takes precedence over :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY`
+when both are set.
+
+In some cases, for example to locate only system wide installations, it
+is not desirable to use the :ref:`User Package Registry` when searching
+for packages. If the :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY`
+variable is ``FALSE``, all the :command:`find_package` commands will skip
+the :ref:`User Package Registry` as if they were called with the
+``NO_CMAKE_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`,
+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
new file mode 100644
index 0000000..899e62e
--- /dev/null
+++ b/Help/variable/CMAKE_FIND_USE_PACKAGE_ROOT_PATH.rst
@@ -0,0 +1,18 @@
+CMAKE_FIND_USE_PACKAGE_ROOT_PATH
+--------------------------------
+
+Controls the searching of :variable:`<PackageName>_ROOT` variables by the
+:command:`find_program`, :command:`find_library`, :command:`find_file`,
+and :command:`find_path` commands.
+This is useful in cross-compiling environments.
+
+By default this variable is not set, which is equivalent to it having
+a value of ``TRUE``.  Explicit options given to the :command:`find_program`,
+:command:`find_library`, :command:`find_file`, and :command:`find_path`
+commands 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_CMAKE_SYSTEM_PATH`,
+:variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`,
+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 fd0582f..604c710 100644
--- a/Help/variable/CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH.rst
+++ b/Help/variable/CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH.rst
@@ -1,11 +1,18 @@
 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH
 --------------------------------------
 
-Controls the searching the standard system environment variables by the :command:`find_program`,
-:command:`find_library`, :command:`find_file`, :command:`find_package`, and :command:`find_path`.
+Controls the searching the standard system environment variables by the
+:command:`find_program`, :command:`find_library`, :command:`find_file`,
+and :command:`find_path` commands.
 This is useful in cross-compiling environments.
 
-By default this this is set to ``TRUE``.
+By default this variable is not set, which is equivalent to it having
+a value of ``TRUE``.  Explicit options given to the :command:`find_program`,
+:command:`find_library`, :command:`find_file`, and :command:`find_path`
+commands 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_CMAKE_SYSTEM_PATH`, and :variable:`CMAKE_FIND_USE_PACAKGE_ROOT_PATH` variables.
+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.