Use Environment Modulefiles with Linux*
Modulefiles can be used to setup your environment, allowing you to specify the precise versions of components you wish to use.
There are two methods for customizing your environment variables in Linux*:
Use modulefiles, as described on this page
Most of the component tool folders contain one or more modulefile scripts that configure the environment variables needed by that component to support development work. Modulefiles are an alternative to using the setvars.sh script to set up the development environment. Because modulefiles do not support arguments, multiple modulefiles are available for oneAPI tools and libraries that support multiple configurations (such as a 32-bit configuration and a 64-bit configuration).
NOTE:
The modulefiles provided with the Intel oneAPI toolkits are compatible with the Tcl Environment Modules (Tmod) and Lua Environment Modules (Lmod). The following minimum versions are supported:
Tmod version 4.2
Tcl version 8.4
Lmod version 8.7.44
Test which version of Tmod is installed on your system using the following command:
module --versionTest which version of Tcl is installed on your system with the following commands:
$ tclsh
$ puts $tcl_version
8.6
$ exitEach modulefile automatically verifies the Tcl version on your system when it runs, but it does not test the version of Tmod on your system.
If your modulefile version is not supported (older than 4.2), a workaround may be possible. See Using Environment Modules with Intel Development Tools for more details.
As of the oneAPI 2024.0 release, the icc modulefile has been removed because the Intel® Classic Compiler has been discontinued. Please use the Intel® oneAPI C/C++ Complier (icx and icpx) instead. The ifort compiler is still available, but you are encouraged to use the equivalent Intel® oneAPI Fortran Compiler (ifx).
Modulefile Auto-Load
The “auto-load” feature in Environment Modules (Tmod) was introduced in version 4.2 of Modulefiles as an experimental feature. The auto-load feature was elevated to a standard feature in the 5.0 release. With the 2024.0 release of Intel oneAPI toolkits, automatic loading of dependent modulefiles now relies on the auto-load feature. If you are using version 4.x of Environment Modules, the auto-load feature of dependent modulefiles (those referenced by the prereq command) is disabled by default. Version 5.x enables auto-load of dependent modules by default.
To control the auto-load function, the MODULES_AUTO_HANDLING environment variable can be used to direct modulefiles to auto-load all referenced prereq modulefiles. This behavior can be temporarily overridden by using the --auto command-line option.
MODULES_AUTO_HANDLING=1 enables auto-loading via the prereq command.
MODULES_AUTO_HANDLING=0 disables auto-loading via the prereq command.
If you experience an error message with the text HINT: the following module must be loaded first, you may need to either add the MODULES_AUTO_HANDLING=1 environment variable or configure your Modules Environment to set the auto_handling configuration to “1” in order to enable automatic loading of prereq commands.
$ module -V
Modules Release 4.4.1 (2020-01-03)
$ module use /opt/intel/oneapi/2024.1/etc/modulefiles/
$ module load compiler
Loading compiler/2024.1.0
ERROR: compiler/2024.1.0 cannot be loaded due to missing prereq.
HINT: the following module must be loaded first: tbbThis issue can be resolved using one of the methods below.
Run command to configure auto_handling to be 1:
$ module config auto_handling 1
$ module load compiler
Loading compiler/2024.1.0
Loading requirement: tbb/2021.12 compiler-rt/2024.1.0 oclfpga/2024.1.0Set MODULES_AUTO_HANDLING=1:
$ export MODULES_AUTO_HANDLING=1
module load compiler
Loading compiler/2024.1.0
Loading requirement: tbb/2021.12 compiler-rt/2024.1.0 oclfpga/2024.1.0Load dependencies manually:
$ module load tbb compiler-rt oclfpga compiler --verbose
Loading tbb/2021.12
Loading compiler-rt/2024.1.0
Loading oclfpga/2024.1.0
Loading compiler/2024.1.0For more details, see MODULES_AUTO_HANDLING.
Load Everything Modulefile
As of the 2024.0 release, there is a “load everything” modulefile named oneapi located in intel/oneapi/2024.0. The oneapi modulefile loads all available modulefiles and ensures that all of the prereq modules are also loaded in the right order without relying on the MODULES_AUTO_HANDLING=1 environment variable described above. It should be usable with the Lmod modulefiles system. If your installation does not include the intel/oneapi/2024.0 directory install the product with a toolkit installer, such as the Intel oneAPI Base Toolkit and/or the Intel® HPC Toolkit (use the customize option if you do not wish to install the entire toolkit). The key feature of the oneapi modulefile is that it only loads those modulefiles that are specific to the toolkit version (e.g., intel/oneapi/2024.0 or intel/oneapi/2024.1, etc.).
Create a Custom Modulefile To Load Specific Modulefiles
To further control which modulefiles are loaded, you can create a “meta” modulefile that loads a specific set of modulefiles (and their prerequisites). For example, if you have a need for an environment that only sets up the Intel compiler, you might create something similar to this:
module load tbb
module load compiler-rt
module load oclfpga
module load compilerLocation of Modulefile Scripts
The oneAPI modulefile scripts are located in a modulefiles directory inside each component folder (similar to where the individual vars scripts are located). For example, in a default installation for 2024.0 and later oneAPI Toolkit releases, the compiler modulefiles script(s) are in the /opt/intel/compiler/<component-version>/etc/modulefiles/ directory. In 2023 or earlier oneAPI Toolkit releases, the compiler modulefiles script(s) are in the /opt/intel/compiler/<component-version>/modulefiles/ directory.
NOTE:
<component-version> is the version number of a component (a library or tool). You may have multiple components installed side-by-side on your development system (e.g., compiler/2023.1, compiler/2023.2, compiler/2024.0, etc.). The Toolkit version, which is the version of a collection of components, may be different than the component version that was delivered with that Toolkit.
Due to how oneAPI component folders are organized on the disk, it can be difficult to use the oneAPI modulefiles directly where they are installed. Therefore, a special modulefiles-setup.sh script is provided in the oneAPI installation folder to make it easier to work with the oneAPI modulefiles. In a default installation, that setup script is located here: /opt/intel/oneapi/modulefiles-setup.sh
The modulefiles-setup.sh script locates all modulefile scripts that are part of your oneAPI installation and organizes them into a single directory of versioned modulefiles scripts.
Each of these versioned modulefiles scripts is a symlink that points to the modulefiles located by the modulefiles-setup.sh script. Each component folder includes (at minimum) a “latest” version modulefile that will be selected, by default, when loading a modulefile without specifying a version label. If you use the --ignore-latest option when running the modulefiles-setup.sh script, the modulefile with the highest version (per semver rules) will be loaded if no version is specified by the module_load command.
Alternatively, on a 2024.0 or later toolkit installation, within the Unified Directory Layout, you will find a modulefiles folder that contains all the component modulefiles associated with that toolkit version. For example, if you install the 2024.0 Intel® oneAPI Base Toolkit into the default location, you will find a preconfigured and ready to use collection of the 2024.0 Base Toolkit modulefiles located in the /opt/intel/oneapi/2024.0/etc/modulefiles folder, which you can add to your modulefile setup by adding that folder to your MODULEPATH environment variable, or by running the module use command and specify that pre-configured modulefile folder. Installing the 2024.0 Intel® HPC Toolkit will add additional modulefiles to that same location, because the two toolkits are of the same version (in this case, 2024.0).
Within the pre-configured toolkit modulefiles folder there is a modulefile named oneapi that will load the 64-bit component modulefiles that belong to that toolkit version. The oneapi modulefile is a convenience modulefile, it is not required to use the individual modulefiles. Also, the oneapi modulefile will not work as expected within a folder created by the modulefiles-setup.sh script.
Creating the modulefiles Directory
Run the modulefiles-setup.sh script.
By default, the modulefiles-setup.sh script creates a folder named modulefiles in the oneAPI toolkit installation folder. If your oneAPI installation folder is not writeable, use the --output-dir=<path-to-folder> option to create the modulefiles folder in a writeable location. Run modulefiles-setup.sh --help for more information about this and other modulefiles-setup.sh script options.
Running the modulefiles-setup.sh script creates the modulefiles output folder, which is organized like the following example (the precise list of modulefiles depends on your installation). In this example, there is one modulefile for configuring the Intel® Advisor environment and two modulefiles for configuring the compiler environment (the compiler modulefile configures the environment for all Intel compilers). If you follow the latest symlinks, they point to the highest version modulefile, per semver rules.
Update your MODULEPATH environment variable to include to the modulefiles output folder that was created by the modulefiles-setup.sh script or run the module use <folder_name> command.
Installing the Tcl Modulefiles Environment onto Your System
The instructions below will help you quickly get started with the Environment Modules utility on Ubuntu*. For full details regarding installation and configuration of the module utility, see http://modules.sourceforge.net/.
Set your environment:
$ sudo apt update
$ sudo apt install tcl
$ sudo apt install environment-modulesConfirm that the local copy of tclsh is new enough (see the beginning of this page for a list of supported versions):
$ echo 'puts [info patchlevel] ; exit 0' | tclsh
8.6.8Test the module installation by initializing the module alias.
$ source /usr/share/modules/init/sh
$ module
NOTE:
Initialization of the Modulefiles environment in POSIX-compatible shells should work with the source command shown above. However, the precise location and name of the modulefiles init folder does vary with the Linux distribution. Most installations of Environment Modules will automatically source the modulefiles initialization script: /etc/profile.d/modules.sh. You can test for proper initialization of the module command by typing the module --version command which should result in a response similar to: Modules Release 4.4.1 (2020-01-03). At this point, the system should be ready to use the module command as shown in the following section.
Getting Started with the modulefiles-setup.sh Script
The following example assumes you have:
installed tclsh on to the Linux development system
installed the Environment Modules utility (i.e., module) onto the system
sourced the .../modules/init/sh (or equivalent) module init command
installed the oneAPI toolkits required for your oneAPI development
Navigate to the install directory, and load tbb:
$ cd <oneapi-root-folder> # cd to the oneapi_root install directory
$ ./modulefiles-setup.sh # run the modulefiles setup script
$ module use modulefiles # use the modulefiles folder created above
$ module avail # will show tbb/X.Y, etc.
$ module load tbb # loads tbb/X.Y module
$ module list # should list the tbb/X.Y module you just loadedUse the env command to inspect the environment and look for the changes that were made by the modulefile you loaded.
$ env | grep -i "intel"For example, if you loaded the tbb modulefile, the command will show you some of the env changes made by that modulefile.
Unload tbb:
$ module unload tbb # removes tbb/X.Y changes from the environment
$ module list # should no longer list the tbb/X.Y env var module
NOTE:
A modulefile is a script, but it does not need to have the ‘x’ (executable) permission set, because it is loaded and interpreted by the “module” interpreter that is installed and maintained by the end-user. Installation of the oneAPI toolkits do not include the modulefile interpreter. It must be installed separately. Likewise, modulefiles do not require that the ‘w’ permission be set, but they must be readable (ideally, the ‘r’ permission is set for all users).
Versioning
The oneAPI toolkit installer uses version folders to allow oneAPI tools and libraries to exist in a side-by-side layout. These versioned component folders are used by the modulefiles-setup.sh script to create the versioned modulefiles. The script organizes the symbolic links it creates in the modulefiles output folder as <modulefile-name>/version, so that each respective modulefile can be referenced by version when using the module command.
$ module avail
---------------- modulefiles -----------------
ipp/1.1 ipp/1.2 compiler/1.0 compiler32/1.0Multiple modulefiles
A tool or library may provide multiple modulefiles within its modulefiles folder. Each becomes a loadable module. They will be assigned a version per the component folder from which they were extracted.
How modulefiles Are Set Up in oneAPI
Symbolic links are used by the modulefiles-setup.sh script to gather all the available modulefiles into a single modulefiles folder. The actual modulefile scripts are not moved or modified. The ${ModulesCurrentModulefile} variable points to the symlink to each modulefile, not to the actual modulefile located in the respective installation folders. To determine the full path to the real modulefiles, each modulefile includes a statement simliar to this:
[ file normalize ${scriptpath} ]to get a direct reference to the original modulefile in the product install directory. This is done because the install location might be customized and is therefore unknown at runtime. The actual modulefile cannot be moved outside of the installed location, otherwise it will not be able to locate the absolute path to the library or application that it must configure.
For a better understanding, review the modulefiles included with the installation. Most include comments explaining how they resolve symlink references to a real file, as well as parsing the version number (and version directory). They also include checks to insure that the installed Tcl is an appropriate version level.
Additional Resources
For more information about modulefiles, see: