Ubuntu Manpage: module - command interface to the Modules package

Provided by: environment-modules_3.2.10-9_amd64

NAME

       module - command interface to the Modules package

SYNOPSIS

       module [ switches ] [ sub-command ] [ sub-command-args ]

DESCRIPTION

module is a user interface to the Modules package. The Modules package provides for the
dynamic modification of the user's environment via modulefiles.

Each modulefile contains the information needed to configure the shell for an application.
Once the Modules package is initialized, the environment can be modified on a per-module
basis using the module command which interprets modulefiles. Typically modulefiles
instruct the module command to alter or set shell environment variables such as PATH,
MANPATH, etc. modulefiles may be shared by many users on a system and users may have
their own collection to supplement or replace the shared modulefiles.

The modulefiles are added to and removed from the current environment by the user. The
environment changes contained in a modulefile can be summarized through the module command
as well. If no arguments are given, a summary of the module usage and sub-commands are
shown.

The action for the module command to take is described by the sub-command and its
associated arguments.

Package Initialization
The Modules package and the module command are initialized when a shell-specific
initialization script is sourced into the shell. The script creates the module command,
either as an alias or shell function, creates Modules environment variables, and if
enabled to do so, a snapshot of the environment is saved as either (if BEGINENV=1)
$HOME/.modulesbeginenv or (if BEGINENV=99) whatever $MODULESBEGINENV points to.

The module alias or function executes the modulecmd program and has the shell evaluate the
command's output. The first argument to modulecmd specifies the type of shell.

The initialization scripts are kept in $MODULESHOME/init/<shell> where <shell> is the name
of the sourcing shell. The sh, csh, tcsh, bash, ksh, and zsh shells are supported by
modulecmd. In addition, python, perl, and cmake "shells" are supported, which writes the
environment changes to stdout as python, perl, or cmake code.

The perl module command is set up with:

use lib $ENV{'MODULESHOME'}."/init";
use perl;

And the python module command is defined with:

import os;
if os.environ.has_key('PYTHONPATH'):
os.environ['PYTHONPATH'] +=':'+os.environ['MODULESHOME']+"/init";
else:
os.environ['PYTHONPATH'] = os.environ['MODULESHOME']+"/init";

from python import module;

Modulecmd startup
Upon invocation modulecmd sources rc files which contain global, user and modulefile
specific setups. These files are interpreted as modulefiles. See modulefile(4) for
detailed information.

Upon invocation of modulecmd module RC files are sourced in the following order:

Global RC file as specified by ${MODULERCFILE} or ${MODULESHOME}/etc/rc

User specific module RC file ${HOME}/.modulerc

All .modulerc and .version files found during modulefile seeking.

Command line switches
The module command accepts command line switches as its first parameter. These may be used
to control output format of all information displayed and the module behavior in case of
locating and interpreting module files.

All switches may be entered either in short or long notation. The following switches are
accepted:

--help, -H
Give some helpful usage information, and terminates the command.

--version, -V
Lists the current version of the module command, and some configured option values.
The command then terminates without further processing.

--force, -f
Force active dependency resolution. This will result in modules found on a prereq
command inside a module file being load automatically. Unloading module files
using this switch will result in all required modules which have been loaded
automatically using the -f switch being unload. This switch is experimental at the
moment.

--terse, -t
Display avail and list output in short format.

--long, -l
Display avail and list output in long format.

--human, -h
Display short output of the avail and list commands in human readable format.

--verbose, -v
Enable verbose messages during module command execution.

--silent, -s
Disable verbose messages. Redirect stderr to /dev/null if stderr is found not to be
a tty. This is a useful option for module commands being written into .cshrc,
.login or .profile files, because some remote shells (as rsh(1)) and remote
execution commands (like rdist) get confused if there is output on stderr.

--create, -c
Create caches for module avail and module apropos. You must be granted write access
to the ${MODULEHOME}/modulefiles/ directory if you try to invoke module with the -c
option.

--icase, -i
Case insensitive module parameter evaluation. Currently only implemented for the
module apropos command.

--userlvl <lvl>, -u <lvl>
Set the user level to the specified value. The argument of this option may be one
of:

novice, nov Novice

expert, exp Experienced module user

advanced, adv Advanced module user

Module Sub-Commands
help [modulefile...]
Print the usage of each sub-command. If an argument is given, print
the Module-specific help information for the modulefile(s).

add modulefile...
load modulefile...
Load modulefile(s) into the shell environment.

rm modulefile...
unload modulefile...
Remove modulefile(s) from the shell environment.

swap [modulefile1] modulefile2
switch [modulefile1] modulefile2
Switch loaded modulefile1 with modulefile2. If modulefile1 is not
specified, then it is assumed to be the currently loaded module with
the same root name as modulefile2.

show modulefile...
display modulefile...
Display information about one or more modulefiles. The display sub-
command will list the full path of the modulefile(s) and all (or
most) of the environment changes the modulefile(s) will make if
loaded. (It will not display any environment changes found within
conditional statements.)

list List loaded modules.

avail [path...]
List all available modulefiles in the current MODULEPATH, where the
sorting order is given by the LC_COLLATE locale environment
variable.

All directories in the MODULEPATH are recursively searched for files
containing the modulefile magic cookie.

If an argument is given, then each directory in the MODULEPATH is
searched for modulefiles whose pathname match the argument.

Multiple versions of an application can be supported by creating a
subdirectory for the application containing modulefiles for each
version.

use [-a|--append] directory...
Prepend one or more directories to the MODULEPATH environment
variable. The --append flag will append the directory to
MODULEPATH.

unuse directory...
Remove one or more directories from the MODULEPATH environment
variable.

update Attempt to reload all loaded modulefiles. The environment will be
reconfigured to match the environment saved in
${HOME}/.modulesbeginenv (if BEGINENV=1) or the file pointed at by
$MODULESBEGINEV (if BEGINENV=99) and the modulefiles will be
reloaded. This is only valid if modules was configured with
--enable-beginenv (which defines BEGINENV), otherwise this will
cause a warning. update will only change the environment variables
that the modulefiles set.

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

purge Unload all loaded modulefiles.

refresh Force a refresh of all non-persistent components of currently loaded
modules. This should be used on derived shells where aliases need
to be reinitialized but the environment variables have already been
set by the currently loaded modules.

whatis [modulefile...]
Display the information set up by the module-whatis commands inside
the specified modulefile(s). If no modulefile is specified, all
'whatis' lines will be shown.

apropos string
keyword string Seeks through the 'whatis' informations of all modulefiles for the
specified string. All module-whatis informations matching the
string will be displayed.

initadd modulefile...
Add modulefile(s) to the shell's initialization file in the user's
home directory. The startup files checked (in order) are:
csh - .modules, .cshrc(.ext), .csh_variables, and .login(.ext)
tcsh - .modules, .tcshrc, .cshrc(.ext), .csh_variables, and
.login(.ext)
sh and ksh - .modules, .profile(.ext), and .kshenv(.ext)
bash - .modules, .bash_profile, .bash_login, .profile(.ext), and
.bashrc(.ext)
zsh - .modules, .zcshrc(.ext), .zshenv(.ext), and .zlogin(.ext)

If a 'module load' line is found in any of these files, the
modulefile(s) is(are) appended to any existing list of modulefiles.
The 'module load' line must be located in at least one of the files
listed above for any of the 'init' sub-commands to work properly.
If the 'module load' line is found in multiple shell initialization
files, all of the lines are changed.

initprepend modulefile [modulefile...]
Does the same as initadd but prepends the given modules to the
beginning of the list.

initrm modulefile...
Remove modulefile(s) from the shell's initialization files.

initswitch modulefile1 modulefile2
Switch modulefile1 with modulefile2 in the shell's initialization
files.

initlist List all of the modulefiles loaded from the shell's initialization
file.

initclear Clear all of the modulefiles from the shell's initialization files.

Modulefiles
modulefiles are written in the Tool Command Language (Tcl) and are interpreted by
modulecmd. modulefiles can use conditional statements. Thus the effect a modulefile will
have on the environment may change depending upon the current state of the environment.

Environment variables are unset when unloading a modulefile. Thus, it is possible to load
a modulefile and then unload it without having the environment variables return to their
prior state.

ENVIRONMENT

       MODULESHOME
              The location of the master Modules package file directory containing module command
              initialization   scripts,   the  executable  program  modulecmd,  and  a  directory
              containing a collection of master modulefiles.

       MODULEPATH
              The path that the module command searches when looking for modulefiles.  Typically,
              it  is  set  to  a default value by the bootstrap procedure.  MODULEPATH can be set
              using 'module use' or by the  module  initialization  script  to  search  group  or
              personal modulefile directories before or after the master modulefile directory.

       LOADEDMODULES
              A colon separated list of all loaded modulefiles.

       _LMFILES_
              A colon separated list of the full pathname for all loaded modulefiles.

       MODULESBEGINENV
              If modules has been configured (BEGINENV=99) to test for this environment variable,
              then if it exists, it is the name of the  file  to  store  the  the  initial  shell
              environment.   This  environment  variable will have embedded environment variables
              unrolled to one level.  The contents of this variable is only used the  first  time
              modules is invoked.

       _MODULESBEGINENV_
              The filename of the file containing the initialization environment snapshot.

FILES

       /usr/Modules/3.2.10
              The MODULESHOME directory.

       ${MODULESHOME}/etc/rc
              The  system-wide  modules  rc file.  The location of this file can be changed using
              the MODULERCFILE environment variable as described above.

       ${HOME}/.modulerc
              The user specific modules rc file.

       ${MODULESHOME}/modulefiles
              The directory for system-wide modulefiles.  The location of the  directory  can  be
              changed using the MODULEPATH environment variable as described above.

       ${MODULESHOME}/bin/modulecmd
              The modulefile interpreter that gets executed upon each invocation of module.

       ${MODULESHOME}/init/<shell>
              The Modules package initialization file sourced into the user's environment.

       ${MODULEPATH}/.moduleavailcache
              File  containing  the  cached  list  of  all  modulefiles for each directory in the
              MODULEPATH (only when the avail cache is enabled via the configure option --enable-
              cache which sets CACHE_AVAIL).

       ${MODULEPATH}/.moduleavailcachedir
              File  containing  the  names and modification times for all sub-directories with an
              avail cache (see above).

       ${HOME}/.modulesbeginenv
              A snapshot  of  the  user's  environment  taken  at  Module  initialization.   This
              information is used by the module update sub-command (if BEGINENV=1), else

       $MODULESBEGINENV
              If  this  defines  a  valid  filename,  it  serves  the  same  purpose as above (if
              BEGINENV=99).

VERSION