Programming Guide

Contents

Use Modulefiles with Linux*

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).
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 4.1
  • Tcl version 8.4
  • Lmod version 8.2.10
Test which version is installed on your system using the following command:
module --version
Each of the modulefiles will automatically verify that the Tcl version on your system is adequate when it runs.
The oneAPI modulefile scripts are found in a
modulefiles
folder located inside each component folder (similar to how the individual vars scripts are located). For example, in a default installation, the
ipp
modulefiles script(s) are located in the
/opt/intel/ipp/latest/modulefiles/
directory.
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. 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 the oneAPI installation and organizes them into a single directory of folders. Those folders are named for each installed oneAPI component that includes one or more modulefiles.
Each of these component-named folders contains symlinks pointing to all of the modulefiles that are provided by that oneAPI component. These symlinks are organized as versioned modulefiles. Each component folder includes (at minimum) a "latest" version modulefile that will be selected, by default, when loading a component modulefile without specifying a version label.
The default name for the top-level directory of oneAPI modulefiles is
modulefiles
and is located in the oneAPI installation folder. For example:
/opt/intel/oneapi/modulefiles

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. Enter
modulefiles-setup.sh --help
for more information about this and other
modulefiles-setup.sh
script options.
After the
modulefiles-setup.sh
script has been run, an organization like the following is created in the top-level
modulefiles
folder:
[oneapi_root] - [modulefiles] - - [compiler] - - - [1.0] -> [oneapi_root/compiler/1.0/modulefiles/compiler] # symlink named 1.0 points to compiler modulefile - - [compiler32] - - - [1.0] -> [oneapi_root/compiler/1.0/modulefiles/compiler32] # symlink named 1.0 points to compiler32 modulefile - - [ipp] - - - [1.1] -> [oneapi_root/ipp/1.1/modulefiles/ipp] - - - [1.2] -> [oneapi_root/ipp/1.2/modulefiles/ipp] - - [ipp32] - - - [1.1] -> [oneapi_root/ipp/1.1/modulefiles/ipp32] - - - [1.2] -> [oneapi_root/ipp/1.2/modulefiles/ipp32] etc…
Now, update the MODULEFILESPATH to point to this new
modulefiles
folder.

Installing the
module
Utility onto Your System

The instructions below will help 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/.
$ sudo apt update $ sudo apt install tcl $ sudo apt install environment-modules
Confirm that the local copy of
tclsh
is new enough (as of this writing, version 8.4 or later is required):
$ tclsh % puts $tcl_version 8.6 % exit
To test the
module
installation, initialize the
module
alias.
$ source /usr/share/modules/init/sh $ module
Initialization for Bourne-compatible shells should work with the
source
command shown above. Additional shell-specific init scripts are provided in the
/usr/share/modules/init/
folder. See that folder and the initialization section in
man module
for more details.
Include sourcing the
module
alias init script (
.../modules/init/sh
) in one of the startup scripts to ensure the module command is always available. 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
    ) on to the system
  • sourced the
    .../modules/init/sh
    (or equivalent) module init command
  • installed the oneAPI toolkits required for your oneAPI development
$ 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 loaded $ module unload tbb # removes tbb/X.Y changes from the environment $ module list # should no longer list the tbb/X.Y env var module
Before the unload step, use the
env
command to inspect the environment and look for the changes that were made by the modulefile you loaded. For example, if you loaded the
tbb modulefile
, the command will show you some of the env changes made by that
modulefile
(inspect the
modulefile
to see all of the changes it will make):
$ env | grep -i "intel"
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 a oneAPI product does 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 installer for oneAPI toolkits applies version folders to individual oneAPI tools and libraries in the form of versioned subdirectories inside the top-level directory for each tool or library. These versioned component folders are used to create the versioned
modulefiles
. This is essentially what the
modulefiles-setup.sh
script does; it organizes the symbolic links it creates in the top-level
$(ONEAPI_ROOT)/modulefiles
folder as
<modulefile-name>/version
, so the respective
modulefiles
can be referenced by version when using the module command.
$ module avail ---------------- modulefiles ----------------- ipp/1.1 ipp/1.2 compiler/1.0 compiler32/1.0

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

Understanding How the
modulefiles
are Written when using oneAPI

Symbolic links are used by the
modulefiles-setup.sh
script to gather all of the available tool and library
modulefiles
into a single top-level
modulefiles
folder for oneAPI. This means that the
modulefiles
for oneAPI are not moved or touched. As a consequence of this approach, the
${ModulesCurrentModulefile}
variable points to a
symlink
to each
modulefile
, not to the actual
modulefile
located in the respective installation folders. Because of this, these
modulefiles
are
not
able to reference other folders or files within the modulefile's component folder, because of the symlinks.
Thus, each modulefile for oneAPI uses a statement such as:
[ file readlink ${ModulesCurrentModulefile} ]
to get a reference to the original
modulefile
located in the respective install directory.
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 and include checks to prevent you from inadvertently loading two versions of the same
modulefile
.

Use of the
module load
Command by
modulefiles

Several of the
modulefiles
use the
module load
command to ensure that any required dependent modules are also loaded. There is no attempt to specify the version of those dependent modulefiles. This means that a specific dependent module can be manually preloaded prior to loading the module that requires that dependent module. If you do not preload a dependent module, the latest available version is loaded.
This is by design, because it gives the flexibility to control the environment. For example, you may have installed an updated version of a library that you want to test against a previous version of the compiler. Perhaps the updated library has a bug fix and you are not interested in changing the version of any other libraries in your build. If the dependent modulefiles were hard-coded to require a specific dependent version of this library, you could not perform such a test.
If a dependent
module load
cannot be satisfied, the currently loading module file will be terminated and no changes will be made to your environment.

Product and Performance Information

1

Performance varies by use, configuration and other factors. Learn more at www.Intel.com/PerformanceIndex.