modulefile

NAME

modulefile - files containing Tcl code for the Modules package

DESCRIPTION

modulefiles are written in the Tool Command Language, Tcl(n) and are interpreted by the modulecmd.tcl program via the module(1) user 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 #%Module file signature, also called the Modules magic cookie. 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. If the mcookie_version_check configuration is disabled the version number set is not checked. 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.

MODULES SPECIFIC TCL COMMANDS

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.















































Modulefiles and run-command (rc) files are differently interpreted. A limited number of the Modules specific Tcl commands are available for rc files interpretation since such files are intended to set parameters for modulefiles (like defining alias, hiding, tagging, etc) and not to change user environment. The following table summarizes the different commands available for each interpretation context.

Commands available from modulefile interpretation	Commands available from run-command (rc) file interpretation
All the Modules specific and standard Tcl commands	is-loaded, is-used, module-alias, module-forbid, module-hide, module-info, module-tag, module-version, module-virtual, system, uname, versioncmp and standard Tcl commands

NOTE:

MODULES VARIABLES

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.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:
The equivalent .modulerc would look like:
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. Every file in searched directories is checked to see if it begins with the Modules magic cookie (i.e., #%Module file signature) to determine if it is a modulefile (see DESCRIPTION section). When the mcookie_check configuration is set to eval, this check is skipped and all files in search directories are considered modulefiles. 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).

HIDING MODULEFILES

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. NOTE:
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. When loading a modulefile or a virtual module targeted by a module-hide --hidden-loaded command, this module inherits the hidden-loaded tag. Hidden loaded modules are not reported among list sub-command results. 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. If the --all is set on list sub-command, hidden loaded modules are included in result output.

ADVANCED MODULE VERSION SPECIFIERS

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 and variants may be added.

Version specifiers

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. Range of versions can be specified in version list, for instance foo@:1.2,1.4:1.6,1.8:. Such specification helps to exclude specific versions, like versions 1.3 and 1.7 in previous example. 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.

Variants

After the module name, variants can be specified. Module variants are alternative evaluation of the same modulefile. A variant is specified by associating a value to its name. This specification is then transmitted to the evaluating modulefile which instantiates the variant in the ModuleVariant array variable when reaching the variant modulefile command declaring this variant. Variant can be specified with the name=value syntax where name is the declared variant name and value, the value this variant is set to when evaluating the modulefile. Boolean variants can be specified with the +name syntax to set this variant on and with the -name or ~name syntaxes to set this variant off. The -name syntax is not supported on ml(1) command as the minus sign already means to unload designated module. The ~name and +name syntaxes could also be defined appended to another specification word (e.g., the module name, version or another variant specification), whereas -name syntax must be the start of a new specification word. Boolean variants may also be specified with the name=value syntax. value should be set to 1, true, t, yes, y or on to enable the variant or it should be set to 0, false, f, no, n or off to disable the variant. Shortcuts may be used to abbreviate variant specification. The variant_shortcut configuration option associates shortcut character to variant name. With a shortcut defined, variant could be specified with the <shortcut>value syntax. For instance if character % is set as a shortcut for variant foo, the %value syntax is equivalent to the foo=value syntax. Specific characters used in variant specification syntax cannot be used as part of the name of a module. These specific characters are +, ~, = and all characters set as variant shortcut. Exception is made for + character which could be set one or several consecutive times at the end of module name (e.g., name+ or name++).

DEPENDENCIES BETWEEN MODULEFILES

A modulefile may express dependencies on other modulefiles. Two kind of dependency exist: pre-requirement and conflict. The former means specified modulefiles should be loaded prior the modulefile that express the requirement. The latter means specified modulefiles should not be loaded for the modulefile that express the conflict to be loaded too. Pre-requirement could be expressed with prereq, prereq-any, prereq-all, depends-on, always-load, module load, module switch, module try-load or module load-any modulefile commands. When the auto_handling configuration option is disabled, required modulefile should be manually loaded prior their dependent modulefile when expressed with the prereq, prereq-any, prereq-all or depends-on modulefile commands. For other commands or when auto_handling is enabled, pre-required modulefiles are automatically loaded. Conflict is expressed with conflict or module unload modulefile commands. A conflicting loaded modulefile should be manually unloaded prior loading the modulefile that express such conflict when defined with conflict. It is automatically unloaded when expressed with module unload. It is strongly advised to define dependencies prior environment changes in a modulefile. Dependency resolution should be done before any environment change to ensure the environment is getting set in the same order whether pre-requirements are already loaded, or if they are automatically loaded when loading the modulefile which depends on them, or if all loaded modules are reloaded or refreshed. This is especially important when the modulefile updates an environment variable also altered by other modulefiles like PATH. As the order of the path elements in such variable defines priority, it is important that this order does not change depending on the way the modulefiles are loaded. module keeps environment consistent which means a modulefile cannot be loaded if its requirements are not loaded or if a conflicting module is loaded. In addition a loaded module cannot be unloaded if other loaded modules depends on it. The automated module handling mechanisms attempt to solve the dependencies expressed by loading or unloading additional modulefiles. When the --no-auto option is set on module command when loading or unload modulefile, automated module handling mechanisms are disabled and dependencies have to be solved manually. When dependencies are not satisfied, modulefile fails to load or unload. Adding the --not-req option when expressing dependencies in modulefile with the module command will attempt to load or unload the designated modulefile but it will not mark them as pre-requirement or conflict. Adding the --optional option on prereq, prereq-any, prereq-all, depends-on or always-load modulefile commands declares the pre-requirement as optional. If an optional pre-requirement is not found loaded or cannot be automatically loaded, the dependency expressed is yet considered satisfied. When an optional requirement is loaded afterward, the dependent module will get automatically reloaded if the auto_handling configuration option is enabled. By adding the --force option to the module command when loading or unloading modulefile, the consistency checks are by-passed. This option cannot be used when expressing dependencies in modulefiles. If a module has been force loaded whereas its requirements are not loaded or whereas a conflicting module is also loaded, the user environment is said inconsistent. Note that a pre-requirement should be found in the loaded module list prior its dependent module. User environment is considered inconsistent if pre-requirement module is found loaded after dependent module, as the environment changes may have been done in the wrong priority order. When user environment is considered inconsistent global operations achieved by refresh, reload and save sub-commands cannot perform. This mechanism is there to avoid the situation to worsen by re-evaluating all loaded modules or recording this environment. When the auto_handling configuration option is enabled, if missing pre-requirement modulefile gets loaded or conflicting modulefile gets unloaded the inconsistent loaded module will be automatically reloaded to make user environment consistent again.

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 SPECIFIC TEST

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.

MODULEFILE DISPLAY

The module display modulefile command will detail all changes that will be made to the environment. After displaying all of the environment changes modulecmd.tcl will call the ModulesDisplay subroutine. The ModulesDisplay subroutine is a good place to put additional descriptive information about the modulefile.

COMPATIBILITY WITH LMOD TCL MODULEFILE

The modulecmd.tcl program supports Tcl modulefile written for Lmod, the alternative module implementation developed in Lua. Such modulefiles can be evaluated by Modules without raising error. Differences between the two implementations are listed below. The add-property, remove-property and extensions modulefile commands are evaluated as a no-operation command. No error is obtained if these commands are used in modulefiles but no change occurs. The break command does not accept any argument. A msg argument can be set on Lmod to provide a customized break error message. Use of reportError command aborts modulefile evaluation on Lmod. This command only reports an error message on Modules. The require-fullname command only aborts load modulefile evaluation whereas the Lmod implementation also aborts unload and display evaluations. When processing a family command, the LMOD_FAMILY_<NAME> environment variable is also defined to be compatible with modulefiles or scripts relying on such variable. When unloading a modulefile, the pushenv command does not update the value of the environment variable if this modulefile was not defining the value currently in use. The third optional argument of append-path and prepend-path commands corresponds to a priority specification on Lmod whereas these two commands accept multiple path element arguments on Modules. The prereq command is equivalent to the prereq-any command on Modules whereas on Lmod it is equivalent to the prereq-all command. If the auto_handling configuration option is disabled, the requirements defined with the depends-on command are not automatically loaded and an error is raised if none of these requirements are found loaded. On module load-any sub-command and modulefile command, a modulefile evaluation error is not reported and module load-any continues to the next modulefile instead of aborting the whole process. No attempt to load listed modulefiles is made if one of these modulefiles is found already loaded. On module try-load modulefile command, each modulefile specified is considered an optional pre-requirement. If it is loaded afterward and if the auto_handling configuration option is enabled, the dependent module will get automatically reloaded.

SHELL SUPPORT

The modulecmd.tcl program that evaluates modulefiles supports a variety of shells or languages: sh family shells (sh, bash, ksh and zsh), csh family shells (csh and tcsh), fish, cmd, python, perl, ruby, tcl, cmake, r, and lisp. Modulefiles produce environment changes when evaluated, like defining an environment variable. The modulecmd.tcl program outputs the corresponding code for the selected "shell". Thereafter this code is evaluated by the module alias or function to update the current environment. Depending on the "shell" kind, not all the environment changes that can be defined in modulefiles are supported. The following table summarizes the changes that are supported by the shells supported by modulecmd.tcl.

	Environment variables (setenv, unsetenv, pushenv, append-path, prepend-path, remove-path)	Shell alias (set-alias, unset-alias)	Shell functions (set-function, unset-function)	Command completion (complete, uncomplete)	chdir	x-resource
sh	⦁	⦁	⦁		⦁	⦁
bash	⦁	⦁	⦁	⦁	⦁	⦁
ksh	⦁	⦁	⦁		⦁	⦁
zsh	⦁	⦁	⦁		⦁	⦁
csh	⦁	⦁			⦁	⦁
tcsh	⦁	⦁		⦁	⦁	⦁
fish	⦁	⦁	⦁	⦁	⦁	⦁
cmd	⦁	⦁			⦁
python	⦁				⦁	⦁
perl	⦁				⦁	⦁
ruby	⦁				⦁	⦁
tcl	⦁				⦁	⦁
cmake	⦁					⦁
r	⦁				⦁	⦁
lisp	⦁				⦁	⦁

The source-sh command evaluates a shell script and produces the modulefile commands corresponding to the environment changes made by this script. source-sh is able to evaluate sh, bash, ksh, zsh, csh, tcsh and fish shell scripts. source-sh produces environment changes corresponding to the kinds listed in the above table. Based on the evaluated script, refer to the above table to know the environment changes that will be rendered for the shell specified to modulecmd.tcl program.

ENVIRONMENT

See the ENVIRONMENT section in the module(1) man page.

SEE ALSO

module(1), ml(1), Tcl(n), TclX(n), id(1), xrdb(1), exec(n), uname(1), domainname(1), tclvars(n), lsort(n)

NOTES

Tcl was developed by John Ousterhout at the University of California at Berkeley. TclX was developed by Karl Lehenbauer and Mark Diekhans.

COPYRIGHT

1996-1999 John L. Furlani & Peter W. Osel, 1998-2017 R.K.Owen, 2002-2004 Mark Lakata, 2004-2017 Kent Mein, 2016-2022 Xavier Delaruelle