FindEnvModules

Finds an Environment Modules implementation and provides commands for use in CMake scripts:

find_package(EnvModules [...])

The Environment Modules system is a command-line tool that manages Unix-like shell environments by dynamically modifying environment variables. It is commonly used in High-Performance Computing (HPC) environments to support multiple software versions or configurations.

This module is compatible with the two most common implementations:

• Lua-based Lmod
• TCL-based Environment Modules

This module is primarily intended for setting up compiler and library environments within a CTest Script (ctest -S). It may also be used in a CMake Script (cmake -P).

Result Variables

This module defines the following variables:

EnvModules_FOUND

Boolean indicating whether a compatible Environment Modules framework was found.

Cache Variables

The following cache variables may also be set:

EnvModules_COMMAND

The path to a low level module command to use.

Hints

This module accepts the following variables before calling the find_package(EnvModules):

ENV{MODULESHOME}

This environment variable is usually set by the Environment Modules implementation, and can be used as a hint to locate the module command to execute.

Commands

This module provides the following commands for interacting with the Environment Modules system, if found:

env_module

Executes an arbitrary module command:

env_module(<command> <args>...)
env_module(
  COMMAND <command> <args>...
  [OUTPUT_VARIABLE <out-var>]
  [RESULT_VARIABLE <ret-var>]
)

The options are:

COMMAND <command> <args>...

The module sub-command and arguments to execute as if passed directly to the module command in the shell environment.

OUTPUT_VARIABLE <out-var>

Stores the standard output of the executed module command in the specified variable.

RESULT_VARIABLE <ret-var>

Stores the return code of the executed module command in the specified variable.

env_module_swap

Swaps one module for another:

env_module_swap(
  <out-mod>
  <in-mod>
  [OUTPUT_VARIABLE <out-var>]
  [RESULT_VARIABLE <ret-var>]
)

This is functionally equivalent to the module swap <out-mod> <in-mod> shell command.

The options are:

OUTPUT_VARIABLE <out-var>

Stores the standard output of the executed module command in the specified variable.

RESULT_VARIABLE <ret-var>

Stores the return code of the executed module command in the specified variable.

env_module_list

Retrieves the list of currently loaded modules:

env_module_list(<out-var>)

This is functionally equivalent to the module list shell command. The result is stored in <out-var> as a properly formatted CMake semicolon-separated list variable.

env_module_avail

Retrieves the list of available modules:

env_module_avail([<mod-prefix>] <out-var>)

This is functionally equivalent to the module avail <mod-prefix> shell command. The result is stored in <out-var> as a properly formatted CMake semicolon-separated list variable.

Examples

In the following example, this module is used in a CTest script to configure the compiler and libraries for a Cray Programming Environment. After the Environment Modules system is found, the env_module() command is used to load the necessary compiler, MPI, and scientific libraries to set up the build environment. The CRAYPE_LINK_TYPE environment variable is set to dynamic to specify dynamic linking. This instructs the Cray Linux Environment compiler driver to link against dynamic libraries at runtime, rather than linking static libraries at compile time. As a result, the compiler produces dynamically linked executable files.

set(CTEST_BUILD_NAME "CrayLinux-CrayPE-Cray-dynamic")
set(CTEST_BUILD_CONFIGURATION Release)
set(CTEST_BUILD_FLAGS "-k -j8")
set(CTEST_CMAKE_GENERATOR "Unix Makefiles")

# ...

find_package(EnvModules REQUIRED)

# Clear all currently loaded Environment Modules to start with a clean state
env_module(purge)

# Load the base module-handling system to use other modules
env_module(load modules)

# Load Cray Programming Environment (Cray PE) support, which manages
# platform-specific optimizations and architecture selection
env_module(load craype)

# Load the Cray programming environment
env_module(load PrgEnv-cray)

# Load settings targeting the Intel Knights Landing (KNL) CPU architecture
env_module(load craype-knl)

# Load the Cray MPI (Message Passing Interface) library, needed for
# distributed computing
env_module(load cray-mpich)

# Load Cray's scientific library package, which includes optimized math
# libraries (like BLAS, LAPACK)
env_module(load cray-libsci)

set(ENV{CRAYPE_LINK_TYPE} dynamic)

# ...