Merge branch 'doc-find_package-root' into release-3.12

Merge-request: !2225

10 files changed, 64 insertions, 23 deletions

diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt
index 48a1a71243..38c231a670 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 53f3819b34..a4416abd39 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 0000000000..e01009bc75
--- /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 2d17bb5401..42aeabc898 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 edfff6cc0a..f6bf0bd92d 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 ffac4a7cb6..896936b212 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 f6fdb5aa92..f00be3e79a 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 0000000000..4f6c25b341
--- /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.
diff --git a/Source/cmPolicies.h b/Source/cmPolicies.h
index 3fe0c844d1..1ef1813c2b 100644
--- a/Source/cmPolicies.h
+++ b/Source/cmPolicies.h
@@ -219,8 +219,8 @@ class cmMakefile;
   SELECT(POLICY, CMP0073,                                                     \
          "Do not produce legacy _LIB_DEPENDS cache entries.", 3, 12, 0,       \
          cmPolicies::WARN)                                                    \
-  SELECT(POLICY, CMP0074, "find_package uses PackageName_ROOT variables.", 3, \
-         12, 0, cmPolicies::WARN)                                             \
+  SELECT(POLICY, CMP0074, "find_package uses <PackageName>_ROOT variables.",  \
+         3, 12, 0, cmPolicies::WARN)                                          \
   SELECT(POLICY, CMP0075,                                                     \
          "Include file check macros honor CMAKE_REQUIRED_LIBRARIES.", 3, 12,  \
          0, cmPolicies::WARN)
diff --git a/Tests/RunCMake/find_package/CMP0074-WARN-stderr.txt b/Tests/RunCMake/find_package/CMP0074-WARN-stderr.txt
index 27fbb86363..fc08163cdc 100644
--- a/Tests/RunCMake/find_package/CMP0074-WARN-stderr.txt
+++ b/Tests/RunCMake/find_package/CMP0074-WARN-stderr.txt
@@ -3,7 +3,7 @@ Foo_ROOT      :<base>/foo/cmake_root
 ENV{Foo_ROOT} :<base>/foo/env_root
 +
 CMake Warning \(dev\) at CMP0074-common.cmake:[0-9]+ \(find_package\):
-  Policy CMP0074 is not set: find_package uses PackageName_ROOT variables.
+  Policy CMP0074 is not set: find_package uses <PackageName>_ROOT variables.
   Run "cmake --help-policy CMP0074" for policy details.  Use the cmake_policy
   command to set the policy and suppress this warning.