ARL DSRC Modules Guide

1. Introduction

Modules provides an easy mechanism for dynamically updating a user's environment, especially the $PATH, $MANPATH, $NLSPATH, and $LD_LIBRARY_PATH environment variables to name a few. Each module contains the information needed to configure the shell for an application or library. To perform this in the current shell, the modules package uses the shell's eval 'command' mechanism for running a program that outputs shell commands and then executes them. There are some limitations and preferred ways for setting up the modules environment because of this implementation. Modulefiles may be shared by many users on a system and users may have their own collection to supplement or replace the existing shared modulefiles.

2. Module Commands

module help [modulefile...]
Print the usage of each sub-command. If an argument is given, print the Module specific help information for the modulefile.
module load modulefile [modulefile...]
Load modulefile into the shell environment.

module unload modulefile [modulefile...]
Remove modulefile from the shell environment.

module switch modulefile1 modulefile2
Switch loaded modulefile1 with modulefile2.

module display modulefile [modulefile...]
The display sub-command will list the full path of the modulefile and all (or most) of the environment changes the modulefile will make if loaded.

module list
List loaded modules.

module avail [path...]
List all available modulefiles in the current $MODULEPATH. All directories in the $MODULEPATH are recursively searched for files containing the modulefile magic cookie.

module use [-a|--append] directory [directory...]
Prepend directory to the $MODULEPATH environment variable. The --append flag will append the directory to $MODULEPATH.

module unuse directory [directory...]
Remove directory from the $MODULEPATH environment variable.

module update
Attempt to reload all loaded modulefiles. The environment will be reconfigured to match the saved ${HOME}/.modulesbeginenv and the modulefiles will be reloaded.

module clear
Force the Modules Package to believe that no modules are currently loaded.

module purge
Unload all loaded modulefiles.

3. Types of Modules Available

When a user enters the module avail command a list of all the modules currently available to the user for loading are displayed. This list is broken down into four categories: COTS, Unsupported, Modules, and Devel.

COTS modules initialize access to vendor codes installed and maintained by ARL DSRC staff. Most of these codes are available to all users. A few of these packages are ITAR controlled, and can only be accessed after requesting to be added the UNIX group under which the code was built. There are sample scripts in the Sample Code Repository ($SAMPLES_HOME) that provide examples of how to run most of these codes on the system.

Unsupported modules initialize access to codes that have been installed and are maintained by individual users who are not part of the ARL DSRC staff. These codes are installed in an area provided to the owner to allow access to them by more than the owner of the code. However, access is usually, but not always, group controlled.

The modules in the Modules area are the modules that are part of a user's default login environment and are automatically loaded as part of the login process.

Devel modules initialize access to program development tools such as compilers, parallel programming libraries, and program development libraries. You can find samples and descriptions of how to use the various compilers and libraries in the Sample Code Repository ($SAMPLES_HOME).

4. Creating Your Own Modules

In addition to the modules that we provide, you may also create your own custom modules. A thorough explanation of module creation is beyond the scope of this document, but the following information may help you get started.

First, you will need to create your module file. Module files are written in the Tool Command Language (TCL) using a simple text editor such as vi or notepad. For a discussion of the TCL syntax and available TCL commands, see the modulefile man page.

The following is an example of a simple module file:

#%Module
proc ModulesHelp { } {
   puts stderr "This modulefile defines the system paths and"
   puts stderr "environment variables needed to use the"
   puts stderr "APP software package"
   puts stderr ""
}
    
set APP_CURPATH /my_home_directory/my_modules/app
setenv APP_HOME $APP_CURPATH
prepend-path PATH $APP_CURPATH/bin

Once your module file is completed, you will need to modify the $MODULEPATH environment variable to include the path to the directory containing your module files. To accomplish this, do the following:

module use --append ${HOME}/my_modules

Your modules should then show up in the output of the module avail command and be available for your use.

To remove your module's path from the $MODULEPATH environment variable, do the following:

module unuse ${HOME}/my_modules