FreeBSD Manual Pages

home | help

MODULEFILE(5) Modules MODULEFILE(5)

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 per-
mits modulefiles to be arbitrarily complex, depending upon the applica-
tion's and the modulefile writer's needs. If support for extended tcl
(tclX) has been configured for your installation of the Modules pack-
age, 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 envi-
ronment information is encapsulated into a single modulefile kept in a
central location. The same modulefile is used by every user on any ma-
chine. So, from the user's perspective, starting an application is ex-
actly 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 ex-
actly 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 soft-
ware is uniform and independent of the user's shell. From the module-
file 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 "stan-
dard" Tool Command Language Tcl(n) package. Unless otherwise specified,
the Module commands return the empty string. Some commands behave dif-
ferently when a modulefile is loaded or unloaded. The command descrip-
tions assume the modulefile is being loaded.

add-property name value
Associate module tag value to currently loading modulefile. Ar-
gument name is ignored. See module-tag command for more informa-
tion 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 de-
pendent 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 mod-
ulefile 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. mod-
ulepathlist corresponds to the concatenation of multiple mod-
ulepaths 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 di-
rectory).

If an attempt to load modulefile is performed and --modulepath
option is set, modulefile will be searched in the enabled mod-
ulepaths whose start match one of the specified paths and in the
specified paths not matching any enabled modulepaths. For in-
stance 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 /an-
other/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 con-
currently. 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 mod-
ulefiles 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 mod-
ulefile, 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 in-
voked. Body corresponds to argument options accepted by the
shell command which defines completion. When a modulefile is un-
loaded, 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 module-
file 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 mecha-
nisms 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 at-
tempting 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 load-
ing module.

In addition, the MODULES_FAMILY_<NAME> environment variable is
defined and set to the currently loading module name minus ver-
sion. 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 fam-
ily, 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 de-
fined, 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 re-
turned 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 dis-
play mode.

haveDynamicMPATH
haveDynamicMPATH command signals that a modulefile modifies the
MODULEPATH environment variable. It is useful when the module-
file 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 module-
file 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 mod-
ulefile 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 argu-
ment 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 mod-
ulefiles 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 sys-
tem 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 defini-
tion of an implicit prereq or conflict requirement onto speci-
fied 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, mod-
ules dependent of the unloaded modules are also unloaded. Other-
wise an error is raised if module to unload has a dependent mod-
ule 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 op-
tions to control the behavior to apply when modulefile is un-
loaded. 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 mod-
ule 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.

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 user-
name 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 pre-
vails over --not-group.

Error message returned when trying to evaluate a forbidden mod-
ule can be supplemented with the text message set through --mes-
sage option.

If --after option is set, modules are considered nearly forbid-
den 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 eval-
uated 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 speci-
fiers 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 dou-
ble-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 proce-
dure 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 keep-
ing 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 module-
file 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 re-
ported 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 speci-
fied date time. Following the same principle, if --before option
is set, hiding is only effective before specified date time. Ac-
cepted date time format is YYYY-MM-DD[THH:MM]. If no time
(HH:MM) is specified, 00:00 is assumed. --after and --before op-
tions are not supported on Tcl versions prior to 8.5.

If --not-user option is set, hiding is not applied if the user-
name 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, hid-
ing 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., de-
clared 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 regu-
lar, a --soft hiding command match a given module, regular hid-
ing 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 speci-
fiers 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 mod-
ulecmd.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. com-
mandname 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 direc-
tory which in case all loaded modulefiles from the directory
will be returned. The parameter modulefile may also be a sym-
bolic 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 path-
name 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 in-
voked 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 in-
voked 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 sym-
bolic 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 be-
tween the two.

module-info usergroups [name]
Returns all the groups the user currently running mod-
ulecmd.tcl is member of as a list of strings if no name is
given.

Returns 1 if one of the group current user running mod-
ulecmd.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 mod-
ulecmd.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 informa-
tion 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 user-
name 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, hid-
den-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 auto-
matically unloaded when it has been auto-loaded and its depen-
dent modules are getting unloaded.

module-version modulefile version-name...
Assigns the symbolic version-name to the modulefile. This com-
mand should be placed in one of the modulecmd.tcl rc files in
order to provide shorthand invocations of frequently used mod-
ulefile 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 for-
mer 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 directo-
ries.)

• 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 mod-
ulefile. 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 speci-
fied 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 op-
tions are not supported on Tcl versions prior to 8.5.

If --not-user option is set, warning is not applied if the user-
name 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 ac-
tions in case of load, display, etc. invocations of mod-
ulecmd.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 mod-
ulepath.

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:di-
rectory: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 en-
vironment 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.

If the variable is MODULEPATH and require_via configuration op-
tion 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 previ-
ously 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 re-
quirements 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. Evalua-
tion 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 mod-
ulefile 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 mod-
ulefile 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 re-
quired.

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 addi-
tional 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 com-
mands but it is enhanced with specific features in the module-
file evaluation context. See the puts(n) Tcl man page for the
basic description of this command. Specific features for mod-
ulefile evaluation context are described in the remainder of
this section.

Content written to the stderr channel is rendered as output mes-
sage produced by modulefile. Content written to the stdout chan-
nel is rendered as shell command evaluated in the user current
shell environment. Content sent to stdout is spooled to be ren-
dered 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-un-
load|--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-un-
load|--prepend-on-unload

See prepend-path or append-path for further explanation of using
an arbitrary delimiter. Every string between colons, or delim-
iters, 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 re-
moval.

When --glob option is set, value refers to a glob-style pattern
which is matched against values in variable to find those to re-
move. * 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 spe-
cial characters.

When modulefile is unloaded, no operation is performed by de-
fault or if the --noop-on-unload option is set. If the --re-
move-on-unload option is set, value is removed. If the --ap-
pend-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 spe-
cific value if any set. These options cannot be set if --index
option is also set. The --append-on-unload and --prepend-on-un-
load 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 de-
creased, 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 desig-
nate it is not the fully qualified one. Module alias or a sym-
bolic version names are considered fully qualified names, excep-
tion 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 sec-
tion). 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 en-
vironment 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 as-
sociative array will reference changes made with the setenv com-
mand. 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 mod-
ulefile 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 com-
mand 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 ob-
tained by comparing environment prior and after script evalua-
tion 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 re-
served by evaluating in the unload context the resulting module-
file commands, which were recorded in the __MODULES_LMSOURCESH
environment variable at load time.

Changes on environment variables, shell aliases, shell func-
tions, shell completions and current working directory are
tracked.

Changes made on environment variable intended for Modules pri-
vate use (e.g., LOADEDMODULES, _LMFILES_, __MODULES_*) are ig-
nored.

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 execu-
tion 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 oper-
ating 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 environ-
ment.

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 un-
loaded. 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 in-
stantiate 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 module-
file. 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 ac-
cepted (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 de-
fine 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 - (mi-
nus) 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 ar-
gument 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 er-
ror 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 in- |
| | terpretation |
+----------------------------+----------------------------+
| All the Modules specific | hide-modulefile, |
| and standard Tcl commands | hide-version, 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 des-
ignate the name of the modulefile version which should be con-
sidered as default in current directory (see Locating Module-
files section below).

ModuleTool
The ModuleTool variable contains the name of the module imple-
mentation currently in use. The value of this variable is set to
Modules for this implementation.

ModuleToolVersion
The ModuleToolVersion variable contains the version of the mod-
ule implementation currently in use. The value of this variable
is set to 5.6.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 di-
rectory in MODULEPATH can have an arbitrary number of sub-directories.
If the user names a modulefile to be loaded which is actually a direc-
tory, the directory is opened and a search begins for an actual module-
file. 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 direc-
tory, the global modulerc file and the .modulerc file found at the root
of the modulepath directory are sourced, too. If a named version de-
fault now exists for the modulefile to be loaded, the assigned module-
file 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, mod-
ulecmd.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 di-
rectory.

If ModulesVersion is a directory, the search begins anew down that di-
rectory. 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 se-
lected 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 numeri-
cally sorted modulefile, virtual module or module alias under the di-
rectory 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 mod-
ulepaths 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 sym-
bolic 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 ex-
plicitly 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 un-
veiled 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 ap-
pears like any other non-hidden module alias. Finally, a hidden sym-
bolic 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-hid-
den, 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 module-
file 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 sepa-
rated 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 in-
stance 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 @ver-
sion1:version2 syntaxes, for instance foo@1.2: will select all ver-
sions of module foo greater than or equal to 1.2, foo@:1.3 will se-
lect 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 bene-
fit 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 ver-
sions 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 ver-
sions are automatically defined for each module name (also at each di-
rectory 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 trans-
mitted 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 vari-
ant.

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 cor-
respond 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 speci-
fied 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 ex-
pressed 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 re-
quirement for the modulefiles loaded from that path. This pre-require-
ment is considered when such modules are already loaded, helping to
maintain consistency when attempting to unload a modulefile that en-
ables a modulepath.

Conflict is expressed with conflict, family or module unload modulefile
commands. When the auto_handling or conflict_unload configuration op-
tions 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 ex-
pressed 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 sat-
isfy 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 envi-
ronment change to ensure the environment is getting set in the same or-
der whether pre-requirements are already loaded, or if they are auto-
matically loaded when loading the modulefile which depends on them, or
if all loaded modules are reloaded or refreshed. This is especially im-
portant when the modulefile updates an environment variable also al-
tered 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 ex-
pressed 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 un-
loading 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 com-
mand. 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 com-
mand. 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 Mod-
ulesDisplay 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. Ex-
cept for the specific cases listed below, such modulefiles can be eval-
uated 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 informa-
tion 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 --re-
spect 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 evalua-
tions.

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 com-
mands 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 automat-
ically loaded and an error is raised if none of these requirements are
found loaded.

If the auto_handling or conflict_unload configuration options are dis-
abled, the conflicts defined with the family command are not automati-
cally 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 corre-
sponding code for the selected "shell". Thereafter this code is evalu-
ated 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 mod-
ulecmd.tcl.
+--------+---------------+--------------+-----------------+-------------+-------+------------+
| | Environ- | Shell | Shell | Command | chdir | x-resource |
| | ment vari- | alias (- | functions | completion | | |
| | ables (- | set-alias, | (- | (complete, | | |
| | setenv, | unset-alias) | set-func- | uncomplete) | | |
| | unsetenv, | | tion, | | | |
| | pushenv, | | unset-function) | | | |
| | 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 module-
file 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 correspond-
ing 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, envml, 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.

5.6.0 2025-07-31 MODULEFILE(5)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=modulefile&sektion=5&manpath=FreeBSD+Ports+15.0>

home | help

Header And Logo

Peripheral Links

Site Navigation

FreeBSD Manual Pages

Header And Logo

Peripheral Links

Search

Site Navigation

FreeBSD Manual Pages