.\" Man page generated from reStructuredText.
.
.TH "MODULE" "1" "2020-11-14" "4.6.1" "Modules"
.SH NAME
module \- command interface to the Modules package
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH SYNOPSIS
.sp
\fBmodule\fP [\fIswitches\fP] [\fIsub\-command\fP [\fIsub\-command\-args\fP]]
.SH DESCRIPTION
.sp
\fBmodule\fP is a user interface to the Modules package. The Modules
package provides for the dynamic modification of the user\(aqs environment
via \fImodulefiles\fP\&.
.sp
Each \fImodulefile\fP 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 \fBmodule\fP
command which interprets \fImodulefiles\fP\&. Typically \fImodulefiles\fP instruct
the \fBmodule\fP command to alter or set shell environment variables such
as \fBPATH\fP, \fBMANPATH\fP, etc. \fIModulefiles\fP may be shared by many
users on a system and users may have their own set to supplement or replace
the shared \fImodulefiles\fP\&.
.sp
The \fImodulefiles\fP are added to and removed from the current environment
by the user. The environment changes contained in a \fImodulefile\fP can be
summarized through the \fBmodule\fP command as well. If no arguments are
given, a summary of the \fBmodule\fP usage and \fIsub\-commands\fP are shown.
.sp
The action for the \fBmodule\fP command to take is described by the
\fIsub\-command\fP and its associated arguments.
.SS Package Initialization
.sp
The Modules package and the \fBmodule\fP command are initialized when a
shell\-specific initialization script is sourced into the shell. The script
creates the \fBmodule\fP command as either an alias or function and
creates Modules environment variables.
.sp
The \fBmodule\fP alias or function executes the \fBmodulecmd.tcl\fP
program located in \fB/usr/lib/x86_64-linux-gnu\fP and has the shell evaluate the command\(aqs
output. The first argument to \fBmodulecmd.tcl\fP specifies the type of
shell.
.sp
The initialization scripts are kept in \fB/usr/share/modules/init/<shell>\fP where
\fI<shell>\fP is the name of the sourcing shell. For example, a C Shell user
sources the \fB/usr/share/modules/init/csh\fP script. The sh, csh, tcsh, bash, ksh,
zsh and fish shells are supported by \fBmodulecmd.tcl\fP\&. In addition,
python, perl, ruby, tcl, cmake, r and lisp "shells" are supported which
writes the environment changes to stdout as python, perl, ruby, tcl, lisp,
r or cmake code.
.sp
Initialization may also be performed by calling the \fBautoinit\fP
sub\-command of the \fBmodulecmd.tcl\fP program. Evaluation into the shell of
the result of this command defines the \fBmodule\fP alias or function.
.sp
A \fBml\fP alias or function may also be defined at initialization time
if enabled (see \fI\%MODULES_ML\fP section). \fBml\fP is a handy
frontend leveraging all \fBmodule\fP command capabilities with less
character typed. See ml(1) for detailed information.
.SS Examples of initialization
.sp
C Shell initialization (and derivatives):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
source /usr/share/modules/init/csh
module load modulefile modulefile ...
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Bourne Shell (sh) (and derivatives):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\&. /usr/share/modules/init/sh
module load modulefile modulefile ...
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Perl:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
require "/usr/share/modules/init/perl.pm";
&module(\(aqload\(aq, \(aqmodulefile\(aq, \(aqmodulefile\(aq, \(aq...\(aq);
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Python:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
import os
exec(open(\(aq/usr/share/modules/init/python.py\(aq).read())
module(\(aqload\(aq, \(aqmodulefile\(aq, \(aqmodulefile\(aq, \(aq...\(aq)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Bourne Shell (sh) (and derivatives) with \fBautoinit\fP sub\-command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
eval "\(ga/usr/lib/x86_64-linux-gnu/modulecmd.tcl sh autoinit\(ga"
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Modulecmd startup
.sp
Upon invocation \fBmodulecmd.tcl\fP sources a site\-specific configuration
script if it exists. The location for this script is
\fB/etc/environment-modules/siteconfig.tcl\fP\&. An additional siteconfig script may be
specified with the \fI\%MODULES_SITECONFIG\fP environment variable, if
allowed by \fBmodulecmd.tcl\fP configuration, and will be loaded if it
exists after \fB/etc/environment-modules/siteconfig.tcl\fP\&. Siteconfig is a Tcl script that enables
to supersede any global variable or procedure definition of
\fBmodulecmd.tcl\fP\&.
.sp
Afterward, \fBmodulecmd.tcl\fP sources rc files which contain global,
user and \fImodulefile\fP specific setups. These files are interpreted as
\fImodulefiles\fP\&. See modulefile(4) for detailed information.
.sp
Upon invocation of \fBmodulecmd.tcl\fP module run\-command files are sourced
in the following order:
.INDENT 0.0
.IP 1. 3
Global RC file as specified by \fI\%MODULERCFILE\fP variable or
\fB/etc/environment-modules/rc\fP\&. If \fI\%MODULERCFILE\fP points to a directory, the
\fBmodulerc\fP file in this directory is used as global RC file.
.IP 2. 3
User specific module RC file \fB$HOME/.modulerc\fP
.IP 3. 3
All \fB\&.modulerc\fP and \fB\&.version\fP files found during modulefile
seeking.
.UNINDENT
.SS Command line switches
.sp
The \fBmodule\fP command accepts command line switches as its first
parameter. These may be used to control output format of all information
displayed and the \fBmodule\fP behavior in case of locating and
interpreting \fImodulefiles\fP\&.
.sp
All switches may be entered either in short or long notation. The following
switches are accepted:
.INDENT 0.0
.TP
.B \-\-all, \-a
Include hidden modules in search performed with \fI\%avail\fP,
\fI\%aliases\fP, \fI\%search\fP or \fI\%whatis\fP sub\-commands.
Hard\-hidden modules are not affected by this option.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-auto
On \fI\%load\fP, \fI\%unload\fP and \fI\%switch\fP sub\-commands, enable
automated module handling mode. See also \fI\%MODULES_AUTO_HANDLING\fP
section.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-color=<WHEN>
Colorize the output. \fIWHEN\fP defaults to \fBalways\fP or can be \fBnever\fP or
\fBauto\fP\&. See also \fI\%MODULES_COLOR\fP section.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-contains, \-C
On \fI\%avail\fP sub\-command, return modules whose fully qualified name
contains search query string.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-debug, \-D, \-DD
Debug mode. Causes \fBmodule\fP to print debugging messages about its
progress. Multiple \fI\%\-D\fP options increase the debug verbosity.  The
maximum is 2.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-default, \-d
On \fI\%avail\fP sub\-command, display only the default version of each
module name. Default version is the explicitly set default version or also
the implicit default version if the configuration option \fBimplicit_default\fP
is enabled (see Locating Modulefiles section in the
modulefile(4) man page for further details on implicit default
version).
.UNINDENT
.INDENT 0.0
.TP
.B \-\-force, \-f
On \fI\%load\fP, \fI\%unload\fP and \fI\%switch\fP sub\-commands,
by\-pass any unsatisfied modulefile constraint corresponding to the declared
\fBprereq\fP and \fBconflict\fP\&. Which means for instance that a
\fImodulefile\fP will be loaded even if it comes in conflict with another loaded
\fImodulefile\fP or that a \fImodulefile\fP will be unloaded even if it is required
as a prereq by another \fImodulefile\fP\&.
.sp
On \fI\%clear\fP sub\-command, skip the confirmation dialog and proceed.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-help, \-h
Give some helpful usage information, and terminates the command.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-icase, \-i
Match module specification arguments in a case insensitive manner.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-indepth
On \fI\%avail\fP sub\-command, include in search results the matching
modulefiles and directories and recursively the modulefiles and directories
contained in these matching directories.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-json, \-j
Display \fI\%avail\fP, \fI\%list\fP, \fI\%savelist\fP, \fI\%whatis\fP
and \fI\%search\fP output in JSON format.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-latest, \-L
On \fI\%avail\fP sub\-command, display only the highest numerically sorted
version of each module name (see Locating Modulefiles section in the
modulefile(4) man page).
.UNINDENT
.INDENT 0.0
.TP
.B \-\-long, \-l
Display \fI\%avail\fP, \fI\%list\fP and \fI\%savelist\fP output in long
format.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-no\-auto
On \fI\%load\fP, \fI\%unload\fP and \fI\%switch\fP sub\-commands,
disable automated module handling mode. See also
\fI\%MODULES_AUTO_HANDLING\fP section.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-no\-indepth
On \fI\%avail\fP sub\-command, limit search results to the matching
modulefiles and directories found at the depth level expressed by the search
query. Thus modulefiles contained in directories part of the result are
excluded.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-no\-pager
Do not pipe message output into a pager.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-paginate
Pipe all message output into \fBless\fP (or if set, to the command
referred in \fI\%MODULES_PAGER\fP variable) if error output stream is a
terminal. See also \fI\%MODULES_PAGER\fP section.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-silent, \-s
Turn off error, warning and informational messages. \fBmodule\fP command
output result is not affected by silent mode.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-starts\-with, \-S
On \fI\%avail\fP sub\-command, return modules whose name starts with search
query string.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-terse, \-t
Display \fI\%avail\fP, \fI\%list\fP and \fI\%savelist\fP output in
short format.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-trace, \-T
Trace mode. Report details on module searches, resolutions, selections and
evaluations in addition to printing verbose messages.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-verbose, \-v
Enable verbose messages during \fBmodule\fP command execution.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-version, \-V
Lists the current version of the \fBmodule\fP command. The command then
terminates without further processing.
.UNINDENT
.SS Module Sub\-Commands
.INDENT 0.0
.TP
.B add modulefile...
See \fI\%load\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B aliases [\-a]
List all available symbolic version\-names and aliases in the current
\fI\%MODULEPATH\fP\&.  All directories in the \fI\%MODULEPATH\fP are
recursively searched in the same manner than for the \fI\%avail\fP
sub\-command. Only the symbolic version\-names and aliases found in the search
are displayed.
.UNINDENT
.INDENT 0.0
.TP
.B append\-path [\-d C|\-\-delim C|\-\-delim=C] [\-\-duplicates] variable value...
Append \fIvalue\fP to environment \fIvariable\fP\&. The \fIvariable\fP is a colon, or
\fIdelimiter\fP, separated list. See \fBappend\-path\fP in the
modulefile(4) man page for further explanation.
.UNINDENT
.INDENT 0.0
.TP
.B apropos [\-a] [\-j] string
See \fI\%search\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B avail [\-d|\-L] [\-t|\-l|\-j] [\-a] [\-S|\-C] [\-\-indepth|\-\-no\-indepth] [path...]
List all available \fImodulefiles\fP in the current \fI\%MODULEPATH\fP\&. All
directories in the \fI\%MODULEPATH\fP are recursively searched for files
containing the \fImodulefile\fP magic cookie. If an argument is given, then
each directory in the \fI\%MODULEPATH\fP is searched for \fImodulefiles\fP
whose pathname, symbolic version\-name or alias match the argument. Argument
may contain wildcard characters. Multiple versions of an application can
be supported by creating a subdirectory for the application containing
\fImodulefiles\fP for each version.
.sp
Symbolic version\-names and aliases found in the search are displayed in the
result of this sub\-command. Symbolic version\-names are displayed next to
the \fImodulefile\fP they are assigned to within parenthesis. Aliases are listed
in the \fI\%MODULEPATH\fP section where they have been defined. To
distinguish aliases from \fImodulefiles\fP a \fB@\fP symbol is added within
parenthesis next to their name. Aliases defined through a global or user
specific module RC file are listed under the \fBglobal/user modulerc\fP
section.
.sp
When colored output is enabled and a specific graphical rendition is defined
for module \fIdefault\fP version, the \fBdefault\fP symbol is omitted and instead
the defined graphical rendition is applied to the relative modulefile. When
colored output is enabled and a specific graphical rendition is defined for
module alias, the \fB@\fP symbol is omitted. The defined graphical rendition
applies to the module alias name. See \fI\%MODULES_COLOR\fP and
\fI\%MODULES_COLORS\fP sections for details on colored output.
.sp
The parameter \fIpath\fP may also refer to a symbolic modulefile name or a
modulefile alias. It may also leverage a specific syntax to finely select
module version (see \fI\%Advanced module version specifiers\fP section below).
.UNINDENT
.INDENT 0.0
.TP
.B clear [\-f]
Force the Modules package to believe that no modules are currently loaded. A
confirmation is requested if command\-line switch \fI\%\-f\fP (or
\fI\%\-\-force\fP) is not passed. Typed confirmation should equal to \fByes\fP
or \fBy\fP in order to proceed.
.UNINDENT
.INDENT 0.0
.TP
.B config [\-\-dump\-state|name [value]|\-\-reset name]
Gets or sets \fBmodulecmd.tcl\fP options. Reports the currently set value
of passed option \fIname\fP or all existing options if no \fIname\fP passed. If a
\fIname\fP and a \fIvalue\fP are provided, the value of option \fIname\fP is set to
\fIvalue\fP\&. If command\-line switch \fB\-\-reset\fP is passed in addition to a
\fIname\fP, overridden value for option \fIname\fP is cleared.
.sp
When a reported option value differs from default value a mention is added
to indicate whether the overridden value is coming from a command\-line switch
(\fBcmd\-line\fP) or from an environment variable (\fBenv\-var\fP). When a reported
option value is locked and cannot be altered a (\fBlocked\fP) mention is added.
.sp
If no value is currently set for an option \fIname\fP, the mention \fB<undef>\fP is
reported.
.sp
When command\-line switch \fB\-\-dump\-state\fP is passed, current
\fBmodulecmd.tcl\fP state and Modules\-related environment variables are
reported in addition to currently set \fBmodulecmd.tcl\fP options.
.sp
Existing option \fInames\fP are:
.INDENT 7.0
.IP \(bu 2
\fBadvanced_version_spec\fP: advanced module version specification to finely
select modulefiles (defines environment variable
\fI\%MODULES_ADVANCED_VERSION_SPEC\fP when set
.IP \(bu 2
\fBauto_handling\fP: automated module handling mode (defines
\fI\%MODULES_AUTO_HANDLING\fP)
.IP \(bu 2
\fBavail_indepth\fP: \fI\%avail\fP sub\-command in depth search mode
(defines \fI\%MODULES_AVAIL_INDEPTH\fP)
.IP \(bu 2
\fBavail_report_dir_sym\fP: display symbolic versions targeting directories
on \fI\%avail\fP sub\-command
.IP \(bu 2
\fBavail_report_mfile_sym\fP: display symbolic versions targeting modulefiles
on \fI\%avail\fP sub\-command
.IP \(bu 2
\fBcollection_pin_version\fP: register exact modulefile version in collection
(defines \fI\%MODULES_COLLECTION_PIN_VERSION\fP)
.IP \(bu 2
\fBcollection_target\fP: collection target which is valid for current system
(defines \fI\%MODULES_COLLECTION_TARGET\fP)
.IP \(bu 2
\fBcolor\fP: colored output mode (defines \fI\%MODULES_COLOR\fP)
.IP \(bu 2
\fBcolors\fP: chosen colors to highlight output items (defines
\fI\%MODULES_COLORS\fP)
.IP \(bu 2
\fBcontact\fP: modulefile contact address (defines \fI\%MODULECONTACT\fP)
.IP \(bu 2
\fBextended_default\fP: allow partial module version specification (defines
\fI\%MODULES_EXTENDED_DEFAULT\fP)
.IP \(bu 2
\fBextra_siteconfig\fP: additional site\-specific configuration script
location (defines \fI\%MODULES_SITECONFIG\fP)
.IP \(bu 2
\fBhome\fP: location of Modules package main directory (defines
\fI\%MODULESHOME\fP)
.IP \(bu 2
\fBicase\fP: enable case insensitive match (defines \fI\%MODULES_ICASE\fP)
.IP \(bu 2
\fBignored_dirs\fP: directories ignored when looking for modulefiles
.IP \(bu 2
\fBimplicit_default\fP: set an implicit default version for modules (defines
\fI\%MODULES_IMPLICIT_DEFAULT\fP)
.IP \(bu 2
\fBlocked_configs\fP: configuration options that cannot be superseded
.IP \(bu 2
\fBml\fP: define \fBml\fP command at initialization time (defines
\fI\%MODULES_ML\fP)
.IP \(bu 2
\fBnearly_forbidden_days\fP: set the number of days a module should be
considered \fInearly forbidden\fP prior reaching its expiry date (defines
\fI\%MODULES_NEARLY_FORBIDDEN_DAYS\fP)
.IP \(bu 2
\fBpager\fP: text viewer to paginate message output (defines
\fI\%MODULES_PAGER\fP)
.IP \(bu 2
\fBrcfile\fP: global run\-command file location (defines
\fI\%MODULERCFILE\fP)
.IP \(bu 2
\fBrun_quarantine\fP: environment variables to indirectly pass to
\fBmodulecmd.tcl\fP (defines \fI\%MODULES_RUN_QUARANTINE\fP)
.IP \(bu 2
\fBsilent_shell_debug\fP: disablement of shell debugging property for the
module command (defines \fI\%MODULES_SILENT_SHELL_DEBUG\fP)
.IP \(bu 2
\fBsearch_match\fP: module search match style (defines
\fI\%MODULES_SEARCH_MATCH\fP)
.IP \(bu 2
\fBset_shell_startup\fP: ensure module command definition by setting shell
startup file (defines \fI\%MODULES_SET_SHELL_STARTUP\fP)
.IP \(bu 2
\fBsiteconfig\fP: primary site\-specific configuration script location
.IP \(bu 2
\fBtcl_ext_lib\fP: Modules Tcl extension library location
.IP \(bu 2
\fBterm_background\fP: terminal background color kind (defines
\fI\%MODULES_TERM_BACKGROUND\fP)
.IP \(bu 2
\fBunload_match_order\fP: unload firstly loaded or lastly loaded module
matching request (defines \fI\%MODULES_UNLOAD_MATCH_ORDER\fP)
.IP \(bu 2
\fBverbosity\fP: module command verbosity level (defines
\fI\%MODULES_VERBOSITY\fP)
.IP \(bu 2
\fBwa_277\fP: workaround for Tcsh history issue (defines
\fI\%MODULES_WA_277\fP)
.UNINDENT
.sp
The options \fBavail_report_dir_sym\fP, \fBavail_report_mfile_sym\fP,
\fBignored_dirs\fP, \fBlocked_configs\fP, \fBsiteconfig\fP and \fBtcl_ext_lib\fP
cannot be altered. Moreover all options referred in \fBlocked_configs\fP value
are locked, thus they cannot be altered.
.UNINDENT
.INDENT 0.0
.TP
.B display modulefile...
Display information about one or more \fImodulefiles\fP\&. The display sub\-command
will list the full path of the \fImodulefile\fP and the environment changes
the \fImodulefile\fP will make if loaded. (Note: It will not display any
environment changes found within conditional statements.)
.sp
The parameter \fImodulefile\fP may also be a symbolic modulefile name or a
modulefile alias. It may also leverage a specific syntax to finely select
module version (see \fI\%Advanced module version specifiers\fP section below).
.UNINDENT
.INDENT 0.0
.TP
.B help [modulefile...]
Print the usage of each sub\-command. If an argument is given, print the
Module\-specific help information for the \fImodulefile\fP\&.
.sp
The parameter \fImodulefile\fP may also be a symbolic modulefile name or a
modulefile alias. It may also leverage a specific syntax to finely select
module version (see \fI\%Advanced module version specifiers\fP section below).
.UNINDENT
.INDENT 0.0
.TP
.B info\-loaded modulefile
Returns the names of currently loaded modules matching passed \fImodulefile\fP\&.
Returns an empty string if passed \fImodulefile\fP does not match any loaded
modules. See \fBmodule\-info loaded\fP in the
modulefile(4) man page for further explanation.
.UNINDENT
.INDENT 0.0
.TP
.B initadd modulefile...
Add \fImodulefile\fP to the shell\(aqs initialization file in the user\(aqs home
directory. The startup files checked (in order) are:
.sp
C Shell
.INDENT 7.0
.INDENT 3.5
\fB\&.modules\fP, \fB\&.cshrc\fP, \fB\&.csh_variables\fP and \fB\&.login\fP
.UNINDENT
.UNINDENT
.sp
TENEX C Shell
.INDENT 7.0
.INDENT 3.5
\fB\&.modules\fP, \fB\&.tcshrc\fP, \fB\&.cshrc\fP, \fB\&.csh_variables\fP
and \fB\&.login\fP
.UNINDENT
.UNINDENT
.sp
Bourne and Korn Shells
.INDENT 7.0
.INDENT 3.5
\fB\&.modules\fP, \fB\&.profile\fP
.UNINDENT
.UNINDENT
.sp
GNU Bourne Again Shell
.INDENT 7.0
.INDENT 3.5
\fB\&.modules\fP, \fB\&.bash_profile\fP, \fB\&.bash_login\fP,
\fB\&.profile\fP and \fB\&.bashrc\fP
.UNINDENT
.UNINDENT
.sp
Z Shell
.INDENT 7.0
.INDENT 3.5
\fB\&.modules\fP, \fB\&.zshrc\fP, \fB\&.zshenv\fP and \fB\&.zlogin\fP
.UNINDENT
.UNINDENT
.sp
Friendly Interactive Shell
.INDENT 7.0
.INDENT 3.5
\fB\&.modules\fP, \fB\&.config/fish/config.fish\fP
.UNINDENT
.UNINDENT
.sp
If a \fBmodule load\fP line is found in any of these files, the \fImodulefiles\fP
are appended to any existing list of \fImodulefiles\fP\&. The \fBmodule load\fP
line must be located in at least one of the files listed above for any of
the \fI\%init\fP sub\-commands to work properly. If the
\fBmodule load\fP line is found in multiple shell initialization files, all of
the lines are changed.
.UNINDENT
.INDENT 0.0
.TP
.B initclear
Clear all of the \fImodulefiles\fP from the shell\(aqs initialization files.
.UNINDENT
.INDENT 0.0
.TP
.B initlist
List all of the \fImodulefiles\fP loaded from the shell\(aqs initialization file.
.UNINDENT
.INDENT 0.0
.TP
.B initprepend modulefile...
Does the same as \fI\%initadd\fP but prepends the given modules to the
beginning of the list.
.UNINDENT
.INDENT 0.0
.TP
.B initrm modulefile...
Remove \fImodulefile\fP from the shell\(aqs initialization files.
.UNINDENT
.INDENT 0.0
.TP
.B initswitch modulefile1 modulefile2
Switch \fImodulefile1\fP with \fImodulefile2\fP in the shell\(aqs initialization files.
.UNINDENT
.INDENT 0.0
.TP
.B is\-avail modulefile...
Returns a true value if any of the listed \fImodulefiles\fP exists in enabled
\fI\%MODULEPATH\fP\&. Returns a false value otherwise. See \fBis\-avail\fP
in the modulefile(4) man page for further explanation.
.sp
The parameter \fImodulefile\fP may also be a symbolic modulefile name or a
modulefile alias. It may also leverage a specific syntax to finely select
module version (see \fI\%Advanced module version specifiers\fP section below).
.UNINDENT
.INDENT 0.0
.TP
.B is\-loaded [modulefile...]
Returns a true value if any of the listed \fImodulefiles\fP has been loaded or if
any \fImodulefile\fP is loaded in case no argument is provided. Returns a false
value otherwise. See \fBis\-loaded\fP in the modulefile(4) man page
for further explanation.
.sp
The parameter \fImodulefile\fP may also be a symbolic modulefile name or a
modulefile alias. It may also leverage a specific syntax to finely select
module version (see \fI\%Advanced module version specifiers\fP section below).
.UNINDENT
.INDENT 0.0
.TP
.B is\-saved [collection...]
Returns a true value if any of the listed \fIcollections\fP exists or if any
\fIcollection\fP exists in case no argument is provided. Returns a false value
otherwise. See \fBis\-saved\fP in the modulefile(4) man page for
further explanation.
.UNINDENT
.INDENT 0.0
.TP
.B is\-used [directory...]
Returns a true value if any of the listed \fIdirectories\fP has been enabled in
\fI\%MODULEPATH\fP or if any \fIdirectory\fP is enabled in case no argument is
provided. Returns a false value otherwise. See \fBis\-used\fP in the
modulefile(4) man page for further explanation.
.UNINDENT
.INDENT 0.0
.TP
.B keyword [\-a] [\-j] string
See \fI\%search\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B list [\-t|\-l|\-j]
List loaded modules.
.UNINDENT
.INDENT 0.0
.TP
.B load [\-\-auto|\-\-no\-auto] [\-f] modulefile...
Load \fImodulefile\fP into the shell environment.
.sp
The parameter \fImodulefile\fP may also be a symbolic modulefile name or a
modulefile alias. It may also leverage a specific syntax to finely select
module version (see \fI\%Advanced module version specifiers\fP section below).
.UNINDENT
.INDENT 0.0
.TP
.B path modulefile
Print path to \fImodulefile\fP\&.
.sp
The parameter \fImodulefile\fP may also be a symbolic modulefile name or a
modulefile alias. It may also leverage a specific syntax to finely select
module version (see \fI\%Advanced module version specifiers\fP section below).
.UNINDENT
.INDENT 0.0
.TP
.B paths modulefile
Print path of available \fImodulefiles\fP matching argument.
.sp
The parameter \fImodulefile\fP may also be a symbolic modulefile name or a
modulefile alias. It may also leverage a specific syntax to finely select
module version (see \fI\%Advanced module version specifiers\fP section below).
.UNINDENT
.INDENT 0.0
.TP
.B prepend\-path [\-d C|\-\-delim C|\-\-delim=C] [\-\-duplicates] variable value...
Prepend \fIvalue\fP to environment \fIvariable\fP\&. The \fIvariable\fP is a colon, or
\fIdelimiter\fP, separated list. See \fBprepend\-path\fP in the
modulefile(4) man page for further explanation.
.UNINDENT
.INDENT 0.0
.TP
.B purge
Unload all loaded \fImodulefiles\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B refresh
See \fI\%reload\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B reload
Unload then load all loaded \fImodulefiles\fP\&.
.sp
No unload then load is performed and an error is returned if the loaded
\fImodulefiles\fP have unsatisfied constraint corresponding to the
\fBprereq\fP and \fBconflict\fP they declare.
.UNINDENT
.INDENT 0.0
.TP
.B remove\-path [\-d C|\-\-delim C|\-\-delim=C] [\-\-index] variable value...
Remove \fIvalue\fP from the colon, or \fIdelimiter\fP, separated list in environment
\fIvariable\fP\&. See \fBremove\-path\fP in the modulefile(4) man page for
further explanation.
.UNINDENT
.INDENT 0.0
.TP
.B restore [collection]
Restore the environment state as defined in \fIcollection\fP\&. If \fIcollection\fP
name is not specified, then it is assumed to be the \fIdefault\fP collection. If
\fIcollection\fP is a fully qualified path, it is restored from this location
rather than from a file under the user\(aqs collection directory. If
\fI\%MODULES_COLLECTION_TARGET\fP is set, a suffix equivalent to the value
of this variable is appended to the \fIcollection\fP file name to restore.
.sp
When restoring a \fIcollection\fP, the currently set \fI\%MODULEPATH\fP
directory list and the currently loaded \fImodulefiles\fP are unused and
unloaded then used and loaded to exactly match the \fI\%MODULEPATH\fP and
loaded \fImodulefiles\fP lists saved in this \fIcollection\fP file. The order
of the paths and modulefiles set in \fIcollection\fP is preserved when
restoring. It means that currently loaded modules are unloaded to get
the same \fI\%LOADEDMODULES\fP root than collection and currently used
module paths are unused to get the same \fI\%MODULEPATH\fP root. Then
missing module paths are used and missing modulefiles are loaded.
.sp
If a module, without a default version explicitly defined, is recorded in a
\fIcollection\fP by its bare name: loading this module when restoring the
collection will fail if the configuration option \fBimplicit_default\fP is
disabled.
.UNINDENT
.INDENT 0.0
.TP
.B rm modulefile...
See \fI\%unload\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B save [collection]
Record the currently set \fI\%MODULEPATH\fP directory list and the
currently loaded \fImodulefiles\fP in a \fIcollection\fP file under the user\(aqs
collection directory \fB$HOME/.module\fP\&. If \fIcollection\fP name is not
specified, then it is assumed to be the \fBdefault\fP collection. If
\fIcollection\fP is a fully qualified path, it is saved at this location rather
than under the user\(aqs collection directory.
.sp
If \fI\%MODULES_COLLECTION_TARGET\fP is set, a suffix equivalent to the
value of this variable will be appended to the \fIcollection\fP file name.
.sp
By default, if a loaded modulefile corresponds to the explicitly defined
default module version, the bare module name is recorded. If the
configuration option \fBimplicit_default\fP is enabled, the bare module name is
also recorded for the implicit default module version. If
\fI\%MODULES_COLLECTION_PIN_VERSION\fP is set to \fB1\fP, module version is
always recorded even if it is the default version.
.sp
No \fIcollection\fP is recorded and an error is returned if the loaded
\fImodulefiles\fP have unsatisfied constraint corresponding to the
\fBprereq\fP and \fBconflict\fP they declare.
.UNINDENT
.INDENT 0.0
.TP
.B savelist [\-t|\-l|\-j]
List collections that are currently saved under the user\(aqs collection
directory. If \fI\%MODULES_COLLECTION_TARGET\fP is set, only collections
matching the target suffix will be displayed.
.UNINDENT
.INDENT 0.0
.TP
.B saverm [collection]
Delete the \fIcollection\fP file under the user\(aqs collection directory. If
\fIcollection\fP name is not specified, then it is assumed to be the \fIdefault\fP
collection. If \fI\%MODULES_COLLECTION_TARGET\fP is set, a suffix
equivalent to the value of this variable will be appended to the \fIcollection\fP
file name.
.UNINDENT
.INDENT 0.0
.TP
.B saveshow [collection]
Display the content of \fIcollection\fP\&. If \fIcollection\fP name is not specified,
then it is assumed to be the \fIdefault\fP collection. If \fIcollection\fP is a
fully qualified path, this location is displayed rather than a collection
file under the user\(aqs collection directory. If
\fI\%MODULES_COLLECTION_TARGET\fP is set, a suffix equivalent to the value
of this variable will be appended to the \fIcollection\fP file name.
.UNINDENT
.INDENT 0.0
.TP
.B search [\-a] [\-j] string
Seeks through the \fBmodule\-whatis\fP informations of all \fImodulefiles\fP
for the specified \fIstring\fP\&. All \fImodule\-whatis\fP informations matching the
\fIstring\fP in a case insensitive manner will be displayed. \fIstring\fP may contain
wildcard characters.
.UNINDENT
.INDENT 0.0
.TP
.B sh\-to\-mod shell script [arg...]
Evaluate with \fIshell\fP the designated \fIscript\fP with defined \fIarguments\fP to
find out the environment changes it does. Environment prior and after
\fIscript\fP evaluation are compared to determine these changes. They are
translated into \fImodulefile\fP commands to output the modulefile content
equivalent to the evaluation of shell script.
.sp
Changes on environment variables, shell aliases, shell functions and current
working directory are tracked.
.sp
\fIShell\fP could be specified as a command name or a fully qualified pathname.
The following shells are supported: sh, dash, csh, tcsh, bash, ksh, ksh93,
zsh and fish.
.UNINDENT
.INDENT 0.0
.TP
.B show modulefile...
See \fI\%display\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B source scriptfile...
Execute \fIscriptfile\fP into the shell environment. \fIscriptfile\fP must be written
with \fImodulefile\fP syntax and specified with a fully qualified path. Once
executed \fIscriptfile\fP is not marked loaded in shell environment which differ
from \fI\%load\fP sub\-command.
.UNINDENT
.INDENT 0.0
.TP
.B swap [modulefile1] modulefile2
See \fI\%switch\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B switch [\-\-auto|\-\-no\-auto] [\-f] [modulefile1] modulefile2
Switch loaded \fImodulefile1\fP with \fImodulefile2\fP\&. If \fImodulefile1\fP is not
specified, then it is assumed to be the currently loaded module with the
same root name as \fImodulefile2\fP\&.
.sp
The parameter \fImodulefile\fP may also be a symbolic modulefile name or a
modulefile alias. It may also leverage a specific syntax to finely select
module version (see \fI\%Advanced module version specifiers\fP section below).
.UNINDENT
.INDENT 0.0
.TP
.B test modulefile...
Execute and display results of the Module\-specific tests for the
\fImodulefile\fP\&.
.sp
The parameter \fImodulefile\fP may also be a symbolic modulefile name or a
modulefile alias. It may also leverage a specific syntax to finely select
module version (see \fI\%Advanced module version specifiers\fP section below).
.UNINDENT
.INDENT 0.0
.TP
.B unload [\-\-auto|\-\-no\-auto] [\-f] modulefile...
Remove \fImodulefile\fP from the shell environment.
.sp
The parameter \fImodulefile\fP may also be a symbolic modulefile name or a
modulefile alias. It may also leverage a specific syntax to finely select
module version (see \fI\%Advanced module version specifiers\fP section below).
.UNINDENT
.INDENT 0.0
.TP
.B unuse directory...
Remove one or more \fIdirectories\fP from the \fI\%MODULEPATH\fP environment
variable if reference counter of these \fIdirectories\fP is equal to 1
or unknown.
.sp
Reference counter of \fIdirectory\fP in \fI\%MODULEPATH\fP denotes the number
of times \fIdirectory\fP has been enabled. When attempting to remove \fIdirectory\fP
from \fI\%MODULEPATH\fP, reference counter variable
\fI\%MODULEPATH_modshare\fP is checked and \fIdirectory\fP is
removed only if its relative counter is equal to 1 or not defined. Otherwise
\fIdirectory\fP is kept and reference counter is decreased by 1.
.UNINDENT
.INDENT 0.0
.TP
.B use [\-a|\-\-append] directory...
Prepend one or more \fIdirectories\fP to the \fI\%MODULEPATH\fP environment
variable.  The \fB\-\-append\fP flag will append the \fIdirectory\fP to
\fI\%MODULEPATH\fP\&.
.sp
Reference counter environment variable
\fI\%MODULEPATH_modshare\fP is also set to increase the
number of times \fIdirectory\fP has been added to \fI\%MODULEPATH\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B whatis [\-a] [\-j] [modulefile...]
Display the information set up by the \fBmodule\-whatis\fP commands inside
the specified \fImodulefiles\fP\&. These specified \fImodulefiles\fP may be
expressed using wildcard characters. If no \fImodulefile\fP is specified,
all \fBmodule\-whatis\fP lines will be shown.
.sp
The parameter \fImodulefile\fP may also be a symbolic modulefile name or a
modulefile alias. It may also leverage a specific syntax to finely select
module version (see \fI\%Advanced module version specifiers\fP section below).
.UNINDENT
.SS Modulefiles
.sp
\fImodulefiles\fP are written in the Tool Command Language (Tcl) and are
interpreted by \fBmodulecmd.tcl\fP\&. \fImodulefiles\fP can use conditional
statements. Thus the effect a \fImodulefile\fP will have on the environment
may change depending upon the current state of the environment.
.sp
Environment variables are unset when unloading a \fImodulefile\fP\&. Thus, it is
possible to \fI\%load\fP a \fImodulefile\fP and then \fI\%unload\fP it without
having the environment variables return to their prior state.
.SS Advanced module version specifiers
.sp
When the advanced module version specifiers mechanism is enabled (see
\fI\%MODULES_ADVANCED_VERSION_SPEC\fP), the specification of modulefile
passed on Modules sub\-commands changes. After the module name a version
constraint prefixed by the \fB@\fP character may be added. It could be directly
appended to the module name or separated from it with a space character.
.sp
Constraints can be expressed to refine the selection of module version to:
.INDENT 0.0
.IP \(bu 2
a single version with the \fB@version\fP syntax, for instance \fBfoo@1.2.3\fP
syntax will select module \fBfoo/1.2.3\fP
.IP \(bu 2
a list of versions with the \fB@version1,version2,...\fP syntax, for instance
\fBfoo@1.2.3,1.10\fP will match modules \fBfoo/1.2.3\fP and \fBfoo/1.10\fP
.IP \(bu 2
a range of versions with the \fB@version1:\fP, \fB@:version2\fP and
\fB@version1:version2\fP syntaxes, for instance \fBfoo@1.2:\fP will select all
versions of module \fBfoo\fP greater than or equal to \fB1.2\fP, \fBfoo@:1.3\fP
will select all versions less than or equal to \fB1.3\fP and \fBfoo@1.2:1.3\fP
matches all versions between \fB1.2\fP and \fB1.3\fP including \fB1.2\fP and
\fB1.3\fP versions
.UNINDENT
.sp
Advanced specification of single version or list of versions may benefit from
the activation of the extended default mechanism (see
\fI\%MODULES_EXTENDED_DEFAULT\fP) to use an abbreviated notation like \fB@1\fP
to refer to more precise version numbers like \fB1.2.3\fP\&. Range of versions on
its side natively handles abbreviated versions.
.sp
In order to be specified in a range of versions or compared to a range of
versions, the version major element should corresponds to a number. For
instance \fB10a\fP, \fB1.2.3\fP, \fB1.foo\fP are versions valid for range
comparison whereas \fBdefault\fP or \fBfoo.2\fP versions are invalid for range
comparison.
.sp
If the implicit default mechanism is also enabled (see
\fI\%MODULES_IMPLICIT_DEFAULT\fP), a \fBdefault\fP and \fBlatest\fP symbolic
versions are automatically defined for each module name (also at each
directory level for deep \fImodulefiles\fP). These automatic version symbols are
defined unless a symbolic version, alias, or regular module version already
exists for these \fBdefault\fP or \fBlatest\fP version names. Using the
\fBmod@latest\fP (or \fBmod/latest\fP) syntax ensures highest available version
will be selected.
.SS Collections
.sp
Collections describe a sequence of \fI\%module use\fP then
\fI\%module load\fP commands that are interpreted by
\fBmodulecmd.tcl\fP to set the user environment as described by this
sequence. When a collection is activated, with the \fI\%restore\fP
sub\-command, module paths and loaded modules are unused or unloaded if they
are not part or if they are not ordered the same way as in the collection.
.sp
Collections are generated by the \fI\%save\fP sub\-command that dumps the
current user environment state in terms of module paths and loaded modules. By
default collections are saved under the \fB$HOME/.module\fP directory.
.sp
Collections may be valid for a given target if they are suffixed. In this
case these collections can only be restored if their suffix correspond to
the current value of the \fI\%MODULES_COLLECTION_TARGET\fP environment
variable (see the dedicated section of this topic below).
.SH EXIT STATUS
.sp
The \fBmodule\fP command exits with \fB0\fP if its execution succeed.
Otherwise \fB1\fP is returned.
.SH ENVIRONMENT
.INDENT 0.0
.TP
.B _LMFILES_
A colon separated list of the full pathname for all loaded \fImodulefiles\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B LOADEDMODULES
A colon separated list of all loaded \fImodulefiles\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B MODULECONTACT
Email address to contact in case any issue occurs during the interpretation
of modulefiles.
.UNINDENT
.INDENT 0.0
.TP
.B MODULEPATH
The path that the \fBmodule\fP command searches when looking for
\fImodulefiles\fP\&. Typically, it is set to the main \fImodulefiles\fP directory,
\fB/usr/share/modules/modulefiles\fP, by the initialization script. \fI\%MODULEPATH\fP
can be set using \fI\%module use\fP or by the module initialization
script to search group or personal \fImodulefile\fP directories before or after
the main \fImodulefile\fP directory.
.sp
Path elements registered in the \fI\%MODULEPATH\fP environment variable may
contain reference to environment variables which are converted to their
corresponding value by \fBmodule\fP command each time it looks at the
\fI\%MODULEPATH\fP value. If an environment variable referred in a path
element is not defined, its reference is converted to an empty string.
.UNINDENT
.INDENT 0.0
.TP
.B MODULERCFILE
The location of a global run\-command file containing \fImodulefile\fP specific
setup. See \fI\%Modulecmd startup\fP section for detailed information.
.UNINDENT
.INDENT 0.0
.TP
.B MODULES_ADVANCED_VERSION_SPEC
If set to \fB1\fP, enable advanced module version specifiers (see \fI\%Advanced
module version specifiers\fP section). If set to \fB0\fP, disable advanced
module version specifiers.
.sp
Advanced module version specifiers enablement is defined in the following
order of preference: \fI\%MODULES_ADVANCED_VERSION_SPEC\fP environment
variable then the default set in \fBmodulecmd.tcl\fP script configuration.
Which means \fI\%MODULES_ADVANCED_VERSION_SPEC\fP overrides default
configuration.
.UNINDENT
.INDENT 0.0
.TP
.B MODULES_AUTO_HANDLING
If set to \fB1\fP, enable automated module handling mode. If set to \fB0\fP
disable automated module handling mode. Other values are ignored.
.sp
Automated module handling mode consists in additional actions triggered when
loading or unloading a \fImodulefile\fP to satisfy the constraints it declares.
When loading a \fImodulefile\fP, following actions are triggered:
.INDENT 7.0
.IP \(bu 2
Requirement Load: load of the \fImodulefiles\fP declared as a \fBprereq\fP
of the loading \fImodulefile\fP\&.
.IP \(bu 2
Dependent Reload: reload of the modulefiles declaring a \fBprereq\fP
onto loaded \fImodulefile\fP or declaring a \fBprereq\fP onto a \fImodulefile\fP
part of this reloading batch.
.UNINDENT
.sp
When unloading a \fImodulefile\fP, following actions are triggered:
.INDENT 7.0
.IP \(bu 2
Dependent Unload: unload of the modulefiles declaring a non\-optional
\fBprereq\fP onto unloaded modulefile or declaring a non\-optional
\fBprereq\fP onto a modulefile part of this unloading batch. A
\fBprereq\fP modulefile is considered optional if the \fBprereq\fP
definition order is made of multiple modulefiles and at least one
alternative modulefile is loaded.
.IP \(bu 2
Useless Requirement Unload: unload of the \fBprereq\fP modulefiles that
have been automatically loaded for either the unloaded modulefile, an
unloaded dependent modulefile or a modulefile part of this useless
requirement unloading batch. Modulefiles are added to this unloading batch
only if they are not required by any other loaded modulefiles.
.IP \(bu 2
Dependent Reload: reload of the modulefiles declaring a \fBconflict\fP
or an optional \fBprereq\fP onto either the unloaded modulefile, an
unloaded dependent or an unloaded useless requirement or declaring a
\fBprereq\fP onto a modulefile part of this reloading batch.
.UNINDENT
.sp
In case a loaded \fImodulefile\fP has some of its declared constraints
unsatisfied (pre\-required modulefile not loaded or conflicting modulefile
loaded for instance), this loaded \fImodulefile\fP is excluded from the automatic
reload actions described above.
.sp
For the specific case of the \fI\%switch\fP sub\-command, where a modulefile
is unloaded to then load another modulefile. Dependent modulefiles to Unload
are merged into the Dependent modulefiles to Reload that are reloaded after
the load of the switched\-to modulefile.
.sp
Automated module handling mode enablement is defined in the following order
of preference: \fI\%\-\-auto\fP/\fI\%\-\-no\-auto\fP command line switches,
then \fI\%MODULES_AUTO_HANDLING\fP environment variable, then the default
set in \fBmodulecmd.tcl\fP script configuration. Which means
\fI\%MODULES_AUTO_HANDLING\fP overrides default configuration and
\fI\%\-\-auto\fP/\fI\%\-\-no\-auto\fP command line switches override every
other ways to enable or disable this mode.
.UNINDENT
.INDENT 0.0
.TP
.B MODULES_AVAIL_INDEPTH
If set to \fB1\fP, enable in depth search results for \fI\%avail\fP
sub\-command. If set to \fB0\fP disable \fI\%avail\fP sub\-command in depth
mode. Other values are ignored.
.sp
When in depth mode is enabled, modulefiles and directories contained in
directories matching search query are also included in search results. When
disabled these modulefiles and directories contained in matching directories
are excluded.
.sp
\fI\%avail\fP sub\-command in depth mode enablement is defined in the
following order of preference: \fI\%\-\-indepth\fP/\fI\%\-\-no\-indepth\fP
command line switches, then \fI\%MODULES_AVAIL_INDEPTH\fP environment
variable, then the default set in \fBmodulecmd.tcl\fP script configuration.
Which means \fI\%MODULES_AVAIL_INDEPTH\fP overrides default configuration
and \fI\%\-\-indepth\fP/\fI\%\-\-no\-indepth\fP command line switches override
every other ways to enable or disable this mode.
.UNINDENT
.INDENT 0.0
.TP
.B MODULES_CMD
The location of the active module command script.
.UNINDENT
.INDENT 0.0
.TP
.B MODULES_COLLECTION_PIN_VERSION
If set to \fB1\fP, register exact version number of modulefiles when saving a
collection. Otherwise modulefile version number is omitted if it corresponds
to the explicitly set default version and also to the implicit default when
the configuration option \fBimplicit_default\fP is enabled.
.UNINDENT
.INDENT 0.0
.TP
.B MODULES_COLLECTION_TARGET
The collection target that determines what collections are valid thus
reachable on the current system.
.sp
Collection directory may sometimes be shared on multiple machines which may
use different modules setup. For instance modules users may access with the
same \fBHOME\fP directory multiple systems using different OS versions.
When it happens a collection made on machine 1 may be erroneous on machine 2.
.sp
When a target is set, only the collections made for that target are
available to the \fI\%restore\fP, \fI\%savelist\fP, \fI\%saveshow\fP
and \fI\%saverm\fP sub\-commands. Saving a collection registers the target
footprint by suffixing the collection filename with
\fB\&.$MODULES_COLLECTION_TARGET\fP\&. The collection target is not involved when
collection is specified as file path on the \fI\%saveshow\fP,
\fI\%restore\fP and \fI\%save\fP sub\-commands.
.sp
For example, the \fI\%MODULES_COLLECTION_TARGET\fP variable may be set with
results from commands like \fBlsb_release\fP, \fBhostname\fP,
\fBdnsdomainname\fP, etc.
.UNINDENT
.INDENT 0.0
.TP
.B MODULES_COLOR
Defines if output should be colored or not. Accepted values are \fBnever\fP,
\fBauto\fP and \fBalways\fP\&.
.sp
When color mode is set to \fBauto\fP, output is colored only if the standard
error output channel is attached to a terminal.
.sp
Colored output enablement is defined in the following order of preference:
\fI\%\-\-color\fP command line switch, then \fI\%MODULES_COLOR\fP
environment variable, then \fBNO_COLOR\fP, \fBCLICOLOR\fP and
\fBCLICOLOR_FORCE\fP environment variables, then the default set in
\fBmodulecmd.tcl\fP script configuration. Which means
\fI\%MODULES_COLOR\fP overrides default configuration and the
\fBNO_COLOR\fP and \fBCLICOLOR\fP/\fBCLICOLOR_FORCE\fP variables.
\fI\%\-\-color\fP command line switch overrides every other ways to enable or
disable this mode.
.sp
\fBNO_COLOR\fP, \fBCLICOLOR\fP and \fBCLICOLOR_FORCE\fP
environment variables are also honored to define color mode. The \fBnever\fP
mode is set if \fBNO_COLOR\fP is defined (regardless of its value) or if
\fBCLICOLOR\fP equals to \fB0\fP\&. If \fBCLICOLOR\fP is set to another
value, it corresponds to the \fBauto\fP mode. The \fBalways\fP mode is set if
\fBCLICOLOR_FORCE\fP is set to a value different than \fB0\fP\&.
\fBNO_COLOR\fP variable prevails over \fBCLICOLOR\fP and
\fBCLICOLOR_FORCE\fP\&. Color mode set with these three variables is
superseded by mode set with \fI\%MODULES_COLOR\fP environment variable.
.UNINDENT
.INDENT 0.0
.TP
.B MODULES_COLORS
Specifies the colors and other attributes used to highlight various parts of
the output. Its value is a colon\-separated list of output items associated to
a Select Graphic Rendition (SGR) code. It follows the same syntax than
\fBLS_COLORS\fP\&.
.sp
Output items are designated by keys. Items able to be colorized are:
highlighted element (\fBhi\fP), debug information (\fBdb\fP), trace information
(\fBtr\fP), tag separator (\fBse\fP); Error (\fBer\fP), warning (\fBwa\fP), module
error (\fBme\fP) and info (\fBin\fP) message prefixes; Modulepath (\fBmp\fP),
directory (\fBdi\fP), module alias (\fBal\fP), module symbolic version (\fBsy\fP),
module \fBdefault\fP version (\fBde\fP) and modulefile command (\fBcm\fP).
.sp
See the Select Graphic Rendition (SGR) section in the documentation of the
text terminal that is used for permitted values and their meaning as
character attributes. These substring values are integers in decimal
representation and can be concatenated with semicolons. Modules takes care of
assembling the result into a complete SGR sequence (\fB\e33[...m\fP). Common
values to concatenate include \fB1\fP for bold, \fB4\fP for underline, \fB30\fP to
\fB37\fP for foreground colors and \fB90\fP to \fB97\fP for 16\-color mode
foreground colors. See also \fI\%https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_(Select_Graphic_Rendition)_parameters\fP
for a complete SGR code reference.
.sp
No graphical rendition will be applied to an output item that could normaly
be colored but which is not defined in the color set. Thus if
\fI\%MODULES_COLORS\fP is defined empty, no output will be colored at all.
.sp
The color set is defined for Modules in the following order of preference:
\fI\%MODULES_COLORS\fP environment variable, then the default set in
\fBmodulecmd.tcl\fP script configuration. Which means
\fI\%MODULES_COLORS\fP overrides default configuration.
.UNINDENT
.INDENT 0.0
.TP
.B MODULES_EXTENDED_DEFAULT
If set to \fB1\fP, a specified module version is matched against starting
portion of existing module versions, where portion is a substring separated
from the rest of the version string by a \fB\&.\fP character. For example
specified modules \fBmod/1\fP and \fBmod/1.2\fP will match existing  modulefile
\fBmod/1.2.3\fP\&.
.sp
In case multiple modulefiles match the specified module version and a single
module has to be selected, the explicitly set default version is returned if
it is part of matching modulefiles. Otherwise the implicit default among
matching modulefiles is returned if defined (see
\fI\%MODULES_IMPLICIT_DEFAULT\fP section)
.sp
This environment variable supersedes the value of the configuration option
\fBextended_default\fP set in \fBmodulecmd.tcl\fP script.
.UNINDENT
.INDENT 0.0
.TP
.B MODULES_ICASE
When module specification are passed as argument to module sub\-commands or
modulefile Tcl commands, defines the case sensitiveness to apply to match
them. When \fI\%MODULES_ICASE\fP is set to \fBnever\fP, a case sensitive
match is applied in any cases. When set to \fBsearch\fP, a case insensitive
match is applied to the \fI\%avail\fP, \fI\%whatis\fP and \fI\%paths\fP
sub\-commands. When set to \fBalways\fP, a case insensitive match is also
applied to the other module sub\-commands and modulefile Tcl commands for the
module specification they receive as argument.
.sp
Case sensitiveness behavior is defined in the following order of preference:
\fI\%\-\-icase\fP command line switch, which corresponds to the \fBalways\fP
mode, then \fI\%MODULES_ICASE\fP environment variable, then the default set
in \fBmodulecmd.tcl\fP script configuration. Which means
\fI\%MODULES_ICASE\fP overrides default configuration and \fI\%\-\-icase\fP
command line switch overrides every other ways to set case sensitiveness
behavior.
.UNINDENT
.INDENT 0.0
.TP
.B MODULES_IMPLICIT_DEFAULT
Defines (if set to \fB1\fP) or not (if set to \fB0\fP) an implicit default
version for modules without a default version explicitly defined (see
Locating Modulefiles section in the modulefile(4) man page).
.sp
Without either an explicit or implicit default version defined a module must
be fully qualified (version should be specified in addition to its name) to
get:
.INDENT 7.0
.IP \(bu 2
targeted by module \fI\%load\fP, \fI\%switch\fP, \fI\%display\fP,
\fI\%help\fP, \fI\%test\fP and \fI\%path\fP sub\-commands.
.IP \(bu 2
restored from a collection, unless already loaded in collection\-specified
order.
.IP \(bu 2
automatically loaded by automated module handling mechanisms (see
\fI\%MODULES_AUTO_HANDLING\fP section) when declared as module
requirement, with \fBprereq\fP or \fBmodule load\fP
modulefile commands.
.UNINDENT
.sp
An error is returned in the above situations if either no explicit or
implicit default version is defined.
.sp
This environment variable supersedes the value of the configuration option
\fBimplicit_default\fP set in \fBmodulecmd.tcl\fP script. This environment
variable is ignored if \fBimplicit_default\fP has been declared locked in
\fBlocked_configs\fP configuration option.
.UNINDENT
.INDENT 0.0
.TP
.B MODULES_LMALTNAME
A colon separated list of the alternative names set through
\fBmodule\-version\fP and \fBmodule\-alias\fP statements corresponding to
all loaded \fImodulefiles\fP\&. Each element in this list starts by the name of the
loaded \fImodulefile\fP followed by all alternative names resolving to it. The
loaded modulefile and its alternative names are separated by the ampersand
character.
.sp
This environment variable is intended for \fBmodule\fP command internal
use to get knowledge of the alternative names matching loaded \fImodulefiles\fP
in order to keep environment consistent when conflicts or pre\-requirements
are set over these alternative designations. It also helps to find a match
after \fImodulefiles\fP being loaded when \fI\%unload\fP, \fI\%is\-loaded\fP
or \fI\%info\-loaded\fP actions are run over these names.
.UNINDENT
.INDENT 0.0
.TP
.B MODULES_LMCONFLICT
A colon separated list of the \fBconflict\fP statements defined by all
loaded \fImodulefiles\fP\&. Each element in this list starts by the name of the
loaded \fImodulefile\fP declaring the conflict followed by the name of all
modulefiles it declares a conflict with. These loaded modulefiles and
conflicting modulefile names are separated by the ampersand character.
.sp
This environment variable is intended for \fBmodule\fP command internal
use to get knowledge of the conflicts declared by the loaded \fImodulefiles\fP
in order to keep environment consistent when a conflicting module is asked
for load afterward.
.UNINDENT
.INDENT 0.0
.TP
.B MODULES_LMNOTUASKED
A colon separated list of all loaded \fImodulefiles\fP that were not explicitly
asked for load from the command\-line.
.sp
This environment variable is intended for \fBmodule\fP command internal
use to distinguish the \fImodulefiles\fP that have been loaded automatically
from modulefiles that have been asked by users.
.UNINDENT
.INDENT 0.0
.TP
.B MODULES_LMPREREQ
A colon separated list of the \fBprereq\fP statements defined by all
loaded \fImodulefiles\fP\&. Each element in this list starts by the name of the
loaded \fImodulefile\fP declaring the pre\-requirement followed by the name of all
modulefiles it declares a \fBprereq\fP with. These loaded modulefiles and
pre\-required modulefile names are separated by the ampersand character. When
a \fBprereq\fP statement is composed of multiple modulefiles, these
modulefile names are separated by the pipe character.
.sp
This environment variable is intended for \fBmodule\fP command internal
use to get knowledge of the pre\-requirement declared by the loaded
\fImodulefiles\fP in order to keep environment consistent when a pre\-required
module is asked for unload afterward.
.UNINDENT
.INDENT 0.0
.TP
.B MODULES_LMSOURCESH
A colon separated list of the \fBsource\-sh\fP statements defined by all
loaded \fImodulefiles\fP\&. Each element in this list starts by the name of the
loaded \fImodulefile\fP declaring the environment changes made by the evaluation
of \fBsource\-sh\fP scripts. This name is followed by each
\fBsource\-sh\fP statement call and corresponding result achieved in
modulefile. The loaded modulefile name and each \fBsource\-sh\fP statement
description are separated by the ampersand character. The \fBsource\-sh\fP
statement call and each resulting modulefile command (corresponding to the
environment changes done by sourced script) are separated by the pipe
character.
.sp
This environment variable is intended for \fBmodule\fP command internal
use to get knowledge of the modulefile commands applied for each
\fBsource\-sh\fP command when loading the modulefile. In order to reverse
these modulefile commands when modulefile is unloaded to undo the environment
changes.
.UNINDENT
.INDENT 0.0
.TP
.B MODULES_ML
If set to \fB1\fP, define \fBml\fP command when initializing Modules (see
\fI\%Package Initialization\fP section). If set to \fB0\fP, \fBml\fP command is
not defined.
.sp
\fBml\fP command enablement is defined in the following order of
preference: \fI\%MODULES_ML\fP environment variable then the default set in
\fBmodulecmd.tcl\fP script configuration. Which means \fI\%MODULES_ML\fP
overrides default configuration.
.UNINDENT
.INDENT 0.0
.TP
.B MODULES_NEARLY_FORBIDDEN_DAYS
Number of days a module is considered \fInearly forbidden\fP prior reaching its
expiry date set by \fBmodule\-forbid\fP modulefile command. When a \fInearly
forbidden\fP module is evaluated a warning message is issued to inform module
will soon be forbidden. If set to \fB0\fP, modules will never be considered
\fInearly forbidden\fP\&. Accepted values are integers.
.sp
This configuration is defined in the following order of preference:
\fI\%MODULES_NEARLY_FORBIDDEN_DAYS\fP environment variable then the default
set in \fBmodulecmd.tcl\fP script configuration. Which means
\fI\%MODULES_NEARLY_FORBIDDEN_DAYS\fP overrides default configuration.
.UNINDENT
.INDENT 0.0
.TP
.B MODULES_PAGER
Text viewer for use to paginate message output if error output stream is
attached to a terminal. The value of this variable is composed of a pager
command name or path eventually followed by command\-line options.
.sp
Paging command and options are defined for Modules in the following order of
preference: \fI\%MODULES_PAGER\fP environment variable, then the default
set in \fBmodulecmd.tcl\fP script configuration. Which means
\fI\%MODULES_PAGER\fP overrides default configuration.
.sp
If \fI\%MODULES_PAGER\fP variable is set to an empty string or to the value
\fBcat\fP, pager will not be launched.
.UNINDENT
.INDENT 0.0
.TP
.B MODULES_RUN_QUARANTINE
A space separated list of environment variable names that should be passed
indirectly to \fBmodulecmd.tcl\fP to protect its run\-time environment from
side\-effect coming from their current definition.
.sp
Each variable found in \fI\%MODULES_RUN_QUARANTINE\fP will have its value
emptied or set to the value of the corresponding
\fI\%MODULES_RUNENV_<VAR>\fP variable when defining \fBmodulecmd.tcl\fP
run\-time environment.
.sp
Original values of these environment variables set in quarantine are passed
to \fBmodulecmd.tcl\fP via \fI\%<VAR>_modquar\fP variables.
.UNINDENT
.INDENT 0.0
.TP
.B MODULES_RUNENV_<VAR>
Value to set to environment variable \fB<VAR>\fP for
\fBmodulecmd.tcl\fP run\-time execution if \fB<VAR>\fP is referred in
\fI\%MODULES_RUN_QUARANTINE\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B MODULES_SEARCH_MATCH
When searching for modules with \fI\%avail\fP sub\-command, defines the way
query string should match against available module names. With
\fBstarts_with\fP value, returned modules are those whose name begins by search
query string. When set to \fBcontains\fP, any modules whose fully qualified
name contains search query string are returned.
.sp
Module search match style is defined in the following order of preference:
\fI\%\-\-starts\-with\fP and \fI\%\-\-contains\fP command line switches, then
\fI\%MODULES_SEARCH_MATCH\fP environment variable, then the default set in
\fBmodulecmd.tcl\fP script configuration. Which means
\fI\%MODULES_SEARCH_MATCH\fP overrides default configuration and
\fI\%\-\-starts\-with\fP/\fI\%\-\-contains\fP command line switches override
every other ways to set search match style.
.UNINDENT
.INDENT 0.0
.TP
.B MODULES_SET_SHELL_STARTUP
If set to \fB1\fP, defines when \fBmodule\fP command initializes the shell
startup file to ensure that the \fBmodule\fP command is still defined in
sub\-shells. Setting shell startup file means defining the \fBENV\fP and
\fBBASH_ENV\fP environment variable to the Modules bourne shell
initialization script. If set to \fB0\fP, shell startup file is not defined.
.UNINDENT
.INDENT 0.0
.TP
.B MODULES_SILENT_SHELL_DEBUG
If set to \fB1\fP, disable any \fBxtrace\fP or \fBverbose\fP debugging property set
on current shell session for the duration of either the module command or the
module shell initialization script. Only applies to Bourne Shell (sh) and its
derivatives.
.UNINDENT
.INDENT 0.0
.TP
.B MODULES_SITECONFIG
Location of a site\-specific configuration script to source into
\fBmodulecmd.tcl\fP\&. See also \fI\%Modulecmd startup\fP section.
.sp
This environment variable is ignored if \fBextra_siteconfig\fP has been
declared locked in \fBlocked_configs\fP configuration option.
.UNINDENT
.INDENT 0.0
.TP
.B MODULES_TERM_BACKGROUND
Inform Modules of the terminal background color to determine if the color set
for dark background or the color set for light background should be used to
color output in case no specific color set is defined with the
\fI\%MODULES_COLORS\fP variable. Accepted values are \fBdark\fP and
\fBlight\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B MODULES_UNLOAD_MATCH_ORDER
When a module unload request matches multiple loaded modules, unload firstly
loaded module or lastly loaded module. Accepted values are \fBreturnfirst\fP
and \fBreturnlast\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B MODULES_USE_COMPAT_VERSION
If set to \fB1\fP prior to Modules package initialization, enable
Modules compatibility version (3.2 release branch) rather main version
at initialization scripts running time. Modules package compatibility
version should be installed along with main version for this environment
variable to have any effect.
.UNINDENT
.INDENT 0.0
.TP
.B MODULES_VERBOSITY
Defines the verbosity level of the module command. Available verbosity levels
from the least to the most verbose are:
.INDENT 7.0
.IP \(bu 2
\fBsilent\fP: turn off error, warning and informational messages but does not
affect module command output result.
.IP \(bu 2
\fBconcise\fP: enable error and warning messages but disable informational
messages.
.IP \(bu 2
\fBnormal\fP: turn on informational messages, like a report of the additional
module evaluations triggered by loading or unloading modules, aborted
evaluation issues or a report of each module evaluation occurring during a
\fI\%restore\fP or \fI\%source\fP sub\-commands.
.IP \(bu 2
\fBverbose\fP: add additional informational messages, like a systematic
report of the loading or unloading module evaluations.
.IP \(bu 2
\fBtrace\fP: provide details on module searches, resolutions, selections and
evaluations.
.IP \(bu 2
\fBdebug\fP: print debugging messages about module command execution.
.IP \(bu 2
\fBdebug2\fP: report \fBmodulecmd.tcl\fP procedure calls in addition to
printing debug messages.
.UNINDENT
.sp
Module command verbosity is defined in the following order of preference:
\fI\%\-\-silent\fP, \fI\%\-\-verbose\fP, \fI\%\-\-debug\fP and
\fI\%\-\-trace\fP command line switches, then \fI\%MODULES_VERBOSITY\fP
environment variable, then the default set in \fBmodulecmd.tcl\fP script
configuration. Which means \fI\%MODULES_VERBOSITY\fP overrides default
configuration and
\fI\%\-\-silent\fP/\fI\%\-\-verbose\fP/\fI\%\-\-debug\fP/\fI\%\-\-trace\fP
command line switches overrides every other ways to set verbosity level.
.UNINDENT
.INDENT 0.0
.TP
.B MODULES_WA_277
If set to \fB1\fP prior to Modules package initialization, enables workaround
for Tcsh history issue (see \fI\%https://github.com/cea\-hpc/modules/issues/277\fP).
This issue leads to erroneous history entries under Tcsh shell. When
workaround is enabled, an alternative \fImodule\fP alias is defined which fixes
the history mechanism issue. However the alternative definition of the
\fImodule\fP alias weakens shell evaluation of the code produced by modulefiles.
Characters with a special meaning for Tcsh shell (like \fB{\fP and \fB}\fP) may
not be used anymore in shell alias definition otherwise the evaluation of the
code produced by modulefiles will return a syntax error.
.UNINDENT
.INDENT 0.0
.TP
.B MODULESHOME
The location of the main Modules package file directory containing module
command initialization scripts, the executable program \fBmodulecmd.tcl\fP,
and a directory containing a collection of main \fImodulefiles\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B <VAR>_modquar
Value of environment variable \fB<VAR>\fP passed to \fBmodulecmd.tcl\fP
in order to restore \fB<VAR>\fP to this value once started.
.UNINDENT
.INDENT 0.0
.TP
.B <VAR>_modshare
Reference counter variable for path\-like variable \fB<VAR>\fP\&. A colon
separated list containing pairs of elements. A pair is formed by a path
element followed its usage counter which represents the number of times
this path has been enabled in variable \fB<VAR>\fP\&. A colon separates the
two parts of the pair.
.UNINDENT
.SH FILES
.sp
\fB/usr/share/modules\fP
.INDENT 0.0
.INDENT 3.5
The \fI\%MODULESHOME\fP directory.
.UNINDENT
.UNINDENT
.sp
\fB/etc/environment-modules/siteconfig.tcl\fP
.INDENT 0.0
.INDENT 3.5
The site\-specific configuration script of \fBmodulecmd.tcl\fP\&. An
additional configuration script could be defined using the
\fI\%MODULES_SITECONFIG\fP environment variable.
.UNINDENT
.UNINDENT
.sp
\fB/etc/environment-modules/rc\fP
.INDENT 0.0
.INDENT 3.5
The system\-wide modules rc file. The location of this file can be changed
using the \fI\%MODULERCFILE\fP environment variable as described above.
.UNINDENT
.UNINDENT
.sp
\fB$HOME/.modulerc\fP
.INDENT 0.0
.INDENT 3.5
The user specific modules rc file.
.UNINDENT
.UNINDENT
.sp
\fB$HOME/.module\fP
.INDENT 0.0
.INDENT 3.5
The user specific collection directory.
.UNINDENT
.UNINDENT
.sp
\fB/usr/share/modules/modulefiles\fP
.INDENT 0.0
.INDENT 3.5
The directory for system\-wide \fImodulefiles\fP\&. The location of the directory
can be changed using the \fI\%MODULEPATH\fP environment variable as
described above.
.UNINDENT
.UNINDENT
.sp
\fB/usr/lib/x86_64-linux-gnu/modulecmd.tcl\fP
.INDENT 0.0
.INDENT 3.5
The \fImodulefile\fP interpreter that gets executed upon each invocation
of \fBmodule\fP\&.
.UNINDENT
.UNINDENT
.sp
\fB/usr/share/modules/init/<shell>\fP
.INDENT 0.0
.INDENT 3.5
The Modules package initialization file sourced into the user\(aqs environment.
.UNINDENT
.UNINDENT
.SH SEE ALSO
.sp
ml(1), modulefile(4)
.SH COPYRIGHT
1996-1999 John L. Furlani & Peter W. Osel, 1998-2017 R.K.Owen, 2002-2004 Mark Lakata, 2004-2017 Kent Mein, 2016-2020 Xavier Delaruelle
.\" Generated by docutils manpage writer.
.