Merge topic 'NO_CMAKE_INSTALL_PREFIX'

42f7e39789 Find: Support per call disabling of CMAKE_INSTALL_PREFIX

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

11 files changed, 70 insertions, 6 deletions

diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt
index ee6c1cc..1e75dc9 100644
--- a/Help/command/FIND_XXX.txt
+++ b/Help/command/FIND_XXX.txt
@@ -23,6 +23,7 @@ The general signature is:
              [NO_CMAKE_ENVIRONMENT_PATH]
              [NO_SYSTEM_ENVIRONMENT_PATH]
              [NO_CMAKE_SYSTEM_PATH]
+             [NO_CMAKE_INSTALL_PREFIX]
              [CMAKE_FIND_ROOT_PATH_BOTH |
               ONLY_CMAKE_FIND_ROOT_PATH |
               NO_CMAKE_FIND_ROOT_PATH]
@@ -154,9 +155,11 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows:
    * |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX|
 
 6. Search cmake variables defined in the Platform files
-   for the current system.  This can be skipped if ``NO_CMAKE_SYSTEM_PATH``
-   is passed or by setting the :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`
-   to ``FALSE``.
+   for the current system.  The searching of ``CMAKE_INSTALL_PREFIX` can be
+   skipped if ``NO_CMAKE_INSTALL_PREFIX`` is passed or by setting the
+   :variable:`CMAKE_FIND_USE_INSTALL_PREFIX` to ``FALSE. All these locations
+   can be skipped if ``NO_CMAKE_SYSTEM_PATH`` is passed or by setting the
+   :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH` to ``FALSE``.
 
    * |CMAKE_SYSTEM_PREFIX_PATH_XXX|
    * |CMAKE_SYSTEM_XXX_PATH|
diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst
index 1187772..86e26e9 100644
--- a/Help/command/find_package.rst
+++ b/Help/command/find_package.rst
@@ -176,6 +176,7 @@ Full Signature
                [NO_CMAKE_PACKAGE_REGISTRY]
                [NO_CMAKE_BUILDS_PATH] # Deprecated; does nothing.
                [NO_CMAKE_SYSTEM_PATH]
+               [NO_CMAKE_INSTALL_PREFIX]
                [NO_CMAKE_SYSTEM_PACKAGE_REGISTRY]
                [CMAKE_FIND_ROOT_PATH_BOTH |
                 ONLY_CMAKE_FIND_ROOT_PATH |
@@ -346,9 +347,11 @@ enabled.
    package registry.
 
 7. Search cmake variables defined in the Platform files for the
-   current system.  This can be skipped if ``NO_CMAKE_SYSTEM_PATH`` is
-   passed or by setting the :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`
-   to ``FALSE``:
+   current system. The searching of ``CMAKE_INSTALL_PREFIX` can be skipped
+   if ``NO_CMAKE_INSTALL_PREFIX`` is passed or by setting the
+   :variable:`CMAKE_FIND_USE_INSTALL_PREFIX` to ``FALSE. All these locations
+   can be skipped if ``NO_CMAKE_SYSTEM_PATH`` is passed or by setting the
+   :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH` to ``FALSE``:
 
    * :variable:`CMAKE_SYSTEM_PREFIX_PATH`
    * :variable:`CMAKE_SYSTEM_FRAMEWORK_PATH`
diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst
index 7d68d4e..70dfc35 100644
--- a/Help/manual/cmake-variables.7.rst
+++ b/Help/manual/cmake-variables.7.rst
@@ -206,6 +206,7 @@ Variables that Change Behavior
    /variable/CMAKE_FIND_ROOT_PATH_MODE_PACKAGE
    /variable/CMAKE_FIND_ROOT_PATH_MODE_PROGRAM
    /variable/CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH
+   /variable/CMAKE_FIND_USE_INSTALL_PREFIX
    /variable/CMAKE_FIND_USE_CMAKE_PATH
    /variable/CMAKE_FIND_USE_CMAKE_SYSTEM_PATH
    /variable/CMAKE_FIND_USE_PACKAGE_REGISTRY
diff --git a/Help/release/dev/find-calls-search-install-prefix.rst b/Help/release/dev/find-calls-search-install-prefix.rst
new file mode 100644
index 0000000..a111a91
--- /dev/null
+++ b/Help/release/dev/find-calls-search-install-prefix.rst
@@ -0,0 +1,12 @@
+find-calls-search-install-prefix
+--------------------------------
+
+* The :command:`find_file`, :command:`find_library`, :command:`find_path`,
+  :command:`find_package`, and :command:`find_program` commands have gained
+  the `NO_CMAKE_INSTALL_PREFIX` option to control searching
+  `CMAKE_INSTALL_PREFIX`.
+
+* Adds support for :variable:`CMAKE_FIND_USE_INSTALL_PREFIX` to toggle
+  behavior of the :command:`find_file`, :command:`find_library`, :command:`find_path`,
+  :command:`find_package`, and :command:`find_program` commands new
+  `NO_CMAKE_INSTALL_PREFIX` option.
diff --git a/Help/variable/CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH.rst b/Help/variable/CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH.rst
index de1bad7..f72fd65 100644
--- a/Help/variable/CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH.rst
+++ b/Help/variable/CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH.rst
@@ -20,6 +20,7 @@ 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_INSTALL_PREFIX`,
 :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`,
 :variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY`,
 :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY`,
diff --git a/Help/variable/CMAKE_FIND_USE_CMAKE_SYSTEM_PATH.rst b/Help/variable/CMAKE_FIND_USE_CMAKE_SYSTEM_PATH.rst
index 2fd00df..2c1d237 100644
--- a/Help/variable/CMAKE_FIND_USE_CMAKE_SYSTEM_PATH.rst
+++ b/Help/variable/CMAKE_FIND_USE_CMAKE_SYSTEM_PATH.rst
@@ -20,6 +20,7 @@ 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_INSTALL_PREFIX`,
 :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`,
 :variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY`,
 :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY`,
diff --git a/Help/variable/CMAKE_FIND_USE_INSTALL_PREFIX.rst b/Help/variable/CMAKE_FIND_USE_INSTALL_PREFIX.rst
new file mode 100644
index 0000000..8494e95
--- /dev/null
+++ b/Help/variable/CMAKE_FIND_USE_INSTALL_PREFIX.rst
@@ -0,0 +1,39 @@
+CMAKE_FIND_USE_INSTALL_PREFIX
+-----------------------------------
+
+.. versionadded:: 3.24
+
+Controls the default behavior of the following commands for whether or not to
+search the install location:
+
+* :command:`find_program`
+* :command:`find_library`
+* :command:`find_file`
+* :command:`find_path`
+* :command:`find_package`
+
+This is useful in cross-compiling environments.
+
+Due to backwards compatibility with :variable:`CMAKE_FIND_NO_INSTALL_PREFIX`,
+the behavior of the find command change based on if this variable exists.
+
+============================== ============================ ===========
+ CMAKE_FIND_USE_INSTALL_PREFIX CMAKE_FIND_NO_INSTALL_PREFIX   Search
+============================== ============================ ===========
+ Not Defined                      On                          NO
+ Not Defined                      Off || Not Defined          YES
+ Off                              On                          NO
+ Off                              Off || Not Defined          NO
+ On                               On                          YES
+ On                               Off || Not Defined          YES
+============================== ============================ ===========
+
+By default this variable is not defined. Explicit options given to the above
+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`,
+: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 3127206..a5eec7a 100644
--- a/Help/variable/CMAKE_FIND_USE_PACKAGE_REGISTRY.rst
+++ b/Help/variable/CMAKE_FIND_USE_PACKAGE_REGISTRY.rst
@@ -26,6 +26,7 @@ the :ref:`User Package Registry` as if they were called with the
 See also :ref:`Disabling the Package Registry` and the
 :variable:`CMAKE_FIND_USE_CMAKE_PATH`,
 :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`,
+:variable:`CMAKE_FIND_USE_INSTALL_PREFIX`,
 :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`,
 :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`,
 :variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY`,
diff --git a/Help/variable/CMAKE_FIND_USE_PACKAGE_ROOT_PATH.rst b/Help/variable/CMAKE_FIND_USE_PACKAGE_ROOT_PATH.rst
index 64e5c6d..1f876a9 100644
--- a/Help/variable/CMAKE_FIND_USE_PACKAGE_ROOT_PATH.rst
+++ b/Help/variable/CMAKE_FIND_USE_PACKAGE_ROOT_PATH.rst
@@ -18,6 +18,7 @@ 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_INSTALL_PREFIX`,
 :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`,
 :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`,
 :variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY`,
diff --git a/Help/variable/CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH.rst b/Help/variable/CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH.rst
index a0a86e4..65edd10 100644
--- a/Help/variable/CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH.rst
+++ b/Help/variable/CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH.rst
@@ -20,6 +20,7 @@ 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_INSTALL_PREFIX`,
 :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`,
 :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY`,
 :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH`,
diff --git a/Help/variable/CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY.rst b/Help/variable/CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY.rst
index 504b7e8..2527904 100644
--- a/Help/variable/CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY.rst
+++ b/Help/variable/CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY.rst
@@ -27,6 +27,7 @@ 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_INSTALL_PREFIX`,
 :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`,
 :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`,
 :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY`,