Cray: Added documentation for cross compiling on a Cray

1 files changed, 30 insertions, 0 deletions

diff --git a/Help/manual/cmake-toolchains.7.rst b/Help/manual/cmake-toolchains.7.rst
index 492fcac..7b294a8 100644
--- a/Help/manual/cmake-toolchains.7.rst
+++ b/Help/manual/cmake-toolchains.7.rst
@@ -151,6 +151,36 @@ target system prefixes, whereas executables which must be run as part of the bui
 should be found only on the host and not on the target. This is the purpose of
 the ``CMAKE_FIND_ROOT_PATH_MODE_*`` variables.
 
+.. _`Cray Cross-Compile`:
+
+Cross Compiling for the Cray Linux Environment
+----------------------------------------------
+
+Cross compiling for compute nodes in the Cray Linux Environment can be done
+without needing a separate toolchain file.  Specifying
+``-DCMAKE_SYSTEM_NAME=CrayLinuxEnvironment`` on the CMake command line will
+ensure that the appropriate build settings and search paths are configured.
+The platform will pull its configuration from the current environment
+variables and will configure a project to use the compiler wrappers from the
+Cray Programming Environment's ``PrgEnv-*`` modules if present and loaded.
+
+The default configuration of the Cray Programming Environment is to only
+support static libraries.  This can be overridden and shared libraries
+enabled by setting the ``CRAYPE_LINK_TYPE`` environment variable to
+``dynamic``.
+
+Running CMake without specifying :variable:`CMAKE_SYSTEM_NAME` will
+run the configure step in host mode assuming a standard Linux environment.
+If not overridden, the ``PrgEnv-*`` compiler wrappers will end up getting used,
+which if targeting the either the login node or compute node, is likely not the
+desired behavior.  The exception to this would be if you are building directly
+on a NID instead of cross-compiling from a login node. If trying to build
+software for a login node, you will need to either first unload the
+currently loaded ``PrgEnv-*`` module or explicitly tell CMake to use the
+system compilers in ``/usr/bin`` instead of the Cray wrappers.  If instead
+targeting a compute node is desired, just specify the
+:variable:`CMAKE_SYSTEM_NAME` as mentioned above.
+
 Cross Compiling using Clang
 ---------------------------