Merge topic 'doc-CMAKE_SYSTEM_PREFIX_PATH'

6b3d8f281e Document which environment variables effect CMAKE_SYSTEM_PREFIX_PATH

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

3 files changed, 38 insertions, 1 deletions

diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt
index cebe051..4a62c5b 100644
--- a/Help/command/FIND_XXX.txt
+++ b/Help/command/FIND_XXX.txt
@@ -143,6 +143,10 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows:
    * |CMAKE_SYSTEM_XXX_PATH|
    * |CMAKE_SYSTEM_XXX_MAC_PATH|
 
+   The platform paths that these variables contain are locations that
+   typically include installed software. An example being ``/usr/local`` for
+   UNIX based platforms.
+
 7. Search the paths specified by the PATHS option
    or in the short-hand version of the command.
    These are typically hard-coded guesses.
diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst
index 6753268..3547ada 100644
--- a/Help/command/find_package.rst
+++ b/Help/command/find_package.rst
@@ -351,6 +351,10 @@ enabled.
      CMAKE_SYSTEM_FRAMEWORK_PATH
      CMAKE_SYSTEM_APPBUNDLE_PATH
 
+   The platform paths that these variables contain are locations that
+   typically include installed software. An example being ``/usr/local`` for
+   UNIX based platforms.
+
 8. Search paths stored in the CMake :ref:`System Package Registry`.
    This can be skipped if ``NO_CMAKE_SYSTEM_PACKAGE_REGISTRY`` is passed
    or by setting the :variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY`
diff --git a/Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst b/Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst
index 87a9d06..e0ee979 100644
--- a/Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst
+++ b/Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst
@@ -8,11 +8,40 @@ CMAKE_SYSTEM_PREFIX_PATH
 subdirectories (like ``bin``, ``lib``, or ``include``) as specified in its own
 documentation.
 
-By default this contains the standard directories for the current system, the
+By default this contains the system directories for the current system, the
 :variable:`CMAKE_INSTALL_PREFIX`, and the :variable:`CMAKE_STAGING_PREFIX`.
 The installation and staging prefixes may be excluded by setting
 the :variable:`CMAKE_FIND_NO_INSTALL_PREFIX` variable.
 
+The system directories that are contained in ``CMAKE_SYSTEM_PREFIX_PATH`` are
+locations that typically include installed software. An example being
+``/usr/local`` for UNIX based platforms. In addition to standard platform
+locations, CMake will also add values to ``CMAKE_SYSTEM_PREFIX_PATH`` based on
+environment variables. The environment variables and search locations that
+CMake uses may evolve over time, as platforms and their conventions also
+evolve. The following provides an indicative list of environment variables
+and locations that CMake searches, but they are subject to change:
+
+
+CrayLinuxEnvironment:
+  * ``ENV{SYSROOT_DIR}/``
+  * ``ENV{SYSROOT_DIR}/usr``
+  * ``ENV{SYSROOT_DIR}/usr/local``
+
+Darwin:
+  * ``ENV{SDKROOT}/usr`` When ``CMAKE_OSX_SYSROOT`` is not explicitly specified.
+
+OpenBSD:
+  * ``ENV{LOCALBASE}``
+
+Windows:
+  * ``ENV{ProgramW6432}``
+  * ``ENV{ProgramFiles}``
+  * ``ENV{ProgramFiles(x86)}``
+  * ``ENV{SystemDrive}/Program Files``
+  * ``ENV{SystemDrive}/Program Files (x86)``
+
+
 ``CMAKE_SYSTEM_PREFIX_PATH`` is *not* intended to be modified by the project;
 use :variable:`CMAKE_PREFIX_PATH` for this.