Find: Provide global controls for the `NO_[]_PATH` call options

12 files changed, 96 insertions, 21 deletions

diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt
index dde4dbb..fc8c55e 100644
--- a/Help/command/FIND_XXX.txt
+++ b/Help/command/FIND_XXX.txt
@@ -89,7 +89,8 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows:
    searched after paths from the current module,
    i.e. ``<CurrentPackage>_ROOT``, ``ENV{<CurrentPackage>_ROOT}``,
    ``<ParentPackage>_ROOT``, ``ENV{<ParentPackage>_ROOT}``, etc.
-   This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed.
+   This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed or by setting
+   the :variable:`CMAKE_FIND_USE_PACAKGE_ROOT_PATH` to ``FALSE``.
    See policy :policy:`CMP0074`.
 
    * |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX|
@@ -97,7 +98,8 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows:
 2. Search paths specified in cmake-specific cache variables.
    These are intended to be used on the command line with a ``-DVAR=value``.
    The values are interpreted as :ref:`semicolon-separated lists <CMake Language Lists>`.
-   This can be skipped if ``NO_CMAKE_PATH`` is passed.
+   This can be skipped if ``NO_CMAKE_PATH`` is passed or by setting the
+   :variable:`CMAKE_FIND_USE_CMAKE_PATH` to ``FALSE``.
 
    * |CMAKE_PREFIX_PATH_XXX|
    * |CMAKE_XXX_PATH|
@@ -107,7 +109,8 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows:
    These are intended to be set in the user's shell configuration,
    and therefore use the host's native path separator
    (``;`` on Windows and ``:`` on UNIX).
-   This can be skipped if ``NO_CMAKE_ENVIRONMENT_PATH`` is passed.
+   This can be skipped if ``NO_CMAKE_ENVIRONMENT_PATH`` is passed or
+   by setting the :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH` to ``FALSE``.
 
    * |CMAKE_PREFIX_PATH_XXX|
    * |CMAKE_XXX_PATH|
@@ -119,13 +122,16 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows:
    Hard-coded guesses should be specified with the ``PATHS`` option.
 
 5. Search the standard system environment variables.
-   This can be skipped if ``NO_SYSTEM_ENVIRONMENT_PATH`` is an argument.
+   This can be skipped if ``NO_SYSTEM_ENVIRONMENT_PATH`` is passed or by
+   setting the :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH` to ``FALSE``.
 
    * |SYSTEM_ENVIRONMENT_PATH_XXX|
+   * |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.
+   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_file.rst b/Help/command/find_file.rst
index 2a14ad7..3f03f37 100644
--- a/Help/command/find_file.rst
+++ b/Help/command/find_file.rst
@@ -17,11 +17,10 @@ find_file
 .. |CMAKE_XXX_PATH| replace:: :variable:`CMAKE_INCLUDE_PATH`
 .. |CMAKE_XXX_MAC_PATH| replace:: :variable:`CMAKE_FRAMEWORK_PATH`
 
-.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: Directories in ``INCLUDE``.
-   On Windows hosts:
-   ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
-   is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|, and the
-   directories in ``PATH`` itself.
+.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: The directories in ``PATH`` and ``INCLUDE``.
+.. |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| replace:: On Windows hosts:
+      ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
+      is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|.
 
 .. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace::
    ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
diff --git a/Help/command/find_library.rst b/Help/command/find_library.rst
index 0861d67..8a55aca 100644
--- a/Help/command/find_library.rst
+++ b/Help/command/find_library.rst
@@ -17,11 +17,10 @@ find_library
 .. |CMAKE_XXX_PATH| replace:: :variable:`CMAKE_LIBRARY_PATH`
 .. |CMAKE_XXX_MAC_PATH| replace:: :variable:`CMAKE_FRAMEWORK_PATH`
 
-.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: Directories in ``LIB``.
-   On Windows hosts:
-   ``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set,
-   and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|,
-   and the directories in ``PATH`` itself.
+.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: The directories in ``PATH`` and ``INCLUDE``.
+.. |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| replace:: On Windows hosts:
+      ``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
+      is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|.
 
 .. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace::
    ``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set,
diff --git a/Help/command/find_path.rst b/Help/command/find_path.rst
index 988a3fa..52ffe3c 100644
--- a/Help/command/find_path.rst
+++ b/Help/command/find_path.rst
@@ -17,11 +17,10 @@ find_path
 .. |CMAKE_XXX_PATH| replace:: :variable:`CMAKE_INCLUDE_PATH`
 .. |CMAKE_XXX_MAC_PATH| replace:: :variable:`CMAKE_FRAMEWORK_PATH`
 
-.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: Directories in ``INCLUDE``.
-   On Windows hosts:
-   ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
-   is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|, and the
-   directories in ``PATH`` itself.
+.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: The directories in ``PATH`` and ``INCLUDE``.
+.. |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| replace:: On Windows hosts:
+      ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
+      is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|.
 
 .. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace::
    ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
diff --git a/Help/command/find_program.rst b/Help/command/find_program.rst
index 4f00773..e2ff693 100644
--- a/Help/command/find_program.rst
+++ b/Help/command/find_program.rst
@@ -15,7 +15,8 @@ find_program
 .. |CMAKE_XXX_PATH| replace:: :variable:`CMAKE_PROGRAM_PATH`
 .. |CMAKE_XXX_MAC_PATH| replace:: :variable:`CMAKE_APPBUNDLE_PATH`
 
-.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: ``PATH``
+.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: The directories in ``PATH`` itself.
+.. |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| replace:: On Windows hosts no extra search paths are included
 
 .. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace::
    |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR|
diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst
index 75ddd5d..cc6a7d2 100644
--- a/Help/manual/cmake-variables.7.rst
+++ b/Help/manual/cmake-variables.7.rst
@@ -180,6 +180,11 @@ Variables that Change Behavior
    /variable/CMAKE_FIND_ROOT_PATH_MODE_LIBRARY
    /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_CMAKE_PATH
+   /variable/CMAKE_FIND_USE_CMAKE_SYSTEM_PATH
+   /variable/CMAKE_FIND_USE_PACAKGE_ROOT_PATH
+   /variable/CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH
    /variable/CMAKE_FRAMEWORK_PATH
    /variable/CMAKE_IGNORE_PATH
    /variable/CMAKE_INCLUDE_DIRECTORIES_BEFORE
diff --git a/Help/release/dev/global-controls-over-find-locations.rst b/Help/release/dev/global-controls-over-find-locations.rst
new file mode 100644
index 0000000..d915fbb
--- /dev/null
+++ b/Help/release/dev/global-controls-over-find-locations.rst
@@ -0,0 +1,11 @@
+global-controls-over-find-locations
+-----------------------------------
+
+* The :command:`find_file`, :command:`find_library`, :command:`find_path`,
+  and :command:`find_program` commands have learned to check the following
+  variables to control searching
+  * :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH` - Controls the searching the cmake-specific environment variables.
+  * :variable:`CMAKE_FIND_USE_CMAKE_PATH` - Controls the searching the cmake-specific cache variables.
+  * :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH` - Controls the searching cmake platform specific variables.
+  * :variable:`CMAKE_FIND_USE_PACAKGE_ROOT_PATH` - Controls the searching of :variable:`<PackageName>_ROOT` variables.
+  * :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH` - Controls the searching the standard system environment variables.
diff --git a/Help/variable/CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH.rst b/Help/variable/CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH.rst
new file mode 100644
index 0000000..3db510f
--- /dev/null
+++ b/Help/variable/CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH.rst
@@ -0,0 +1,11 @@
+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`.
+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_SYSTEM_PATH`,
+:variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`, and :variable:`CMAKE_FIND_USE_PACAKGE_ROOT_PATH` variables.
diff --git a/Help/variable/CMAKE_FIND_USE_CMAKE_PATH.rst b/Help/variable/CMAKE_FIND_USE_CMAKE_PATH.rst
new file mode 100644
index 0000000..86a6186
--- /dev/null
+++ b/Help/variable/CMAKE_FIND_USE_CMAKE_PATH.rst
@@ -0,0 +1,11 @@
+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`.
+This is useful in cross-compiling environments.
+
+By default this this is set to ``TRUE``.
+
+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.
diff --git a/Help/variable/CMAKE_FIND_USE_CMAKE_SYSTEM_PATH.rst b/Help/variable/CMAKE_FIND_USE_CMAKE_SYSTEM_PATH.rst
new file mode 100644
index 0000000..b4171c0
--- /dev/null
+++ b/Help/variable/CMAKE_FIND_USE_CMAKE_SYSTEM_PATH.rst
@@ -0,0 +1,11 @@
+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`.
+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_SYSTEM_ENVIRONMENT_PATH`, and :variable:`CMAKE_FIND_USE_PACAKGE_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
new file mode 100644
index 0000000..ac25ec9
--- /dev/null
+++ b/Help/variable/CMAKE_FIND_USE_PACAKGE_ROOT_PATH.rst
@@ -0,0 +1,11 @@
+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_SYSTEM_ENVIRONMENT_PATH.rst b/Help/variable/CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH.rst
new file mode 100644
index 0000000..fd0582f
--- /dev/null
+++ b/Help/variable/CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH.rst
@@ -0,0 +1,11 @@
+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`.
+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_PACAKGE_ROOT_PATH` variables.