1. Introduction

Software modules are a very convenient way to set needed environment variables and include necessary directories in your path so commands for particular applications can be found. Our systems use "modules" to initialize your environment with COTS application software, system commands and libraries, compiler suites, environment variables, and batch system commands.

Module information is stored in specially formatted files called "modulefiles" or simply "modules." These files can be loaded and unloaded to tailor your shell environment to specific needs. Several modules are loaded automatically as soon as you log in. You can modify your default environment manually using the module command.

In addition to modules we provide, you can also create your own modules to share with other users or to supplement or replace the existing shared modules if desired.

2. Module Commands

The module command is the primary means of managing the modules loaded in your environment. There are a number of subcommands to the module command that allow you to see what is available and what is currently loaded, and to modify your selections as needed.

module help [module...]

Print the usage of each subcommand. If an argument is given, print the module-specific help information for that module.

module load module [module...]

Load module into the shell environment. If you are attempting to replace a module that is currently loaded, use the swap (or switch) subcommand instead of load.

module unload module [module...]

Remove module from the shell environment.

module swap module1 module2

Unload module1 and load module2. The swap subcommand is synonymous with the switch subcommand, which you may see in some documentation.

module show module [module...]

The show subcommand will list the full path of the module and all (or most) of the environment changes the module will make if loaded. The show subcommand is synonymous with the display command, which you may see in some documentation.

module list

List the modules that are currently loaded.

module avail [path...]

List all available modules in the current $MODULEPATH. All directories in the $MODULEPATH are recursively searched for modules. If the path argument is given, then only the modules available within that specific directory tree are listed.

module use [-a |--append] directory [directory...]

By default, this subcommand prepends the directory to the $MODULEPATH environment variable. If the -a or --append argument is used, then the directory will be appended to $MODULEPATH.

module unuse directory [directory...]

Remove the directory from the $MODULEPATH environment variable.

module update

Attempt to reload all loaded modules. The environment will be reconfigured to match the saved $HOME/.modulesbeginenv and the modules will be reloaded.

module purge

Unload all loaded modules.

3. Types of Modules Available

We provide two types of modules on our systems: system modules and application modules. In general, module names consist of a base name + a version number, for instance abaqus/2023. Sometimes, there may be multiple versions of the same module available for use. In such cases, one version will always be designated as the default. To see these, use the module avail command and note the modules with (default) at the end of the module name. If there is only one version of a particular module available, then (default) may not be present in the module name, but it is still treated as the default version. To load the default version of a module, use the module load command and simply omit the version number from the module name, for instance module load abaqus.

3.1. System Modules

System modules are provided by the system vendor and include programming environments, libraries, debuggers, profiling tools, system support, and batch schedulers. In the output of the module avail command, these modules are grouped under /app/modulefiles on all systems at Navy DSRC.

3.2. Application Modules

Application modules are created by our support staff to configure your environment to run specific applications. These are grouped under /app/modulefiles/apps on all systems at Navy DSRC. As a rule-of-thumb, we provide at least two versions of each application module: the current and previous default versions. In some cases, we also provide the latest release, although it may not yet be the default.

4. Creating Your Own Modules

In addition to the modules 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