DESCRIPTION
modulefiles are written in the Tool Command Language, Tcl(3) and are
interpreted by the modulecmd program via the module(1) user interface.
modulefiles can be loaded, unloaded, or switched on-the-fly while the
user is working.
A modulefile begins with the magic cookie, '#%Module'. A version
number may be placed after this string. The version number is useful
as the format of modulefiles may change. If a version number doesn't
exist, then modulecmd will assume the modulefile is compatible with the
latest version. The current version for modulefiles is 1.0. Files
without the magic cookie will not be interpreted by modulecmd.
Each modulefile contains the changes to a user's environment needed to
access an application. Tcl is a simple programming language which
permits modulefiles to be arbitrarily complex, depending upon the
application's and the modulefile writer's needs. If support for
extended tcl (tclX) has been configured for your installation of
modules, you may use all the extended commands provided by tclX, too.
modulefiles can be used to implement site policies regarding the access
and use of applications.
A typical modulefiles is a simple bit of code that set or add entries
to the PATH, MANPATH, or other environment variables. Tcl has
conditional statements that are evaluated when the modulefile is
loaded. This is very effective for managing path or environment
changes due to different OS releases or architectures. The user
environment information is encapsulated into a single modulefile kept
in a central location. The same modulefile is used by every user on
any machine. So, from the user's perspective, starting an application
is exactly the same irregardless of the machine or platform they are
on.
modulefiles also hide the notion of different types of shells. From
the user's perspective, changing the environment for one shell looks
exactly the same as changing the environment for another shell. This
is useful for new or novice users and eliminates the need for
statements such as "if you're using the C Shell do this ..., otherwise
if you're using the Bourne shell do this ..." Announcing and accessing
new software is uniform and independent of the user's shell. From the
modulefile writer's perspective, this means one set of information will
take care of every type of shell.
Modules Specific Tcl Commands
The Modules Package uses commands which are extensions to the
"standard" Tool Command Language Tcl(3) package. Unless otherwise
specified, the Module commands return the empty string. Some commands
behave differently when a modulefile is loaded or unloaded. The
command descriptions assume the modulefile is being loaded.
break
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
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 modulefile is unloaded, setenv becomes
unsetenv. If the environment variable had been defined it will
be overwritten while loading the modulefile. A subsequent
unload will unset the environment variable - the previous value
cannot be restored! (Unless you handle it explicitly ... see
below.)
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.
append-path variable value
prepend-path variable value
Append or prepend value to environment variable. The variable
is a colon separated list such as
"PATH=directory:directory:directory". If the variable is not
set, it is created. When a modulefile is unloaded, append-path
and prepend-path become remove-path.
remove-path variable value
Remove value from the colon separated list in variable. Every
string between colons in variable is compared to value. If the
two match, value is removed from variable.
prereq modulefile [ modulefile ... ]
conflict modulefile [ 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
If an argument for conflict is a directory and any other
modulefile from that directory has been loaded, then a conflict
will occur. For example, specifying X11 as a conflict will stop
X11/R4 and X11/R5 from being loaded at the same time.
is-loaded modulefile [ modulefile ... ]
The is-loaded command returns a true value if any of the listed
modulefiles has been loaded. 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.
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 remove 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
commands.
module-info option [ info-args ]
Provide information about the modulecmd program's state. Some
of the information is specific to the internals of modulecmd.
option is the type of information to be provided, and info-args
are any arguments needed.
module-info flags
Returns the integer value of modulecmd's flags state.
module-info mode [modetype]
Returns the current modulecmd's mode as a string if no
modetype is given.
Returns 1 if modulecmd's mode is modetype. modetype can
be: load, remove, display, help, whatis, switch, switch1,
switch2, or switch3.
module-info name
Return the name of the modulefile. This is not the full
pathname for modulefile. See the Modules Variables
section for information on the full pathname.
module-info specified
Return the name of the modulefile specified on the
command line.
module-info shell
Return the current shell under which modulecmd was
invoked. This is the first parameter of modulecmd, which
Returns a list of all symbolic versions assigned to the
passed module-file. The paremeter module-file might
either be a full qualified module file with name and
version, another symbolic module file name or a module
file alias.
module-version module-file version-name [version-name ...]
Assignes the symbolic version-name to the module file module-
file This command should be placed in one of the modulecmd rc
files in order to provide shorthand invocations of frequently
used module file names.
The special version-name default specifies the default version
to be used for module commands, if no specific verion is given.
This replaces the definitions made in the .version file in
former modulecmd releases.
The parameter module-file may be either
a fully qualified modulefile with name and version
a symbolic module file name
another module file alias
module-alias name module-file
Assignes the module file module-file to the alias name. This
command should be placed in one of the modulecmd rc files in
order to provide shorthand invocations of frequently used module
file names.
The parameter module-file may be either
a fully qualified modulefile with name and version
a symbolic module file name
another module file alias
module-trace {on|off} [command [command ...]] [-module modulefile
[modulefile ...]]
Switches tracing on or off. Without parameters this command will
affect globally all tracing setups for all commands and
modulefiles. The command parameter may be used to affect tracing
of specified module commands only and the switch -module finally
limits the affect of the module-trace command to a well defined
set of module files.
The command may be one of the following
avail - 'module avail' command
clear - 'module clear' command
display - 'module display' command
init - 'module init' command
help - 'module help' command
list - 'module list' command
gnu/2.0 affects only version 2.0 of the gnu modulefile
The module parameter is prepended to the current tracing pattern
list for the specified module command. It is evaluated from the
left to the right. The first matching pattern defines the
tracing parameter.
The internal trace pattern list is stored as a colon separated
list. In advanced user level only, colons may be specified on
the module parameter of the module-trace command. This will
directly take effect in the internal trace pattern list. In
novice or expert user level a warning messge will be generated.
module-user level
Defines the user level under wich module-cmd runs. This takes
effect on the error messages being produced and on the behavior
of modulecmd in case of detecting an outage.
The level parameter specifies the user level and may be one of
the following values:
advanced, adv - advanced user level
expert, exp - expert user level
novice, nov - novice user level
module-verbosity {on|off}
Switches verbose modulecmd message display on or off.
module-log error-weight log-facility
Defines whether error messages of the specified weight should be
logged and conditionally assignes a log-facility. alias-name
The error-weight parameter specifies the error level to be
logged. It may be one of the following values:
verb - verbose messages
info - informal messages
debug - debugging messages
trace - tracing output
warn - warnings
prob - problems (normally the modulecmd may be completed)
error - errors (which normally leads to unsuccessful end
of the modulecmd)
fatal - fatal system errors
panic - very fatal system errors, e.g. internal program
inconsistencies.
The log-facility parameter specifies the log destination. This
may either switch off logging for the specified error-weight,
direct log messages to a special stream or a file or specify a
syslog facility for logging. The following values are allowed:
module-whatis string
Defines a string which is displayed in case of the invocation of
the 'module whatis' command. There may be more than one module-
whatis line in a modulefile. This command takes no actions in
case of load, display, etc. invocations of modulecmd.
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).
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. Arguments can be
specified using the Bourne Shell style of function arguments.
If the string contains "$1", then this will become the first
argument when the alias is interpreted by the shell. The string
"$*" corresponds to all of the arguments given to the alias.
The character '$' may be escaped using the '\' character.
For some shells, aliases are not possible and the command has no
effect. For Bourne shell derivatives, a shell function will be
written (if supported) to give the impression of an alias. When
a modulefile is unloaded, set-alias becomes unset-alias.
unset-alias alias-name
Unsets an alias with the name alias-name in the user's
environment. If the shell supports functions then the shell is
instructed to unset function alias-name.
system string
Pass string to the C library routine system(3). For the
system(3) call modulecmd 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 fast lookup of system information on systems that
support uname(3). uname is significantly faster than using
system to execute a program to return host information. If
uname(3) is not available, gethostname(3) or some program will
make the nodename available. uname will return the string
"unknown" if information is unavailable for the field.
uname will invoke getdomainname in order 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
modulefiles that use this command, should in most cases contain
one or more x-resource lines, each defining one X11 resource.
Reading resources from filename is much slower, due to the
preprocessing. 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 file Ileaf is preprocessed by cpp(1) and the result
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-
directories. If the user names a modulefile to be loaded which is
actually a directory, the directory is opened and a search begins for
an actual modulefile. First, modulecmd 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 module file to be load. You may place module-
version and module-alias commands inside this file. Additionally,
before seeking for .modulerc files in the module directory, the global
.modulerc file is sourced, too. If a named version default now exists
for the module file to be load, the assigned modulefile now will be
sourced. Otherwise the file .version is looked up in the directory. If
the .version file exists, it is opened and interpreted as Tcl code. If
the Tcl variable ModulesVersion is set by the .version file, modulecmd
will use the name as if it specifies a modulefile in the directory.
This will become the default module file in this case. 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 Tcl interpreted. So,
changes made in these file will affect the subsequently interpreted
modulefile.
Modulefile Specific Help
Users can request help about a specific modulefile through the
module(1) 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 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 will call the ModulesDisplay subroutine.
The ModulesDisplay subroutine is a good place to put additional
descriptive information about the modulefile.
ENVIRONMENT
${MODULEPATH}
Path of directories containing modulefiles.
SEE ALSO
module(1), Tcl(3), TclX(3), xrdb(1), cpp(1), system(3), uname(3),
gethostname(3) getdomainname(3)
NOTES
Tcl was developed by John Ousterhout at the University of California at
Berkeley.
TclX was developed by Karl Lehenbauer and Mark Diekhans.
1 July 1994 MODULEFILE(5)
Man(1) output converted with
man2html