Provided by: environment-modules_5.5.0-1_amd64 
NAME
modulefile - files containing Tcl code for the Modules package
DESCRIPTION
modulefiles are written in the Tool Command Language, Tcl(n) and are interpreted by the
modulecmd.tcl program via the module user interface. modulefiles can be loaded, unloaded,
or switched on-the-fly while the user is working; and can be used to implement site
policies regarding the access and use of applications.
A modulefile begins with the #%Module file signature, also called the Modules magic
cookie. A version number may be placed after this string. The version number is useful as
the modulefile format may change thus it reflects the minimum version of modulecmd.tcl
required to interpret the modulefile. If a version number doesn't exist, then
modulecmd.tcl will assume the modulefile is compatible. Files without the magic cookie or
with a version number greater than the current version of modulecmd.tcl will not be
interpreted. If the mcookie_version_check configuration is disabled the version number set
is not checked.
Each modulefile contains the changes to a user's environment needed to access an
application. Tcl is a simple programming language which permits modulefiles to be
arbitrarily complex, depending upon the application's and the modulefile writer's needs.
If support for extended tcl (tclX) has been configured for your installation of the
Modules package, you may use all the extended commands provided by tclX, too.
A typical modulefile is a simple bit of code that set or add entries to the PATH, MANPATH,
or other environment variables. A Modulefile is evaluated against current modulecmd.tcl's
mode which leads to specific evaluation results. For instance if the modulefile sets a
value to an environment variable, this variable is set when modulefile is loaded and unset
when modulefile is unloaded.
Tcl has conditional statements that are evaluated when the modulefile is interpreted. This
is very effective for managing path or environment changes due to different OS releases or
architectures. The user environment information is encapsulated into a single modulefile
kept in a central location. The same modulefile is used by every user on any machine. So,
from the user's perspective, starting an application is exactly the same irrespective of
the machine or platform they are on.
modulefiles also hide the notion of different types of shells. From the user's
perspective, changing the environment for one shell looks exactly the same as changing the
environment for another shell. This is useful for new or novice users and eliminates the
need for statements such as "if you're using the C Shell do this ..., otherwise if you're
using the Bourne shell do this ...". Announcing and accessing new software is uniform and
independent of the user's shell. From the modulefile writer's perspective, this means one
set of information will take care of every type of shell.
MODULES SPECIFIC TCL COMMANDS
The Modules Package uses commands which are extensions to the "standard" Tool Command
Language Tcl(n) package. Unless otherwise specified, the Module commands return the empty
string. Some commands behave differently when a modulefile is loaded or unloaded. The
command descriptions assume the modulefile is being loaded.
always-load [options] modulefile...
Load modulefile and apply the keep-loaded tag to it in order to avoid the automatic
unload of this modulefile when modules dependent of it are unloaded.
always-load command accepts the following options:
• --modulepath modulepathlist
• --optional
• --tag taglist
modulefile is declared as a requirement of currently loading module. This command
acts as an alias of module load command. If more than one modulefile are specified,
then this list acts as a Boolean AND operation, which means all specified
modulefiles are required.
When the --optional option is set, each specified modulefile is declared as an
optional requirement. A modulefile that cannot be loaded, will not stop the
evaluation.
The --tag option accepts a list of module tags to apply to modulefile once loaded
in addition to the keep-loaded tag. taglist corresponds to the concatenation of
multiple tags separated by colon character. taglist should not contain tags
inherited from modulefile state or from other modulefile commands. If module is
already loaded, tags from taglist are added to the list of tags already applied to
this module.
The --modulepath option accepts a list of modulepath. modulepathlist corresponds to
the concatenation of multiple modulepaths separated by colon character. When this
option is set, required modulefile should be located within one of the listed
modulepaths. A path in this list may correspond to the first path elements of an
actual modulepath (e.g., /path/to will match modulefiles located into the
/path/to/modulefiles modulepath directory).
If an attempt to load modulefile is performed and --modulepath option is set,
modulefile will be searched in the enabled modulepaths whose start match one of the
specified paths and in the specified paths not matching any enabled modulepaths.
For instance if this option is set to /path/to:/another/path and
/path/to/modulefiles is currently the sole enabled modulepath, modulefile will be
searched into /path/to/modulefiles and /another/path directories.
append-path [-d C|--delim C|--delim=C] [--duplicates] variable value...
See prepend-path.
break This is not a Modules-specific command, it's actually part of Tcl, which has been
overloaded similar to the continue and exit commands to have the effect of causing
the module not to be listed as loaded and not affect other modules being loaded
concurrently. All non-environment commands within the module will be performed up
to this point. Processing will continue on to the next module on the command line
unless if abort_on_error configuration option is enabled for running module
sub-command. The break command will only have this effect if not used within a Tcl
loop though.
An example: Suppose that a full selection of modulefiles are needed for various
different architectures, but some of the modulefiles are not needed and the user
should be alerted. Having the unnecessary modulefile be a link to the following
notavail modulefile will perform the task as required.
#%Module
proc ModulesHelp {} {
puts stderr {This module does nothing but alert the user}
puts stderr "that the [module-info name] module is not available"
}
module-whatis {Notifies user that module is not available.}
set curMod [module-info name]
if {[module-info mode load]} {
puts stderr "Note: '$curMod' is not available for [uname sysname]."
}
break
Modulefile using break command when unloading may be unloaded anyway if --force
option is set. To forbid the unload of a modulefile, it is recommended to tag it
super-sticky with module-tag command.
chdir directory
Set the current working directory to directory.
complete shell name body
Define shell completion for command name with specified body if shell is the
current shell under which modulecmd.tcl was invoked. Body corresponds to argument
options accepted by the shell command which defines completion. When a modulefile
is unloaded, complete becomes uncomplete.
The following shells are supported: bash, tcsh, bash and fish. Please refer to the
documentation of these shells to learn how to define completion. The command is
ignored if an unsupported shell is specified.
conflict modulefile...
conflict controls whether or not the modulefile will be loaded. The conflict
command lists modulefiles which conflict with the current modulefile. If a list
contains more than one modulefile, then each member of the list acts as a Boolean
OR operation. Multiple conflict commands may be used to create a Boolean AND
operation. If one of the requirements have not been satisfied, an error is reported
and the current modulefile makes no changes to the user's environment.
If an argument for conflict is a directory and any other modulefile from that
directory has been loaded, then a conflict will occur. For example, specifying X11
as a conflict will stop X11/R4 and X11/R5 from being loaded at the same time.
The parameter modulefile may also be a symbolic modulefile name or a modulefile
alias. It may also leverage a specific syntax to finely select module version (see
Advanced module version specifiers section below).
If the conflict_unload and auto_handling configuration options are enabled,
conflict will attempt to unload all loaded modules that match specification. (see
MODULES_AUTO_HANDLING in module).
continue
This is not a modules specific command but another overloaded Tcl command and is
similar to the break or exit commands except the module will be listed as loaded as
well as performing any environment or Tcl commands up to this point and then
continuing on to the next module on the command line. The continue command will
only have this effect if not used within a Tcl loop though.
depends-on [options] modulefile...
Alias of prereq-all command.
exit [N]
This is not a modules specific command but another overloaded Tcl command and is
similar to the break or continue commands. However, this command will cause the
immediate cessation of this module. Any additional modules on the command line will
not be evaluated even if the abort_on_error configuration option is disabled for
running module sub-command. This module and the subsequent modules will not be
listed as loaded. No environment commands will be performed in the current module.
family name
Defines loading modulefile as a member of family name. Only one member of a family
could be loaded. Error is raised when attempting to load another member of the same
family name.
family corresponds to the definition of a conflict on name and the definition of a
module-alias name targeting currently loading module.
In addition, the MODULES_FAMILY_<NAME> environment variable is defined and set to
the currently loading module name minus version. This variable helps to know what
module provides for the family name in the currently loaded environment. For
instance if loading modulefile foo/1.0 defines being member of the bar family, the
MODULES_FAMILY_BAR will be set to the foo value. For compatibility, the
LMOD_FAMILY_<NAME> environment variable is also defined and set to the same value
than MODULES_FAMILY_<NAME>.
name should be a non-empty string only containing characters that could be part of
an environment variable name (i.e., [a-zA-Z0-9_]).
If the conflict_unload and auto_handling configuration options are enabled, an
attempt to unload loaded module that defines the same family is made. (see
MODULES_AUTO_HANDLING in module).
getenv [--return-value] variable [value]
Returns value of environment variable. If variable is not defined, value is
returned if set, an empty string is returned otherwise. The getenv command should
be preferred over the Tcl global variable env to query environment variables.
When modulefile is evaluated in display mode, getenv returns variable name prefixed
with dollar sign (e.g., $variable) unless if the --return-value option is set. When
this option is set the value of environment variable or defined fallback value is
returned in display mode.
getvariant [--return-value] variant [value]
Returns value of designated variant. If variant is not defined, value is returned
if set, an empty string is returned otherwise. The getvariant command should be
preferred over the ModuleVariant Tcl array to query a variant value.
When modulefile is evaluated in display mode, getvariant returns variant name
enclosed in curly braces (e.g., {variant}) unless if the --return-value option is
set. When this option is set the value of variant or defined fallback value is
returned in display mode.
hide-modulefile modulefile
Alias of module-hide command.
hide-version modulefile
Alias of module-hide command.
is-avail modulefile...
The is-avail command returns a true value if any of the listed modulefiles exists
in enabled MODULEPATH. If a list contains more than one modulefile, then each
member acts as a boolean OR operation. If an argument for is-avail is a directory
and a modulefile exists in the directory is-avail would return a true value.
The parameter modulefile may also be a symbolic modulefile name or a modulefile
alias. It may also leverage a specific syntax to finely select module version (see
Advanced module version specifiers section below).
is-loaded [modulefile...]
The is-loaded command returns a true value if any of the listed modulefiles has
been loaded or if any modulefile is loaded in case no argument is provided. If a
list contains more than one modulefile, then each member acts as a boolean OR
operation. If an argument for is-loaded is a directory and any modulefile from the
directory has been loaded is-loaded would return a true value.
The parameter modulefile may also be a symbolic modulefile name or a modulefile
alias. It may also leverage a specific syntax to finely select module version (see
Advanced module version specifiers section below).
is-saved [collection...]
The is-saved command returns a true value if any of the listed collections exists
or if any collection exists in case no argument is provided. If a list contains
more than one collection, then each member acts as a boolean OR operation.
If MODULES_COLLECTION_TARGET is set, a suffix equivalent to the value of this
variable is appended to the passed collection name. In case no collection argument
is provided, a true value will only be returned if a collection matching currently
set target exists.
is-used [directory...]
The is-used command returns a true value if any of the listed directories has been
enabled in MODULEPATH or if any directory is enabled in case no argument is
provided. If a list contains more than one directory, then each member acts as a
boolean OR operation.
lsb-release field
Provide certain Linux Standard Base (LSB) information. lsb-release will invoke the
lsb_release(1) command to get each field information.
field values are:
• id: string id of distributor
• release: release number of distribution
• codename: codename according to distribution release
module [sub-command] [sub-command-options] [sub-command-args]
This command permits a modulefile to load or unload other modulefiles or to use or
unuse modulepaths. No checks are made to ensure that the modulefile does not try to
load itself. Often it is useful to have a single modulefile that performs a number
of module load commands. For example, if every user on the system requires a basic
set of applications loaded, then a core modulefile would contain the necessary
module load commands.
The --not-req option may be set for the load, try-load, load-any, unload and switch
sub-commands to inhibit the definition of an implicit prereq or conflict
requirement onto specified modules.
On try-load sub-command, modulefiles are considered optional prereq requirement.
However an error is raised if they cannot be loaded unless if they are not found or
forbidden.
The load-any sub-command loads one modulefile from the specified list. An error is
obtained if no modulefile from the list can be loaded. No operation is performed if
a modulefile from the list is found already loaded.
The unload sub-command unloads one matching modulefile for each module
specification provided as argument if auto_handling or conflict_unload
configuration options are disabled. When both options are enabled, unload removes
all loaded modules matching each module specification. When both options are
enabled, modules dependent of the unloaded modules are also unloaded. Otherwise an
error is raised if module to unload has a dependent module loaded.
The unuse sub-command accepts the --remove-on-unload, --noop-on-unload,
--append-on-unload and --prepend-on-unload options to control the behavior to apply
when modulefile is unloaded. See remove-path for further explanation.
The load, try-load, load-any and switch sub-commands accept the --tag option to
apply specified tags to modulefile once loaded. Option accepts a concatenation of
multiple module tags separated by colon character. taglist should not contain tags
inherited from modulefile state or from other modulefile commands. If module is
already loaded, tags from taglist are added to the list of tags already applied to
this module.
Command line switches --auto, --no-auto and --force are ignored when passed to a
module command set in a modulefile.
Not all the sub-commands described in the Module Sub-Commands section of the module
man page are available when module is used as a Modules specific Tcl command. The
following table summarizes the different sub-commands available for each
interpretation context.
┌─────────────────────────┬──────────────────────────┬──────────────────────────┐
│Sub-commands available │ Sub-commands available │ Sub-commands available │
│from modulefile │ from initrc │ from run-command (rc) │
│interpretation │ configuration file and │ file interpretation │
│ │ sourced script file │ │
└─────────────────────────┴──────────────────────────┴──────────────────────────┘
│load, load-any, switch, │ Same sub-commands │ None │
│try-load, unload, unuse, │ available than for │ │
│use. Also available but │ modulefile and config │ │
│not recommended for use │ sub-command. │ │
│from regular modulefile: │ │ │
│aliases, avail, display, │ │ │
│initadd, initclear, │ │ │
│initlist, initprepend, │ │ │
│initrm, initswitch, │ │ │
│list, purge, reload, │ │ │
│restore, save, savelist, │ │ │
│saverm, saveshow, │ │ │
│search, test, whatis │ │ │
└─────────────────────────┴──────────────────────────┴──────────────────────────┘
module-alias name modulefile
Assigns the modulefile to the alias name. This command should be placed in one of
the modulecmd.tcl rc files in order to provide shorthand invocations of frequently
used modulefile names.
The parameter modulefile may be either
• a fully qualified modulefile with name and version
• a symbolic modulefile name
• another modulefile alias
module-forbid [options] modulefile...
Forbid use of modulefile. An error is obtained when trying to evaluate a forbidden
module. This command should be placed in one of the modulecmd.tcl rc files.
module-forbid command accepts the following options:
• --after datetime
• --before datetime
• --not-user {user...}
• --not-group {group...}
• --user {user...}
• --group {group...}
• --message {text message}
• --nearly-message {text message}
If --after option is set, forbidding is only effective after specified date time.
Following the same principle, if --before option is set, forbidding is only
effective before specified date time. Accepted date time format is
YYYY-MM-DD[THH:MM]. If no time (HH:MM) is specified, 00:00 is assumed. --after and
--before options are not supported on Tcl versions prior to 8.5.
If --not-user option is set, forbidding is not applied if the username of the user
currently running modulecmd.tcl is part of the list of username specified.
Following the same approach, if --not-group option is set, forbidding is not
applied if current user is member of one the group specified. When both options are
set, forbidding is not applied if a match is found for --not-user or --not-group.
If --user option is set, forbidding is applied only if the username of the user
currently running modulecmd.tcl is part of the list of username specified.
Following the same approach, if --group option is set, forbidding is applied only
if current user is member of one the group specified. When both options are set,
forbidding is applied if a match is found for --user or --group. These two options
prevail over --not-user and --not-group options.
Error message returned when trying to evaluate a forbidden module can be
supplemented with the text message set through --message option.
If --after option is set, modules are considered nearly forbidden during a number
of days defined by the nearly_forbidden_days modulecmd.tcl configuration option
(see MODULES_NEARLY_FORBIDDEN_DAYS), prior reaching the expiry date fixed by
--after option. When a nearly forbidden module is evaluated a warning message is
issued to inform module will soon be forbidden. This warning message can be
supplemented with the text message set through --nearly-message option.
If a module-forbid command applies to a modulefile also targeted by a module-hide
--hard command, this module is unveiled when precisely named to return an access
error.
Forbidden modules included in the result of an avail sub-command are reported with
a forbidden tag applied to them. Nearly forbidden modules included in the result of
an avail or a list sub-command are reported with a nearly-forbidden tag applied to
them. See Module tags section in module.
The parameter modulefile may leverage a specific syntax to finely select module
version (see Advanced module version specifiers section below). It may also be a
full path file name to precisely designate one module in a specific modulepath.
module-hide [options] modulefile...
Hide modulefile to exclude it from available module search or module selection
unless query refers to modulefile by its exact name. This command should be placed
in one of the modulecmd.tcl rc files.
module-hide command accepts the following options:
• --soft|--hard
• --hidden-loaded
• --after datetime
• --before datetime
• --not-user {user...}
• --not-group {group...}
• --user {user...}
• --group {group...}
When --soft option is set, modulefile is also set hidden, but hiding is disabled
when search or selection query's root name matches module's root name. This soft
hiding mode enables to hide modulefiles from bare module availability listing yet
keeping the ability to select such module for load with the regular resolution
mechanism (i.e., no need to use module exact name to select it)
When --hard option is set, modulefile is also set hidden and stays hidden even if
search or selection query refers to modulefile by its exact name.
When --hidden-loaded option is set, hidden state also applies to the modulefile
when it is loaded. Hidden loaded modules do not appear on list sub-command output,
unless --all option is set. Their loading or unloading informational messages are
not reported unless the verbosity of Modules is set to a level higher than verbose.
Hidden loaded modules are detected in any cases by state query commands like
is-loaded.
If --after option is set, hiding is only effective after specified date time.
Following the same principle, if --before option is set, hiding is only effective
before specified date time. Accepted date time format is YYYY-MM-DD[THH:MM]. If no
time (HH:MM) is specified, 00:00 is assumed. --after and --before options are not
supported on Tcl versions prior to 8.5.
If --not-user option is set, hiding is not applied if the username of the user
currently running modulecmd.tcl is part of the list of username specified.
Following the same approach, if --not-group option is set, hiding is not applied if
current user is member of one the group specified. When both options are set,
hiding is not applied if a match is found for --not-user or --not-group.
If --user option is set, hiding is applied only if the username of the user
currently running modulecmd.tcl is part of the list of username specified.
Following the same approach, if --group option is set, hiding is applied only if
current user is member of one the group specified. When both options are set,
hiding is applied if a match is found for --user or --group. These two options
prevail over --not-user and --not-group options.
If the --all option is set on avail, aliases, whatis or search sub-commands, hiding
is disabled thus hidden modulefiles are included in module search. Hard-hidden
modules (i.e., declared hidden with --hard option) are not affected by --all and
stay hidden even if option is set. --all option does not apply to module selection
sub-commands like load. Thus in such context a hidden module should always be
referred by its exact full name (e.g., foo/1.2.3 not foo) unless if it has been
hidden in --soft mode. A hard-hidden module cannot be unveiled or selected in any
case.
If several module-hide commands target the same modulefile, the strongest hiding
level is retained which means if both a regular, a --soft hiding command match a
given module, regular hiding mode is considered. If both a regular and a --hard
hiding command match a given module, hard hiding mode is retained. A set
--hidden-loaded option is retained even if the module-hide statement on which it is
declared is superseded by a stronger module-hide statement with no --hidden-loaded
option set.
Hidden modules included in the result of an avail sub-command are reported with a
hidden tag applied to them. Hidden loaded modules included in the result of a list
sub-command are reported with a hidden-loaded tag applied to them. This tag is not
reported on avail sub-command context. See Module tags section in module.
The parameter modulefile may also be a symbolic modulefile name or a modulefile
alias. It may also leverage a specific syntax to finely select module version (see
Advanced module version specifiers section below). Moreover it may also be a full
path file name to precisely designate one module in a specific modulepath.
module-info option [info-args]
Provide information about the modulecmd.tcl program's state. Some of the
information is specific to the internals of modulecmd.tcl. option is the type of
information to be provided, and info-args are any arguments needed.
module-info alias name
Returns the full modulefile name to which the modulefile alias name is assigned
module-info command [commandname]
Returns the currently running modulecmd.tcl's command as a string if no
commandname is given.
Returns 1 if modulecmd.tcl's command is commandname. commandname can be: load,
unload, refresh, reload, source, switch, display, avail, aliases, list, whatis,
search, purge, restore, help, test, try-load, load-any, mod-to-sh, reset, stash
or stashpop.
module-info loaded modulefile
Returns the names of currently loaded modules matching passed modulefile. The
parameter modulefile might either be a fully qualified modulefile with name and
version or just a directory which in case all loaded modulefiles from the
directory will be returned. The parameter modulefile may also be a symbolic
modulefile name or a modulefile alias.
This command only returns the name and version of designated loaded module. The
defined variants of the loaded module are not included in the returned string.
module-info mode [modetype]
Returns the current modulecmd.tcl's mode as a string if no modetype is given.
Returns 1 if modulecmd.tcl's mode is modetype. modetype can be: load, unload,
remove (alias of unload), switch, refresh, nonpersist (alias of refresh),
display, help, test, whatis or scan.
module-info name
Return the name of the modulefile. This is not the full pathname for modulefile.
See the Modules Variables section for information on the full pathname.
This command only returns the name and version of currently evaluating
modulefile. The defined variants are not included in the returned string. See
getvariant command or ModuleVariant array variable to get defined variant values
for currently evaluating modulefile.
module-info shell [shellname]
Return the current shell under which modulecmd.tcl was invoked if no shellname
is given. The current shell is the first parameter of modulecmd.tcl, which is
normally hidden by the module alias.
If a shellname is given, returns 1 if modulecmd.tcl's current shell is
shellname, returns 0 otherwise. shellname can be: sh, bash, ksh, zsh, csh, tcsh,
fish, cmd, pwsh, tcl, perl, python, ruby, lisp, cmake, r.
module-info shelltype [shelltypename]
Return the family of the shell under which modulefile was invoked if no
shelltypename is given. As of module-info shell this depends on the first
parameter of modulecmd.tcl. The output reflects a shell type determining the
shell syntax of the commands produced by modulecmd.tcl.
If a shelltypename is given, returns 1 if modulecmd.tcl's current shell type is
shelltypename, returns 0 otherwise. shelltypename can be: sh, csh, fish, cmd,
pwsh, tcl, perl, python, ruby, lisp, cmake, r.
module-info specified
Return the module designation (name, version and variants) specified that led to
current modulefile evaluation.
module-info symbols modulefile
Returns a list of all symbolic versions assigned to the passed modulefile. The
parameter modulefile might either be a full qualified modulefile with name and
version, another symbolic modulefile name or a modulefile alias.
module-info tags [tag]
Returns all tags assigned to currently evaluated modulefile as a list of strings
if no tag name is given (see Module tags section in module)
When tags are assigned to specific module variants, they are returned only if
this variant is the one currently evaluated.
Returns 1 if one of the tags applying to currently evaluated modulefile is tag.
Returns 0 otherwise.
module-info type
Returns either C or Tcl to indicate which module command is being executed,
either the C version or the Tcl-only version, to allow the modulefile writer to
handle any differences between the two.
module-info usergroups [name]
Returns all the groups the user currently running modulecmd.tcl is member of as
a list of strings if no name is given.
Returns 1 if one of the group current user running modulecmd.tcl is member of is
name. Returns 0 otherwise.
If the Modules Tcl extension library is disabled, the id(1) command is invoked
to fetch groups of current user.
module-info username [name]
Returns the username of the user currently running modulecmd.tcl as a string if
no name is given.
Returns 1 if username of current user running modulecmd.tcl is name. Returns 0
otherwise.
If the Modules Tcl extension library is disabled, the id(1) command is invoked
to fetch username of current user.
module-info version modulefile
Returns the physical module name and version of the passed symbolic version
modulefile. The parameter modulefile might either be a full qualified modulefile
with name and version, another symbolic modulefile name or a modulefile alias.
module-tag [options] tag modulefile...
Associate tag to designated modulefile. This tag information will be reported along
modulefile on avail and list sub-commands (see Module tags section in module). Tag
information can be queried during modulefile evaluation with the module-info tags
modulefile command. module-tag commands should be placed in one of the
modulecmd.tcl rc files.
module-tag command accepts the following options:
• --not-user {user...}
• --not-group {group...}
• --user {user...}
• --group {group...}
If --not-user option is set, the tag is not applied if the username of the user
currently running modulecmd.tcl is part of the list of username specified.
Following the same approach, if --not-group option is set, the tag is not applied
if current user is member of one the group specified. When both options are set,
the tag is not applied if a match is found for --not-user or --not-group.
If --user option is set, the tag is applied only if the username of the user
currently running modulecmd.tcl is part of the list of username specified.
Following the same approach, if --group option is set, the tag is applied only if
current user is member of one the group specified. When both options are set, the
tag is applied if a match is found for --user or --group. These two options prevail
over --not-user and --not-group options.
The parameter modulefile may also be a symbolic modulefile name or a modulefile
alias. It may also leverage a specific syntax to finely select module version (see
Advanced module version specifiers section below). Moreover it may also be a full
path file name to precisely designate one module in a specific modulepath.
Tags inherited from other modulefile commands or module states cannot be set with
module-tag. Otherwise an error is returned. Those special tags are: auto-loaded,
forbidden, hidden, hidden-loaded, loaded and nearly-forbidden.
When tag equals sticky or super-sticky, designated modulefile is defined Sticky
modules.
When tag equals keep-loaded, designated modulefile is not automatically unloaded
when it has been auto-loaded and its dependent modules are getting unloaded.
module-version modulefile version-name...
Assigns the symbolic version-name to the modulefile. This command should be placed
in one of the modulecmd.tcl rc files in order to provide shorthand invocations of
frequently used modulefile names.
The special version-name default specifies the default version to be used for
module commands, if no specific version is given. This replaces the definitions
made in the .version file in former modulecmd.tcl releases.
The parameter modulefile may be either
• a fully or partially qualified modulefile with name / version. If name is . (dot)
then the current directory name is assumed to be the module name. (Use this for
deep modulefile directories.)
• a symbolic modulefile name
• another modulefile alias
module-virtual name modulefile
Assigns the modulefile to the virtual module name. This command should be placed in
rc files in order to define virtual modules.
A virtual module stands for a module name associated to a modulefile. The
modulefile is the script interpreted when loading or unloading the virtual module
which appears or can be found with its virtual name.
The parameter modulefile corresponds to the relative or absolute file location of a
modulefile.
module-whatis string
Defines a string which is displayed in case of the invocation of the module whatis
command. There may be more than one module-whatis line in a modulefile. This
command takes no actions in case of load, display, etc. invocations of
modulecmd.tcl.
The string parameter has to be enclosed in double-quotes if there's more than one
word specified. Words are defined to be separated by whitespace characters (space,
tab, cr).
modulepath-label directory label
Assigns label string to modulepath directory. This label is used on avail output to
refer to the modulepath.
The parameter directory corresponds to a fully or partially qualified modulepath.
If directory is . (dot) then the current directory of the modulerc file defining
this command is assumed.
prepend-path [-d C|--delim C|--delim=C] [--duplicates] variable value...
Append or prepend value to environment variable. The variable is a colon, or
delimiter, separated list such as PATH=directory:directory:directory. The default
delimiter is a colon :, but an arbitrary one can be given by the --delim option.
For example a space can be used instead (which will need to be handled in the Tcl
specially by enclosing it in " " or { }). A space, however, can not be specified by
the --delim=C form.
A reference counter environment variable is also set to know the number of times
value has been added to environment variable when it is added more than one time.
This reference counter environment variable is named by prefixing variable by
__MODULES_SHARE_.
When value is already defined in environment variable, it is not added again or
moved at the end or at the beginning of variable. Exception is made when the
--duplicates option is set in which case value is added again to variable.
If the variable is not set, it is created. When a modulefile is unloaded,
append-path and prepend-path become remove-path.
If value corresponds to the concatenation of multiple elements separated by colon,
or delimiter, character, each element is treated separately.
prereq [options] modulefile...
prereq controls whether or not the modulefile will be loaded. The prereq command
lists modulefiles which must have been previously loaded before the current
modulefile will be loaded. If a list contains more than one modulefile, then each
member of the list acts as a Boolean OR operation. Multiple prereq commands may be
used to create a Boolean AND operation. If one of the requirements have not been
satisfied, an error is reported and the current modulefile makes no changes to the
user's environment.
If an argument for prereq is a directory and any modulefile from the directory has
been loaded, then the prerequisite is met. For example, specifying X11 as a prereq
means that any version of X11, X11/R4 or X11/R5, must be loaded before proceeding.
The parameter modulefile may also be a symbolic modulefile name or a modulefile
alias. It may also leverage a specific syntax to finely select module version (see
Advanced module version specifiers section below).
prereq command accepts the following options:
• --modulepath modulepathlist
• --optional
• --tag taglist
When the --optional option is set, the whole list of specified modulefiles is
declared as an optional requirement list. Evaluation is not stopped if no
modulefile from the list is loaded.
If the auto_handling configuration option is enabled prereq will attempt to load
specified modulefile if not found loaded yet (see MODULES_AUTO_HANDLING in module).
The --tag option accepts a list of module tags to apply to modulefile once loaded.
taglist corresponds to the concatenation of multiple tags separated by colon
character. taglist should not contain tags inherited from modulefile state or from
other modulefile commands. If module is already loaded, tags from taglist are added
to the list of tags already applied to this module.
The --modulepath option accepts a list of modulepath. modulepathlist corresponds to
the concatenation of multiple modulepaths separated by colon character. When this
option is set, required modulefile should be located within one of the listed
modulepaths. A path in this list may correspond to the first path elements of an
actual modulepath (e.g., /path/to will match modulefiles located into the
/path/to/modulefiles modulepath directory).
If an attempt to load modulefile is performed and --modulepath option is set,
modulefile will be searched in the enabled modulepaths whose start match one of the
specified paths and in the specified paths not matching any enabled modulepaths.
For instance if this option is set to /path/to:/another/path and
/path/to/modulefiles is currently the sole enabled modulepath, modulefile will be
searched into /path/to/modulefiles and /another/path directories.
prereq-all [options] modulefile...
Declare modulefile as a requirement of currently loading module. This command acts
as an alias of prereq command. If more than one modulefile are specified, then this
list acts as a Boolean AND operation, which means all specified modulefiles are
required.
prereq-all command accepts the following options:
• --modulepath modulepathlist
• --optional
• --tag taglist
When the --optional option is set, each specified modulefile is declared as an
optional requirement. A modulefile that cannot be loaded, will not stop the
evaluation.
prereq-any [options] modulefile...
Alias of prereq command.
pushenv variable value
Set environment variable to value and save previous value of variable to restore it
when modulefile is unloaded. Like for setenv modulefile command, changes made to
variable with pushenv are applied to variable in Tcl's env array to update
environment variable value in current evaluation context.
When modulefile is unloaded, the value saved from the pushenv command of this
modulefile is removed from saved value stack list. variable is then set to the
remaining value on top of the stack or it is unset if stack becomes empty.
Saved value stack list for variable is stored in an environment variable which is
named by prefixing variable by __MODULES_PUSHENV_.
puts [-nonewline] [channelId] string
Writes the characters given by string to the channel given by channelId. This
command is part of the regular set of Tcl commands but it is enhanced with specific
features in the modulefile evaluation context. See the puts(n) Tcl man page for the
basic description of this command. Specific features for modulefile evaluation
context are described in the remainder of this section.
Content written to the stderr channel is rendered as output message produced by
modulefile. Content written to the stdout channel is rendered as shell command
evaluated in the user current shell environment. Content sent to stdout is spooled
to be rendered after the environment changes made by modulefile.
When channelId equals prestdout, content is rendered as shell command evaluated in
current shell environment. This content is spooled and rendered prior any other
environment changes.
When channelId equals log, content is sent to the log system through the defined
logger command.
remove-path [options] variable value... [--append-on-unload|--prepend-on-unload value...]
Remove value from the colon, or delimiter, separated list in variable.
remove-path command accepts the following options:
• -d C|--delim C|--delim=C
• --index
• --glob
• --remove-on-unload|--noop-on-unload|--append-on-unload|--prepend-on-unload
See prepend-path or append-path for further explanation of using an arbitrary
delimiter. Every string between colons, or delimiters, in variable is compared to
value. If the two match, value is removed from variable if its reference counter is
equal to 1 or unknown.
When --index option is set, value refers to an index in variable list. The string
element pointed by this index is set for removal.
When --glob option is set, value refers to a glob-style pattern which is matched
against values in variable to find those to remove. * character in value matches
any sequence of characters, including a null string. ? character in value matches
any single character. See string(n) Tcl command for the full list of special
characters.
When modulefile is unloaded, no operation is performed by default or if the
--noop-on-unload option is set. If the --remove-on-unload option is set, value is
removed. If the --append-on-unload option is set, append back value removed at load
time or specific value if any set. If the --prepend-on-unload option is set,
prepend back value removed at load time or specific value if any set. These options
cannot be set if --index option is also set. The --append-on-unload and
--prepend-on-unload options cannot be set if --glob option is also set.
Reference counter of value in variable denotes the number of times value has been
added to variable. This information is stored in environment
__MODULES_SHARE_variable. When attempting to remove value from variable, relative
reference counter is checked and value is removed only if counter is equal to 1 or
not defined. Otherwise value is kept in variable and reference counter is
decreased by 1. If counter equals 1 after being decreased, value and its counter
are removed from reference counter variable.
If value corresponds to the concatenation of multiple elements separated by colon,
or delimiter, character, each element is treated separately.
An error is raised if value equals delimiter character.
reportError string
Output string as an error message during modulefile evaluation and raise error
count. reportError does not abort modulefile evaluation. Use the error(n) Tcl
command to abort evaluation in addition to emit an error message.
reportWarning string
Output string as a warning message during modulefile evaluation.
require-fullname
Abort load evaluation of modulefile if name specified to designate it is not the
fully qualified one. Module alias or a symbolic version names are considered fully
qualified names, exception made for the default symbol.
set-alias alias-name alias-string
Sets an alias with the name alias-name in the user's environment to the string
alias-string. For some shells, aliases are not possible and the command has no
effect (see Shell support section). When a modulefile is unloaded, set-alias
becomes unset-alias.
set-function function-name function-string
Creates a function with the name function-name in the user's environment with the
function body function-string. For some shells, functions are not possible and the
command has no effect (see Shell support section). When a modulefile is unloaded,
set-function becomes unset-function.
setenv [--set-if-undef] variable value
Set environment variable to value. The setenv command will also change the process'
environment. A reference using Tcl's env associative array will reference changes
made with the setenv command. Changes made using Tcl's env associative array will
NOT change the user's environment variable like the setenv command. An environment
change made this way will only affect the module parsing process. The setenv
command is also useful for changing the environment prior to the exec or system
command. When a modulefile is unloaded, setenv becomes unsetenv. If the environment
variable had been defined it will be overwritten while loading the modulefile. A
subsequent unload will unset the environment variable - the previous value cannot
be restored! (Unless you handle it explicitly or if you use the pushenv modulefile
command instead of setenv)
When the --set-if-undef option is set, environment variable is defined when
modulefile is loaded only if not yet defined.
source-sh [--ignore eltlist] shell script [arg...]
Evaluate with shell the designated script with defined arguments to find out the
environment changes it does. Those changes obtained by comparing environment prior
and after script evaluation are then translated into corresponding modulefile
commands, which are then applied during modulefile evaluation as if they were
directly written in it.
When modulefile is unloaded, environment changes done are reserved by evaluating in
the unload context the resulting modulefile commands, which were recorded in the
__MODULES_LMSOURCESH environment variable at load time.
Changes on environment variables, shell aliases, shell functions, shell completions
and current working directory are tracked.
Changes made on environment variable intended for Modules private use (e.g.,
LOADEDMODULES, _LMFILES_, __MODULES_*) are ignored.
Shell 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.
Shell could also be set to bash-eval. In this mode, bash shell script is not
sourced but the output resulting from its execution is evaluated to determine the
environment changes it does.
The --ignore option accepts a list of shell elements whose changes made by script
should be ignored. eltlist corresponds to the concatenation of multiple shell
element separated by colon character. Accepted shell elements are: envvar, alias,
function, chdir and complete.
system string
Run string command through shell. On Unix, command is passed to the /bin/sh shell
whereas on Windows it is passed to cmd.exe. modulecmd.tcl redirects stdout to
stderr since stdout would be parsed by the evaluating shell. The exit status of the
executed command is returned.
uname field
Provide lookup of system information. Most field information are retrieved from the
tcl_platform array (see the tclvars(n) man page). Uname will return the string
unknown if information is unavailable for the field.
uname will invoke the uname(1) command in order to get the operating system version
and domainname(1) to figure out the name of the domain.
field values are:
• sysname: the operating system name
• nodename: the hostname
• domain: the name of the domain
• release: the operating system release
• version: the operating system version
• machine: a standard name that identifies the system's hardware
uncomplete name
Unsets completion for command name in the user's environment. When a modulefile is
unloaded, no operation is performed.
The following shells are supported: bash, tcsh and fish.
unset-alias alias-name
Unsets an alias with the name alias-name in the user's environment.
unset-function function-name
Removes a function with the name function-name from the user's environment.
unsetenv [options] variable [value]
Unsets environment variable. When a modulefile is unloaded, no operation is
performed unless if an optional value is defined, in which case variable is to
value. The unsetenv command changes the process' environment like setenv.
If the --noop-on-unload option is set, no operation is performed when modulefile is
unloaded. If the --unset-on-unload option is set, environment variable is also
unset when modulefile is unloaded. These behaviors are applied even if an optional
value is defined.
variant [--boolean] [--default value] name [value...]
Declare module variant name with list of accepted value and instantiate it in the
ModuleVariant array variable.
Variant's value is selected through the module designation that leads to the
modulefile evaluation. See Advanced module version specifiers section to learn how
variants could be specified.
Selected variant value is transmitted to the evaluating modulefile. A value must be
specified for variant name and it must corresponds to a value in the accepted value
list if such list is defined. Otherwise an error is raised. An exception is made if
modulefile is evaluated in display mode: no error is raised if no value is
specified for a given variant and variant is not instantiated in the ModuleVariant
array variable. When no list of accepted value is defined, variant could be set to
any value.
When the --default option is set, variant name is set to the value associated with
this option in case no value is specified for variant in module designation.
If the --boolean option is set, variant name is defined as a Boolean variant. No
list of accepted value should be defined in this case. All values recognized as
Boolean value in Tcl are accepted (i.e., 1, true, t, yes, y, on, 0, false, f, no, n
or off). Boolean variants are instantiated in ModuleVariant using Tcl canonical
form of Boolean value (i.e., 0 or 1).
A variant which is not defined as a Boolean variant cannot define Boolean values in
its accepted value list, exception made for the 0 and 1 integers. An error is
raised otherwise.
Variant name should only be composed of characters part of the A-Za-z0-9_- range.
Also, a variant name cannot start with - (minus) character and the overall name
cannot just be a number. An error is raised if specified name does not match these
rules.
A variant cannot be named version. An error is raised otherwise.
versioncmp version1 version2
Compare version string version1 against version string version2. Returns -1, 0 or 1
respectively if version1 is less than, equal to or greater than version2.
x-resource [resource-string|filename]
Merge resources into the X11 resource database. The resources are used to control
look and behavior of X11 applications. The command will attempt to read resources
from filename. If the argument isn't a valid file name, then string will be
interpreted as a resource. Either filename or resource-string is then passed down
to be xrdb(1) command.
modulefiles that use this command, should in most cases contain one or more
x-resource lines, each defining one X11 resource. The DISPLAY environment variable
should be properly set and the X11 server should be accessible. If x-resource can't
manipulate the X11 resource database, the modulefile will exit with an error
message.
Examples:
x-resource /u2/staff/leif/.xres/Ileaf
The content of the Ileaf file is merged into the X11 resource database.
x-resource [glob ~/.xres/ileaf]
The Tcl glob function is used to have the modulefile read different resource
files for different users.
x-resource {Ileaf.popup.saveUnder: True}
Merge the Ileaf resource into the X11 resource database.
Modulefiles and run-command (rc) files are differently interpreted. A limited number of
the Modules specific Tcl commands are available for rc files interpretation since such
files are intended to set parameters for modulefiles (like defining alias, hiding,
tagging, etc) and not to change user environment. The following table summarizes the
different commands available for each interpretation context.
┌─────────────────────────────────┬──────────────────────────────────┐
│Commands available from │ Commands available from │
│modulefile interpretation │ run-command (rc) file │
│ │ interpretation │
├─────────────────────────────────┼──────────────────────────────────┤
│All the Modules specific and │ hide-modulefile, hide-version, │
│standard Tcl commands │ is-loaded, is-used, lsb-release, │
│ │ module-alias, module-forbid, │
│ │ module-hide, module-info, │
│ │ module-tag, module-version, │
│ │ module-virtual, │
│ │ modulepath-label, system, uname, │
│ │ versioncmp and standard Tcl │
│ │ commands │
└─────────────────────────────────┴──────────────────────────────────┘
NOTE:
Global and user run-command files are interpreted like modulefiles and benefit from all
Modules specific Tcl commands. However it not advised to perform environment changes
from such files.
MODULES VARIABLES
ModulesCurrentModulefile
The ModulesCurrentModulefile variable contains the full pathname of the modulefile
being interpreted.
ModulesVersion
The ModulesVersion variable can be set in .version file to designate the name of
the modulefile version which should be considered as default in current directory
(see Locating Modulefiles section below).
ModuleTool
The ModuleTool variable contains the name of the module implementation currently in
use. The value of this variable is set to Modules for this implementation.
ModuleToolVersion
The ModuleToolVersion variable contains the version of the module implementation
currently in use. The value of this variable is set to 5.5.0 for this version of
Modules.
ModuleVariant
The ModuleVariant array variable contains an element entry for each defined variant
associated to the value of this variant (e.g., the $ModuleVariant(foo) syntax
corresponds to the value of variant foo if defined). A Tcl evaluation error is
obtained when accessing an undefined variant in ModuleVariant array. Use preferably
the getvariant command to retrieve a variant value when this variant state is not
known.
The list of the currently defined variants can be retrieved with [array names
ModuleVariant] Tcl code.
LOCATING MODULEFILES
Every directory in MODULEPATH is searched to find the modulefile. A directory in
MODULEPATH can have an arbitrary number of sub-directories. If the user names a modulefile
to be loaded which is actually a directory, the directory is opened and a search begins
for an actual modulefile. First, modulecmd.tcl looks for a file with the name .modulerc in
the directory. If this file exists, its contents will be evaluated as if it was a
modulefile to be loaded. You may place module-version, module-alias and module-virtual
commands inside this file.
Additionally, before seeking for .modulerc files in the module directory, the global
modulerc file and the .modulerc file found at the root of the modulepath directory are
sourced, too. If a named version default now exists for the modulefile to be loaded, the
assigned modulefile now will be sourced. Otherwise the file .version is looked up in the
module directory.
If the .version file exists, it is opened and interpreted as Tcl code and takes precedence
over a .modulerc file in the same directory. If the Tcl variable ModulesVersion is set by
the .version file, modulecmd.tcl will use the name as if it specifies a modulefile in this
directory. This will become the default modulefile in this case. ModulesVersion cannot
refer to a modulefile located in a different directory.
If ModulesVersion is a directory, the search begins anew down that directory. If the name
does not match any files located in the current directory, the search continues through
the remaining directories in MODULEPATH.
Every .version and .modulerc file found is interpreted as Tcl code. The difference is that
.version only applies to the current directory, and the .modulerc applies to the current
directory and all subdirectories. Changes made in these files will affect the subsequently
interpreted modulefile.
If a .modulecache file is found at the root of a modulepath directory, this file is
interpreted as Tcl code to learn all .modulerc, .version and modulefiles available.
Modulepath content is read from module cache file. Modulepath directory is only walked
through to check if limited access modulefiles or directories are available to current
user.
If no default version may be figured out, an implicit default is selected when this
behavior is enabled (see MODULES_IMPLICIT_DEFAULT in module). If disabled, module names
should be fully qualified when no explicit default is defined for them, otherwise no
default version is found and an error is returned. If enabled, then the highest
numerically sorted modulefile, virtual module or module alias under the directory will be
used. The dictionary comparison method of the lsort(n) Tcl command is used to achieve
this sort. If highest numerically sorted element is an alias, search continues on its
modulefile target.
For example, it is possible for a user to have a directory named X11 which simply contains
a .version file specifying which version of X11 is to be loaded. Such a file would look
like:
#%Module
set ModulesVersion R4
The equivalent .modulerc would look like:
#%Module
module-version ./R4 default
If the extended default mechanism is enabled (see MODULES_EXTENDED_DEFAULT in module) the
module version specified is matched against starting portion of existing module versions,
where portion is a substring separated from the rest of version string by a . character.
When the implicit default mechanism and the Advanced module version specifiers are both
enabled, a default and latest symbolic versions are automatically defined for each module
name (also at each directory level in case of deep modulefile). Unless a symbolic version,
alias, or regular module version already exists for these version names.
Every file in searched directories is checked to see if it begins with the Modules magic
cookie (i.e., #%Module file signature) to determine if it is a modulefile (see DESCRIPTION
section). When the mcookie_check configuration is set to eval, this check is skipped and
all files in search directories are considered modulefiles.
If user names a modulefile that cannot be found in the first modulepath directory,
modulefile will be searched in next modulepath directory and so on until a matching
modulefile is found. If search goes through a module alias or a symbolic version, this
alias or symbol is resolved by first looking at the modulefiles in the modulepath where
this alias or symbol is defined. If not found, resolution looks at the other modulepaths
in their definition order.
When locating modulefiles, if a .modulerc, a .version, a directory or a modulefile cannot
be read during the search it is simply ignored with no error message produced. Visibility
of modulefiles can thus be adapted to the rights the user has been granted. Exception is
made when trying to directly access a directory or a modulefile. In this case, the access
issue is returned as an error message.
Depending on their name, their file permissions or the use of specific modulefile
commands, modulefile, virtual module, module alias or symbolic version may be set hidden
which impacts available modules search or module selection processes (see Hiding
modulefiles section below).
HIDING MODULEFILES
A modulefile, virtual module, module alias or symbolic version whose name or element in
their name starts with a dot character (.) or who are targeted by a module-hide command
are considered hidden. Hidden modules are not displayed or taken into account except if
they are explicitly named (e.g., foo/1.2.3 or foo/.2.0 not foo). If module has been hidden
with the --soft option of the module-hide command set, it is not considered hidden if the
root name of the query to search it matches module root name (e.g., searching foo will
return a foo/1.2.3 modulefile targeted by a module-hide --soft command). If module has
been hidden with the --hard option of the module-hide command set, it is always considered
hidden thus it is never displayed nor taken into account even if it is explicitly named.
A modulefile, virtual module, module alias or symbolic version who are targeted by a
module-hide --hard command and a module-forbid command or whose file access permissions
are restricted are considered hard-hidden and forbidden. Such modules are not displayed or
taken into account. When explicitly named for evaluation selection, such modules are
unveiled to return an access error.
NOTE:
When the mcookie_check configuration is set to eval, file access permissions are not
checked thus files with restricted permissions are included in search results but still
lead to error if evaluated.
A symbolic version-name assigned to a hidden module is displayed or taken into account
only if explicitly named and if module is not hard-hidden. Non-hidden module alias
targeting a hidden modulefile appears like any other non-hidden module alias. Finally, a
hidden symbolic version targeting a non-hidden module is displayed or taken into account
only if not hard-hidden and explicitly named to refer to its non-hidden target.
The automatic version symbols (e.g., default and latest) are unaffected by hiding.
Moreover when a regular default or latest version is set hidden, the corresponding
automatic version symbol takes the left spot. For instance, if foo/default which targets
foo/1.2.3 is set hard-hidden, the default automatic version symbol will be set onto
foo/2.1.3, the highest available version of foo.
When loading a modulefile or a virtual module targeted by a module-hide --hidden-loaded
command, this module inherits the hidden-loaded tag. Hidden loaded modules are not
reported among list sub-command results.
If the --all is set on avail, aliases, whatis or search sub-commands, hidden modules are
taken into account in search. Hard-hidden modules are unaffected by this option.
If the --all is set on list sub-command, hidden loaded modules are included in result
output.
ADVANCED MODULE VERSION SPECIFIERS
When the advanced module version specifiers mechanism is enabled (see
MODULES_ADVANCED_VERSION_SPEC in module), the specification of modulefile passed on
Modules specific Tcl commands changes. After the module name a version constraint and
variants may be added.
Version specifiers
After the module name a version constraint prefixed by the @ character may be added. It
could be directly appended to the module name or separated from it with a space character.
Constraints can be expressed to refine the selection of module version to:
• a single version with the @version syntax, for instance foo@1.2.3 syntax will select
module foo/1.2.3
• a list of versions with the @version1,version2,... syntax, for instance foo@1.2.3,1.10
will match modules foo/1.2.3 and foo/1.10
• a range of versions with the @version1:, @:version2 and @version1:version2 syntaxes, for
instance foo@1.2: will select all versions of module foo greater than or equal to 1.2,
foo@:1.3 will select all versions less than or equal to 1.3 and foo@1.2:1.3 matches all
versions between 1.2 and 1.3 including 1.2 and 1.3 versions
Advanced specification of single version or list of versions may benefit from the
activation of the extended default mechanism (see MODULES_EXTENDED_DEFAULT in module) to
use an abbreviated notation like @1 to refer to more precise version numbers like 1.2.3.
Range of versions on its side natively handles abbreviated versions.
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 10a, 1.2.3, 1.foo are
versions valid for range comparison whereas default or foo.2 versions are invalid for
range comparison.
Range of versions can be specified in version list, for instance foo@:1.2,1.4:1.6,1.8:.
Such specification helps to exclude specific versions, like versions 1.3 and 1.7 in
previous example.
If the implicit default mechanism is also enabled (see MODULES_IMPLICIT_DEFAULT in
module), a default and latest symbolic versions are automatically defined for each module
name (also at each directory level for deep modulefiles). These automatic version symbols
are defined unless a symbolic version, alias, or regular module version already exists for
these default or latest version names. Using the mod@latest (or mod/latest) syntax
ensures highest available version will be selected.
Variants
After the module name, variants can be specified. Module variants are alternative
evaluation of the same modulefile. A variant is specified by associating a value to its
name. This specification is then transmitted to the evaluating modulefile which
instantiates the variant in the ModuleVariant array variable when reaching the variant
modulefile command declaring this variant.
Variant can be specified with the name=value syntax where name is the declared variant
name and value, the value this variant is set to when evaluating the modulefile.
Boolean variants can be specified with the +name syntax to set this variant on and with
the -name or ~name syntaxes to set this variant off. The -name syntax is not supported on
ml command as the minus sign already means to unload designated module. The ~name and
+name syntaxes could also be defined appended to another specification word (e.g., the
module name, version or another variant specification), whereas -name syntax must be the
start of a new specification word.
Boolean variants may also be specified with the name=value syntax. value should be set to
1, true, t, yes, y or on to enable the variant or it should be set to 0, false, f, no, n
or off to disable the variant.
Shortcuts may be used to abbreviate variant specification. The variant_shortcut
configuration option associates shortcut character to variant name. With a shortcut
defined, variant could be specified with the <shortcut>value syntax. For instance if
character % is set as a shortcut for variant foo, the %value syntax is equivalent to the
foo=value syntax.
Variant name should only be composed of characters part of the A-Za-z0-9_- range. Also, a
variant name cannot start with - (minus) character and the overall name cannot just be a
number.
Specific characters used in variant specification syntax cannot be used as part of the
name or version of a module. These specific characters are +, ~, = and all characters set
as variant shortcut. Exception is made for + and ~ characters if string that follows after
does not correspond to a valid variant name (e.g., name+, name++, name/version+1).
DEPENDENCIES BETWEEN MODULEFILES
A modulefile may express dependencies on other modulefiles. Two kind of dependency exist:
pre-requirement and conflict. The former means specified modulefiles should be loaded
prior the modulefile that express the requirement. The latter means specified modulefiles
should not be loaded for the modulefile that express the conflict to be loaded too.
Pre-requirement could be expressed with prereq, prereq-any, prereq-all, depends-on,
always-load, module load, module switch, module try-load or module load-any modulefile
commands. When the auto_handling configuration option is disabled, required modulefile
should be manually loaded prior their dependent modulefile when expressed with the prereq,
prereq-any, prereq-all or depends-on modulefile commands. For other commands or when
auto_handling is enabled, pre-required modulefiles are automatically loaded.
Conflict is expressed with conflict, family or module unload modulefile commands. When the
auto_handling or conflict_unload configuration options are disabled, a conflicting loaded
modulefile should be manually unloaded prior loading the modulefile that express such
conflict when defined with conflict or family. It is automatically unloaded when expressed
with module unload (unless dependent modulefiles are loaded) or if auto_handling and
conflict_unload options are enabled. An error is raised when trying to load a module that
is already loaded but with a different variant set or coming from a different modulepath.
If both options are enabled the loaded module is automatically unloaded to satisfy the new
set of variant or modulepath asked.
It is strongly advised to define dependencies prior environment changes in a modulefile.
Dependency resolution should be done before any environment change to ensure the
environment is getting set in the same order whether pre-requirements are already loaded,
or if they are automatically loaded when loading the modulefile which depends on them, or
if all loaded modules are reloaded or refreshed. This is especially important when the
modulefile updates an environment variable also altered by other modulefiles like PATH. As
the order of the path elements in such variable defines priority, it is important that
this order does not change depending on the way the modulefiles are loaded.
module keeps environment consistent which means a modulefile cannot be loaded if its
requirements are not loaded or if a conflicting module is loaded. In addition a loaded
module cannot be unloaded if other loaded modules depends on it. The automated module
handling mechanisms attempt to solve the dependencies expressed by loading or unloading
additional modulefiles. When the --no-auto option is set on module command when loading or
unload modulefile, automated module handling mechanisms are disabled and dependencies have
to be solved manually. When dependencies are not satisfied, modulefile fails to load or
unload.
Adding the --not-req option when expressing dependencies in modulefile with the module
command will attempt to load or unload the designated modulefile but it will not mark them
as pre-requirement or conflict.
Adding the --optional option on prereq, prereq-any, prereq-all, depends-on or always-load
modulefile commands declares the pre-requirement as optional. If an optional
pre-requirement is not found loaded or cannot be automatically loaded, the dependency
expressed is yet considered satisfied. When an optional requirement is loaded afterward,
the dependent module will get automatically reloaded if the auto_handling configuration
option is enabled.
By adding the --force option to the module command when loading or unloading modulefile,
the consistency checks are by-passed. This option cannot be used when expressing
dependencies in modulefiles. If a module has been force loaded whereas its requirements
are not loaded or whereas a conflicting module is also loaded, the user environment is
said inconsistent.
Note that a pre-requirement should be found in the loaded module list prior its dependent
module. User environment is considered inconsistent if pre-requirement module is found
loaded after dependent module, as the environment changes may have been done in the wrong
priority order.
When user environment is considered inconsistent global operations achieved by refresh,
reload and save sub-commands cannot perform. This mechanism is there to avoid the
situation to worsen by re-evaluating all loaded modules or recording this environment.
When the auto_handling configuration option is enabled, if missing pre-requirement
modulefile gets loaded or conflicting modulefile gets unloaded the inconsistent loaded
module will be automatically reloaded to make user environment consistent again.
MODULEFILE SPECIFIC HELP
Users can request help about a specific modulefile through the module command. The
modulefile can print helpful information or start help oriented programs by defining a
ModulesHelp subroutine. The subroutine will be called when the module help modulefile
command is used.
MODULEFILE SPECIFIC TEST
Users can request test of a specific modulefile through the module command. The modulefile
can perform some sanity checks on its definition or on its underlying programs by defining
a ModulesTest subroutine. The subroutine will be called when the module test modulefile
command is used. The subroutine should return 1 in case of success. If no or any other
value is returned, test is considered failed.
MODULEFILE DISPLAY
The module display modulefile command will detail all changes that will be made to the
environment. After displaying all of the environment changes modulecmd.tcl will call the
ModulesDisplay subroutine. The ModulesDisplay subroutine is a good place to put additional
descriptive information about the modulefile.
COMPATIBILITY WITH LMOD TCL MODULEFILE
The modulecmd.tcl program supports Tcl modulefile or modulerc written for Lmod, the
alternative module implementation developed in Lua. Such modulefiles can be evaluated by
Modules without raising error. Differences between the two implementations are listed
below.
The add-property, remove-property and extensions modulefile commands are evaluated as a
no-operation command. No error is obtained if these commands are used in modulefiles but
no change occurs.
The break command does not accept any argument. A msg argument can be set on Lmod to
provide a customized break error message.
Use of reportError command aborts modulefile evaluation on Lmod. This command only reports
an error message on Modules.
The require-fullname command only aborts load modulefile evaluation whereas the Lmod
implementation also aborts unload and display evaluations.
When processing a family command, the LMOD_FAMILY_<NAME> environment variable is also
defined to be compatible with modulefiles or scripts relying on such variable.
When unloading a modulefile, the pushenv command does not update the value of the
environment variable if this modulefile was not defining the value currently in use.
The third optional argument of append-path and prepend-path commands corresponds to a
priority specification on Lmod whereas these two commands accept multiple path element
arguments on Modules.
The prereq command is equivalent to the prereq-any command on Modules whereas on Lmod it
is equivalent to the prereq-all command.
If the auto_handling configuration option is disabled, the requirements defined with the
depends-on command are not automatically loaded and an error is raised if none of these
requirements are found loaded.
If the auto_handling or conflict_unload configuration options are disabled, the conflicts
defined with the family command are not automatically unloaded and an error is raised when
trying to load a module defining a family already defined by a loaded module.
On module load-any sub-command and modulefile command, a modulefile evaluation error is
not reported and module load-any continues to the next modulefile instead of aborting the
whole process. No attempt to load listed modulefiles is made if one of these modulefiles
is found already loaded.
On module try-load modulefile command, each modulefile specified is considered an optional
pre-requirement. If it is loaded afterward and if the auto_handling configuration option
is enabled, the dependent module will get automatically reloaded.
SHELL SUPPORT
The modulecmd.tcl program that evaluates modulefiles supports a variety of shells or
languages: sh family shells (sh, bash, ksh and zsh), csh family shells (csh and tcsh),
fish, cmd, pwsh, python, perl, ruby, tcl, cmake, r, and lisp.
Modulefiles produce environment changes when evaluated, like defining an environment
variable. The modulecmd.tcl program outputs the corresponding code for the selected
"shell". Thereafter this code is evaluated by the module alias or function to update the
current environment.
Depending on the "shell" kind, not all the environment changes that can be defined in
modulefiles are supported. The following table summarizes the changes that are supported
by the shells supported by modulecmd.tcl.
┌───────┬───────────────┬──────────────┬─────────────────┬─────────────┬───────┬────────────┐
│ │ Environment │ Shell alias │ Shell │ Command │ chdir │ x-resource │
│ │ variables (‐ │ (set-alias, │ functions (‐ │ completion │ │ │
│ │ setenv, │ unset-alias) │ set-function, │ (complete, │ │ │
│ │ unsetenv, │ │ unset-function) │ uncomplete) │ │ │
│ │ pushenv, │ │ │ │ │ │
│ │ append-path, │ │ │ │ │ │
│ │ prepend-path, │ │ │ │ │ │
│ │ remove-path) │ │ │ │ │ │
├───────┼───────────────┼──────────────┼─────────────────┼─────────────┼───────┼────────────┤
│sh │ ⦁ │ ⦁ │ ⦁ │ │ ⦁ │ ⦁ │
├───────┼───────────────┼──────────────┼─────────────────┼─────────────┼───────┼────────────┤
│bash │ ⦁ │ ⦁ │ ⦁ │ ⦁ │ ⦁ │ ⦁ │
├───────┼───────────────┼──────────────┼─────────────────┼─────────────┼───────┼────────────┤
│ksh │ ⦁ │ ⦁ │ ⦁ │ │ ⦁ │ ⦁ │
├───────┼───────────────┼──────────────┼─────────────────┼─────────────┼───────┼────────────┤
│zsh │ ⦁ │ ⦁ │ ⦁ │ │ ⦁ │ ⦁ │
└───────┴───────────────┴──────────────┴─────────────────┴─────────────┴───────┴────────────┘
│csh │ ⦁ │ ⦁ │ │ │ ⦁ │ ⦁ │
├───────┼───────────────┼──────────────┼─────────────────┼─────────────┼───────┼────────────┤
│tcsh │ ⦁ │ ⦁ │ │ ⦁ │ ⦁ │ ⦁ │
├───────┼───────────────┼──────────────┼─────────────────┼─────────────┼───────┼────────────┤
│fish │ ⦁ │ ⦁ │ ⦁ │ ⦁ │ ⦁ │ ⦁ │
├───────┼───────────────┼──────────────┼─────────────────┼─────────────┼───────┼────────────┤
│cmd │ ⦁ │ ⦁ │ │ │ ⦁ │ │
├───────┼───────────────┼──────────────┼─────────────────┼─────────────┼───────┼────────────┤
│pwsh │ ⦁ │ ⦁ │ ⦁ │ ⦁ │ ⦁ │ │
├───────┼───────────────┼──────────────┼─────────────────┼─────────────┼───────┼────────────┤
│python │ ⦁ │ │ │ │ ⦁ │ ⦁ │
├───────┼───────────────┼──────────────┼─────────────────┼─────────────┼───────┼────────────┤
│perl │ ⦁ │ │ │ │ ⦁ │ ⦁ │
├───────┼───────────────┼──────────────┼─────────────────┼─────────────┼───────┼────────────┤
│ruby │ ⦁ │ │ │ │ ⦁ │ ⦁ │
├───────┼───────────────┼──────────────┼─────────────────┼─────────────┼───────┼────────────┤
│tcl │ ⦁ │ │ │ │ ⦁ │ ⦁ │
├───────┼───────────────┼──────────────┼─────────────────┼─────────────┼───────┼────────────┤
│cmake │ ⦁ │ │ │ │ │ ⦁ │
├───────┼───────────────┼──────────────┼─────────────────┼─────────────┼───────┼────────────┤
│r │ ⦁ │ │ │ │ ⦁ │ ⦁ │
├───────┼───────────────┼──────────────┼─────────────────┼─────────────┼───────┼────────────┤
│lisp │ ⦁ │ │ │ │ ⦁ │ ⦁ │
└───────┴───────────────┴──────────────┴─────────────────┴─────────────┴───────┴────────────┘
The source-sh command evaluates a shell script and produces the modulefile commands
corresponding to the environment changes made by this script. source-sh is able to
evaluate sh, bash, ksh, zsh, csh, tcsh and fish shell scripts. source-sh produces
environment changes corresponding to the kinds listed in the above table. Based on the
evaluated script, refer to the above table to know the environment changes that will be
rendered for the shell specified to modulecmd.tcl program.
ENVIRONMENT
See the ENVIRONMENT section in the module man page.
SEE ALSO
module, ml, Tcl(n), TclX(n), id(1), xrdb(1), exec(n), uname(1), domainname(1), tclvars(n),
lsort(n), string(n)
NOTES
Tcl was developed by John Ousterhout at the University of California at Berkeley.
TclX was developed by Karl Lehenbauer and Mark Diekhans.
COPYRIGHT
1996-1999 John L. Furlani & Peter W. Osel, 1998-2017 R.K.Owen, 2002-2004 Mark Lakata,
2004-2017 Kent Mein, 2016-2024 Xavier Delaruelle