Merge topic 'doc-find_package-root'

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

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

8 files changed, 61 insertions, 20 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.
diff --git a/Help/envvar/PackageName_ROOT.rst b/Help/envvar/PackageName_ROOT.rst
new file mode 100644
index 0000000..e01009b
--- /dev/null
+++ b/Help/envvar/PackageName_ROOT.rst
@@ -0,0 +1,15 @@
+<PackageName>_ROOT
+------------------
+
+Calls to :command:`find_package(<PackageName>)` will search in prefixes
+specified by the ``<PackageName>_ROOT`` environment variable, where
+``<PackageName>`` is the name given to the ``find_package`` call
+and ``_ROOT`` is literal.  For example, ``find_package(Foo)`` will search
+prefixes specified in the ``Foo_ROOT`` environment variable (if set).
+See policy :policy:`CMP0074`.
+
+This variable may hold a single prefix or a list of prefixes separated
+by ``:`` on UNIX or ``;`` on Windows (the same as the ``PATH`` environment
+variable convention on those platforms).
+
+See also the :variable:`<PackageName>_ROOT` CMake variable.
diff --git a/Help/manual/cmake-env-variables.7.rst b/Help/manual/cmake-env-variables.7.rst
index 2d17bb5..42aeabc 100644
--- a/Help/manual/cmake-env-variables.7.rst
+++ b/Help/manual/cmake-env-variables.7.rst
@@ -20,6 +20,7 @@ Environment Variables that Control the Build
    /envvar/DESTDIR
    /envvar/LDFLAGS
    /envvar/MACOSX_DEPLOYMENT_TARGET
+   /envvar/PackageName_ROOT
 
 Environment Variables for Languages
 ===================================
diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst
index 451bd23..48b1f20 100644
--- a/Help/manual/cmake-variables.7.rst
+++ b/Help/manual/cmake-variables.7.rst
@@ -204,6 +204,7 @@ Variables that Change Behavior
    /variable/CMAKE_WARN_DEPRECATED
    /variable/CMAKE_WARN_ON_ABSOLUTE_INSTALL_DESTINATION
    /variable/CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY
+   /variable/PackageName_ROOT
 
 Variables that Describe the System
 ==================================
diff --git a/Help/policy/CMP0074.rst b/Help/policy/CMP0074.rst
index ffac4a7..896936b 100644
--- a/Help/policy/CMP0074.rst
+++ b/Help/policy/CMP0074.rst
@@ -1,18 +1,19 @@
 CMP0074
 -------
 
-:command:`find_package` uses ``PackageName_ROOT`` variables.
+:command:`find_package` uses ``<PackageName>_ROOT`` variables.
 
-In CMake 3.12 and above the ``find_package(PackageName)`` command now searches
-a prefix specified by a ``PackageName_ROOT`` CMake or environment variable.
+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
 provides compatibility with projects that have not been updated to avoid using
-``PackageName_ROOT`` variables for other purposes.
+``<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 ``PackageName_ROOT``
-variables.
+The ``OLD`` behavior for this policy is to ignore ``<PackageName>_ROOT``
+variables.  The ``NEW`` behavior for this policy is to use
+``<PackageName>_ROOT`` variables.
 
 This policy was introduced in CMake version 3.12.  CMake version
 |release| warns when the policy is not set and uses ``OLD`` behavior.
diff --git a/Help/release/3.12.rst b/Help/release/3.12.rst
index bbeb11e..481027e 100644
--- a/Help/release/3.12.rst
+++ b/Help/release/3.12.rst
@@ -46,8 +46,9 @@ Commands
   were added to expose ``TOUCH`` functionality without having to use
   CMake's command-line tool mode with :command:`execute_process`.
 
-* The :command:`find_package` command now searches a prefix specified by
-  a ``PackageName_ROOT`` CMake or environment variable.  Package roots are
+* The :command:`find_package` 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.
   See policy :policy:`CMP0074`.
diff --git a/Help/variable/PackageName_ROOT.rst b/Help/variable/PackageName_ROOT.rst
new file mode 100644
index 0000000..4f6c25b
--- /dev/null
+++ b/Help/variable/PackageName_ROOT.rst
@@ -0,0 +1,14 @@
+<PackageName>_ROOT
+------------------
+
+Calls to :command:`find_package(<PackageName>)` will search in prefixes
+specified by the ``<PackageName>_ROOT`` CMake variable, where
+``<PackageName>`` is the name given to the ``find_package`` call
+and ``_ROOT`` is literal.  For example, ``find_package(Foo)`` will search
+prefixes specified in the ``Foo_ROOT`` CMake variable (if set).
+See policy :policy:`CMP0074`.
+
+This variable may hold a single prefix or a
+:ref:`;-list <CMake Language Lists>` of multiple prefixes.
+
+See also the :envvar:`<PackageName>_ROOT` environment variable.