Environment variables reference for Arm Server and HPC tools

Environment variables for Arm Server and HPC tools

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

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 22.0 module on a SUSE 15 installation use:

module load <install_dir>/acfl/22.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.

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.

Module layout

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

The Arm Performance Libraries modulefile is called 'armpl/<package-version>'. The Arm Performance Libraries modulefile is located in the '/moduledeps/' directory of the Arm Compiler for Linux installation package, and is 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
│          ├── acfl
│          │    └── 22.0
│          │         └── armpl
│          │             └── 22.0.0
│          │        
│          │             
│          └── gnu
│               └── 11.2.0
│                    └── armpl
│                        └── 22.0.0
│                    
│                         
└── modulefiles
     ├── acfl
     │    └── 22.0
     ├── binutils
     │    └── 11.2.0
     └── gnu
          └── 11.2.0

Modulefile structure

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

############################################################################
##
##        acfl
##
##
## Copyright 2015-2022 Arm Limited. All rights reserved.
##

###########################################################################
# Module description                                                      #
###########################################################################

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

module-whatis "Name: Arm Linux Compiler"
module-whatis "Version: 22.0"
module-whatis "Category: compiler, runtime support"
module-whatis "Description: This module loads the Arm Linux Compiler, providing armclang, armclang++, and armflang."

###########################################################################
# Variable definitions                                                    #
###########################################################################

# Base install directory of Arm Compiler for Linux
set install_prefix /opt/arm

# 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]/../..

# Base directory of all dependent
modules set moduledeps $install_prefix/moduledeps

# Licensing directories to search (colon-separated)
set license_paths    $install_prefix/licences:$install_prefix/licenses

###########################################################################
# Main section                                                            #
###########################################################################

# Pull in some utility functions
source $module_prefix/moduleglobals/compiler_functions/22.0

# Load modules on which this module depends
set dependencies [list \ 
    binutils/11.2.0 \
    ]
depends-on $dependencies

# Install directory of this package

set package_prefix $install_prefix/arm-linux-compiler-22.0_Generic-AArch64_SUSE-15_aarch64-linux

# 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

# 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

# Make dependant modules available
prepend-path MODULEPATH $moduledeps/acfl/22.0

# Configure Licensing
# Arm Linux Compiler searches these directories for a valid product license
append-path     ARM_LICENSE_DIR                  $license_paths

if { [is-lmod] } {
 # Lmod family
 # When this modulefile is used with lmod, This ensures only one compiler is loaded at once
 family "compiler"
}

if { [is-lmod] } {
  module load clang-autocomplete/22.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"
      }
    }
  }
}

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>

module show acfl/22.0

the output is:

-------------------------------------------------------------------
<install-path>/modulefiles/acfl/22.0:

module-whatis   Name: Arm Linux Compiler
module-whatis   Version: 22.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-22.0_Generic-AArch64_SUSE-15_aarch64-linux
setenv          ARM_LINUX_COMPILER_BUILD        <build-version>
setenv          ARM_LINUX_COMPILER_INCLUDES     <install-path>/arm-linux-compiler-22.0_Generic-AArch64_SUSE-15_aarch64-linux/includes
append-path     ARM_LINUX_COMPILER_LIBRARIES /<install-path>/arm-linux-compiler-22.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-22.0_Generic-AArch64_SUSE-15_aarch64-linux/bin
prepend-path    CPATH <install-path>/arm-linux-compiler-22.0_Generic-AArch64_SUSE-15_aarch64-linux/include
prepend-path    LD_LIBRARY_PATH <install-path>/arm-linux-compiler-22.0_Generic-AArch64_SUSE-15_aarch64-linux/lib
append-path     LD_LIBRARY_PATH <install-path>/arm-linux-compiler-22.0_Generic-AArch64_SUSE-15_aarch64-linux/lib/clang/13.0.0/armpl_links/lib
prepend-path    LIBRARY_PATH <install-path>/arm-linux-compiler-22.0_Generic-AArch64_SUSE-15_aarch64-linux/lib
prepend-path    MANPATH <install-path>/arm-linux-compiler-22.0_Generic-AArch64_SUSE-15_aarch64-linux/share/man
prepend-path    MODULEPATH <install-path>/modulefiles/acfl/../../moduledeps/acfl/22.0
append-path     ARM_LICENSE_DIR <install-path>/licences:/<install-path>/licenses

• The environment variable ARM_LINUX_COMPILER_DIR is set to (setenv) /<install-path>/arm-linux-compiler-22.0_Generic-AArch64_SUSE-15_aarch64-linux.
• The path /<install-path>/arm-linux-compiler-22.0_Generic-AArch64_SUSE-15_aarch64-linux/bin is prepended (prepend-path) to the environment variable PATH, to become /<install-path>/arm-linux-compiler-22.0_Generic-AArch64_SUSE-15_aarch64-linux/bin/PATH.
• The path /<install-path>/arm-linux-compiler-22.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-22.0_Generic-AArch64_SUSE-15_aarch64-linux/lib.