Document which environment variables effect CMAKE_SYSTEM_PREFIX_PATH

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.

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`

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.
 

Modules/Platform/UnixPaths.cmake

@@ -21,6 +21,10 @@ get_filename_component(_CMAKE_INSTALL_DIR "${_CMAKE_INSTALL_DIR}" PATH)
 
 # List common installation prefixes.  These will be used for all
 # search types.
+#
+# Reminder when adding new locations computed from environment variables
+# please make sure to keep Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst
+# synchronized
 list(APPEND CMAKE_SYSTEM_PREFIX_PATH
   # Standard
   /usr/local /usr /
@@ -86,6 +90,9 @@ set(_CMAKE_CUDA_IMPLICIT_INCLUDE_DIRECTORIES_INIT
 
 unset(_cmake_sysroot_compile)
 
+# Reminder when adding new locations computed from environment variables
+# please make sure to keep Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst
+# synchronized
 if(CMAKE_COMPILER_SYSROOT)
   list(PREPEND CMAKE_SYSTEM_PREFIX_PATH "${CMAKE_COMPILER_SYSROOT}")
 endif()

Modules/Platform/WindowsPaths.cmake

@@ -24,6 +24,10 @@ set(__WINDOWS_PATHS_INCLUDED 1)
 #   ENV{ProgramFiles(x86)} = [C:\Program Files (x86)]
 #   ENV{ProgramFiles} = [C:\Program Files (x86)]
 #   ENV{ProgramW6432} = [C:\Program Files]
+#
+# Reminder when adding new locations computed from environment variables
+# please make sure to keep Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst
+# synchronized
 set(_programfiles "")
 foreach(v "ProgramW6432" "ProgramFiles" "ProgramFiles(x86)")
   if(DEFINED "ENV{${v}}")