Ubuntu Manpage: modulefile - files containing Tcl code for the Modules package

Provided by: environment-modules_5.6.1-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.

add-property name value
Associate module tag value to currently loading modulefile. Argument name is ignored. See
module-tag command for more information on tags.

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

module-help {This module does nothing but alert the user}
module-help "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.

If the conflict_unload and auto_handling configuration options are enabled, conflict will attempt
to unload all loaded modules that match specification. (see Automated module handling mechanisms
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.

depends-on-any [options] modulefile...
Alias of prereq 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.

extensions modulefile...
Alias of provide command.

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 Automated module handling mechanisms 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.

haveDynamicMPATH
haveDynamicMPATH command signals that a modulefile modifies the MODULEPATH environment variable.
It is useful when the modulefile conditionally updates MODULEPATH and is processed by Lmod tool.

Here in the Modules tool, this command is implemented as a no-operation, since the spider
sub-command evaluates the modulefile in the context of the current user to determine whether
MODULEPATH is updated.

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.

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.

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.

If the require_via configuration option is enabled, the use sub-command defines a requirement of
modulefiles stored in the added modulepath onto current modulefile.

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 from │ Sub-commands available from │ Sub-commands available from │
│ modulefile interpretation │ initrc configuration file │ run-command (rc) file │
│ │ and sourced script file │ interpretation │
├──────────────────────────────┼──────────────────────────────┼──────────────────────────────┤
│ load, load-any, switch, │ Same sub-commands available │ None │
│ try-load, unload, unuse, │ than for modulefile and │ │
│ use. Also available but not │ config sub-command. │ │
│ recommended for use 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 of the
groups 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 of the groups
specified. When both options are set, forbidding is applied if a match is found for --user or
--group. If the same user name is set on both --user and --not-user options, --user prevails over
--not-user. If the same group name is set on both --group and --not-group, --group prevails over
--not-group.

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 avail or spider sub-commands are reported with a
forbidden tag applied to them. Nearly forbidden modules included in the result of avail, list or
spider sub-commands 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-help string
Defines a string which is displayed in case of the invocation of the module help command. This
command takes no action on non-help modulefile evaluation.

Multi-word string should be enclosed in curly-braces or double-quotes. There may be more than one
module-help command call in a modulefile. In which case each command call is reported as a
separate line.

If a modulefile also defines a ModulesHelp procedure, the text defined with module-help is printed
before running this procedure on help evaluation mode.

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 of the groups
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 of the groups specified.
When both options are set, hiding is applied if a match is found for --user or --group. If the
same user name is set on both --user and --not-user options, --user prevails over --not-user. If
the same group name is set on both --group and --not-group, --group prevails over --not-group.

If the --all option is set on avail, aliases, whatis, search or spider 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 avail or spider sub-commands are reported with a hidden
tag applied to them. Hidden loaded modules included in the result of list sub-command are reported
with a hidden-loaded tag applied to them. This tag is not reported on avail or spider sub-commands
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, stashpop or spider.

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, list and spider 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 of the groups
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 of the groups specified.
When both options are set, the tag is applied if a match is found for --user or --group. If the
same user name is set on both --user and --not-user options, --user prevails over --not-user. If
the same group name is set on both --group and --not-group, --group prevails over --not-group.

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, nearly-forbidden and warning.

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-warn [options] --message {text message} modulefile...
Print warning message when evaluating modulefile. This command could be placed in one of the
modulecmd.tcl rc files or within modulefiles. Warning is emitted when modulefile is evaluated in
load, display, test, help.

module-warn command accepts the following options:

• --after datetime

• --before datetime

• --not-user {user...}

• --not-group {group...}

• --user {user...}

• --group {group...}

If --after option is set, warning is only effective after specified date time. Following the same
principle, if --before option is set, warning 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, warning 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, warning is not applied if current user is member of one of the groups
specified. When both options are set, warning is not applied if a match is found for --not-user or
--not-group.

If --user option is set, warning 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, warning is applied only if current user is member of one of the groups specified.
When both options are set, warning is applied if a match is found for --user or --group. If the
same user name is set on both --user and --not-user options, --user prevails over --not-user. If
the same group name is set on both --group and --not-group, --group prevails over --not-group.

Modules in warning included in the result of avail, list or spider sub-commands are reported with
a warning tag applied to them. See Module tags section in module.

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, whatis, search and
spider 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.

The provided value is used as-is. If any path resolution is required, it must be performed within
the modulefile itself. Use caution when including characters with special meanings in the shell
context (such as ~), as the shell may expand these paths automatically. This can prevent the
corresponding entries from being properly removed when the modulefile is unloaded.

If the variable is MODULEPATH and require_via configuration option is activated, the modulefile is
considered a dependency by the loaded modulefiles stored in the added modulepaths.

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.

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 Automated module handling mechanisms 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.

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.

provide modulefile...
Define each specified modulefile as a module alias of currently evaluating module. provide command
helps to declare the additional elements included in a modulefile.

The provide command should be paired with a conflict command if the specified alias should be
uniquely provided in the currently loaded environment.

Note: A module alias defined using provide command will not be recognized during module
resolution. It is recommended to use the module-alias command to define an alias that points to
the default resolution target.

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.

report string
Output string as a message during modulefile evaluation.

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.

Any newline character in value is chopped if using csh or tcsh shells.

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 set 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 modulefile │ Commands available from run-command │
│ interpretation │ (rc) file interpretation │
├───────────────────────────────────────┼───────────────────────────────────────┤
│ All the Modules specific and standard │ hide-modulefile, hide-version, │
│ Tcl commands │ is-loaded, is-used, lsb-release, │
│ │ module-alias, module-forbid, │
│ │ module-hide, module-info, module-tag, │
│ │ module-version, module-virtual, │
│ │ module-warn, 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.6.1 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 option is set on avail, aliases, whatis, search or spider sub-commands, hidden modules are
taken into account in search. Hard-hidden modules are unaffected by this option.

If the --all option is set on list sub-command, hidden loaded modules are included in result output.

A behavior equivalent to the use of the --all option is obtained on avail, list and spider sub-commands
by adding the hidden element to the output configuration option controlling regular or terse reporting of
these sub-commands: avail_output, avail_terse_output, list_output, list_terse_output, spider_output,
spider_terse_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, depends-on-any,
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, depends-on or depends-on-any
modulefile commands. For other commands or when auto_handling is enabled, pre-required modulefiles are
automatically loaded.

Another form of pre-requirement is expressed through the use of the modulefile commands module use,
append-path MODULEPATH, or prepend-path MODULEPATH, when the require_via configuration option is enabled.
In this context, a modulefile that adds a modulepath is treated as a requirement for the modulefiles
loaded from that path. This pre-requirement is considered when such modules are already loaded, helping
to maintain consistency when attempting to unload a modulefile that enables a modulepath.

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, depends-on-any 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.

       Help  text  may  also  be  defined  within  modulefile with module-help command. Text defined such way is
       printed before evaluation of ModulesHelp subroutine if any.

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. Except for the specific cases listed below, such modulefiles can be
evaluated by Modules without producing errors. Key differences between the two implementations are
outlined below.

The remove-property modulefile command is evaluated as a no-operation command. No error is obtained if
this command is used in modulefiles but no change occurs.

The haveDynamicMPATH is evaluated as a no-operation modulefile command. If modulefile conditionally
updates MODULEPATH environment variable, this command is needed to help Lmod know that modulefile changes
MODULEPATH. spider sub-command on Modules does not need this information as modulefile is evaluated in
the context of the current user to determine whether MODULEPATH is updated.

The break command does not accept any argument. A msg argument can be set on Lmod to provide a customized
break error message.

The setenv, unsetenv, prepend-path, append-path, remove-path, pushenv and module load, load-any, try-load
and unload modulefile commands do not support the --mode option. An error is raised if this option is
used.

The setenv and unsetenv modulefile commands do not support the --respect option. An error is raised if
this option is used.

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 or
depends-on-any commands 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     │ x              │ x              │ x               │                │ x     │ x          │
         ├────────┼────────────────┼────────────────┼─────────────────┼────────────────┼───────┼────────────┤
         │ bash   │ x              │ x              │ x               │ x              │ x     │ x          │
         ├────────┼────────────────┼────────────────┼─────────────────┼────────────────┼───────┼────────────┤
         │ ksh    │ x              │ x              │ x               │                │ x     │ x          │
         ├────────┼────────────────┼────────────────┼─────────────────┼────────────────┼───────┼────────────┤
         │ zsh    │ x              │ x              │ x               │                │ x     │ x          │
         ├────────┼────────────────┼────────────────┼─────────────────┼────────────────┼───────┼────────────┤
         │ csh    │ x              │ x              │                 │                │ x     │ x          │
         ├────────┼────────────────┼────────────────┼─────────────────┼────────────────┼───────┼────────────┤
         │ tcsh   │ x              │ x              │                 │ x              │ x     │ x          │
         ├────────┼────────────────┼────────────────┼─────────────────┼────────────────┼───────┼────────────┤
         │ fish   │ x              │ x              │ x               │ x              │ x     │ x          │
         ├────────┼────────────────┼────────────────┼─────────────────┼────────────────┼───────┼────────────┤
         │ cmd    │ x              │ x              │                 │                │ x     │            │
         ├────────┼────────────────┼────────────────┼─────────────────┼────────────────┼───────┼────────────┤
         │ pwsh   │ x              │ x              │ x               │ x              │ x     │            │
         ├────────┼────────────────┼────────────────┼─────────────────┼────────────────┼───────┼────────────┤
         │ python │ x              │                │                 │                │ x     │ x          │
         ├────────┼────────────────┼────────────────┼─────────────────┼────────────────┼───────┼────────────┤
         │ perl   │ x              │                │                 │                │ x     │ x          │
         ├────────┼────────────────┼────────────────┼─────────────────┼────────────────┼───────┼────────────┤
         │ ruby   │ x              │                │                 │                │ x     │ x          │
         ├────────┼────────────────┼────────────────┼─────────────────┼────────────────┼───────┼────────────┤
         │ tcl    │ x              │                │                 │                │ x     │ x          │
         ├────────┼────────────────┼────────────────┼─────────────────┼────────────────┼───────┼────────────┤
         │ cmake  │ x              │                │                 │                │       │ x          │
         ├────────┼────────────────┼────────────────┼─────────────────┼────────────────┼───────┼────────────┤
         │ r      │ x              │                │                 │                │ x     │ x          │
         ├────────┼────────────────┼────────────────┼─────────────────┼────────────────┼───────┼────────────┤
         │ lisp   │ x              │                │                 │                │ x     │ x          │
         └────────┴────────────────┴────────────────┴─────────────────┴────────────────┴───────┴────────────┘

       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.

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-2025, Modules Contributors

5.6.1                                              2025-11-25                                      MODULEFILE(5)

NAME

DESCRIPTION

MODULES SPECIFIC TCL COMMANDS

MODULES VARIABLES

LOCATING MODULEFILES

HIDING MODULEFILES

ADVANCED MODULE VERSION SPECIFIERS

DEPENDENCIES BETWEEN MODULEFILES

MODULEFILE SPECIFIC HELP

MODULEFILE SPECIFIC TEST

MODULEFILE DISPLAY

COMPATIBILITY WITH LMOD TCL MODULEFILE

SHELL SUPPORT

ENVIRONMENT

SEE ALSO

NOTES

COPYRIGHT