.\" Man page generated from reStructuredText.
.
.TH "MODULEFILE" "4" "2020-11-14" "4.6.1" "Modules"
.SH NAME
modulefile \- files containing Tcl code for the Modules package
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH DESCRIPTION
.sp
\fImodulefiles\fP are written in the Tool Command Language, \fBTcl(n)\fP and
are interpreted by the \fBmodulecmd.tcl\fP program via the module(1)
user interface. \fImodulefiles\fP 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.
.sp
A \fImodulefile\fP begins with the magic cookie, \fB#%Module\fP\&. A version number
may be placed after this string. The version number is useful as the
\fImodulefile\fP format may change thus it reflects the minimum version of
\fBmodulecmd.tcl\fP required to interpret the modulefile. If a version
number doesn\(aqt exist, then \fBmodulecmd.tcl\fP will assume the \fImodulefile\fP
is compatible. Files without the magic cookie or with a version number greater
than the current version of \fBmodulecmd.tcl\fP will not be interpreted.
.sp
Each \fImodulefile\fP contains the changes to a user\(aqs environment needed to
access an application. Tcl is a simple programming language which permits
\fImodulefiles\fP to be arbitrarily complex, depending upon the application\(aqs
and the \fImodulefile\fP writer\(aqs needs. If support for extended tcl (tclX)
has been configured for your installation of the Modules package, you may
use all the extended commands provided by tclX, too.
.sp
A typical \fImodulefile\fP is a simple bit of code that set or add entries
to the \fBPATH\fP, \fBMANPATH\fP, or other environment variables. A
Modulefile is evaluated against current \fBmodulecmd.tcl\fP\(aqs mode which
leads to specific evaluation results. For instance if the \fImodulefile\fP sets a
value to an environment variable, this variable is set when modulefile is
loaded and unset when modulefile is unloaded.
.sp
Tcl has conditional statements that are evaluated when the \fImodulefile\fP is
interpreted. This is very effective for managing path or environment changes
due to different OS releases or architectures. The user environment
information is encapsulated into a single \fImodulefile\fP kept in a central
location. The same \fImodulefile\fP is used by every user on any machine. So,
from the user\(aqs perspective, starting an application is exactly the same
irrespective of the machine or platform they are on.
.sp
\fImodulefiles\fP also hide the notion of different types of shells. From the
user\(aqs 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\(aqre using the C Shell do this ..., otherwise if you\(aqre using the Bourne
shell do this ...". Announcing and accessing new software is uniform and
independent of the user\(aqs shell. From the \fImodulefile\fP writer\(aqs perspective,
this means one set of information will take care of every type of shell.
.SH MODULES SPECIFIC TCL COMMANDS
.sp
The Modules Package uses commands which are extensions to the "standard"
Tool Command Language \fBTcl(n)\fP package. Unless otherwise specified,
the Module commands return the empty string. Some commands behave differently
when a \fImodulefile\fP is loaded or unloaded. The command descriptions assume
the \fImodulefile\fP is being loaded.
.INDENT 0.0
.TP
.B append\-path [\-d C|\-\-delim C|\-\-delim=C] [\-\-duplicates] variable value...
See \fI\%prepend\-path\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B break
This is not a Modules\-specific command, it\(aqs actually part of Tcl, which
has been overloaded similar to the \fI\%continue\fP and \fI\%exit\fP
commands to have the effect of causing the module not to be listed as loaded
and not affect other modules being loaded concurrently. All non\-environment
commands within the module will be performed up to this point and processing
will continue on to the next module on the command line. The \fI\%break\fP
command will only have this effect if not used within a Tcl loop though.
.sp
An example: Suppose that a full selection of \fImodulefiles\fP are needed for
various different architectures, but some of the \fImodulefiles\fP are not
needed and the user should be alerted. Having the unnecessary \fImodulefile\fP
be a link to the following notavail \fImodulefile\fP will perform the task
as required.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
#%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: \(aq$curMod\(aq is not available for [uname sysname]."
}
break
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B chdir directory
Set the current working directory to \fIdirectory\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B conflict modulefile...
\fI\%prereq\fP and \fI\%conflict\fP control whether or not the \fImodulefile\fP
will be loaded. The \fI\%prereq\fP command lists \fImodulefiles\fP which must
have been previously loaded before the current \fImodulefile\fP will be loaded.
Similarly, the \fI\%conflict\fP command lists \fImodulefiles\fP which
\fI\%conflict\fP with the current \fImodulefile\fP\&. If a list contains more than
one \fImodulefile\fP, then each member of the list acts as a Boolean OR
operation. Multiple \fI\%prereq\fP and \fI\%conflict\fP 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 \fImodulefile\fP makes no
changes to the user\(aqs environment.
.sp
If an argument for \fI\%prereq\fP is a directory and any \fImodulefile\fP from
the directory has been loaded, then the prerequisite is met. For example,
specifying X11 as a \fI\%prereq\fP means that any version of X11, X11/R4 or
X11/R5, must be loaded before proceeding.
.sp
If an argument for \fI\%conflict\fP is a directory and any other
\fImodulefile\fP from that directory has been loaded, then a conflict will occur.
For example, specifying X11 as a \fI\%conflict\fP will stop X11/R4 and
X11/R5 from being loaded at the same time.
.sp
The parameter \fImodulefile\fP may also be a symbolic modulefile name or a
modulefile alias. It may also leverage a specific syntax to finely select
module version (see \fI\%Advanced module version specifiers\fP section below).
.UNINDENT
.INDENT 0.0
.TP
.B continue
This is not a modules specific command but another overloaded Tcl command
and is similar to the \fI\%break\fP or \fI\%exit\fP 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 \fI\%continue\fP command will only have this effect if
not used within a Tcl loop though.
.UNINDENT
.INDENT 0.0
.TP
.B exit [N]
This is not a modules specific command but another overloaded Tcl command
and is similar to the \fI\%break\fP or \fI\%continue\fP 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.
.UNINDENT
.INDENT 0.0
.TP
.B getenv variable [value]
Returns value of environment \fIvariable\fP\&. If \fIvariable\fP is not defined,
\fIvalue\fP is returned if set, \fB_UNDEFINED_\fP is returned otherwise. The
\fI\%getenv\fP command should be preferred over the Tcl global variable
\fBenv\fP to query environment variables.
.UNINDENT
.INDENT 0.0
.TP
.B is\-avail modulefile...
The \fI\%is\-avail\fP command returns a true value if any of the listed
\fImodulefiles\fP exists in enabled \fBMODULEPATH\fP\&. If a list contains more
than one \fImodulefile\fP, then each member acts as a boolean OR operation. If an
argument for \fI\%is\-avail\fP is a directory and a \fImodulefile\fP exists in
the directory \fI\%is\-avail\fP would return a true value.
.sp
The parameter \fImodulefile\fP may also be a symbolic modulefile name or a
modulefile alias. It may also leverage a specific syntax to finely select
module version (see \fI\%Advanced module version specifiers\fP section below).
.UNINDENT
.INDENT 0.0
.TP
.B is\-loaded [modulefile...]
The \fI\%is\-loaded\fP command returns a true value if any of the listed
\fImodulefiles\fP has been loaded or if any \fImodulefile\fP is loaded in case no
argument is provided. If a list contains more than one \fImodulefile\fP, then
each member acts as a boolean OR operation. If an argument for
\fI\%is\-loaded\fP is a directory and any \fImodulefile\fP from the directory has
been loaded \fI\%is\-loaded\fP would return a true value.
.sp
The parameter \fImodulefile\fP may also be a symbolic modulefile name or a
modulefile alias. It may also leverage a specific syntax to finely select
module version (see \fI\%Advanced module version specifiers\fP section below).
.UNINDENT
.INDENT 0.0
.TP
.B is\-saved [collection...]
The \fI\%is\-saved\fP command returns a true value if any of the listed
\fIcollections\fP exists or if any \fIcollection\fP exists in case no argument is
provided. If a list contains more than one \fIcollection\fP, then each member
acts as a boolean OR operation.
.sp
If \fBMODULES_COLLECTION_TARGET\fP is set, a suffix equivalent to the
value of this variable is appended to the passed \fIcollection\fP name. In case
no \fIcollection\fP argument is provided, a true value will only be returned if
a collection matching currently set target exists.
.UNINDENT
.INDENT 0.0
.TP
.B is\-used [directory...]
The \fI\%is\-used\fP command returns a true value if any of the listed
\fIdirectories\fP has been enabled in \fBMODULEPATH\fP or if any \fIdirectory\fP
is enabled in case no argument is provided. If a list contains more than one
\fIdirectory\fP, then each member acts as a boolean OR operation.
.UNINDENT
.INDENT 0.0
.TP
.B module [sub\-command] [sub\-command\-args]
Contains the same \fIsub\-commands\fP as described in the module(1)
man page in the Module Sub\-Commands section. This command permits a
\fImodulefile\fP to \fBload\fP or \fBunload\fP other \fImodulefiles\fP\&. No
checks are made to ensure that the \fImodulefile\fP does not try to load itself.
Often it is useful to have a single \fImodulefile\fP that performs a number of
\fBmodule load\fP commands. For example, if every user on the system
requires a basic set of applications loaded, then a core \fImodulefile\fP
would contain the necessary \fBmodule load\fP commands.
.sp
Command line switches \fB\-\-auto\fP, \fB\-\-no\-auto\fP and
\fB\-\-force\fP are ignored when passed to a \fI\%module\fP command set in
a \fImodulefile\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B module\-alias name modulefile
Assigns the \fImodulefile\fP to the alias \fIname\fP\&. This command should be
placed in one of the \fBmodulecmd.tcl\fP rc files in order to provide
shorthand invocations of frequently used \fImodulefile\fP names.
.sp
The parameter \fImodulefile\fP may be either
.INDENT 7.0
.IP \(bu 2
a fully qualified \fImodulefile\fP with name and version
.IP \(bu 2
a symbolic \fImodulefile\fP name
.IP \(bu 2
another \fImodulefile\fP alias
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B module\-forbid [options] modulefile...
Forbid use of \fImodulefile\fP\&. An error is obtained when trying to evaluate a
forbidden module. This command should be placed in one of the
\fBmodulecmd.tcl\fP rc files.
.sp
\fI\%module\-forbid\fP command accepts the following options:
.INDENT 7.0
.IP \(bu 2
\fB\-\-after datetime\fP
.IP \(bu 2
\fB\-\-before datetime\fP
.IP \(bu 2
\fB\-\-not\-user {user...}\fP
.IP \(bu 2
\fB\-\-not\-group {group...}\fP
.IP \(bu 2
\fB\-\-message {text message}\fP
.IP \(bu 2
\fB\-\-nearly\-message {text message}\fP
.UNINDENT
.sp
If \fB\-\-after\fP option is set, forbidding is only effective after specified
date time. Following the same principle, if \fB\-\-before\fP option is set,
forbidding is only effective before specified date time. Accepted date time
format is \fBYYYY\-MM\-DD[THH:MM]\fP\&. If no time (\fBHH:MM\fP) is specified,
\fB00:00\fP is assumed. \fB\-\-after\fP and \fB\-\-before\fP options are not supported
on Tcl versions prior to 8.5.
.sp
If \fB\-\-not\-user\fP option is set, forbidding is not applied if the username of
the user currently running \fBmodulecmd.tcl\fP is part of the list of
username specified. Following the same approach, if \fB\-\-not\-group\fP 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 \fB\-\-not\-user\fP or \fB\-\-not\-group\fP\&.
.sp
Error message returned when trying to evaluate a forbidden module can be
supplemented with the \fItext message\fP set through \fB\-\-message\fP option.
.sp
If \fB\-\-after\fP option is set, modules are considered \fInearly forbidden\fP
during a number of days defined by the \fBnearly_forbidden_days\fP
\fBmodulecmd.tcl\fP configuration option
(see \fBMODULES_NEARLY_FORBIDDEN_DAYS\fP), prior reaching the expiry
date fixed by \fB\-\-after\fP option. When a \fInearly forbidden\fP module is
evaluated a warning message is issued to inform module will soon be
forbidden. This warning message can be supplemented with the \fItext message\fP
set through \fB\-\-nearly\-message\fP option.
.sp
If a \fI\%module\-forbid\fP command applies to a \fImodulefile\fP also targeted
by a \fI\%module\-hide \-\-hard\fP command, this module is
unveiled when precisely named to return an access error.
.sp
The parameter \fImodulefile\fP may leverage a specific syntax to finely select
module version (see \fI\%Advanced module version specifiers\fP section below).
.UNINDENT
.INDENT 0.0
.TP
.B module\-hide [options] modulefile...
Hide \fImodulefile\fP to exclude it from available module search or module
selection unless query refers to \fImodulefile\fP by its exact name. This command
should be placed in one of the \fBmodulecmd.tcl\fP rc files.
.sp
\fI\%module\-hide\fP command accepts the following options:
.INDENT 7.0
.IP \(bu 2
\fB\-\-soft|\-\-hard\fP
.IP \(bu 2
\fB\-\-after datetime\fP
.IP \(bu 2
\fB\-\-before datetime\fP
.IP \(bu 2
\fB\-\-not\-user {user...}\fP
.IP \(bu 2
\fB\-\-not\-group {group...}\fP
.UNINDENT
.sp
When \fB\-\-soft\fP option is set, \fImodulefile\fP is also set hidden, but hiding is
disabled when search or selection query\(aqs root name matches module\(aqs root
name. This soft hiding mode enables to hide modulefiles from bare module
availability listing yet keeping the ability to select such module for load
with the regular resolution mechanism (i.e., no need to use module exact name
to select it)
.sp
When \fB\-\-hard\fP option is set, \fImodulefile\fP is also set hidden and stays
hidden even if search or selection query refers to \fImodulefile\fP by its exact
name.
.sp
If \fB\-\-after\fP option is set, hiding is only effective after specified date
time. Following the same principle, if \fB\-\-before\fP option is set, hiding is
only effective before specified date time. Accepted date time format is
\fBYYYY\-MM\-DD[THH:MM]\fP\&. If no time (\fBHH:MM\fP) is specified, \fB00:00\fP is
assumed. \fB\-\-after\fP and \fB\-\-before\fP options are not supported on Tcl
versions prior to 8.5.
.sp
If \fB\-\-not\-user\fP option is set, hiding is not applied if the username of the
user currently running \fBmodulecmd.tcl\fP is part of the list of username
specified. Following the same approach, if \fB\-\-not\-group\fP 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
\fB\-\-not\-user\fP or \fB\-\-not\-group\fP\&.
.sp
If the \fB\-\-all\fP option is set on \fBavail\fP, \fBaliases\fP,
\fBwhatis\fP or \fBsearch\fP sub\-commands, hiding is disabled thus
hidden modulefiles are included in module search. Hard\-hidden modules (i.e.,
declared hidden with \fB\-\-hard\fP option) are not affected by \fB\-\-all\fP
and stay hidden even if option is set. \fB\-\-all\fP option does not apply
to \fImodule selection\fP sub\-commands like \fBload\fP\&. Thus in such context
a hidden module should always be referred by its exact full name (e.g.,
\fBfoo/1.2.3\fP not \fBfoo\fP) unless if it has been hidden in \fB\-\-soft\fP mode. A
hard\-hidden module cannot be unveiled or selected in any case.
.sp
If several \fI\%module\-hide\fP commands target the same \fImodulefile\fP, the
strongest hiding level is retained which means if both a regular, a
\fB\-\-soft\fP hiding command match a given module, regular hiding mode is
considered. If both a regular and a \fB\-\-hard\fP hiding command match a given
module, hard hiding mode is retained.
.sp
The parameter \fImodulefile\fP may also be a symbolic modulefile name or a
modulefile alias. It may also leverage a specific syntax to finely select
module version (see \fI\%Advanced module version specifiers\fP section below).
.UNINDENT
.INDENT 0.0
.TP
.B module\-info option [info\-args]
Provide information about the \fBmodulecmd.tcl\fP program\(aqs state. Some of
the information is specific to the internals of \fBmodulecmd.tcl\fP\&.
\fIoption\fP is the type of information to be provided, and \fIinfo\-args\fP are any
arguments needed.
.sp
\fBmodule\-info alias\fP name
.INDENT 7.0
.INDENT 3.5
Returns the full \fImodulefile\fP name to which the \fImodulefile\fP alias \fIname\fP
is assigned
.UNINDENT
.UNINDENT
.sp
\fBmodule\-info command\fP [commandname]
.INDENT 7.0
.INDENT 3.5
Returns the currently running \fBmodulecmd.tcl\fP\(aqs command as a string
if no \fIcommandname\fP is given.
.sp
Returns \fB1\fP if \fBmodulecmd.tcl\fP\(aqs command is \fIcommandname\fP\&.
\fIcommandname\fP can be: \fBload\fP, \fBunload\fP, \fBreload\fP, \fBsource\fP,
\fBswitch\fP, \fBdisplay\fP, \fBavail\fP, \fBaliases\fP, \fBlist\fP, \fBwhatis\fP,
\fBsearch\fP, \fBpurge\fP, \fBrestore\fP, \fBhelp\fP or \fBtest\fP\&.
.UNINDENT
.UNINDENT
.sp
\fBmodule\-info loaded\fP modulefile
.INDENT 7.0
.INDENT 3.5
Returns the names of currently loaded modules matching passed \fImodulefile\fP\&.
The parameter \fImodulefile\fP might either be a fully qualified \fImodulefile\fP
with name and version or just a directory which in case all loaded
\fImodulefiles\fP from the directory will be returned. The parameter
\fImodulefile\fP may also be a symbolic modulefile name or a modulefile alias.
.UNINDENT
.UNINDENT
.sp
\fBmodule\-info mode\fP [modetype]
.INDENT 7.0
.INDENT 3.5
Returns the current \fBmodulecmd.tcl\fP\(aqs mode as a string if no
\fImodetype\fP is given.
.sp
Returns \fB1\fP if \fBmodulecmd.tcl\fP\(aqs mode is \fImodetype\fP\&. \fImodetype\fP can
be: \fBload\fP, \fBunload\fP, \fBremove\fP, \fBswitch\fP, \fBdisplay\fP, \fBhelp\fP,
\fBtest\fP or \fBwhatis\fP\&.
.UNINDENT
.UNINDENT
.sp
\fBmodule\-info name\fP
.INDENT 7.0
.INDENT 3.5
Return the name of the \fImodulefile\fP\&. This is not the full pathname for
\fImodulefile\fP\&. See the \fI\%Modules Variables\fP section for information on the
full pathname.
.UNINDENT
.UNINDENT
.sp
\fBmodule\-info shell\fP [shellname]
.INDENT 7.0
.INDENT 3.5
Return the current shell under which \fBmodulecmd.tcl\fP was invoked if
no \fIshellname\fP is given. The current shell is the first parameter of
\fBmodulecmd.tcl\fP, which is normally hidden by the \fBmodule\fP
alias.
.sp
If a \fIshellname\fP is given, returns \fB1\fP if \fBmodulecmd.tcl\fP\(aqs current
shell is \fIshellname\fP, returns \fB0\fP otherwise. \fIshellname\fP can be: \fBsh\fP,
\fBbash\fP, \fBksh\fP, \fBzsh\fP, \fBcsh\fP, \fBtcsh\fP, \fBfish\fP, \fBtcl\fP, \fBperl\fP,
\fBpython\fP, \fBruby\fP, \fBlisp\fP, \fBcmake\fP, \fBr\fP\&.
.UNINDENT
.UNINDENT
.sp
\fBmodule\-info shelltype\fP [shelltypename]
.INDENT 7.0
.INDENT 3.5
Return the family of the shell under which \fImodulefile\fP was invoked if no
\fIshelltypename\fP is given. As of \fBmodule\-info shell\fP this depends on
the first parameter of \fBmodulecmd.tcl\fP\&. The output reflects a shell
type determining the shell syntax of the commands produced by
\fBmodulecmd.tcl\fP\&.
.sp
If a \fIshelltypename\fP is given, returns \fB1\fP if \fBmodulecmd.tcl\fP\(aqs
current shell type is \fIshelltypename\fP, returns \fB0\fP otherwise.
\fIshelltypename\fP can be: \fBsh\fP, \fBcsh\fP, \fBfish\fP, \fBtcl\fP, \fBperl\fP,
\fBpython\fP, \fBruby\fP, \fBlisp\fP, \fBcmake\fP, \fBr\fP\&.
.UNINDENT
.UNINDENT
.sp
\fBmodule\-info specified\fP
.INDENT 7.0
.INDENT 3.5
Return the name of the \fImodulefile\fP specified on the command line.
.UNINDENT
.UNINDENT
.sp
\fBmodule\-info symbols\fP modulefile
.INDENT 7.0
.INDENT 3.5
Returns a list of all symbolic versions assigned to the passed
\fImodulefile\fP\&.  The parameter \fImodulefile\fP might either be a full qualified
\fImodulefile\fP with name and version, another symbolic \fImodulefile\fP name
or a \fImodulefile\fP alias.
.UNINDENT
.UNINDENT
.sp
\fBmodule\-info type\fP
.INDENT 7.0
.INDENT 3.5
Returns either \fBC\fP or \fBTcl\fP to indicate which \fBmodule\fP command
is being  executed, either the C version or the Tcl\-only version, to allow
the \fImodulefile\fP writer to handle any differences between the two.
.UNINDENT
.UNINDENT
.sp
\fBmodule\-info usergroups\fP [name]
.INDENT 7.0
.INDENT 3.5
Returns all the groups the user currently running \fBmodulecmd.tcl\fP is
member of as a list of strings if no \fIname\fP is given.
.sp
Returns \fB1\fP if one of the group current user running \fBmodulecmd.tcl\fP
is member of is \fIname\fP\&. Returns \fB0\fP otherwise.
.sp
If the Modules Tcl extension library is disabled, the \fBid(1)\fP
command is invoked to fetch groups of current user.
.UNINDENT
.UNINDENT
.sp
\fBmodule\-info username\fP [name]
.INDENT 7.0
.INDENT 3.5
Returns the username of the user currently running \fBmodulecmd.tcl\fP as
a string if no \fIname\fP is given.
.sp
Returns \fB1\fP if username of current user running \fBmodulecmd.tcl\fP is
\fIname\fP\&. Returns \fB0\fP otherwise.
.sp
If the Modules Tcl extension library is disabled, the \fBid(1)\fP
command is invoked to fetch username of current user.
.UNINDENT
.UNINDENT
.sp
\fBmodule\-info version\fP modulefile
.INDENT 7.0
.INDENT 3.5
Returns the physical module name and version of the passed symbolic
version \fImodulefile\fP\&.  The parameter \fImodulefile\fP might either be a full
qualified \fImodulefile\fP with name and version, another symbolic \fImodulefile\fP
name or a \fImodulefile\fP alias.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B module\-version modulefile version\-name...
Assigns the symbolic \fIversion\-name\fP to the \fImodulefile\fP\&. This command
should be placed in one of the \fBmodulecmd.tcl\fP rc files in order to
provide shorthand invocations of frequently used \fImodulefile\fP names.
.sp
The special \fIversion\-name\fP default specifies the default version to be
used for module commands, if no specific version is given. This replaces
the definitions made in the \fB\&.version\fP file in former
\fBmodulecmd.tcl\fP releases.
.sp
The parameter \fImodulefile\fP may be either
.INDENT 7.0
.IP \(bu 2
a fully or partially qualified \fImodulefile\fP with name / version. If
name is \fB\&.\fP (dot) then the current directory name is assumed to be the
module name. (Use this for deep \fImodulefile\fP directories.)
.IP \(bu 2
a symbolic \fImodulefile\fP name
.IP \(bu 2
another \fImodulefile\fP alias
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B module\-virtual name modulefile
Assigns the \fImodulefile\fP to the virtual module \fIname\fP\&. This command should be
placed in rc files in order to define virtual modules.
.sp
A virtual module stands for a module \fIname\fP associated to a \fImodulefile\fP\&. The
modulefile is the script interpreted when loading or unloading the virtual
module which appears or can be found with its virtual name.
.sp
The parameter \fImodulefile\fP corresponds to the relative or absolute file
location of a \fImodulefile\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B module\-whatis string
Defines a string which is displayed in case of the invocation of the
\fBmodule whatis\fP command. There may be more than one
\fI\%module\-whatis\fP line in a \fImodulefile\fP\&. This command takes no actions
in case of \fBload\fP, \fBdisplay\fP, etc. invocations of
\fBmodulecmd.tcl\fP\&.
.sp
The \fIstring\fP parameter has to be enclosed in double\-quotes if there\(aqs more
than one word specified. Words are defined to be separated by whitespace
characters (space, tab, cr).
.UNINDENT
.INDENT 0.0
.TP
.B prepend\-path [\-d C|\-\-delim C|\-\-delim=C] [\-\-duplicates] variable value...
Append or prepend \fIvalue\fP to environment \fIvariable\fP\&. The
\fIvariable\fP is a colon, or \fIdelimiter\fP, separated list such as
\fBPATH=directory:directory:directory\fP\&. The default delimiter is a colon
\fB:\fP, but an arbitrary one can be given by the \fB\-\-delim\fP option. For
example a space can be used instead (which will need to be handled in
the Tcl specially by enclosing it in \fB" "\fP or \fB{ }\fP). A space, however,
can not be specified by the \fB\-\-delim=C\fP form.
.sp
A reference counter environment variable is also set to increase the
number of times \fIvalue\fP has been added to environment \fIvariable\fP\&. This
reference counter environment variable is named by suffixing \fIvariable\fP
by \fB_modshare\fP\&.
.sp
When \fIvalue\fP is already defined in environement \fIvariable\fP, it is not added
again except if \fB\-\-duplicates\fP option is set.
.sp
If the \fIvariable\fP is not set, it is created. When a \fImodulefile\fP is
unloaded, \fI\%append\-path\fP and \fI\%prepend\-path\fP become
\fI\%remove\-path\fP\&.
.sp
If \fIvalue\fP corresponds to the concatenation of multiple elements separated by
colon, or \fIdelimiter\fP, character, each element is treated separately.
.UNINDENT
.INDENT 0.0
.TP
.B prereq modulefile...
See \fI\%conflict\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B remove\-path [\-d C|\-\-delim C|\-\-delim=C] [\-\-index] variable value...
Remove \fIvalue\fP from the colon, or \fIdelimiter\fP, separated list in
\fIvariable\fP\&. See \fI\%prepend\-path\fP or \fI\%append\-path\fP for further
explanation of using an arbitrary delimiter. Every string between colons, or
delimiters, in \fIvariable\fP is compared to \fIvalue\fP\&. If the two match, \fIvalue\fP
is removed from \fIvariable\fP if its reference counter is equal to 1 or unknown.
.sp
When \fB\-\-index\fP option is set, \fIvalue\fP refers to an index in \fIvariable\fP
list. The string element pointed by this index is set for removal.
.sp
Reference counter of \fIvalue\fP in \fIvariable\fP denotes the number of times
\fIvalue\fP has been added to \fIvariable\fP\&. This information is stored in
environment \fIvariable_modshare\fP\&. When attempting to remove \fIvalue\fP from
\fIvariable\fP, relative reference counter is checked and \fIvalue\fP is removed
only if counter is equal to 1 or not defined. Otherwise \fIvalue\fP is kept
in \fIvariable\fP and reference counter is decreased by 1.
.sp
If \fIvalue\fP corresponds to the concatenation of multiple elements separated by
colon, or \fIdelimiter\fP, character, each element is treated separately.
.UNINDENT
.INDENT 0.0
.TP
.B set\-alias alias\-name alias\-string
Sets an alias or function with the name \fIalias\-name\fP in the user\(aqs
environment to the string \fIalias\-string\fP\&. For some shells, aliases are not
possible and the command has no effect. When a \fImodulefile\fP is unloaded,
\fI\%set\-alias\fP becomes \fI\%unset\-alias\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B set\-function function\-name function\-string
Creates a function with the name \fIfunction\-name\fP in the user\(aqs environment
with the function body \fIfunction\-string\fP\&. For some shells, functions are not
possible and the command has no effect. When a \fImodulefile\fP is unloaded,
\fI\%set\-function\fP becomes \fI\%unset\-function\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B setenv variable value
Set environment \fIvariable\fP to \fIvalue\fP\&. The \fI\%setenv\fP command will also
change the process\(aq environment. A reference using Tcl\(aqs env associative
array will reference changes made with the \fI\%setenv\fP command. Changes
made using Tcl\(aqs \fBenv\fP associative array will \fBNOT\fP change the user\(aqs
environment \fIvariable\fP like the \fI\%setenv\fP command. An environment
change made this way will only affect the module parsing process. The
\fI\%setenv\fP command is also useful for changing the environment prior to
the \fBexec\fP or \fI\%system\fP command. When a \fImodulefile\fP is unloaded,
\fI\%setenv\fP becomes \fI\%unsetenv\fP\&. If the environment \fIvariable\fP had
been defined it will be overwritten while loading the \fImodulefile\fP\&. A
subsequent \fBunload\fP will unset the environment \fIvariable\fP \- the
previous value cannot be restored! (Unless you handle it explicitly ... see
below.)
.UNINDENT
.INDENT 0.0
.TP
.B source\-sh shell script [arg...]
Evaluate with \fIshell\fP the designated \fIscript\fP with defined \fIarguments\fP to
find out the environment changes it does. Those changes obtained by comparing
environment prior and after \fIscript\fP evaluation are then translated into
corresponding \fImodulefile\fP commands, which are then applied during modulefile
evaluation as if they were directly written in it.
.sp
When modulefile is unloaded, environment changes done are reserved by
evaluating in the \fBunload\fP context the resulting modulefile commands, which
were recorded in the \fBMODULES_LMSOURCESH\fP environment variable at
\fBload\fP time.
.sp
Changes on environment variables, shell aliases, shell functions and current
working directory are tracked.
.sp
\fIShell\fP 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.
.UNINDENT
.INDENT 0.0
.TP
.B system string
Run \fIstring\fP command through shell. On Unix, command is passed to the
\fB/bin/sh\fP shell whereas on Windows it is passed to \fBcmd.exe\fP\&.
\fBmodulecmd.tcl\fP redirects stdout to stderr since stdout would be parsed
by the evaluating shell. The exit status of the executed command is returned.
.UNINDENT
.INDENT 0.0
.TP
.B uname field
Provide lookup of system information. Most \fIfield\fP information are retrieved
from the \fBtcl_platform\fP array (see the \fBtclvars(n)\fP man page).
Uname will return the string \fBunknown\fP if information is unavailable for
the \fIfield\fP\&.
.sp
\fI\%uname\fP will invoke the \fBuname(1)\fP command in order to get
the operating system version and \fBdomainname(1)\fP to figure out the
name of the domain.
.sp
\fIfield\fP values are:
.INDENT 7.0
.IP \(bu 2
\fBsysname\fP: the operating system name
.IP \(bu 2
\fBnodename\fP: the hostname
.IP \(bu 2
\fBdomain\fP: the name of the domain
.IP \(bu 2
\fBrelease\fP: the operating system release
.IP \(bu 2
\fBversion\fP: the operating system version
.IP \(bu 2
\fBmachine\fP: a standard name that identifies the system\(aqs hardware
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B unset\-alias alias\-name
Unsets an alias with the name \fIalias\-name\fP in the user\(aqs environment.
.UNINDENT
.INDENT 0.0
.TP
.B unset\-function function\-name
Removes a function with the name \fIfunction\-name\fP from the user\(aqs environment.
.UNINDENT
.INDENT 0.0
.TP
.B unsetenv variable [value]
Unsets environment \fIvariable\fP\&. However, if there is an optional \fIvalue\fP,
then when unloading a module, it will set \fIvariable\fP to \fIvalue\fP\&. The
\fI\%unsetenv\fP command changes the process\(aq environment like
\fI\%setenv\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B 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 \fIfilename\fP\&. If the argument isn\(aqt a valid file
name, then string will be interpreted as a resource. Either \fIfilename\fP
or \fIresource\-string\fP is then passed down to be \fBxrdb(1)\fP command.
.sp
\fImodulefiles\fP that use this command, should in most cases contain one or
more \fI\%x\-resource\fP lines, each defining one X11 resource. The
\fBDISPLAY\fP environment variable should be properly set and the X11
server should be accessible. If \fI\%x\-resource\fP can\(aqt manipulate the X11
resource database, the \fImodulefile\fP will exit with an error message.
.sp
Examples:
.sp
\fBx\-resource /u2/staff/leif/.xres/Ileaf\fP
.INDENT 7.0
.INDENT 3.5
The content of the \fIIleaf\fP file is merged into the X11 resource database.
.UNINDENT
.UNINDENT
.sp
\fBx\-resource [glob ~/.xres/ileaf]\fP
.INDENT 7.0
.INDENT 3.5
The Tcl glob function is used to have the \fImodulefile\fP read different
resource files for different users.
.UNINDENT
.UNINDENT
.sp
\fBx\-resource {Ileaf.popup.saveUnder: True}\fP
.INDENT 7.0
.INDENT 3.5
Merge the Ileaf resource into the X11 resource database.
.UNINDENT
.UNINDENT
.UNINDENT
.SH MODULES VARIABLES
.sp
The \fBModulesCurrentModulefile\fP variable contains the full pathname of
the \fImodulefile\fP being interpreted.
.SH LOCATING MODULEFILES
.sp
Every directory in \fBMODULEPATH\fP is searched to find the
\fImodulefile\fP\&. A directory in \fBMODULEPATH\fP can have an arbitrary number
of sub\-directories. If the user names a \fImodulefile\fP to be loaded which
is actually a directory, the directory is opened and a search begins for
an actual \fImodulefile\fP\&. First, \fBmodulecmd.tcl\fP looks for a file with
the name \fB\&.modulerc\fP in the directory. If this file exists, its contents
will be evaluated as if it was a \fImodulefile\fP to be loaded. You may place
\fI\%module\-version\fP, \fI\%module\-alias\fP and \fI\%module\-virtual\fP
commands inside this file.
.sp
Additionally, before seeking for \fB\&.modulerc\fP files in the module
directory, the global modulerc file and the \fB\&.modulerc\fP file found at
the root of the modulepath directory are sourced, too. If a named version
default now exists for the \fImodulefile\fP to be loaded, the assigned
\fImodulefile\fP now will be sourced. Otherwise the file \fB\&.version\fP is
looked up in the module directory.
.sp
If the \fB\&.version\fP file exists, it is opened and interpreted as Tcl code
and takes precedence over a \fB\&.modulerc\fP file in the same directory. If
the Tcl variable \fBModulesVersion\fP is set by the \fB\&.version\fP file,
\fBmodulecmd.tcl\fP will use the name as if it specifies a \fImodulefile\fP in
this directory. This will become the default \fImodulefile\fP in this case.
\fBModulesVersion\fP cannot refer to a \fImodulefile\fP located in a different
directory.
.sp
If \fBModulesVersion\fP 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
\fBMODULEPATH\fP\&.
.sp
Every \fB\&.version\fP and \fB\&.modulerc\fP file found is interpreted as Tcl
code. The difference is that \fB\&.version\fP only applies to the current
directory, and the \fB\&.modulerc\fP applies to the current directory and all
subdirectories. Changes made in these files will affect the subsequently
interpreted \fImodulefile\fP\&.
.sp
If no default version may be figured out, an implicit default is selected when
this behavior is enabled (see \fBMODULES_IMPLICIT_DEFAULT\fP 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 numerically sorted
\fImodulefile\fP, virtual module or module alias under the directory will be used.
The dictionary comparison method of the \fBlsort(n)\fP Tcl command is
used to achieve this sort. If highest numerically sorted element is an alias,
search continues on its \fImodulefile\fP target.
.sp
For example, it is possible for a user to have a directory named X11 which
simply contains a \fB\&.version\fP file specifying which version of X11 is to
be loaded. Such a file would look like:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#%Module1.0
##
##  The desired version of X11
##
set ModulesVersion "R4"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The equivalent \fB\&.modulerc\fP would look like:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#%Module1.0
##
##  The desired version of X11
##
module\-version "./R4" default
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If the extended default mechanism is enabled (see
\fBMODULES_EXTENDED_DEFAULT\fP 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
\fB\&.\fP character.
.sp
When the implicit default mechanism and the \fI\%Advanced module version
specifiers\fP are both enabled, a \fBdefault\fP and \fBlatest\fP symbolic versions
are automatically defined for each module name (also at each directory level
in case of deep \fImodulefile\fP). Unless a symbolic version, alias, or regular
module version already exists for these version names.
.sp
If user names a \fImodulefile\fP that cannot be found in the first \fImodulepath\fP
directory, \fImodulefile\fP will be searched in next \fImodulepath\fP directory
and so on until a matching \fImodulefile\fP is found. If search goes through
a module alias or a symbolic version, this alias or symbol is resolved by
first looking at the \fImodulefiles\fP in the \fImodulepath\fP where this alias or
symbol is defined. If not found, resolution looks at the other \fImodulepaths\fP
in their definition order.
.sp
When locating \fImodulefiles\fP, if a \fB\&.modulerc\fP, a \fB\&.version\fP, a
directory or a \fImodulefile\fP cannot be read during the search it is simply
ignored with no error message produced. Visibility of \fImodulefiles\fP can thus
be adapted to the rights the user has been granted. Exception is made when
trying to directly access a directory or a \fImodulefile\fP\&. In this case,
the access issue is returned as an error message.
.sp
Depending on their name, their file permissions or the use of specific
modulefile commands, \fImodulefile\fP, virtual module, module alias or symbolic
version may be set hidden which impacts available modules search or module
selection processes (see \fI\%Hiding modulefiles\fP section below).
.SH HIDING MODULEFILES
.sp
A \fImodulefile\fP, virtual module, module alias or symbolic version whose name or
element in their name starts with a dot character (\fB\&.\fP) or who are targeted
by a \fI\%module\-hide\fP command are considered hidden. Hidden modules are
not displayed or taken into account except if they are explicitly named (e.g.,
\fBfoo/1.2.3\fP or \fBfoo/.2.0\fP not \fBfoo\fP). If module has been hidden with the
\fB\-\-soft\fP option of the \fI\%module\-hide\fP command set, it is not
considered hidden if the root name of the query to search it matches module
root name (e.g., searching \fBfoo\fP will return a \fBfoo/1.2.3\fP modulefile
targeted by a \fBmodule\-hide \-\-soft\fP command). If module has been hidden with
the \fB\-\-hard\fP option of the \fI\%module\-hide\fP command set, it is always
considered hidden thus it is never displayed nor taken into account even if
it is explicitly named.
.sp
A \fImodulefile\fP, virtual module, module alias or symbolic version who are
targeted by a \fI\%module\-hide \-\-hard\fP command and a
\fI\%module\-forbid\fP command or whose file access permissions are restricted
are considered hard\-hidden and forbidden. Such modules are not displayed or
taken into account. When explicitly named for evaluation selection, such
modules are unveiled to return an access error.
.sp
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 \fImodulefile\fP appears like any other non\-hidden
module alias. Finally, a hidden symbolic version targeting a non\-hidden module
is displayed or taken into account only if not hard\-hidden and explicitly
named to refer to its non\-hidden target.
.sp
The automatic version symbols (e.g., \fBdefault\fP and \fBlatest\fP) are
unaffected by hiding. Moreover when a regular \fBdefault\fP or \fBlatest\fP
version is set hidden, the corresponding automatic version symbol takes the
left spot. For instance, if \fBfoo/default\fP which targets \fBfoo/1.2.3\fP is set
hard\-hidden, the \fBdefault\fP automatic version symbol will be set onto
\fBfoo/2.1.3\fP, the highest available version of \fBfoo\fP\&.
.sp
If the \fB\-\-all\fP is set on \fBavail\fP, \fBaliases\fP,
\fBwhatis\fP or \fBsearch\fP sub\-commands, hidden modules are taken
into account in search. Hard\-hidden modules are unaffected by this option.
.SH ADVANCED MODULE VERSION SPECIFIERS
.sp
When the advanced module version specifiers mechanism is enabled (see
\fBMODULES_ADVANCED_VERSION_SPEC\fP in module(1)), the
specification of modulefile passed on Modules specific Tcl commands changes.
After the module name a version constraint prefixed by the \fB@\fP character may
be added. It could be directly appended to the module name or separated from
it with a space character.
.sp
Constraints can be expressed to refine the selection of module version to:
.INDENT 0.0
.IP \(bu 2
a single version with the \fB@version\fP syntax, for instance \fBfoo@1.2.3\fP
syntax will select module \fBfoo/1.2.3\fP
.IP \(bu 2
a list of versions with the \fB@version1,version2,...\fP syntax, for instance
\fBfoo@1.2.3,1.10\fP will match modules \fBfoo/1.2.3\fP and \fBfoo/1.10\fP
.IP \(bu 2
a range of versions with the \fB@version1:\fP, \fB@:version2\fP and
\fB@version1:version2\fP syntaxes, for instance \fBfoo@1.2:\fP will select all
versions of module \fBfoo\fP greater than or equal to \fB1.2\fP, \fBfoo@:1.3\fP
will select all versions less than or equal to \fB1.3\fP and \fBfoo@1.2:1.3\fP
matches all versions between \fB1.2\fP and \fB1.3\fP including \fB1.2\fP and
\fB1.3\fP versions
.UNINDENT
.sp
Advanced specification of single version or list of versions may benefit from
the activation of the extended default mechanism (see
\fBMODULES_EXTENDED_DEFAULT\fP in module(1)) to use an abbreviated
notation like \fB@1\fP to refer to more precise version numbers like \fB1.2.3\fP\&.
Range of versions on its side natively handles abbreviated versions.
.sp
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 \fB10a\fP, \fB1.2.3\fP, \fB1.foo\fP are versions valid for range
comparison whereas \fBdefault\fP or \fBfoo.2\fP versions are invalid for range
comparison.
.sp
If the implicit default mechanism is also enabled (see
\fBMODULES_IMPLICIT_DEFAULT\fP in module(1)), a \fBdefault\fP and
\fBlatest\fP symbolic versions are automatically defined for each module name
(also at each directory level for deep \fImodulefiles\fP). These automatic version
symbols are defined unless a symbolic version, alias, or regular module
version already exists for these \fBdefault\fP or \fBlatest\fP version names.
Using the \fBmod@latest\fP (or \fBmod/latest\fP) syntax ensures highest available
version will be selected.
.SH MODULEFILE SPECIFIC HELP
.sp
Users can request help about a specific \fImodulefile\fP through the
module(1) command. The \fImodulefile\fP can print helpful information or
start help oriented programs by defining a \fBModulesHelp\fP subroutine. The
subroutine will be called when the \fBmodule help modulefile\fP
command is used.
.SH MODULEFILE SPECIFIC TEST
.sp
Users can request test of a specific \fImodulefile\fP through the module(1)
command. The \fImodulefile\fP can perform some sanity checks on its
definition or on its underlying programs by defining a \fBModulesTest\fP
subroutine. The subroutine will be called when the
\fBmodule test modulefile\fP command is used. The subroutine should
return 1 in case of success. If no or any other value is returned, test is
considered failed.
.SH MODULEFILE DISPLAY
.sp
The \fBmodule display modulefile\fP command will detail all
changes that will be made to the environment. After displaying all of the
environment changes \fBmodulecmd.tcl\fP will call the \fBModulesDisplay\fP
subroutine. The \fBModulesDisplay\fP subroutine is a good place to put
additional descriptive information about the \fImodulefile\fP\&.
.SH ENVIRONMENT
.sp
See the ENVIRONMENT section in the
module(1) man page.
.SH SEE ALSO
.sp
module(1), ml(1), \fBTcl(n)\fP, \fBTclX(n)\fP,
\fBid(1)\fP, \fBxrdb(1)\fP, \fBexec(n)\fP, \fBuname(1)\fP,
\fBdomainname(1)\fP, \fBtclvars(n)\fP, \fBlsort(n)\fP
.SH NOTES
.sp
Tcl was developed by John Ousterhout at the University of California
at Berkeley.
.sp
TclX was developed by Karl Lehenbauer and Mark Diekhans.
.SH 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
.\" Generated by docutils manpage writer.
.