Environment variables for Arm Server and HPC tools

This topic describes the environment variables available through the Arm-provided environment modules.

Note: This topic describes the variables available with Arm Compiler for Linux, Arm Performance Libraries, and Arm Instruction Emulator (the Arm Linux toolchain tools). For information about the environment variables available in Arm Forge, see the Arm DDT, Arm MAP, and Arm Performance Reports environment variables.

To configure your environment to use an Arm Linux toolchain tool, you must load the modulefile for the appropriate tool. You might also want to include the environment variables in Makefiles, or possibly to customize these environment variables for individual sessions.

Administrators need to know which modulefiles are made available by an Arm Linux toolchain tool installation, 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 Linux tools are available here.

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.

Environment Modules and the Lmod Environment Module system are open-source packages that help 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 Linux 21.0 module on a SUSE 15 installation use:

module load <install_dir>/arm21/21.0

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 in Arm Compiler for Linux and Arm Instruction Emulator

The environment variables available through the Arm-provided environment modules are listed below.
The variables are separated into two groups: (1) variables that are useful to include in Makefiles, and (2) variables that are 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_LINUX_COMPILER, 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_LINUX_COMPILER
ARMPL
ARM_INSTRUCTION_EMULATOR
<MODULE_BASE_NAME>_DIR Tool installation directory. Set $PREFIX
ARMPL
ARM_INSTRUCTION_EMULATOR
<MODULE_BASE_NAME>_LIBRARIES Tool libraries directory. Append to path $PREFIX/lib$PREFIX/lib
ARM_LINUX_COMPILER
ARMPL
ARM_INSTRUCTION_EMULATOR
<MODULE_BASE_NAME>_INCLUDES The /includes directory path. Set $PREFIX/include
ARMPL

ARMPL_INCLUDES_<string>
            MP
            {ILP|INT}64
            {ILP|INT}64_MP
            LP64_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.
Directory for the 32-bit parallel library header files.
Set
 
$PREFIX/include_mp
$PREFIX/include_ilp64
$PREFIX/include_ilp64_mp
$PREFIX/include_lp64_mp

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 can be useful to set for Arm's Linux tools.

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

Module layout

The Arm Compiler for Linux modulefile is called 'arm<major-version>/<package-version></package-version></major-version>', where '<package-version></package-version>' is equivalent to '<major-version>.<minor-version>{.<patch-version>}</patch-version></minor-version></major-version>'. For example, 'arm21/21.0. Similarly, the version of GNU GCC that is included in the Arm Compiler for Linux package, takes a similar modufile naming scheme: 'gnu<major-version>/<package-version></package-version></major-version>'. For example, 'gnu10/10.2.0'.

The Arm Performance Libraries modufile is called 'armpl-AArch64{-SVE}/<package-version></package-version>'. Where '-SVE' indicates the SVE variant of the libraries. The Arm Performance Libraries modulefiles are located in the '/moduledeps/' directory of the Arm Compiler for Linux installation package, and are only available to load once either the Arm C/C++/Fortran Compiler or GNU GCC modulefile has been loaded.

The dependency between '/modulefiles/' and '/moduledeps/' is illustrated below:

├── moduledeps
│          ├── arm21
│          │    └── 21.0
│          │        ├── armpl-AArch64-SVE
│          │        │    └── 21.0
│          │        └── armpl-AArch64
│          │             └── 21.0
│          └── gnu10
│               └── 10.2.0
│                    ├── armpl-AArch64-SVE
│                    │    └── 21.0
│                    └── armpl-AArch64
│                         └── 21.0
└── modulefiles
     ├── arm21
     │    └── 21.0
     ├── binutils
     │    └── 10.2.0
     └── gnu10
          └── 10.2.0

Modulefile structure

A detailed description of the modulefile can be found in the following table:

 Content  Description
############################################################################
##
## arm21/21.0
##
##
## Copyright 2015-2021 Arm Limited. All rights reserved.
##
 Header section.
###########################################################################
# Module description                                                      #
###########################################################################

proc ModulesHelp { } {
  puts stderr " "
  puts stderr "This module loads the the Arm Linux Compiler 0 'arm0' toolchain."
  puts stderr "\nVersion 21.0\n"
}

module-whatis "Name: Arm Linux Compiler"
module-whatis "Version: 21.0"
module-whatis "Category: compiler, runtime support"
module-whatis "Description: This module loads the Arm Linux Compiler, providing armclang, armclang++, and armflang."
 ModuleHelp and module-whatis definitions.
###########################################################################
# Variable definitions #
###########################################################################
 Section to define module variables
# Base install directory of Arm Compiler for Linux
set install_prefix /opt/arm
 install_prefix is set at install time, to the base directory of each of the packages.
# Base module directory of Arm Linux Compiler
# This is worked out dynamically so that the modulefiles can be moved
# from the install directory set module_prefix [file dirname $ModulesCurrentModulefile]/../..
 Build-generated path to the module_prefix. Allows the module tree to be moved from its initial location, without breaking.
# Base directory of all dependent
modules set moduledeps $install_prefix/moduledeps
 The /moduledeps/ directory is used to find Arm Performance Libraries modulefiles.
# Licensing directories to search (colon-separated)
set license_paths    $install_prefix/licences:$install_prefix/licenses
 Sets the directory locations that Arm Compiler for Linux searches for valid licenses.
###########################################################################
# Main section #
###########################################################################
 The main section of the modulefile which sets the environment.
# Pull in some utility functions
source $module_prefix/moduleglobals/compiler_functions/21.0
 Pulls in functions that Arm Compiler for Linux uses throughout the module. Both GCC ('gcc') and Arm Compiler for Linux ('arm-linux-compiler') are sourced to avoid causing file ownership clashes, where multiple GCC versions might be available.
# Load modules on which this module depends
set dependencies [list \
binutils/10.2.0 \
]
depends-on $dependencies
 Loads all the dependencies of this module
# Install directory of this package
set package_prefix $install_prefix/arm-linux-compiler-21.0_Generic-AArch64_SUSE-15_aarch64-linux
 Sets the install location.
# Arm-specific environment variables
  setenv ARM_LINUX_COMPILER_DIR $package_prefix
setenv ARM_LINUX_COMPILER_BUILD <build-version>
setenv ARM_LINUX_COMPILER_INCLUDES $package_prefix/includes
append-path ARM_LINUX_COMPILER_LIBRARIES $package_prefix/lib
append-path ARM_HPC_COMPILER_LICENSE_SEARCH_PATH /opt/arm/licenses
append-path ARM_HPC_COMPILER_LICENSE_SEARCH_PATH /opt/arm/licences
 Arm-specific environment variables that are required for Arm Compiler for Linux and provide useful information.
# Standard environment variables

prepend-path PATH $package_prefix/bin
prepend-path CPATH $package_prefix/include
prepend-path LD_LIBRARY_PATH $package_prefix/lib
append-path LD_LIBRARY_PATH $package_prefix/lib/clang/<clang-version>/armpl_links/lib
prepend-path LIBRARY_PATH $package_prefix/lib prepend-path MANPATH $package_prefix/share/man
 Environment variables that are required for the operations of Arm Compiler for Linux, or that provide interfaces to the rest of the system.
# Make dependant modules available
prepend-path MODULEPATH $moduledeps/arm21/21.0
 Update the MODULEPATH so any dependent modules become available.
# Configure Licensing
# Arm Linux Compiler searches these directories for a valid product license
append-path     ARM_LICENSE_DIR                  $license_paths
 Configures the licensing directories that Arm Compiler for Linux searches for valid licenses.
if { [is-lmod] } {
# Lmod family
# When this modulefile is used with lmod, This ensures only one compiler is loaded at once
family "compiler"
}
 To correctly work with Environment Modules-based systems, the Lmod family declaration is placed behind an 'is_lmod' function call.
if { [is-lmod] } {
  module load clang-autocomplete/21.0
} else {
  # Source the bash-autocomplete.sh
  set SHELL [module-info shell]
  switch -- $SHELL {
    {sh} - {bash} {
      set autocomplete_file $package_prefix/share/utils/bash-autocomplete.sh
      if { [file exists $autocomplete_file] } {
        puts "source $autocomplete_file"
      }
    }
  }
}
 If the bash-autocomplete.sh script is available, add the script into the environment.

 

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 Linux modulefile, use:

module show <modulename>
For example, for SLES 15 installation of Arm Compiler for Linux 21.0:
module show arm21/21.0

the output is:

-------------------------------------------------------------------
<install-path>/modulefiles/arm21/21.0:

module-whatis   Name: Arm Linux Compiler
module-whatis   Version: 21.0
module-whatis   Category: compiler, runtime support
module-whatis   Description: This module loads the Arm Linux Compiler, providing armclang, armclang++, and armflang.
setenv          ARM_LINUX_COMPILER_DIR  <install-path>/arm-linux-compiler-21.0_Generic-AArch64_SUSE-15_aarch64-linux
setenv          ARM_LINUX_COMPILER_BUILD        <build-version>
setenv          ARM_LINUX_COMPILER_INCLUDES     <install-path>/arm-linux-compiler-21.0_Generic-AArch64_SUSE-15_aarch64-linux/includes
append-path     ARM_LINUX_COMPILER_LIBRARIES /<install-path>/arm-linux-compiler-21.0_Generic-AArch64_SUSE-15_aarch64-linux/lib
append-path     ARM_HPC_COMPILER_LICENSE_SEARCH_PATH <install-path>/licenses
append-path     ARM_HPC_COMPILER_LICENSE_SEARCH_PATH <install-path>/licences
prepend-path    PATH <install-path>/arm-linux-compiler-21.0_Generic-AArch64_SUSE-15_aarch64-linux/bin
prepend-path    CPATH <install-path>/arm-linux-compiler-21.0_Generic-AArch64_SUSE-15_aarch64-linux/include
prepend-path    LD_LIBRARY_PATH <install-path>/arm-linux-compiler-21.0_Generic-AArch64_SUSE-15_aarch64-linux/lib
append-path     LD_LIBRARY_PATH <install-path>/arm-linux-compiler-21.0_Generic-AArch64_SUSE-15_aarch64-linux/lib/clang/11.0.0/armpl_links/lib
prepend-path    LIBRARY_PATH <install-path>/arm-linux-compiler-21.0_Generic-AArch64_SUSE-15_aarch64-linux/lib
prepend-path    MANPATH <install-path>/arm-linux-compiler-21.0_Generic-AArch64_SUSE-15_aarch64-linux/share/man
prepend-path    MODULEPATH <install-path>/modulefiles/arm21/../../moduledeps/arm21/21.0
append-path     ARM_LICENSE_DIR <install-path>/licences:/<install-path>/licenses


Where, for example:
  • The environment variable ARM_LINUX_COMPILER_DIR is set to (setenv) /<install-path>/arm-linux-compiler-21.0_Generic-AArch64_SUSE-15_aarch64-linux.
  • The path /<install-path>/arm-linux-compiler-21.0_Generic-AArch64_SUSE-15_aarch64-linux/bin is prepended (prepend-path) to the environment variable PATH, to become /<install-path>/arm-linux-compiler-21.0_Generic-AArch64_SUSE-15_aarch64-linux/bin/PATH.
  • The path /<install-path>/arm-linux-compiler-21.0_Generic-AArch64_SUSE-15_aarch64-linux/lib is appended (append-path) to the environment variable ARM_LINUX_COMPILER_LIBRARIES, to become ARM_LINUX_COMPILER_LIBRARIES/<install-path>/arm-linux-compiler-21.0_Generic-AArch64_SUSE-15_aarch64-linux/lib.