FindEnvModules

版本 3.15 新增。

查找 Environment Modules 实现并提供在 CMake 脚本中使用的命令

find_package(EnvModules [...])

Environment Modules 系统是一个命令行工具，通过动态修改环境变量来管理类 Unix shell 环境。它通常用于高性能计算 (HPC) 环境中，以支持多个软件版本或配置。

此模块与两种最常见的实现兼容

• 基于 Lua 的 Lmod

• 基于 TCL 的 Environment Modules

此模块主要用于在 CTest 脚本 (ctest -S) 中设置编译器和库环境。它也可以在 CMake 脚本 (cmake -P) 中使用。

注意

加载的环境在调用进程结束时将不再保留。请勿在 CMake 项目代码（例如 CMakeLists.txt）中使用此模块加载编译器环境，因为环境更改在构建阶段将不可用。在这种情况下，请在调用 CMake 或生成的构建系统之前加载所需的环境。

结果变量

此模块定义了以下变量

EnvModules_FOUND

布尔值，指示是否找到兼容的 Environment Modules 框架。

缓存变量

以下缓存变量也可以设置

EnvModules_COMMAND

要使用的底层模块命令的路径。

提示

在调用 find_package(EnvModules) 之前，此模块接受以下变量

ENV{MODULESHOME}

此环境变量通常由 Environment Modules 实现设置，可用作查找要执行的模块命令的提示。

命令

如果找到，此模块提供以下用于与 Environment Modules 系统交互的命令

env_module

执行任意模块命令

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

选项包括

COMMAND <command> <args>...

要执行的模块子命令和参数，就像直接在 shell 环境中传递给模块命令一样。

OUTPUT_VARIABLE <out-var>

将执行的模块命令的标准输出存储在指定变量中。

RESULT_VARIABLE <ret-var>

将执行的模块命令的返回代码存储在指定变量中。

env_module_swap

用一个模块替换另一个模块

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

这在功能上等同于 module swap <out-mod> <in-mod> shell 命令。

选项包括

OUTPUT_VARIABLE <out-var>

将执行的模块命令的标准输出存储在指定变量中。

RESULT_VARIABLE <ret-var>

将执行的模块命令的返回代码存储在指定变量中。

env_module_list

检索当前加载的模块列表

env_module_list(<out-var>)

这在功能上等同于 module list shell 命令。结果以正确格式化的 CMake 分号分隔列表 变量形式存储在 <out-var> 中。

env_module_avail

检索可用模块列表

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

这在功能上等同于 module avail <mod-prefix> shell 命令。结果以正确格式化的 CMake 分号分隔列表 变量形式存储在 <out-var> 中。

示例

在以下示例中，此模块在 CTest 脚本中用于配置 Cray 编程环境的编译器和库。找到 Environment Modules 系统后，使用 env_module() 命令加载必要的编译器、MPI 和科学库以设置构建环境。环境变量 CRAYPE_LINK_TYPE 设置为 dynamic 以指定动态链接。这指示 Cray Linux 环境编译器驱动程序在运行时链接动态库，而不是在编译时链接静态库。因此，编译器生成动态链接的可执行文件。

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)

# ...