NAME¶

modulefile - files containing Tcl code for the Modules package

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; and can be used to implement site policies regarding 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. If a version number doesn't exist, then modulecmd will assume the modulefile is compatible with the latest version. The current modulefile version 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 the Modules package, 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. 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 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 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

#%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

continue

exit [N]

setenv variable value

unsetenv variable [value]

append-path [ -d C | --delim C | --delim=C ] variable value
prepend-path [ -d C | --delim C | --delim=C ] variable value

remove-path [ -d C | --delim C | --delim=C ] variable value

prereq modulefile [ modulefile ... ]
conflict modulefile [ modulefile ... ]

is-loaded modulefile [ modulefile ... ]

module [ sub-command ] [ sub-command-args ]

module-info option [ info-args ]

module-version module-file version-name [version-name ...]

module-alias name module-file

module-trace {on|off} [command [command ...]] [-module modulefile [modulefile ...]]

module-user level

module-verbosity {on|off}

module-log error-weight log-facility

module-whatis string

set-alias alias-name alias-string

unset-alias alias-name

system string

uname field

x-resource resource-string
x-resource filename

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 loaded. 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 loaded, 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 and takes precedence over a .modulerc file in the same directory. 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.

If no default version may be figured out, then the highest lexicographically sorted modulefile under the directory using the 'C' locale will be used.

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"

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.

VERSION¶

3.2.13

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.