MODULEFILE(4) | Modules | MODULEFILE(4) |
modulefile - files containing Tcl code for the Modules package
modulefiles are written in the Tool Command Language, Tcl(n) and are interpreted by the modulecmd.tcl 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 thus it reflects the minimum version of modulecmd.tcl required to interpret the modulefile. If a version number doesn't exist, then modulecmd.tcl will assume the modulefile is compatible. Files without the magic cookie or with a version number greater than the current version of modulecmd.tcl will not be interpreted.
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. 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 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.
The Modules Package uses commands which are extensions to the "standard" Tool Command Language Tcl(n) 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.
An example: Suppose that a full selection of modulefiles are needed for various different architectures, but some of the modulefiles 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
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 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.
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 specifiers section below).
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 specifiers section below).
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 specifiers section below).
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.
Command line switches --auto, --no-auto and --force are ignored when passed to a module command set in a modulefile.
The parameter modulefile may be either
module-forbid command accepts the following options:
If --after option is set, forbidding is only effective after specified date time. Following the same principle, if --before option is set, forbidding is only effective before specified date time. Accepted date time format is YYYY-MM-DD[THH:MM]. If no time (HH:MM) is specified, 00:00 is assumed. --after and --before options are not supported on Tcl versions prior to 8.5.
If --not-user option is set, forbidding is not applied if the username of the user currently running modulecmd.tcl is part of the list of username specified. Following the same approach, if --not-group option is set, forbidding is not applied if current user is member of one the group specified. When both options are set, forbidding is not applied if a match is found for --not-user or --not-group.
Error message returned when trying to evaluate a forbidden module can be supplemented with the text message set through --message option.
If --after option is set, modules are considered nearly forbidden during a number of days defined by the nearly_forbidden_days modulecmd.tcl configuration option (see MODULES_NEARLY_FORBIDDEN_DAYS), prior reaching the expiry date fixed by --after option. When a nearly forbidden module is evaluated a warning message is issued to inform module will soon be forbidden. This warning message can be supplemented with the text message set through --nearly-message option.
If a module-forbid command applies to a modulefile also targeted by a module-hide --hard command, this module is unveiled when precisely named to return an access error.
The parameter modulefile may leverage a specific syntax to finely select module version (see Advanced module version specifiers section below).
module-hide command accepts the following options:
When --soft option is set, modulefile is also set hidden, but hiding is disabled when search or selection query's root name matches module's root name. This soft hiding mode enables to hide modulefiles from bare module availability listing yet 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)
When --hard option is set, modulefile is also set hidden and stays hidden even if search or selection query refers to modulefile by its exact name.
If --after option is set, hiding is only effective after specified date time. Following the same principle, if --before option is set, hiding is only effective before specified date time. Accepted date time format is YYYY-MM-DD[THH:MM]. If no time (HH:MM) is specified, 00:00 is assumed. --after and --before options are not supported on Tcl versions prior to 8.5.
If --not-user option is set, hiding is not applied if the username of the user currently running modulecmd.tcl is part of the list of username specified. Following the same approach, if --not-group option is set, hiding is not applied if current user is member of one the group specified. When both options are set, hiding is not applied if a match is found for --not-user or --not-group.
If the --all option is set on avail, aliases, whatis or search sub-commands, hiding is disabled thus hidden modulefiles are included in module search. Hard-hidden modules (i.e., declared hidden with --hard option) are not affected by --all and stay hidden even if option is set. --all option does not apply to module selection sub-commands like load. Thus in such context a hidden module should always be referred by its exact full name (e.g., foo/1.2.3 not foo) unless if it has been hidden in --soft mode. A hard-hidden module cannot be unveiled or selected in any case.
If several module-hide commands target the same modulefile, the strongest hiding level is retained which means if both a regular, a --soft hiding command match a given module, regular hiding mode is considered. If both a regular and a --hard hiding command match a given module, hard hiding mode is retained.
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 specifiers section below).
module-info alias name
module-info command [commandname]
Returns 1 if modulecmd.tcl's command is commandname. commandname can be: load, unload, reload, source, switch, display, avail, aliases, list, whatis, search, purge, restore, help or test.
module-info loaded modulefile
module-info mode [modetype]
Returns 1 if modulecmd.tcl's mode is modetype. modetype can be: load, unload, remove, switch, display, help, test or whatis.
module-info name
module-info shell [shellname]
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]
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
module-info symbols modulefile
module-info type
module-info usergroups [name]
Returns 1 if one of the group current user running modulecmd.tcl is member of is name. Returns 0 otherwise.
If the Modules Tcl extension library is disabled, the id(1) command is invoked to fetch groups of current user.
module-info username [name]
Returns 1 if username of current user running modulecmd.tcl is name. Returns 0 otherwise.
If the Modules Tcl extension library is disabled, the id(1) command is invoked to fetch username of current user.
module-info version modulefile
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 former modulecmd.tcl releases.
The parameter modulefile may be either
A virtual module stands for a module name associated to a modulefile. 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.
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).
A reference counter environment variable is also set to increase the number of times value has been added to environment variable. 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.
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.
When modulefile is unloaded, environment changes done are reserved by evaluating in the unload context the resulting modulefile commands, which were recorded in the MODULES_LMSOURCESH environment variable at load time.
Changes on environment variables, shell aliases, shell functions and current working directory are tracked.
Shell could be specified as a command name or a fully qualified pathname. The following shells are supported: sh, dash, csh, tcsh, bash, ksh, ksh93, zsh and fish.
uname will invoke the uname(1) command in order to get the operating system version and domainname(1) to figure out the name of the domain.
field values are:
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
x-resource [glob ~/.xres/ileaf]
x-resource {Ileaf.popup.saveUnder: True}
The ModulesCurrentModulefile variable contains the full pathname of the modulefile being interpreted.
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.tcl looks for a file with the name .modulerc in the directory. If this file exists, its contents will be evaluated as if it was a modulefile to be loaded. You may place module-version, module-alias and module-virtual commands inside this file.
Additionally, before seeking for .modulerc files in the module directory, 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 modulefile 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, modulecmd.tcl will use the name as if it specifies a modulefile in this directory. This will become the default modulefile in this case. ModulesVersion cannot refer to a modulefile located in a different directory.
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 numerically 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 numerically sorted element is an alias, search continues on its modulefile target.
For example, it is possible for a user to have a directory named X11 which simply contains a .version file specifying which version of X11 is to be loaded. Such a file would look like:
#%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 MODULES_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 modulepaths in their definition order.
When locating modulefiles, if a .modulerc, a .version, a directory or a modulefile cannot be read during the search it is simply ignored with no error message produced. Visibility of modulefiles can thus be adapted to the rights the user has been granted. Exception is made when trying to directly access a directory or a modulefile. In this case, the access issue is returned as an error message.
Depending on their name, their file permissions or the use of specific modulefile commands, modulefile, virtual module, module alias or symbolic version may be set hidden which impacts available modules search or module selection processes (see Hiding modulefiles section below).
A modulefile, virtual module, module alias or symbolic version whose name or element in their name starts with a dot character (.) or who are targeted by a module-hide command are considered hidden. Hidden modules are not displayed or taken into account except if they are explicitly named (e.g., foo/1.2.3 or foo/.2.0 not foo). If module has been hidden with the --soft option of the module-hide command set, it is not considered hidden if the root name of the query to search it matches module root name (e.g., searching foo will return a foo/1.2.3 modulefile targeted by a module-hide --soft command). If module has been hidden with the --hard option of the module-hide command set, it is always considered hidden thus it is never displayed nor taken into account even if it is explicitly named.
A modulefile, virtual module, module alias or symbolic version who are targeted by a module-hide --hard command and a module-forbid command or whose file access permissions are restricted are considered hard-hidden and forbidden. Such modules are not displayed or taken into account. When explicitly named for evaluation selection, such modules are unveiled to return an access error.
A symbolic version-name assigned to a hidden module is displayed or taken into account only if explicitly named and if module is not hard-hidden. Non-hidden module alias targeting a hidden modulefile 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.
The automatic version symbols (e.g., default and latest) are unaffected by hiding. Moreover when a regular default or latest version is set hidden, the corresponding automatic version symbol takes the left spot. For instance, if foo/default which targets foo/1.2.3 is set hard-hidden, the default automatic version symbol will be set onto foo/2.1.3, the highest available version of foo.
If the --all is set on avail, aliases, whatis or search sub-commands, hidden modules are taken into account in search. Hard-hidden modules are unaffected by this option.
When the advanced module version specifiers mechanism is enabled (see MODULES_ADVANCED_VERSION_SPEC in module(1)), the specification of modulefile 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:
Advanced specification of single version or list of versions may benefit from the activation of the extended default mechanism (see MODULES_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 versions 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 MODULES_IMPLICIT_DEFAULT in module(1)), a default and latest symbolic versions 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.
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.
Users can request test of a specific modulefile through the module(1) command. The modulefile can perform some sanity checks on its definition or on its underlying programs by defining a ModulesTest subroutine. The subroutine will be called when the module test modulefile command is used. The subroutine should return 1 in case of success. If no or any other value is returned, test is considered failed.
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 ModulesDisplay subroutine is a good place to put additional descriptive information about the modulefile.
See the ENVIRONMENT section in the module(1) man page.
module(1), ml(1), Tcl(n), TclX(n), id(1), xrdb(1), exec(n), uname(1), domainname(1), tclvars(n), lsort(n)
Tcl was developed by John Ousterhout at the University of California at Berkeley.
TclX was developed by Karl Lehenbauer and Mark Diekhans.
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
2020-11-14 | 4.6.1 |