Environment variables used in the Arm suite of tools for HPC

This topic will describe the environment variables provided by the Arm-provided environment modules.

User types

Cluster users need to load modulefiles to configure their environment before using a tool from the Arm suite of HPC tools. Some more experienced users may also want to include environment variables in Makefiles, or possibly to customize these environment variables for individual sessions.

Administrators need to know which modulefiles are made available by installation of an Arm HPC tool, in order to enable them to be made visible and available for users to use. Installation instructions for each tool within the Arm suite of HPC tools are available here.

Background information on environment variables for cluster users

What are environment variables and modules?

An environment variable is a dynamic object on a computer that stores a value, which in turn can be referenced by one or more software programs. They form part of the environment in which a process runs. For example, a running process may query an environment variable to request the directory structure to find or store information.

Users can set, prepend or append an environment variable:

  • setenv <EnvironmentVariable> <Value> - sets environment variable to a value
  • prepend-path <EnvironmentVariable> <Value> - prepends a value to an environment variable, such that it becomes: value/environment_variable.
  • append-path <EnvironmentVariable> <Value> - appends a value to an environment variable, such that it becomes: environment_variable/value.

Environment Modules is an open-source package that helps users manage and modify their environment during a session, through modulefiles. A modulefile contains the necessary information to configure a shell session for an application, typically by containing instructions to alter or set environment variables. Modulefiles are interpreted using the module command. Common interpretations involve loading, unloading or switching using load <modulefile>, unload <modulefile> and switch <modulefile1> <modulefile2>, respectively. For example, to load the Arm Compiler for HPC module, use:

$ module load <user_directory>/Generic-AArch64/SUSE/12/arm-hpc-compiler/1.3

Using environment variables in Makefiles

Arm makes environment variables available to establish best practices and help users write robust scripts.

It is good practice to use these Arm-provided environment variables in Makefiles rather than setting absolute paths that may change in future releases, for example:

# Location of ARMPL installation
ARMPLDIR := ${ARMPL_DIR}

 

Note for Administrators

Administrators should ensure that the Arm modulefiles receive the correct file permissions, enabling cluster users to load the appropriate module for their session, or to include them in their job submission scripts. You should also notify cluster users of the necessary Arm module to load in order to use an Arm tool.

Environment variables used in the Arm suite of HPC tools

The environment variables provided by the Arm-provided environment modules are given below.
They are separated into those users may find useful to include in Makefiles, and those that are additionally available for customization.

The following generalizations are used for denoting tool names, numbers and paths:

  • <MODULE_BASE_NAME> is the tool name, for example: ARM_HPC_COMPILER, ARM_CODE_ADVISOR, ARMPL or ARM_INSTRUCTION_EMULATOR.
  • <NUMBER> is the tool build number.
  • $PREFIX is the path to the installation location of the given component.

Useful environment variables to include in a Makefile

The following table summarizes useful Arm-provided environment variables to include in a Makefile.

Tool (<MODULE_BASE_NAME>)
Environment Variable Description Action Value
ARM_CODE_ADVISOR
ARM_HPC_COMPILER
ARMPL
ARM_INSTRUCTION_EMULATOR
<MODULE_BASE_NAME>_DIR Tool installation directory. setenv $PREFIX
ARM_HPC_COMPILER
ARMPL
ARM_INSTRUCTION_EMULATOR
<MODULE_BASE_NAME>_LIBRARIES Tool libraries directory. append-path $PREFIX/lib$PREFIX/lib
ARM_HPC_COMPILER
ARMPL
ARM_INSTRUCTION_EMULATOR
<MODULE_BASE_NAME>_INCLUDES The /includes directory path. setenv $PREFIX/include
ARMPL ARMPL_INCLUDES_<string>
                                MP
               INT64
               INT64_MP
 
Directory for the parallel library header files.
Directory for the 64-bit integer library header files.
Directory for the 64-bit parallel library header files.
setenv
 
$PREFIX/include_mp
$PREFIX/include_int64
$PREFIX/include_int64_mp
ARM_CODE_ADVISOR
ARM_HPC_COMPILER
ARMPL
ARM_INSTRUCTION_EMULATOR
<MODULE_BASE_NAME>_BUILD <NUMBER> Tool module version. setenv N/A

Note: Arm Performance Libraries uses three further environment variables (final table entry) to locate specific parallel libraries.

Utility environment variables

The following table summarizes the additional environment variables which are useful to set for Arm HPC tools.

Tool (<MODULE_BASE_NAME>)
Environment Variable Description Action Value
ARM_CODE_ADVISOR
ARM_HPC_COMPILER
ARM_INSTRUCTION_EMULATOR
PATH Default tool path.
prepend-path $PREFIX/bin
ARM_HPC_COMPILER
ARMPL
CPATH Environment variable some compilers use
to set their /include directory.
prepend-path $PREFIX/include
ARM_HPC_COMPILER
ARMPL
ARM_INSTRUCTION_EMULATOR
LD_LIBRARY_PATH Dynamic libraries. prepend-path $PREFIX/lib

 

Interpretation of an example modulefile

The command module show <modulefile> will interpret and display the environment variable information contained in that modulefile.

For example, to show which environment variables are set by the Arm Compiler for HPC modulefile, use:

module show Generic-AArch64/SUSE/12/arm-hpc-compiler/1.3

to give the output:

-------------------------------------------------------------------
<user_directory>/Generic-AArch64/SUSE/12/arm-hpc-compiler/1.3:
module load      Generic-AArch64/SUSE/12/gcc/6.1.0 setenv           ARM_HPC_COMPILER_DIR /<user_directory>/arm-hpc-compiler-1.3_Generic-AArch64_SUSE-12_aarch64-linux prepend-path     PATH /<user_directory>/arm-hpc-compiler-1.3_Generic-AArch64_SUSE-12_aarch64-linux/bin setenv           ARM_HPC_COMPILER_BUILD 32 setenv           ARM_HPC_COMPILER_INCLUDES /<user_directory>/arm-hpc-compiler-1.3_Generic-AArch64_SUSE-12_aarch64-linux/include prepend-path     CPATH /<user_directory>/arm-hpc-compiler-1.3_Generic-AArch64_SUSE-12_aarch64-linux/include prepend-path     LD_LIBRARY_PATH /<user_directory>/arm-hpc-compiler-1.3_Generic-AArch64_SUSE-12_aarch64-linux/lib append-path      ARM_HPC_COMPILER_LIBRARIES /<user_directory>/arm-hpc-compiler-1.3_Generic-AArch64_SUSE-12_aarch64-linux/lib prepend-path     MANPATH /<user_directory>/arm-hpc-compiler-1.3_Generic-AArch64_SUSE-12_aarch64-linux/share/man module-whatis    ARM Compiler 1.3.

 Where, for example:

  • The environment variable ARM_HPC_COMPILER_DIR is set to (setenv) /<user_directory>/arm-hpc-compiler-18.1_Generic-AArch64_Ubuntu-14.04_aarch64-linux.

  • The path /<user_directory>/arm-hpc-compiler-18.1_Generic-AArch64_Ubuntu-14.04_aarch64-linux/bin is prepended (prepend-path) to the environment variable PATH, to become /<user_directory>/arm-hpc-compiler-18.1_Generic-AArch64_Ubuntu-14.04_aarch64-linux/bin/PATH.

  • The path /<user_directory>/arm-hpc-compiler-18.1_Generic-AArch64_Ubuntu-14.04_aarch64-linux/lib is appended (append-path) to the environment variable ARM_HPC_COMPILER_LIBRARIES, to become ARM_HPC_COMPILER_LIBRARIES/<user_directory>/arm-hpc-compiler-18.1_Generic-AArch64_Ubuntu-14.04_aarch64-linux/lib.