Merge topic 'doc-find_package-root'

492ade276b Help: Add explicit <PackageName>_ROOT variable documentation

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

2 files changed, 19 insertions, 11 deletions

diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt
index 48a1a71..38c231a 100644
--- a/Help/command/FIND_XXX.txt
+++ b/Help/command/FIND_XXX.txt
@@ -62,8 +62,11 @@ added to the search.
 If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows:
 
 .. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR| replace::
-   |prefix_XXX_SUBDIR| for each ``<prefix>`` in ``PackageName_ROOT`` if called
-   from within a find module
+   |prefix_XXX_SUBDIR| for each ``<prefix>`` in the
+   :variable:`<PackageName>_ROOT` CMake variable and the
+   :envvar:`<PackageName>_ROOT` environment variable if
+   called from within a find module loaded by
+   :command:`find_package(<PackageName>)`
 
 .. |CMAKE_PREFIX_PATH_XXX_SUBDIR| replace::
    |prefix_XXX_SUBDIR| for each ``<prefix>`` in :variable:`CMAKE_PREFIX_PATH`
@@ -76,13 +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, search prefix paths unique to the
-   current package being found.  Specifically look in the ``PackageName_ROOT``
-   CMake and environment variables.  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 searched after paths from the current module,
-   i.e. ``CurrentPackage_ROOT``, ``ENV{CurrentPackage_ROOT}``,
-   ``ParentPackage_ROOT``, ``ENV{ParentPackage_ROOT}``, etc.
+1. If called from within a find module loaded by
+   :command:`find_package(<PackageName>)`, search prefixes unique to 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
+   nested find modules, root paths from the parent's find module will be
+   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.
    See policy :policy:`CMP0074`.
 
diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst
index 53f3819..a4416ab 100644
--- a/Help/command/find_package.rst
+++ b/Help/command/find_package.rst
@@ -262,8 +262,10 @@ The set of installation prefixes is constructed using the following
 steps.  If ``NO_DEFAULT_PATH`` is specified all ``NO_*`` options are
 enabled.
 
-1. Search paths specified in the ``PackageName_ROOT`` CMake and environment
-   variables.  The package root variables are maintained as a stack so if
+1. Search paths specified in the :variable:`<PackageName>_ROOT` CMake
+   variable and the :envvar:`<PackageName>_ROOT` environment variable,
+   where ``<PackageName>`` is the package to be found.
+   The package root variables are maintained as a stack so if
    called from within a find module, root paths from the parent's find
    module will also be searched after paths for the current package.
    This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed.