Merge topic 'doc-xref-find-env-vars'

c584882b26 Help: change links to point to the env.vars, not to the cmake vars
e40d4eb644 Help: add documentation for some CMAKE_XXX_PATH env.vars
73ce0b792f Help: minor improvement for the CMAKE_PREFIX_PATH docs

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

18 files changed, 133 insertions, 11 deletions

diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt
index 21236fa427..fe26d2b9a5 100644
--- a/Help/command/FIND_XXX.txt
+++ b/Help/command/FIND_XXX.txt
@@ -132,6 +132,9 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows:
 .. |CMAKE_PREFIX_PATH_XXX_SUBDIR| replace::
    |prefix_XXX_SUBDIR| for each ``<prefix>`` in :variable:`CMAKE_PREFIX_PATH`
 
+.. |ENV_CMAKE_PREFIX_PATH_XXX_SUBDIR| replace::
+   |prefix_XXX_SUBDIR| for each ``<prefix>`` in :envvar:`CMAKE_PREFIX_PATH`
+
 .. |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR| replace::
    |prefix_XXX_SUBDIR| for each ``<prefix>/[s]bin`` in ``PATH``, and
    |entry_XXX_SUBDIR| for other entries in ``PATH``
@@ -194,9 +197,9 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows:
    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|
-   * |CMAKE_XXX_MAC_PATH|
+   * |ENV_CMAKE_PREFIX_PATH_XXX|
+   * |ENV_CMAKE_XXX_PATH|
+   * |ENV_CMAKE_XXX_MAC_PATH|
 
 4. Search the paths specified by the ``HINTS`` option.
    These should be paths computed by system introspection, such as a
diff --git a/Help/command/find_file.rst b/Help/command/find_file.rst
index c5c40149de..9f89f5251d 100644
--- a/Help/command/find_file.rst
+++ b/Help/command/find_file.rst
@@ -19,6 +19,13 @@ find_file
 .. |CMAKE_XXX_PATH| replace:: :variable:`CMAKE_INCLUDE_PATH`
 .. |CMAKE_XXX_MAC_PATH| replace:: :variable:`CMAKE_FRAMEWORK_PATH`
 
+.. |ENV_CMAKE_PREFIX_PATH_XXX| replace::
+   ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set,
+   and |ENV_CMAKE_PREFIX_PATH_XXX_SUBDIR|
+.. |ENV_CMAKE_XXX_PATH| replace:: :envvar:`CMAKE_INCLUDE_PATH`
+.. |ENV_CMAKE_XXX_MAC_PATH| replace:: :envvar:`CMAKE_FRAMEWORK_PATH`
+
+
 .. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: The directories in ``INCLUDE``
    and ``PATH``.
 .. |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| replace:: On Windows hosts:
diff --git a/Help/command/find_library.rst b/Help/command/find_library.rst
index c237e7f0d3..99e36a49b6 100644
--- a/Help/command/find_library.rst
+++ b/Help/command/find_library.rst
@@ -19,6 +19,12 @@ find_library
 .. |CMAKE_XXX_PATH| replace:: :variable:`CMAKE_LIBRARY_PATH`
 .. |CMAKE_XXX_MAC_PATH| replace:: :variable:`CMAKE_FRAMEWORK_PATH`
 
+.. |ENV_CMAKE_PREFIX_PATH_XXX| replace::
+   ``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set,
+   and |ENV_CMAKE_PREFIX_PATH_XXX_SUBDIR|
+.. |ENV_CMAKE_XXX_PATH| replace:: :envvar:`CMAKE_LIBRARY_PATH`
+.. |ENV_CMAKE_XXX_MAC_PATH| replace:: :envvar:`CMAKE_FRAMEWORK_PATH`
+
 .. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: The directories in ``LIB``
    and ``PATH``.
 .. |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| replace:: On Windows hosts:
diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst
index b82088eaa0..b0b6fe1112 100644
--- a/Help/command/find_package.rst
+++ b/Help/command/find_package.rst
@@ -418,8 +418,8 @@ enabled.
 
    * ``<PackageName>_DIR``
    * :envvar:`CMAKE_PREFIX_PATH`
-   * ``CMAKE_FRAMEWORK_PATH``
-   * ``CMAKE_APPBUNDLE_PATH``
+   * :envvar:`CMAKE_FRAMEWORK_PATH`
+   * :envvar:`CMAKE_APPBUNDLE_PATH`
 
 4. Search paths specified by the ``HINTS`` option.  These should be paths
    computed by system introspection, such as a hint provided by the
diff --git a/Help/command/find_path.rst b/Help/command/find_path.rst
index 1d7648d05c..f0522f6430 100644
--- a/Help/command/find_path.rst
+++ b/Help/command/find_path.rst
@@ -19,6 +19,12 @@ find_path
 .. |CMAKE_XXX_PATH| replace:: :variable:`CMAKE_INCLUDE_PATH`
 .. |CMAKE_XXX_MAC_PATH| replace:: :variable:`CMAKE_FRAMEWORK_PATH`
 
+.. |ENV_CMAKE_PREFIX_PATH_XXX| replace::
+   ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set,
+   and |ENV_CMAKE_PREFIX_PATH_XXX_SUBDIR|
+.. |ENV_CMAKE_XXX_PATH| replace:: :envvar:`CMAKE_INCLUDE_PATH`
+.. |ENV_CMAKE_XXX_MAC_PATH| replace:: :envvar:`CMAKE_FRAMEWORK_PATH`
+
 .. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: The directories in ``INCLUDE``
    and ``PATH``.
 .. |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| replace:: On Windows hosts:
diff --git a/Help/command/find_program.rst b/Help/command/find_program.rst
index f4149be5ad..fe95a9a300 100644
--- a/Help/command/find_program.rst
+++ b/Help/command/find_program.rst
@@ -17,6 +17,11 @@ find_program
 .. |CMAKE_XXX_PATH| replace:: :variable:`CMAKE_PROGRAM_PATH`
 .. |CMAKE_XXX_MAC_PATH| replace:: :variable:`CMAKE_APPBUNDLE_PATH`
 
+.. |ENV_CMAKE_PREFIX_PATH_XXX| replace::
+   |ENV_CMAKE_PREFIX_PATH_XXX_SUBDIR|
+.. |ENV_CMAKE_XXX_PATH| replace:: :envvar:`CMAKE_PROGRAM_PATH`
+.. |ENV_CMAKE_XXX_MAC_PATH| replace:: :envvar:`CMAKE_APPBUNDLE_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
 
diff --git a/Help/envvar/CMAKE_APPBUNDLE_PATH.rst b/Help/envvar/CMAKE_APPBUNDLE_PATH.rst
new file mode 100644
index 0000000000..d80e08dcf7
--- /dev/null
+++ b/Help/envvar/CMAKE_APPBUNDLE_PATH.rst
@@ -0,0 +1,14 @@
+CMAKE_APPBUNDLE_PATH
+--------------------
+
+.. include:: ENV_VAR.txt
+
+The ``CMAKE_APPBUNDLE_PATH`` environment variable may be set to a list of
+directories to be searched for macOS application bundles
+by the :command:`find_program` and :command:`find_package` commands.
+
+This variable may hold a single directory or a list of directories separated
+by ``:`` on UNIX or ``;`` on Windows (the same as the ``PATH`` environment
+variable convention on those platforms).
+
+See also the :variable:`CMAKE_APPBUNDLE_PATH` CMake variable.
diff --git a/Help/envvar/CMAKE_FRAMEWORK_PATH.rst b/Help/envvar/CMAKE_FRAMEWORK_PATH.rst
new file mode 100644
index 0000000000..f543132dbc
--- /dev/null
+++ b/Help/envvar/CMAKE_FRAMEWORK_PATH.rst
@@ -0,0 +1,15 @@
+CMAKE_FRAMEWORK_PATH
+--------------------
+
+.. include:: ENV_VAR.txt
+
+The ``CMAKE_FRAMEWORK_PATH`` environment variable may be set to a list of
+directories to be searched for macOS frameworks by the :command:`find_library`,
+:command:`find_package`, :command:`find_path` and :command:`find_file` commands.
+
+
+This variable may hold a single directory or a list of directories separated
+by ``:`` on UNIX or ``;`` on Windows (the same as the ``PATH`` environment
+variable convention on those platforms).
+
+See also the :variable:`CMAKE_FRAMEWORK_PATH` CMake variable.
diff --git a/Help/envvar/CMAKE_INCLUDE_PATH.rst b/Help/envvar/CMAKE_INCLUDE_PATH.rst
new file mode 100644
index 0000000000..a42460d9d6
--- /dev/null
+++ b/Help/envvar/CMAKE_INCLUDE_PATH.rst
@@ -0,0 +1,13 @@
+CMAKE_INCLUDE_PATH
+------------------
+
+.. include:: ENV_VAR.txt
+
+The ``CMAKE_INCLUDE_PATH`` environment variable may be set to a list of
+directories to be searched by the :command:`find_file` and :command:`find_path` commands.
+
+This variable may hold a single directory or a list of directories separated
+by ``:`` on UNIX or ``;`` on Windows (the same as the ``PATH`` environment
+variable convention on those platforms).
+
+See also the :variable:`CMAKE_INCLUDE_PATH` CMake variable.
diff --git a/Help/envvar/CMAKE_LIBRARY_PATH.rst b/Help/envvar/CMAKE_LIBRARY_PATH.rst
new file mode 100644
index 0000000000..a51100d2ea
--- /dev/null
+++ b/Help/envvar/CMAKE_LIBRARY_PATH.rst
@@ -0,0 +1,13 @@
+CMAKE_LIBRARY_PATH
+------------------
+
+.. include:: ENV_VAR.txt
+
+The ``CMAKE_LIBRARY_PATH`` environment variable may be set to a list of
+directories to be searched by the :command:`find_library` command.
+
+This variable may hold a single directory or a list of directories separated
+by ``:`` on UNIX or ``;`` on Windows (the same as the ``PATH`` environment
+variable convention on those platforms).
+
+See also the :variable:`CMAKE_LIBRARY_PATH` CMake variable.
diff --git a/Help/envvar/CMAKE_PROGRAM_PATH.rst b/Help/envvar/CMAKE_PROGRAM_PATH.rst
new file mode 100644
index 0000000000..bfc7a306ce
--- /dev/null
+++ b/Help/envvar/CMAKE_PROGRAM_PATH.rst
@@ -0,0 +1,13 @@
+CMAKE_PROGRAM_PATH
+------------------
+
+.. include:: ENV_VAR.txt
+
+The ``CMAKE_PROGRAM_PATH`` environment variable may be set to a list of
+directories to be searched by the :command:`find_program` command.
+
+This variable may hold a single directory or a list of directories separated
+by ``:`` on UNIX or ``;`` on Windows (the same as the ``PATH`` environment
+variable convention on those platforms).
+
+See also the :variable:`CMAKE_PROGRAM_PATH` CMake variable.
diff --git a/Help/manual/cmake-env-variables.7.rst b/Help/manual/cmake-env-variables.7.rst
index 1f0c9111aa..f7ae94d339 100644
--- a/Help/manual/cmake-env-variables.7.rst
+++ b/Help/manual/cmake-env-variables.7.rst
@@ -20,8 +20,13 @@ Environment Variables that Change Behavior
 .. toctree::
    :maxdepth: 1
 
+   /envvar/CMAKE_APPBUNDLE_PATH
+   /envvar/CMAKE_FRAMEWORK_PATH
+   /envvar/CMAKE_INCLUDE_PATH
+   /envvar/CMAKE_LIBRARY_PATH
    /envvar/CMAKE_MAXIMUM_RECURSION_DEPTH
    /envvar/CMAKE_PREFIX_PATH
+   /envvar/CMAKE_PROGRAM_PATH
    /envvar/SSL_CERT_DIR
    /envvar/SSL_CERT_FILE
 
diff --git a/Help/variable/CMAKE_APPBUNDLE_PATH.rst b/Help/variable/CMAKE_APPBUNDLE_PATH.rst
index 1c7ca51c2a..441ee8ebb2 100644
--- a/Help/variable/CMAKE_APPBUNDLE_PATH.rst
+++ b/Help/variable/CMAKE_APPBUNDLE_PATH.rst
@@ -4,3 +4,6 @@ CMAKE_APPBUNDLE_PATH
 :ref:`Semicolon-separated list <CMake Language Lists>` of directories specifying a search path
 for macOS application bundles used by the :command:`find_program`, and
 :command:`find_package` commands.
+
+There is also an environment variable :envvar:`CMAKE_APPBUNDLE_PATH`, which is used
+as an additional list of search directories.
diff --git a/Help/variable/CMAKE_FRAMEWORK_PATH.rst b/Help/variable/CMAKE_FRAMEWORK_PATH.rst
index 13ade4e5fc..8d62b028f7 100644
--- a/Help/variable/CMAKE_FRAMEWORK_PATH.rst
+++ b/Help/variable/CMAKE_FRAMEWORK_PATH.rst
@@ -5,3 +5,6 @@ CMAKE_FRAMEWORK_PATH
 for macOS frameworks used by the :command:`find_library`,
 :command:`find_package`, :command:`find_path`, and :command:`find_file`
 commands.
+
+There is also an environment variable :envvar:`CMAKE_FRAMEWORK_PATH`, which is used
+as an additional list of search directories.
diff --git a/Help/variable/CMAKE_INCLUDE_PATH.rst b/Help/variable/CMAKE_INCLUDE_PATH.rst
index 4918e99602..3a4472a85f 100644
--- a/Help/variable/CMAKE_INCLUDE_PATH.rst
+++ b/Help/variable/CMAKE_INCLUDE_PATH.rst
@@ -3,5 +3,10 @@ CMAKE_INCLUDE_PATH
 
 :ref:`Semicolon-separated list <CMake Language Lists>` of directories specifying a search path
 for the :command:`find_file` and :command:`find_path` commands.  By default it
-is empty, it is intended to be set by the project.  See also
-:variable:`CMAKE_SYSTEM_INCLUDE_PATH` and :variable:`CMAKE_PREFIX_PATH`.
+is empty, it is intended to be set by the project.
+
+
+There is also an environment variable :envvar:`CMAKE_INCLUDE_PATH`, which is used
+as an additional list of search directories.
+
+See also :variable:`CMAKE_SYSTEM_INCLUDE_PATH` and :variable:`CMAKE_PREFIX_PATH`.
diff --git a/Help/variable/CMAKE_LIBRARY_PATH.rst b/Help/variable/CMAKE_LIBRARY_PATH.rst
index 8135b65818..4265982c2c 100644
--- a/Help/variable/CMAKE_LIBRARY_PATH.rst
+++ b/Help/variable/CMAKE_LIBRARY_PATH.rst
@@ -3,5 +3,9 @@ CMAKE_LIBRARY_PATH
 
 :ref:`Semicolon-separated list <CMake Language Lists>` of directories specifying a search path
 for the :command:`find_library` command.  By default it is empty, it is
-intended to be set by the project.  See also
-:variable:`CMAKE_SYSTEM_LIBRARY_PATH` and :variable:`CMAKE_PREFIX_PATH`.
+intended to be set by the project.
+
+There is also an environment variable :envvar:`CMAKE_LIBRARY_PATH`, which is used
+as an additional list of search directories.
+
+See also :variable:`CMAKE_SYSTEM_LIBRARY_PATH` and :variable:`CMAKE_PREFIX_PATH`.
diff --git a/Help/variable/CMAKE_PREFIX_PATH.rst b/Help/variable/CMAKE_PREFIX_PATH.rst
index 1d4fd0b426..54f2aecde0 100644
--- a/Help/variable/CMAKE_PREFIX_PATH.rst
+++ b/Help/variable/CMAKE_PREFIX_PATH.rst
@@ -10,6 +10,9 @@ documentation.
 
 By default this is empty.  It is intended to be set by the project.
 
+There is also an environment variable :envvar:`CMAKE_PREFIX_PATH`, which is used
+as an additional list of search prefixes.
+
 See also :variable:`CMAKE_SYSTEM_PREFIX_PATH`, :variable:`CMAKE_INCLUDE_PATH`,
 :variable:`CMAKE_LIBRARY_PATH`, :variable:`CMAKE_PROGRAM_PATH`, and
 :variable:`CMAKE_IGNORE_PATH`.
diff --git a/Help/variable/CMAKE_PROGRAM_PATH.rst b/Help/variable/CMAKE_PROGRAM_PATH.rst
index 2d0c090df5..240bacb9a0 100644
--- a/Help/variable/CMAKE_PROGRAM_PATH.rst
+++ b/Help/variable/CMAKE_PROGRAM_PATH.rst
@@ -3,5 +3,9 @@ CMAKE_PROGRAM_PATH
 
 :ref:`Semicolon-separated list <CMake Language Lists>` of directories specifying a search path
 for the :command:`find_program` command.  By default it is empty, it is
-intended to be set by the project.  See also
-:variable:`CMAKE_SYSTEM_PROGRAM_PATH` and :variable:`CMAKE_PREFIX_PATH`.
+intended to be set by the project.
+
+There is also an environment variable :envvar:`CMAKE_PROGRAM_PATH`, which is used
+as an additional list of search directories.
+
+See also :variable:`CMAKE_SYSTEM_PROGRAM_PATH` and :variable:`CMAKE_PREFIX_PATH`.