MODULEFILE(4) Modules MODULEFILE(4)
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(1) user inter-
face. modulefiles can be loaded, unloaded, or switched on-the-fly while
the user is working; and can be used to implement site policies regard-
ing the access and use of applications.
A modulefile begins with the magic cookie, #%Module. 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 compat-
ible. Files without the magic cookie or with a version number greater
than the current version of modulecmd.tcl will not be interpreted.
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
machine. So, from the user's perspective, starting an application is
exactly the same irrespective of the machine or platform they are on.
modulefiles also hide the notion of different types of shells. From the
user's perspective, changing the environment for one shell looks
exactly the same as changing the environment for another shell. This is
useful for new or novice users and eliminates the need for statements
such as "if you're using the C Shell do this ..., otherwise if you're
using the Bourne shell do this ...". Announcing and accessing new 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.
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 and processing will continue on to
the next module on the command line. 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.
#%Module1.0
## notavail modulefile
##
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
chdir directory
Set the current working directory to directory.
conflict modulefile...
prereq and conflict control whether or not the modulefile will
be loaded. The prereq command lists modulefiles which must have
been previously loaded before the current modulefile will be
loaded. Similarly, 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 prereq and 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 environ-
ment.
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.
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.
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).
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.
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 and any additional ones on the command line. This module
and the subsequent modules will not be listed as loaded. No
environment commands will be performed in the current module.
getenv variable [value]
Returns value of environment variable. If variable is not
defined, value is returned if set, _UNDEFINED_ is returned oth-
erwise. The getenv command should be preferred over the Tcl
global variable env to query environment variables.
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.
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).
is-loaded [modulefile...]
The is-loaded command returns a true value if any of the listed
modulefiles has been loaded or if any modulefile is loaded in
case no argument is provided. If a list contains more than one
modulefile, then each member acts as a boolean OR operation. If
an argument for is-loaded is a directory and any modulefile from
the directory has been loaded is-loaded would return a true
value.
The parameter modulefile may also be a symbolic modulefile name
or a modulefile alias. It may also leverage a specific syntax to
finely select module version (see Advanced module version speci-
fiers section below).
is-saved [collection...]
The is-saved command returns a true value if any of the listed
collections exists or if any collection exists in case no 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-args]
Contains the same sub-commands as described in the module(1) man
page in the Module Sub-Commands section. This command permits a
modulefile to load or unload other modulefiles. No checks are
made to ensure that the modulefile does not try to load itself.
Often it is useful to have a single modulefile that performs a
number of module load commands. For example, if every user on
the system requires a basic set of applications loaded, then a
core modulefile would contain the necessary module load com-
mands.
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
o a fully qualified modulefile with name and version
o a symbolic modulefile name
o another modulefile alias
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, reload, source, switch, dis-
play, avail, aliases, list, whatis, search, purge, restore,
help or test.
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.
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, switch, display, help, test or
whatis.
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.
module-info shell [shellname]
Return the current shell under which modulecmd.tcl was
invoked if no shellname is given. The current shell is the
first parameter of modulecmd.tcl, which is normally hidden by
the module alias.
If a shellname is given, returns 1 if modulecmd.tcl's current
shell is shellname, returns 0 otherwise. shellname can be:
sh, bash, ksh, zsh, csh, tcsh, fish, tcl, perl, python, ruby,
lisp, cmake, r.
module-info shelltype [shelltypename]
Return the family of the shell under which modulefile was
invoked if no shelltypename is given. As of module-info shell
this depends on the first parameter of modulecmd.tcl. The
output reflects a shell type determining the shell syntax of
the commands produced by modulecmd.tcl.
If a shelltypename is given, returns 1 if modulecmd.tcl's
current shell type is shelltypename, returns 0 otherwise.
shelltypename can be: sh, csh, fish, tcl, perl, python, ruby,
lisp, cmake, r.
module-info specified
Return the name of the modulefile specified on the command
line.
module-info symbols modulefile
Returns a list of all symbolic versions assigned to the
passed modulefile. The parameter modulefile might either be
a full qualified modulefile with name and version, another
symbolic modulefile name or a modulefile alias.
module-info type
Returns either C or Tcl to indicate which module command is
being executed, either the C version or the Tcl-only ver-
sion, to allow the modulefile writer to handle any differ-
ences between the two.
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-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
o 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.)
o a symbolic modulefile name
o 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
actions 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).
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=direc-
tory:directory:directory. The default delimiter is a colon :,
but an arbitrary one can be given by the --delim option. For
example a space can be used instead (which will need to be han-
dled 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 increase
the number of times value has been added to environment vari-
able. This reference counter environment variable is named by
suffixing variable by _modshare.
When value is already defined in environement variable, it is
not added again except if --duplicates option is set.
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 modulefile...
See conflict.
remove-path [-d C|--delim C|--delim=C] [--index] variable value...
Remove value from the colon, or delimiter, separated list in
variable. See prepend-path or append-path for further explana-
tion of using an arbitrary delimiter. Every string between
colons, or delimiters, in variable is compared to value. If the
two match, value is removed from variable if its reference
counter is equal to 1 or unknown.
When --index option is set, value refers to an index in variable
list. The string element pointed by this index is set for
removal.
Reference counter of value in variable denotes the number of
times value has been added to variable. This information is
stored in environment variable_modshare. 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 value corresponds to the concatenation of multiple elements
separated by colon, or delimiter, character, each element is
treated separately.
set-alias alias-name alias-string
Sets an alias or function 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. When a module-
file is unloaded, set-alias becomes unset-alias.
set-function function-name function-string
Creates a function with the name function-name in the user's
environment with the function body function-string. For some
shells, functions are not possible and the command has no
effect. When a modulefile is unloaded, set-function becomes
unset-function.
setenv variable value
Set environment variable to value. The setenv command will also
change the process' environment. A reference using Tcl's env
associative array will reference changes made with the setenv
command. Changes made using Tcl's env associative array will NOT
change the user's environment variable like the setenv command.
An environment change made this way will only affect the module
parsing process. The setenv command is also useful for changing
the environment prior to the exec or system command. When a 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 ... see below.)
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:
o sysname: the operating system name
o nodename: the hostname
o domain: the name of the domain
o release: the operating system release
o version: the operating system version
o machine: a standard name that identifies the system's hardware
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 variable [value]
Unsets environment variable. However, if there is an optional
value, then when unloading a module, it will set variable to
value. The unsetenv command changes the process' environment
like setenv.
x-resource [resource-string|filename]
Merge resources into the X11 resource database. The resources
are used to control look and behavior of X11 applications. The
command will attempt to read resources from filename. If the
argument isn't a valid file name, then string will be inter-
preted as a resource. Either filename or resource-string is then
passed down to be xrdb(1) command.
modulefiles that use this command, should in most cases contain
one or more x-resource lines, each defining one X11 resource.
The DISPLAY environment variable should be properly set and the
X11 server should be accessible. If x-resource can't manipulate
the X11 resource database, the modulefile will exit with an
error message.
Examples:
x-resource /u2/staff/leif/.xres/Ileaf
The content of the Ileaf file is merged into the X11 resource
database.
x-resource [glob ~/.xres/ileaf]
The Tcl glob function is used to have the modulefile read
different resource files for different users.
x-resource {Ileaf.popup.saveUnder: True}
Merge the Ileaf resource into the X11 resource database.
MODULES VARIABLES
The ModulesCurrentModulefile variable contains the full pathname of the
modulefile being interpreted.
LOCATING MODULEFILES
Every directory in MODULEPATH is searched to find the modulefile. A
directory in MODULEPATH can have an arbitrary number of sub-directo-
ries. If the user names a modulefile to be loaded which is actually a
directory, the directory is opened and a search begins for an actual
modulefile. First, modulecmd.tcl looks for a file with the name .mod-
ulerc in the directory. If this file exists, its contents will be eval-
uated 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
default now exists for the modulefile to be loaded, the assigned mod-
ulefile 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. Mod-
ulesVersion cannot refer to a modulefile located in a different direc-
tory.
If ModulesVersion is a directory, the search begins anew down that
directory. If the name does not match any files located in the current
directory, the search continues through the remaining directories in
MODULEPATH.
Every .version and .modulerc file found is interpreted as Tcl code. The
difference is that .version only applies to the current directory, and
the .modulerc applies to the current directory and all subdirectories.
Changes made in these files will affect the subsequently interpreted
modulefile.
If no default version may be figured out, an implicit default is
selected when this behavior is enabled (see MODULES_IMPLICIT_DEFAULT in
module(1)). 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
directory will be used. The dictionary comparison method of the
lsort(n) Tcl command is used to achieve this sort. If highest numeri-
cally 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:
#%Module1.0
##
## The desired version of X11
##
set ModulesVersion "R4"
The equivalent .modulerc would look like:
#%Module1.0
##
## The desired version of X11
##
module-version "./R4" default
If the extended default mechanism is enabled (see MOD-
ULES_EXTENDED_DEFAULT in module(1)) 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.
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.
A modulefile, virtual module, module alias or symbolic version whose
name or element in their name starts with a . (dot) are considered hid-
den. Hidden modulefile, virtual module, module alias or symbolic ver-
sion are not displayed or taken into account except if they are explic-
itly named. By inheritance, a symbolic version-name assigned to a hid-
den modulefile, virtual module or module alias is displayed or taken
into account only if explicitly named. Non-hidden module alias target-
ing a hidden modulefile appears like any other non-hidden module alias.
Finally, a hidden symbolic version targeting a non-hidden module will
be displayed along its non-hidden target.
ADVANCED MODULE VERSION SPECIFIERS
When the advanced module version specifiers mechanism is enabled (see
MODULES_ADVANCED_VERSION_SPEC in module(1)), the specification of mod-
ulefile passed on Modules specific Tcl commands changes. After the
module name a version constraint prefixed by the @ character may be
added. It could be directly appended to the module name or separated
from it with a space character.
Constraints can be expressed to refine the selection of module version
to:
o a single version with the @version syntax, for instance foo AT 1.3
syntax will select module foo/1.2.3
o a list of versions with the @version1,version2,... syntax, for
instance foo AT 1.3,1.10 will match modules foo/1.2.3 and foo/1.10
o a range of versions with the @version1:, @:version2 and @ver-
sion1:version2 syntaxes, for instance foo AT 1.2: will select all ver-
sions of module foo greater than or equal to 1.2, foo@:1.3 will
select all versions less than or equal to 1.3 and foo AT 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 MOD-
ULES_EXTENDED_DEFAULT in module(1)) 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.
If the implicit default mechanism is also enabled (see MOD-
ULES_IMPLICIT_DEFAULT in module(1)), a default and latest symbolic ver-
sions are automatically defined for each module name (also at each
directory level for deep modulefiles). These automatic version symbols
are defined unless a symbolic version, alias, or regular module version
already exists for these default or latest version names. Using the
mod@latest (or mod/latest) syntax ensures highest available version
will be selected.
MODULEFILE SPECIFIC HELP
Users can request help about a specific modulefile through the mod-
ule(1) command. The modulefile can print helpful information or start
help oriented programs by defining a ModulesHelp subroutine. The sub-
routine 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(1)
command. The modulefile can perform some sanity checks on its defini-
tion or on its underlying programs by defining a ModulesTest subrou-
tine. 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.
ENVIRONMENT
MODULEPATH
Path of directories containing modulefiles.
SEE ALSO
module(1), ml(1), Tcl(n), TclX(n), xrdb(1), exec(n), uname(1), domain-
name(1), tclvars(n), lsort(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-2020 Xavier Delaruelle
4.5.2 2020-07-30 MODULEFILE(4)
Linux-Distributionen
Huschi als Linux-Admin