Merge branch 'docs-find-vars' into release-3.16

Merge-request: !3952

Help/command/FIND_XXX.txt

@@ -79,15 +79,16 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows:
    |prefix_XXX_SUBDIR| for each ``<prefix>`` in
    :variable:`CMAKE_SYSTEM_PREFIX_PATH`
 
-1. If called from within a find module loaded by
+1. If called from within a find module or any other script loaded by a call to
    :command:`find_package(<PackageName>)`, search prefixes unique to the
-   current package being found.  Specifically look in the
+   current package being found.  Specifically, look in the
    :variable:`<PackageName>_ROOT` CMake variable and the
    :envvar:`<PackageName>_ROOT` environment variable.
-   The package root variables are maintained as a stack so if called from
+   The package root variables are maintained as a stack, so if called from
-   nested find modules, root paths from the parent's find module will be
+   nested find modules or config packages, root paths from the parent's find
-   searched after paths from the current module,
+   module or config package will be searched after paths from the current
-   i.e. ``<CurrentPackage>_ROOT``, ``ENV{<CurrentPackage>_ROOT}``,
+   module or package.  In other words, the search order would be
+   ``<CurrentPackage>_ROOT``, ``ENV{<CurrentPackage>_ROOT}``,
    ``<ParentPackage>_ROOT``, ``ENV{<ParentPackage>_ROOT}``, etc.
    This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed or by setting
    the :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` to ``FALSE``.

Help/policy/CMP0074.rst

@@ -7,9 +7,9 @@ In CMake 3.12 and above the :command:`find_package(<PackageName>)` command now
 searches prefixes specified by the :variable:`<PackageName>_ROOT` CMake
 variable and the :envvar:`<PackageName>_ROOT` environment variable.
 Package roots are maintained as a stack so nested calls to all ``find_*``
-commands inside find modules also search the roots as prefixes.  This policy
+commands inside find modules and config packages also search the roots as
-provides compatibility with projects that have not been updated to avoid using
+prefixes.  This policy provides compatibility with projects that have not been
-``<PackageName>_ROOT`` variables for other purposes.
+updated to avoid using ``<PackageName>_ROOT`` variables for other purposes.
 
 The ``OLD`` behavior for this policy is to ignore ``<PackageName>_ROOT``
 variables.  The ``NEW`` behavior for this policy is to use

Help/release/3.16.rst

@@ -75,28 +75,27 @@ Commands
 
 * The :command:`find_file`, :command:`find_library`, :command:`find_path`,
   :command:`find_package`, and :command:`find_program` commands have learned to
-  check the following variables to control searching
+  check the following variables to control the default behavior for groups of
+  search locations:
 
-  * :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH` - Controls the searching
+  * :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` - Controls the default
-    the cmake-specific environment variables.
+    behavior of searching the :variable:`<PackageName>_ROOT` variables.
 
-  * :variable:`CMAKE_FIND_USE_CMAKE_PATH` - Controls the searching the
+  * :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH` - Controls the default
-    cmake-specific cache variables.
+    behavior of searching the CMake-specific environment variables.
 
-  * :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH` - Controls the searching
+  * :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH` - Controls the default
-    cmake platform specific variables.
+    behavior of searching the standard system environment variables.
 
-  * :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` - Controls the searching of
+  * :variable:`CMAKE_FIND_USE_CMAKE_PATH` - Controls the default behavior of
-    :variable:`<PackageName>_ROOT` variables.
+    searching the CMake-specific cache variables.
 
-  * :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH` - Controls the searching
+  * :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH` - Controls the default
-    the standard system environment variables.
+    behavior of searching the platform-specific CMake variables.
 
-* The :command:`find_package` command has learned to check the following
+* The :command:`find_package` command has learned to check the
-  variables to control searching
+  :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` variable to control the default
-
+  behavior of searching the CMake user package registry.
-  * :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` - Controls the searching the
-    cmake user registry.
 
 * The :command:`message` command learned indentation control with the new
   :variable:`CMAKE_MESSAGE_INDENT` variable.

Help/variable/CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY.rst

@@ -8,8 +8,8 @@ CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY
 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
+:command:`find_package()` will use the :ref:`User Package Registry`
-`NO_CMAKE_PACKAGE_REGISTRY` option is provided.
+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.

Help/variable/CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH.rst

@@ -1,15 +1,20 @@
 CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH
 -------------------------------------
 
-Controls the searching the cmake-specific environment variables by the
+Controls the default behavior of the following commands for whether or not to
-:command:`find_program`, :command:`find_library`, :command:`find_file`,
+search paths provided by cmake-specific environment variables:
-:command:`find_path`, and command:`find_package` commands.
+
+* :command:`find_program`
+* :command:`find_library`
+* :command:`find_file`
+* :command:`find_path`
+* :command:`find_package`
+
 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`,
+a value of ``TRUE``.  Explicit options given to the above commands
-:command:`find_library`, :command:`find_file`, and :command:`find_path`
+take precedence over this variable.
-commands take precedence over this variable.
 
 See also the :variable:`CMAKE_FIND_USE_CMAKE_PATH`,
 :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`,

Help/variable/CMAKE_FIND_USE_CMAKE_PATH.rst

@@ -1,15 +1,20 @@
 CMAKE_FIND_USE_CMAKE_PATH
 -------------------------
 
-Controls the searching the cmake-specific cache variables by the
+Controls the default behavior of the following commands for whether or not to
-:command:`find_program`, :command:`find_library`, :command:`find_file`,
+search paths provided by cmake-specific cache variables:
-:command:`find_path`, and command:`find_package` commands.
+
+* :command:`find_program`
+* :command:`find_library`
+* :command:`find_file`
+* :command:`find_path`
+* :command:`find_package`
+
 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`,
+a value of ``TRUE``.  Explicit options given to the above commands
-:command:`find_library`, :command:`find_file`, and :command:`find_path`
+take precedence over this variable.
-commands take precedence over this variable.
 
 See also the :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`,
 :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`,

Help/variable/CMAKE_FIND_USE_CMAKE_SYSTEM_PATH.rst

@@ -1,15 +1,20 @@
 CMAKE_FIND_USE_CMAKE_SYSTEM_PATH
 --------------------------------
 
-Controls the searching cmake platform specific variables by the
+Controls the default behavior of the following commands for whether or not to
-:command:`find_program`, :command:`find_library`, :command:`find_file`,
+search paths provided by platform-specific cmake variables:
-:command:`find_path`, and command:`find_package` commands.
+
+* :command:`find_program`
+* :command:`find_library`
+* :command:`find_file`
+* :command:`find_path`
+* :command:`find_package`
+
 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`,
+a value of ``TRUE``.  Explicit options given to the above commands
-:command:`find_library`, :command:`find_file`, and :command:`find_path`
+take precedence over this variable.
-commands take precedence over this variable.
 
 See also the :variable:`CMAKE_FIND_USE_CMAKE_PATH`,
 :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`,

Help/variable/CMAKE_FIND_USE_PACKAGE_REGISTRY.rst

@@ -1,28 +1,28 @@
 CMAKE_FIND_USE_PACKAGE_REGISTRY
 -------------------------------
 
-Controls the searching the :ref:`User Package Registry` by the :command:`find_package`
+Controls the default behavior of the :command:`find_package` command for
-command.
+whether or not to search paths provided by the :ref:`User Package Registry`.
 
 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`
+to that determined by the deprecated
-variable.  If that is also not set, then `find_package()` will use the
+:variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` variable.  If that is
-`User Package Registry` unless the `NO_CMAKE_PACKAGE_REGISTRY` option
+also not set, then :command:`find_package` will use the
+:ref:`User Package Registry` unless the ``NO_CMAKE_PACKAGE_REGISTRY`` option
 is provided.
 
-This variable takes precedence over :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY`
+This variable takes precedence over
-when both are set.
+: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`
+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 :ref:`Disabling the Package Registry` and the
-
+:variable:`CMAKE_FIND_USE_CMAKE_PATH`,
-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`,

Help/variable/CMAKE_FIND_USE_PACKAGE_ROOT_PATH.rst

@@ -1,15 +1,18 @@
 CMAKE_FIND_USE_PACKAGE_ROOT_PATH
 --------------------------------
 
-Controls the searching of :variable:`<PackageName>_ROOT` variables by the
+Controls the default behavior of the following commands for whether or not to
-:command:`find_program`, :command:`find_library`, :command:`find_file`,
+search paths provided by :variable:`<PackageName>_ROOT` variables:
-:command:`find_path`, and command:`find_package` commands.
+
-This is useful in cross-compiling environments.
+* :command:`find_program`
+* :command:`find_library`
+* :command:`find_file`
+* :command:`find_path`
+* :command:`find_package`
 
 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`,
+a value of ``TRUE``.  Explicit options given to the above commands
-:command:`find_library`, :command:`find_file`, and :command:`find_path`
+take precedence over this variable.
-commands take precedence over this variable.
 
 See also the :variable:`CMAKE_FIND_USE_CMAKE_PATH`,
 :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`,

Help/variable/CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH.rst

@@ -1,15 +1,20 @@
 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH
 --------------------------------------
 
-Controls the searching the standard system environment variables by the
+Controls the default behavior of the following commands for whether or not to
-:command:`find_program`, :command:`find_library`, :command:`find_file`,
+search paths provided by standard system environment variables:
-:command:`find_path`, and command:`find_package` commands.
+
+* :command:`find_program`
+* :command:`find_library`
+* :command:`find_file`
+* :command:`find_path`
+* :command:`find_package`
+
 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`,
+a value of ``TRUE``.  Explicit options given to the above commands
-:command:`find_library`, :command:`find_file`, and :command:`find_path`
+take precedence over this variable.
-commands take precedence over this variable.
 
 See also the :variable:`CMAKE_FIND_USE_CMAKE_PATH`,
 :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`,