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.

always-load [--optional] [--tag taglist] 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.

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.

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

proc ModulesHelp {} {
puts stderr {This module does nothing but alert the user}
puts stderr "that the [module-info name] module is not available"
}

module-whatis {Notifies user that module is not available.}

set curMod [module-info name]
if {[module-info mode load]} {
puts stderr "Note: '$curMod' is not available for [uname sysname]."
}
break

Modulefile using break command when unloading may be unloaded
anyway if --force option is set. To forbid the unload of a 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.

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 [--optional] [--tag taglist] modulefile...
Alias of prereq-all command.

exit [N]
This is not a modules specific command but another overloaded
Tcl command and is similar to the break or continue commands.
However, this command will cause the immediate cessation of this
module. Any additional modules on the command line will not be
evaluated even if the abort_on_error configuration option is
disabled for running module sub-command. This module and the
subsequent modules will not be listed as loaded. No environment
commands will be performed in the current module.

family name
Defines loading modulefile as a member of family name. Only one
member of a family could be loaded. Error is raised when 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_]).

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.

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.

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 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 the group specified. When both options are
set, forbidding is not applied if a match is found for
--not-user or --not-group.

If --user option is set, forbidding is applied only if the 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 the group specified. When both options are
set, forbidding is applied if a match is found for --user or
--group. These two options prevail over --not-user and
--not-group options.

Error message returned when trying to evaluate a forbidden 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 an avail sub-command
are reported with a forbidden tag applied to them. Nearly for-
bidden modules included in the result of an avail or a list
sub-command are reported with a nearly-forbidden tag applied to
them. See Module tags section in module.

The parameter modulefile may leverage a specific syntax to
finely select module version (see Advanced module version speci-
fiers section below). It may also be a full path file name to
precisely designate one module in a specific modulepath.

module-hide [options] modulefile...
Hide modulefile to exclude it from available module search or
module selection unless query refers to modulefile by its exact
name. This command should be placed in one of the modulecmd.tcl
rc files.

module-hide command accepts the following options:

• --soft|--hard

• --hidden-loaded

• --after datetime

• --before datetime

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

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

• --user {user...}

• --group {group...}

When --soft option is set, modulefile is also set hidden, but
hiding is disabled when search or selection query's root name
matches module's root name. This soft hiding mode enables to
hide modulefiles from bare module availability listing yet 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 the group specified. When both options are
set, hiding is not applied if a match is found for --not-user or
--not-group.

If --user option is set, hiding is applied only if the username
of the user currently running modulecmd.tcl is part of the list
of username specified. Following the same approach, if --group
option is set, hiding is applied only if current user is member
of one the group specified. When both options are set, hiding is
applied if a match is found for --user or --group. These two op-
tions prevail over --not-user and --not-group options.

If the --all option is set on avail, aliases, whatis or search
sub-commands, hiding is disabled thus hidden modulefiles are in-
cluded 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 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 an avail sub-command
are reported with a hidden tag applied to them. Hidden loaded
modules included in the result of a list sub-command are re-
ported with a hidden-loaded tag applied to them. This tag is not
reported on avail sub-command context. See Module tags section
in module.

The parameter modulefile may also be a symbolic modulefile name
or a modulefile alias. It may also leverage a specific syntax to
finely select module version (see Advanced module version 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 or stashpop.

module-info loaded modulefile
Returns the names of currently loaded modules matching passed
modulefile. The parameter modulefile might either be a fully
qualified modulefile with name and version or just a 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, 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, 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 and list sub-commands
(see Module tags section in module). Tag information can be
queried during modulefile evaluation with the module-info tags
modulefile command. module-tag commands should be placed in one
of the modulecmd.tcl rc files.

module-tag command accepts the following options:

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

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

• --user {user...}

• --group {group...}

If --not-user option is set, the tag is not applied if the 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 the group specified. When both options are
set, the tag is not applied if a match is found for --not-user
or --not-group.

If --user option is set, the tag is applied only if the username
of the user currently running modulecmd.tcl is part of the list
of username specified. Following the same approach, if --group
option is set, the tag is applied only if current user is member
of one the group specified. When both options are set, the tag
is applied if a match is found for --user or --group. These two
options prevail over --not-user and --not-group options.

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

When tag equals sticky or super-sticky, designated modulefile is
defined Sticky modules.

When tag equals keep-loaded, designated modulefile is not 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-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 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: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.

prereq [--optional] [--tag taglist] 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.

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 MODULES_AUTO_HANDLING 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 [--optional] [--tag taglist] 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.

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 [--optional] [--tag taglist] modulefile...
Alias of prereq command.

pushenv variable value
Set environment variable to value and save previous value of
variable to restore it when modulefile is unloaded. Like for
setenv modulefile command, changes made to variable with pushenv
are applied to variable in Tcl's env array to update environment
variable value in current evaluation context.

When modulefile is unloaded, the value saved from the pushenv
command of this modulefile is removed from saved value stack
list. variable is then set to the remaining value on top of the
stack or it is unset if stack becomes empty.

Saved value stack list for variable is stored in an environment
variable which is named by prefixing variable by
__MODULES_PUSHENV_.

puts [-nonewline] [channelId] string
Writes the characters given by string to the channel given by
channelId. This command is not a Modules-specific command, it
is actually part of Tcl. See the puts(n) Tcl man page for a
complete description of this command.

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.

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.

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 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.

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 | is-loaded, is-used, |
| and standard Tcl commands | module-alias, |
| | module-forbid, |
| | module-hide, module-info, |
| | module-tag, |
| | module-version, |
| | module-virtual, |
| | modulepath-label, system, |
| | uname, versioncmp and |
| | standard Tcl commands |
+----------------------------+----------------------------+

NOTE:
Global and user run-command files are interpreted like modulefiles
and benefit from all Modules specific Tcl commands. However it not
advised to perform environment changes from such files.

MODULES VARIABLES
ModulesCurrentModulefile
The ModulesCurrentModulefile variable contains the full pathname
of the modulefile being interpreted.

ModulesVersion
The ModulesVersion variable can be set in .version file to 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.4.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 is set on avail, aliases, whatis or search sub-commands,
hidden modules are taken into account in search. Hard-hidden modules
are unaffected by this option.

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

ADVANCED MODULE VERSION SPECIFIERS
When the advanced module version specifiers mechanism is enabled (see
MODULES_ADVANCED_VERSION_SPEC in module), the specification of 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.

Specific characters used in variant specification syntax cannot be used
as part of the name of a module. These specific characters are +, ~, =
and all characters set as variant shortcut. Exception is made for +
character which could be set one or several consecutive times at the
end of module name (e.g., name+ or name++).

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, always-load, module load, module switch, module try-load or
module load-any modulefile commands. When the auto_handling configura-
tion option is disabled, required modulefile should be manually loaded
prior their dependent modulefile when expressed with the prereq,
prereq-any, prereq-all or depends-on modulefile commands. For other
commands or when auto_handling is enabled, pre-required modulefiles are
automatically loaded.

Conflict is expressed with conflict or module unload modulefile com-
mands. A conflicting loaded modulefile should be manually unloaded
prior loading the modulefile that express such conflict when defined
with conflict. It is automatically unloaded when expressed with module
unload.

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 or always-load modulefile commands declares the pre-require-
ment as optional. If an optional pre-requirement is not found loaded or
cannot be automatically loaded, the dependency expressed is yet consid-
ered 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.

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 written for Lmod, the
alternative module implementation developed in Lua. Such modulefiles
can be evaluated by Modules without raising error. Differences between
the two implementations are listed below.

The add-property, remove-property and extensions modulefile commands
are evaluated as a no-operation command. No error is obtained if these
commands are used in modulefiles but no change occurs.

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

Use of reportError command aborts modulefile evaluation on Lmod. This
command only reports an error message on Modules.

The require-fullname command only aborts load modulefile evaluation
whereas the Lmod implementation also aborts unload and display 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 command are not automatically loaded and an
error is raised if none of these requirements are found loaded.

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, 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
----------------------------------------------------------------------------------------------
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, Tcl(n), TclX(n), id(1), xrdb(1), exec(n), uname(1), domain- | |
| name(1), tclvars(n), lsort(n), string(n) | | | |
| | | | | | | |
NOTES | | | | | | |
| Tcl was developed by John Ousterhout at the University of California at | |
| Berkeley. | | | | | |
| | | | | | | |
| TclX was developed|by Karl Lehenbauer and Mark Diekhans. | | |
| | | | | | | |
COPYRIGHT| | | | | | |
| 1996-1999 John L. Furlani & Peter W. Osel, 1998-2017 R.K.Owen, | |
| 2002-2004 Mark Lakata, 2004-2017 Kent Mein, 2016-2024 Xavier Delaruelle | |
| | | | | | | |
5.4.0 | | 2024-02-20 | 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+14.3.quarterly>

home | help

Header And Logo

Peripheral Links

Site Navigation

FreeBSD Manual Pages

Header And Logo

Peripheral Links

Search

Site Navigation

FreeBSD Manual Pages