# FindEnvModules

Added in version 3.15.

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`).

Note

The loaded environment will not persist beyond the end of the calling process. Do not use this module in CMake project code (such as `CMakeLists.txt`) to load compiler environments, as the environment changes will not be available during the build phase. In such a case, load the desired environment before invoking CMake or the generated build system.

## 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.

`example-script.cmake`

    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)

    # ...