Environment Modules¶

Welcome to the Environment Modules documentation portal. The Environment Modules package provides for the dynamic modification of a user’s environment via modulefiles.

The Modules package is a tool that simplify shell initialization and lets users easily modify their environment during the session with modulefiles.

Each modulefile contains the information needed to configure the shell for an application. Once the Modules package is initialized, the environment can be modified on a per-module basis using the module command which interprets modulefiles. Typically modulefiles instruct the module command to alter or set shell environment variables such as PATH, MANPATH, etc. modulefiles may be shared by many users on a system and users may have their own collection to supplement or replace the shared modulefiles.

Modules can be loaded and unloaded dynamically and atomically, in an clean fashion. All popular shells are supported, including bash, ksh, zsh, sh, csh, tcsh, fish, as well as some scripting languages such as tcl, perl, python, ruby, cmake and r.

Modules are useful in managing different versions of applications. Modules can also be bundled into metamodules that will load an entire suite of different applications.

Quick examples¶

Here is an example of loading a module on a Linux machine under bash.

$ module load gcc/6.1.1
$ which gcc
$ /usr/local/gcc/6.1.1/linux-x86_64/bin/gcc

Now we’ll switch to a different version of the module

$ module switch gcc gcc/6.3.1
$ which gcc
/usr/local/gcc/6.3.1/linux-x86_64/bin/gcc

And now we’ll unload the module altogether

$ module unload gcc
$ which gcc
gcc not found

Now we’ll log into a different machine, using a different shell (tcsh).

% module load gcc/6.3.1
% which gcc
/usr/local/gcc/6.3.1/linux-aarch64/bin/gcc

Note that the command line is exactly the same, but the path has automatically configured to the correct architecture.

Installing Modules on Unix¶

This document is an overview of building and installing Modules on a Unix system.

Requirements¶

Modules consists of one Tcl script so to run it from a user shell the only requirement is to have a working version of tclsh (version 8.4 or later) available on your system. tclsh is a part of Tcl (http://www.tcl.tk/software/tcltk/).

To install Modules from a distribution tarball or a clone of the git repository, a build step is there to adapt the initialization scripts to your configuration and create the documentation files. This build step requires the tools to be found on your system:

bash
make
sed
runtest

When also installing the bundled compatibility version of Modules (enabled by default), these additional tools are needed:

autoconf
automake
autopoint
grep
gcc
tcl-devel >= 8.4

When installing from a distribution tarball, documentation is pre-built and does not require additional software. When installing from a clone of the git repository, document has to be built and the following tools are required:

sphinx >= 1.0

Installation instructions¶

The simplest way to build and install Modules is:

$ ./configure
$ make
$ make install

Some explanation, step by step:

cd to the directory containing the package’s source code. Your system must have the above requirements installed to properly build scripts, compatibility version of Modules if enabled, and documentation if build occurs from a clone of the git repository.
Type ./configure to adapt the installation for your system. At this step you can choose the installation paths and the features you want to enable in the initialization scripts (see Build and installation options section below for a complete overview of the available options)
Type make to adapt scripts to the configuration, build compatibility version if enabled and build documentation if working from git repository.
Optionally, type make test to run the test suite.
Type make install to install modulecmd.tcl, initialization scripts, compatibility version if built and documentation.
Optionally, type make testinstall to run the installation test suite.
You can remove the built files from the source code directory by typing make clean. To also remove the files that configure created, type make distclean.

A default installation process like described above will install Modules under /usr/local/Modules. You can change this with the --prefix option. By default, /usr/local/Modules/modulefiles will be setup as the default directory containing modulefiles. --modulefilesdir option enables to change this directory location. For example:

$ ./configure --prefix=/usr/share/Modules \
              --modulefilesdir=/etc/modulefiles

See Build and installation options section to discover all ./configure option available.

Note

GNU Make is excepted to be used for this build and installation process. On non-Linux systems, the gmake should be called instead of make.

Configuration¶

Once installed you should review and adapt the configuration to make it fit your needs. The following steps are provided for example. They are not necessarily mandatory as it depends of the kind of setup you want to achieve.

Tune the initialization scripts. Review of these scripts is highly encouraged as you may add or adapt specific stuff to get Modules initialized the way you want.
Enable Modules initialization at shell startup. An easy way to get module function defined and its associated configuration setup at shell startup is to make the initialization scripts part of the system-wide environment setup in /etc/profile.d. To do so, make a link in this directory to the profile scripts that can be found in your Modules installation init directory:
```
$ ln -s PREFIX/init/profile.sh /etc/profile.d/modules.sh
$ ln -s PREFIX/init/profile.csh /etc/profile.d/modules.csh
```
These profile scripts will automatically adapt to the kind of sh or csh shell you are running.

Another approach may be to get the Modules initialization script sourced from the shell configuration startup file. For instance following line could be added to the end of the ~/.bashrc file if running Bash shell:
```
source PREFIX/init/bash
```
Beware that shells have multiple ways to initialize depending if they are a login shell or not and if they are launched in interactive mode or not.
Define module paths to enable by default. Edit modulerc configuration file or .modulespath if you have chosen --enable-dotmodulespath at configure time. Add there all the modulefile directories you want to activate by default at Modules initialization time.

If you use .modulespath configuration file, add one line mentioning each modulefile directory:
```
/path/to/regular/modulefiles
/path/to/other/modulefiles
```
If you use modulerc configuration file, add one line mentioning each modulefile directory prefixed by the module use command:
```
module use /path/to/regular/modulefiles
module use /path/to/other/modulefiles
```
Define modulefiles to load by default. Edit modulerc configuration file (modulefiles to load cannot be specified in .modulespath file). Add there all the modulefiles you want to load by default at Modules initialization time.

Add one line mentioning each modulefile to load prefixed by the module load command:
```
module load foo
module load bar
```
In fact you can add to the modulerc configuration file any kind of supported module command.

If you go through the above steps you should have a valid setup tuned to your needs. After that you still have to write modulefiles to get something to load and unload in your newly configured Modules setup. Please have a look at the doc/example.txt that explains how the user environment is setup with Modules at the University of Minnesota computer science department.

Build and installation options¶

Options available at the ./configure installation step are described below. These options enable to choose the installation paths and the features to enable or disable. You can also get a description of these options by typing ./configure --help.

Fine tuning of the installation directories (the default value for each option is displayed within brakets):

`--prefix=PREFIX`
	Installation root directory [`/usr/local/Modules`]
`--bindir=DIR`	Directory for executables reachable by users [`PREFIX/bin`]
`--libexecdir=DIR`
	Directory for executables called by other executables like modulecmd.tcl [`PREFIX/libexec`]
`--etcdir=DIR`	Directory for the executable configuration scripts [`PREFIX/etc`]
`--initdir=DIR`	Directory for the per-shell environment initialization scripts [`PREFIX/init`]
`--datarootdir=DIR`
	Base directory to set the man and doc directories [`PREFIX/share`]
`--mandir=DIR`	Directory to host man pages [`DATAROOTDIR/man`]
`--docdir=DIR`	Directory to host documentation other than man pages like README, license file, etc [`DATAROOTDIR/doc`]
`--modulefilesdir=DIR`
	Directory or main modulefiles also called system modulefiles [`PREFIX/modulefiles`]

Optional Features (the default for each option is displayed within parenthesis, to disable an option replace enable by disable for instance --disable-set-manpath):

`--enable-set-manpath`
	Prepend man page directory defined by the `--mandir` option to the MANPATH environment variable in the shell initialization scripts. (default=yes)
`--enable-set-binpath`
	Prepend binary directory defined by the `--bindir` option to the PATH environment variable in the shell initialization scripts. (default=yes)
`--enable-dotmodulespath`
	Set the module paths defined by `--with-modulepath` option in a `.modulespath` file (following C version fashion) within the initialization directory defined by the `--initdir` option rather than within the `modulerc` file. (default=no)
`--enable-doc-install`
	Install the documentation files in the documentation directory defined with the `--docdir` option. This feature has no impact on manual pages installation. Disabling documentation file installation is useful in case of installation process handled via a package manager which handles by itself the installation of this kind of documents. (default=yes)
`--enable-example-modulefiles`
	Install some modulefiles provided as example in the system modulefiles directory defined with the `modulefilesdir` option. (default=yes)
`--enable-compat-version`
	Build and install the Modules compatibility (C) version in addition to the main released version. This feature also enables switching capabilities from initialization script between the two installed version of Modules (by setting-up the `switchml` shell function or alias). (default=yes)
`--enable-versioning`
	Append Modules version to installation prefix and deploy a `versions` modulepath shared between all versioning enabled Modules installation. A modulefile corresponding to Modules version is added to the shared modulepath and enables to switch from one Modules version to another. (default=no)

Optional Packages (the default for each option is displayed within parenthesis, to disable an option replace with by without for instance --without-modulepath):

`--with-tclsh=BIN`
	Name or full path of Tcl interpreter shell (default=`tclsh`)
`--with-pager=BIN`
	Name or full path of default pager program to use to paginate informational message output (can be superseded at run-time by environment variable) (default=`less`)
`--with-pager-opts=OPTLIST`
	Settings to apply to default pager program (default=`-eFKRX`)
`--with-modulepath=PATHLIST`
	Default path list to setup as the default modulepaths. Each path in this list should be separated by `:`. Defined value is registered in the `modulerc` or `.modulespath` configuration file, depending on the `--enable-dotmodulespath` option. This value is read at initialization time to populate the MODULEPATH environment variable. By default, this modulepath is composed of the directory set for the system modulefiles (default=`PREFIX/modulefiles` or `BASEPREFIX/$MODULE_VERSION/modulefiles` if versioning installation mode enabled)
`--with-loadedmodules=MODLIST`
	Default modulefiles to load at Modules initialization time. Each modulefile in this list should be separated by `:`. Defined value is registered in the `modulerc` configuration file. (default=no)
`--with-quarantine-vars=<VARNAME[=VALUE] …>`
	Environment variables to put in quarantine when running the module command to ensure it a sane execution environment (each variable should be separated by space character). A value can eventually be set to a quarantine variable instead of emptying it. (default=no)

MIGRATING¶

This document describes the major changes occurring between versions of Modules. It provides an overview of the new features and changed behaviors that will be encountered when upgrading.

Migrating from v4.0 to v4.1¶

This new version is backward-compatible with v4.0 and primarily fixes bugs and adds new features.

New features¶

Version 4.1 introduces a bunch of new functionalities. These major new features are described in this section.

Virtual modules¶

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 module-virtual modulefile command is introduced to give the ability to define these virtual modules. This new command takes a module name as first argument and a modulefile location as second argument:

module-virtual app/1.2.3 /path/to/virtualmod/app

With this feature it is now possible to dynamically define modulefiles depending on the context.

Extend module command with site-specific Tcl code¶

module command can now be extended with site-specific Tcl code. modulecmd.tcl now looks at a siteconfig.tcl file in an etcdir defined at configure time (by default $prefix/etc). If it finds this Tcl script file, it is sourced within modulecmd.tcl at the beginning of the main procedure code.

siteconfig.tcl enables to supersede any global variable or procedure definitions made in modulecmd.tcl with site-specific code. A module sub-command can for instance be redefined to make it fit local needs without having to touch the main modulecmd.tcl.

Quarantine mechanism to protect module execution¶

To protect the module command run-time environment from side effect coming from the current environment definition a quarantine mechanism is introduced. This mechanism, sets within module function definition and shell initialization script, modifies the modulecmd.tcl run-time environment to sanitize it.

The mechanism is piloted by environment variables. First of all MODULES_RUN_QUARANTINE, a space-separated list of environment variable names. Every variable found in MODULES_RUN_QUARANTINE will be set in quarantine during the modulecmd.tcl run-time. Their value will be set empty or set to the value of the corresponding MODULES_RUNENV_<VAR> environment variable if defined. Once modulecmd.tcl is started it restores quarantine variables to their original values.

MODULES_RUN_QUARANTINE and MODULES_RUNENV_<VAR> environment variables can be defined at build time by using the following configure option:

--with-quarantine-vars='VARNAME[=VALUE] ...'

Quarantine mechanism is available for all supported shells except csh and tcsh.

Module function to return value in scripting languages¶

On Tcl, Perl, Python, Ruby, CMake and R scripting shells, module function was not returning value and until now an occurred error led to raising a fatal exception.

To make module function more friendly to use on these scripting shells it now returns a value. False in case of error, true if everything goes well.

As a consequence, returned value of a module sub-command can be checked. For instance in Python:

if module('load foo'):
  # success
else:
  # failure

New modulefile commands¶

4 new modulefile Tcl commands have are introduced:

is-saved: returns true or false whether a collection, corresponding to currently set collection target, exists or not.
is-used: returns true or false whether a given directory is currently enabled in MODULEPATH.
is-avail: returns true or false whether a given modulefile exists in currently enabled module paths.
module-info loaded: returns the exact name of the modulefile currently loaded corresponding to the name argument.

Multiple collections, paths or modulefiles can be passed respectively to is-saved, is-used and is-avail in which case true is returned if at least one argument matches condition (acts as a OR boolean operation). No argument may be passed to is-loaded, is-saved and is-used commands to return if anything is respectively loaded, saved or used.

If no loaded modulefile matches the module-info loaded query, an empty string is returned.

New module sub-commands¶

Modulefile-specific commands are sometimes wished to be used outside of a modulefile context. Especially for the commands managing path variables or commands querying current environment context. So the following modulefile-specific commands have been made reachable as module sub-commands with same arguments and properties as if called from within a modulefile:

append-path
prepend-path
remove-path
is-loaded
info-loaded

The is-loaded sub-command returns a boolean value. Small Python example:

if module('is-loaded app'):
  print 'app is loaded'
else:
  print 'app not loaded'

info-loaded returns a string value and is the sub-command counterpart of the module-info loaded modulefile command:

$ module load app/0.8
$ module info-loaded app
app/0.8

Migrating from v3.2 to v4.0¶

Major evolution occurs with this v4.0 release as the traditional module command implemented in C is replaced by the native Tcl version. This full Tcl rewrite of the Modules package was started in 2002 and has now reached maturity to take over the binary version. This flavor change enables to refine and push forward the module concept.

This document provides an outlook of what is changing when migrating from v3.2 to v4.0 by first describing the introduced new features. Both v3.2 and v4.0 are quite similar and transition to the new major version should be smooth. Slights differences may be noticed in a few use-cases. So the second part of the document will help to learn about them by listing the features that have been discontinued in this new major release or the features where a behavior change can be noticed.

New features¶

On its overall this major release brings a lot more robustness to the module command with now more than 4000 non-regression tests crafted to ensure correct operations over the time. This version 4.0 also comes with fair amount of improved functionalities. The major new features are described in this section.

Additional shells supported¶

Modules v4 introduces support for fish, lisp, tcl and R code output.

Non-zero exit code in case of error¶

All module sub-commands will now return a non-zero exit code in case of error whereas Modules v3.2 always returned zero exit code even if issue occurred.

Output redirect¶

Traditionally the module command output text that should be seen by the user on stderr since shell commands are output to stdout to change shell’s environment. Now on sh, bash, ksh, zsh and fish shells, output text is redirected to stdout after shell command evaluation if shell is in interactive mode.

Filtering avail output¶

Results obtained from the avail sub-command can now be filtered to only get the default version of each module name with use of the –default or -d command line switch. Default version is either the explicitly set default version or the highest numerically sorted modulefile or module alias if no default version set.

It is also possible to filter results to only get the highest numerically sorted version of each module name with use of the –latest or -L command line switch.

Extended support for module alias and symbolic version¶

Module aliases are now included in the result of the avail, whatis and apropos sub-commands. They are displayed in the module path section where they are defined or in a global/user modulerc section for aliases set in user’s or global modulerc file. A @ symbol is added in parenthesis next to their name to distinguish them from modulefiles.

Search may be performed with an alias or a symbolic version-name passed as argument on avail, whatis and apropos sub-commands.

Modules v4 resolves module alias or symbolic version passed to unload command to then remove the loaded modulefile pointed by the mentioned alias or symbolic version.

A symbolic version sets on a module alias is now propagated toward the resolution path to also apply to the relative modulefile if it still correspond to the same module name.

Hiding modulefiles¶

Visibility of modulefiles can be adapted by use of file mode bits or file ownership. If a modulefile should only be used by a given subset of persons, its mode an ownership can be tailored to provide read rights to this group of people only. In this situation, module only reports the modulefile, during an avail command for instance, if this modulefile can be read by the current user.

These hidden modulefiles are simply ignored when walking through the modulepath content. Access issues (permission denied) occur only when trying to access directly a hidden modulefile or when accessing a symbol or an alias targeting a hidden modulefile.

Improved modulefiles location¶

When looking for an implicit default in a modulefile directory, aliases are now taken into account in addition to modulefiles and directories to determine the highest numerically sorted element.

Modules v4 resolves module alias or symbolic version when it points to a modulefile located in another modulepath.

Access issues (permission denied) are now distinguished from find issues (cannot locate) when trying to access directly a directory or a modulefile as done on load, display or whatis commands. In addition, on this kind of access not readable .modulerc or .version files are ignored rather producing a missing magic cookie error.

Module collection¶

Modules v4 introduces support for module collections. Collections describe a sequence of module use then module load commands that are interpreted by Modules to set the user environment as described by this sequence. When a collection is activated, with the restore sub-command, modulepaths and loaded modules are unused or unloaded if they are not part or if they are not ordered the same way as in the collection.

Collections are generated by the save sub-command that dumps the current user environment state in terms of modulepaths and loaded modules. By default collections are saved under the $HOME/.module directory. Collections can be listed with savelist sub-command, displayed with saveshow and removed with saverm.

Collections may be valid for a given target if they are suffixed. In this case these collections can only be restored if their suffix correspond to the current value of the MODULES_COLLECTION_TARGET environment variable. Saving collection registers the target footprint by suffixing the collection filename with .$MODULES_COLLECTION_TARGET.

Path variable element counter¶

Modules 4 provides path element counting feature which increases a reference counter each time a given path entry is added to a given path-like environment variable. As consequence a path entry element is removed from a path-like variable only if the related element counter is equal to 1. If this counter is greater than 1, path element is kept in variable and reference counter is decreased by 1.

This feature allows shared usage of particular path elements. For instance, modulefiles can append /usr/local/bin to PATH, which is not unloaded until all the modulefiles that loaded it unload too.

Optimized I/O operations¶

Substantial work has been done to reduce the number of I/O operations done during global modulefile analysis commands like avail or whatis. stat, open, read and close I/O operations have been cut down to the minimum required when walking through the modulepath directories to check if files are modulefiles or to resolve module aliases.

Interpretation of modulefiles and modulerc are handled by the minimum required Tcl interpreters. Which means a configured Tcl interpreter is reused as much as possible between each modulefile interpretation or between each modulerc interpretation.

Sourcing modulefiles¶

Modules 4 introduces the possibility to source a modulefile rather loading it. When it is sourced, a modulefile is interpreted into the shell environment but then it is not marked loaded in shell environment which differ from load sub-command.

This functionality is used in shell initialization scripts once module function is defined. There the etc/modulerc modulefile is sourced to setup the initial state of the environment, composed of module use and module load commands.

Removed features and substantial behavior changes¶

Following sections provide list of Modules v3.2 features that are discontinued on Modules v4 or features with a substantial behavior change that should be taken in consideration when migrating to v4.

Package initialization¶

MODULESBEGINENV environment snapshot functionality is not supported anymore on Modules v4. Modules collection mechanism should be used instead to save and restore sets of enabled modulepaths and loaded modulefiles.

Command line switches¶

Some command line switches are not supported anymore on v4.0. When still using them, a warning message is displayed and the command is ran with these unsupported switches ignored. Following command line switches are concerned:

--force, -f
--human
--verbose, -v
--silent, -s
--create, -c
--icase, -i
--userlvl lvl, -u lvl

Module sub-commands¶

During an help sub-command, Modules v4 does not redirect output made on stdout in ModulesHelp Tcl procedure to stderr. Moreover when running help, version 4 interprets all the content of the modulefile, then call the ModulesHelp procedure if it exists, whereas Modules 3.2 only interprets the ModulesHelp procedure and not the rest of the modulefile content.

When load is asked on an already loaded modulefiles, Modules v4 ignores this new load order whereas v3.2 refreshed shell alias definitions found in this modulefile.

When switching on version 4 an old modulefile by a new one, no error is raised if old modulefile is not currently loaded. In this situation v3.2 threw an error and abort switch action. Additionally on switch sub-command, new modulefile does not keep the position held by old modulefile in loaded modules list on Modules v4 as it was the case on v3.2. Same goes for path-like environment variables: replaced path component is appended to the end or prepended to the beginning of the relative path-like variable, not appended or prepended relatively to the position hold by the swapped path component.

During a switch command, version 4 interprets the swapped-out modulefile in unload mode, so the sub-modulefiles loaded, with module load order in the swapped-out modulefile are also unloaded during the switch.

Modules 4 provides path element counting feature which increases a reference counter each time a given path entry is added to a given environment variable. This feature also applies to the MODULEPATH environment variable. As consequence a modulepath entry element is removed from the modulepath enabled list only if the related element counter is equal to 1. When unusing a modulepath if its reference counter is greater than 1, modulepath is kept enabled and reference counter is decreased by 1.

On Modules 3.2 paths composing the MODULEPATH environment variable may contain reference to environment variable. These variable references are resolved dynamically when MODULEPATH is looked at during module sub-command action. This feature has been discontinued on Modules v4.

Following Modules sub-commands are not supported anymore on v4.0:

clear
update

Modules specific Tcl commands¶

Modules v4 provides path element counting feature which increases a reference counter each time a given path entry is added to a given environment variable. As a consequence a path entry element is not always removed from a path-like variable when calling to remove-path or calling to append-path or append-path at unloading time. The path element is removed only if its related element counter is equal to 1. If this counter is greater than 1, path element is kept in variable and reference counter is decreased by 1.

On Modules v4, module-info mode returns during an unload sub-command the unload value instead of remove on Modules v3.2. However if mode is tested against remove value, true will be returned. During a switch sub-command on Modules v4, unload then load is returned instead of switch1 then switch2 then switch3 on Modules v3.2. However if mode is tested against switch value, true will be returned.

When using set-alias, Modules v3.2 defines a shell function when variables are in use in alias value on Bourne shell derivatives, Modules 4 always defines a shell alias never a shell function.

Some Modules specific Tcl commands are not supported anymore on v4.0. When still using them, a warning message is displayed and these unsupported Tcl commands are ignored. Following Modules specific Tcl commands are concerned:

module-info flags
module-info trace
module-info tracepat
module-info user
module-log
module-trace
module-user
module-verbosity

module¶

SYNOPSIS¶

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

DESCRIPTION¶

module is a user interface to the Modules package. The Modules package provides for the dynamic modification of the user’s environment via modulefiles.

Each modulefile contains the information needed to configure the shell for an application. Once the Modules package is initialized, the environment can be modified on a per-module basis using the module command which interprets modulefiles. Typically modulefiles instruct the module command to alter or set shell environment variables such as PATH, MANPATH, etc. Modulefiles may be shared by many users on a system and users may have their own set to supplement or replace the shared modulefiles.

The modulefiles are added to and removed from the current environment by the user. The environment changes contained in a modulefile can be summarized through the module command as well. If no arguments are given, a summary of the module usage and sub-commands are shown.

The action for the module command to take is described by the sub-command and its associated arguments.

Package Initialization¶

The Modules package and the module command are initialized when a shell-specific initialization script is sourced into the shell. The script creates the module command as either an alias or function and creates Modules environment variables.

The module alias or function executes the modulecmd.tcl program located in /usr/share/Modules/libexec and has the shell evaluate the command’s output. The first argument to modulecmd.tcl specifies the type of shell.

The initialization scripts are kept in /usr/share/Modules/init/<shell> where <shell> is the name of the sourcing shell. For example, a C Shell user sources the /usr/share/Modules/init/csh script. The sh, csh, tcsh, bash, ksh, zsh and fish shells are supported by modulecmd.tcl. In addition, python, perl, ruby, tcl, cmake, r and lisp “shells” are supported which writes the environment changes to stdout as python, perl, ruby, tcl, lisp, r or cmake code.

Initialization may also be performed by calling the autoinit sub-command of the modulecmd.tcl program. Evaluation into the shell of the result of this command defines the module alias or function.

Examples of initialization¶

C Shell initialization (and derivatives):

source /usr/share/Modules/init/csh
module load modulefile modulefile ...

Bourne Shell (sh) (and derivatives):

. /usr/share/Modules/init/sh
module load modulefile modulefile ...

Perl:

require "/usr/share/Modules/init/perl.pm";
&module("load modulefile modulefile ...");

Python:

import os
exec(open('/usr/share/Modules/init/python.py').read())
module('load modulefile modulefile ...')

Bourne Shell (sh) (and derivatives) with autoinit sub-command:

eval "`/usr/share/Modules/libexec/modulecmd.tcl sh autoinit`"

Modulecmd startup¶

Upon invocation modulecmd.tcl sources if it exists a site-specific configuration script located in /usr/share/Modules/etc/siteconfig.tcl. This Tcl script enables to supersede any global variable or procedure definition of modulecmd.tcl.

Afterward, modulecmd.tcl sources rc files which contain global, user and modulefile specific setups. These files are interpreted as modulefiles. See modulefile for detailed information.

Upon invocation of modulecmd.tcl module run-command files are sourced in the following order:

Global RC file as specified by $MODULERCFILE or /usr/share/Modules/etc/rc. If $MODULERCFILE points to a directory, the modulerc file in this directory is used as global RC file.
User specific module RC file $HOME/.modulerc
All .modulerc and .version files found during modulefile seeking.

Command line switches¶

The module command accepts command line switches as its first parameter. These may be used to control output format of all information displayed and the module behavior in case of locating and interpreting modulefiles.

All switches may be entered either in short or long notation. The following switches are accepted:

–help, -h

Give some helpful usage information, and terminates the command.

–version, -V

Lists the current version of the module command. The command then terminates without further processing.

–debug, -D

Debug mode. Causes module to print debugging messages about its progress.

–paginate

Pipe all message output into less (or if set, $MODULES_PAGER) if error output stream is a terminal. See also MODULES_PAGER section.

–no-pager

Do not pipe message output into a pager.

–terse, -t

Display avail, list and savelist output in short format.

–long, -l

Display avail, list and savelist output in long format.

–default, -d

On avail sub-command, display only the default version of each module name. Default version is either the explicitly set default version or the highest numerically sorted modulefile if no default version set (see Locating Modulefiles section in the modulefile man page).

–latest, -L

On avail sub-command, display only the highest numerically sorted version of each module name (see Locating Modulefiles section in the modulefile man page).

Module Sub-Commands¶

help [modulefile…]

Print the usage of each sub-command. If an argument is given, print the Module-specific help information for the modulefile.

add modulefile…

See load.

load modulefile…

Load modulefile into the shell environment.

rm modulefile…

See unload.

unload modulefile…

Remove modulefile from the shell environment.

swap [modulefile1] modulefile2

See switch.

switch [modulefile1] modulefile2

Switch loaded modulefile1 with modulefile2. If modulefile1 is not specified, then it is assumed to be the currently loaded module with the same root name as modulefile2.

show modulefile…

See display.

display modulefile…

Display information about one or more modulefiles. The display sub-command will list the full path of the modulefile and the environment changes the modulefile will make if loaded. (Note: It will not display any environment changes found within conditional statements.)

list [-t|-l]

List loaded modules.

avail [-d|-L] [-t|-l] [path…]

List all available modulefiles in the current MODULEPATH. All directories in the MODULEPATH are recursively searched for files containing the modulefile magic cookie. If an argument is given, then each directory in the MODULEPATH is searched for modulefiles whose pathname, symbolic version-name or alias match the argument. Argument may contain wildcard characters. Multiple versions of an application can be supported by creating a subdirectory for the application containing modulefiles for each version.

Symbolic version-names and aliases found in the search are displayed in the result of this sub-command. Symbolic version-names are displayed next to the modulefile they are assigned to within parenthesis. Aliases are listed in the MODULEPATH section where they have been defined. To distinguish aliases from modulefiles a @ symbol is added within parenthesis next to their name. Aliases defined through a global or user specific module RC file are listed under the global/user modulerc section.

aliases

List all available symbolic version-names and aliases in the current MODULEPATH. All directories in the MODULEPATH are recursively searched in the same manner than for the avail sub-command. Only the symbolic version-names and aliases found in the search are displayed.

use [-a|–append] directory…

Prepend one or more directories to the MODULEPATH environment variable. The –append flag will append the directory to MODULEPATH.

Reference counter environment variable MODULEPATH_modshare is also set to increase the number of times directory has been added to MODULEPATH.

unuse directory…

Remove one or more directories from the MODULEPATH environment variable if reference counter of these directories is equal to 1 or unknown.

Reference counter of directory in MODULEPATH denotes the number of times directory has been enabled. When attempting to remove directory from MODULEPATH, reference counter variable MODULEPATH_modshare is checked and directory is removed only if its relative counter is equal to 1 or not defined. Elsewhere directory is kept and reference counter is decreased by 1.

refresh

See reload.

reload

Unload then load all loaded modulefiles.

purge

Unload all loaded modulefiles.

source modulefile…

Execute modulefile into the shell environment. modulefile must be specified with a fully qualified path. Once executed modulefile is not marked loaded in shell environment which differ from load sub-command.

whatis [modulefile…]

Display the information set up by the module-whatis commands inside the specified modulefiles. These specified modulefiles may be expressed using wildcard characters. If no modulefile is specified, all module-whatis lines will be shown.

apropos string

See search.

keyword string

See search.

search string

Seeks through the module-whatis informations of all modulefiles for the specified string. All module-whatis informations matching the string will be displayed. string may contain wildcard characters.

test modulefile…

Execute and display results of the Module-specific tests for the modulefile.

save [collection]

Record the currently set MODULEPATH directory list and the currently loaded modulefiles in a collection file under the user’s collection directory $HOME/.module. If collection name is not specified, then it is assumed to be the default collection. If collection is a fully qualified path, it is saved at this location rather than under the user’s collection directory.

If MODULES_COLLECTION_TARGET is set, a suffix equivalent to the value of this variable will be appended to the collection file name.

By default, if loaded modulefile corresponds to the default module version, the bare module name is recorded. If MODULES_COLLECTION_PIN_VERSION is set to 1, module version is always recorded even if it is the default version.

restore [collection]

Restore the environment state as defined in collection. If collection name is not specified, then it is assumed to be the default collection. If collection is a fully qualified path, it is restored from this location rather than from a file under the user’s collection directory. If MODULES_COLLECTION_TARGET is set, a suffix equivalent to the value of this variable is appended to the collection file name to restore.

When restoring a collection, the currently set MODULEPATH directory list and the currently loaded modulefiles are unused and unloaded then used and loaded to exactly match the MODULEPATH and loaded modulefiles lists saved in this collection file. The order of the paths and modulefiles set in collection is preserved when restoring. It means that currently loaded modules are unloaded to get the same LOADEDMODULES root than collection and currently used module paths are unused to get the same MODULEPATH root. Then missing module paths are used and missing modulefiles are loaded.

saverm [collection]

Delete the collection file under the user’s collection directory. If collection name is not specified, then it is assumed to be the default collection. If MODULES_COLLECTION_TARGET is set, a suffix equivalent to the value of this variable will be appended to the collection file name.

saveshow [collection]

Display the content of collection. If collection name is not specified, then it is assumed to be the default collection. If collection is a fully qualified path, this location is displayed rather than a collection file under the user’s collection directory. If MODULES_COLLECTION_TARGET is set, a suffix equivalent to the value of this variable will be appended to the collection file name.

savelist [-t|-l]

List collections that are currently saved under the user’s collection directory. If MODULES_COLLECTION_TARGET is set, only collections matching the target suffix will be displayed.

initadd modulefile…

Add modulefile to the shell’s initialization file in the user’s home directory. The startup files checked (in order) are:

C Shell

.modules, .cshrc, .csh_variables and .login

TENEX C Shell

.modules, .tcshrc, .cshrc, .csh_variables and .login

Bourne and Korn Shells

.modules, .profile

GNU Bourne Again Shell

.modules, .bash_profile, .bash_login, .profile and .bashrc

Z Shell

.modules, .zshrc, .zshenv and .zlogin

Friendly Interactive Shell

.modules, .config/fish/config.fish

If a module load line is found in any of these files, the modulefiles are appended to any existing list of modulefiles. The module load line must be located in at least one of the files listed above for any of the init sub-commands to work properly. If the module load line is found in multiple shell initialization files, all of the lines are changed.

initprepend modulefile…

Does the same as initadd but prepends the given modules to the beginning of the list.

initrm modulefile…

Remove modulefile from the shell’s initialization files.

initswitch modulefile1 modulefile2

Switch modulefile1 with modulefile2 in the shell’s initialization files.

initlist

List all of the modulefiles loaded from the shell’s initialization file.

initclear

Clear all of the modulefiles from the shell’s initialization files.

path modulefile

Print path to modulefile.

paths modulefile

Print path of available modulefiles matching argument.

append-path [-d C|–delim C|–delim=C] [–duplicates] variable value…

Append value to environment variable. The variable is a colon, or delimiter, separated list. See append-path in the modulefile man page for further explanation.

prepend-path [-d C|–delim C|–delim=C] [–duplicates] variable value…

Prepend value to environment variable. The variable is a colon, or delimiter, separated list. See prepend-path in the modulefile man page for further explanation.

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

Remove value from the colon, or delimiter, separated list in environment variable. See remove-path in the modulefile man page for further explanation.

is-loaded [modulefile…]

Returns a true value if any of the listed modulefiles has been loaded or if any modulefile is loaded in case no argument is provided. Returns a false value elsewhere. See is-loaded in the modulefile man page for further explanation.

is-saved [collection…]

Returns a true value if any of the listed collections exists or if any collection exists in case no argument is provided. Returns a false value elsewhere. See is-saved in the modulefile man page for further explanation.

is-used [directory…]

Returns a true value if any of the listed directories has been enabled in MODULEPATH or if any directory is enabled in case no argument is provided. Returns a false value elsewhere. See is-used in the modulefile man page for further explanation.

is-avail modulefile…

Returns a true value if any of the listed modulefiles exists in enabled MODULEPATH. Returns a false value elsewhere. See is-avail in the modulefile man page for further explanation.

info-loaded modulefile

Returns the names of currently loaded modules matching passed modulefile. Returns an empty string if passed modulefile does not match any loaded modules. See module-info loaded in the modulefile man page for further explanation.

Modulefiles¶

modulefiles are written in the Tool Command Language (Tcl) and are interpreted by modulecmd.tcl. modulefiles can use conditional statements. Thus the effect a modulefile will have on the environment may change depending upon the current state of the environment.

Environment variables are unset when unloading a modulefile. Thus, it is possible to load a modulefile and then unload it without having the environment variables return to their prior state.

Collections¶

Collections describe a sequence of module use then module load commands that are interpreted by modulecmd.tcl to set the user environment as described by this sequence. When a collection is activated, with the restore sub-command, module paths and loaded modules are unused or unloaded if they are not part or if they are not ordered the same way as in the collection.

Collections are generated by the save sub-command that dumps the current user environment state in terms of module paths and loaded modules. By default collections are saved under the $HOME/.module directory.

Collections may be valid for a given target if they are suffixed. In this case these collections can only be restored if their suffix correspond to the current value of the MODULES_COLLECTION_TARGET environment variable (see the dedicated section of this topic below).

EXIT STATUS¶

The module command exits with 0 if its execution succeed. Elsewhere 1 is returned.

ENVIRONMENT¶

LOADEDMODULES

A colon separated list of all loaded modulefiles.

MODULEPATH

The path that the module command searches when looking for modulefiles. Typically, it is set to the master modulefiles directory, /usr/share/Modules/modulefiles, by the initialization script. MODULEPATH can be set using module use or by the module initialization script to search group or personal modulefile directories before or after the master modulefile directory.

Path elements registered in the MODULEPATH environment variable may contain reference to environment variables which are converted to their corresponding value by module command each time it looks at the MODULEPATH value. If an environment variable referred in a path element is not defined, its reference is converted to an empty string.

MODULESHOME

The location of the master Modules package file directory containing module command initialization scripts, the executable program modulecmd.tcl, and a directory containing a collection of master modulefiles.

MODULES_CMD

The location of the active module command script.

MODULES_COLLECTION_PIN_VERSION

If set to 1, register exact version number of modulefiles when saving a collection. Elsewhere modulefile version number is omitted if it corresponds to the implicit or explicitly set default version.

MODULES_COLLECTION_TARGET

The collection target that determines what collections are valid thus reachable on the current system.

Collection directory may sometimes be shared on multiple machines which may use different modules setup. For instance modules users may access with the same HOME directory multiple systems using different OS versions. When it happens a collection made on machine 1 may be erroneous on machine 2.

When a target is set, only the collections made for that target are available to the restore, savelist, saveshow and saverm sub-commands. Saving collection registers the target footprint by suffixing the collection filename with .$MODULES_COLLECTION_TARGET. Collection target is not involved when collection is specified as file path on the saveshow, restore and save sub-commands.

For example, the MODULES_COLLECTION_TARGET variable may be set with results from commands like lsb_release, hostname, dnsdomainname, etc.

MODULES_PAGER

Text viewer for use to paginate message output if error output stream is attached to a terminal. The value of this variable is composed of a pager command name or path eventually followed by command-line options.

Paging command and options are defined for Modules in the following order of preference: MODULES_PAGER environment variable, then the default set in modulecmd.tcl script configuration. Which means MODULES_PAGER overrides default configuration.

If MODULES_PAGER variable is set to an empty string or to the value cat, pager will not be launched.

MODULES_RUNENV_<VAR>

Value to set to environment variable <VAR> for modulecmd.tcl run-time execution if <VAR> is referred in MODULES_RUN_QUARANTINE.

MODULES_RUN_QUARANTINE

A space separated list of environment variable names that should be passed indirectly to modulecmd.tcl to protect its run-time environment from side-effect coming from their current definition.

Each variable found in MODULES_RUN_QUARANTINE will have its value emptied or set to the value of the corresponding MODULES_RUNENV_<VAR> variable when defining modulecmd.tcl run-time environment.

Original values of these environment variables set in quarantine are passed to modulecmd.tcl via <VAR>_modquar variables.

MODULES_SILENT_SHELL_DEBUG

If set to 1, disable any xtrace or verbose debugging property set on current shell session for the duration of either the module command or the module shell initialization script. Only applies to Bourne Shell (sh) and its derivatives.

MODULES_USE_COMPAT_VERSION

If set to 1 prior to Modules package initialization, enable Modules compatibility version (3.2 release branch) rather main version at initialization scripts running time. Modules package compatibility version should be installed along with main version for this environment variable to have any effect.

_LMFILES_

A colon separated list of the full pathname for all loaded modulefiles.

<VAR>_modquar

Value of environment variable <VAR> passed to modulecmd.tcl in order to restore <VAR> to this value once started.

<VAR>_modshare

Reference counter variable for path-like variable <VAR>. A colon separated list containing pairs of elements. A pair is formed by a path element followed its usage counter which represents the number of times this path has been enabled in variable <VAR>. A colon separates the two parts of the pair.

FILES¶

/usr/share/Modules

The MODULESHOME directory.

/usr/share/Modules/etc/rc

The system-wide modules rc file. The location of this file can be changed using the MODULERCFILE environment variable as described above.

$HOME/.modulerc

The user specific modules rc file.

$HOME/.module

The user specific collection directory.

/usr/share/Modules/modulefiles

The directory for system-wide modulefiles. The location of the directory can be changed using the MODULEPATH environment variable as described above.

/usr/share/Modules/libexec/modulecmd.tcl

The modulefile interpreter that gets executed upon each invocation of module.

/usr/share/Modules/init/<shell>

The Modules package initialization file sourced into the user’s environment.

modulefile¶

DESCRIPTION¶

modulefiles are written in the Tool Command Language, Tcl(n) and are interpreted by the modulecmd.tcl program via the module 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.tcl 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.tcl.

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 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 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.

break

This is not a Modules-specific command, it’s actually part of Tcl, which has been overloaded similar to the continue and exit 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 break command will only have this effect if not used within a Tcl loop though.

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

chdir directory

Set the current working directory to directory.

continue

This is not a modules specific command but another overloaded Tcl command and is similar to the break or exit 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 continue command will only have this effect if not used within a Tcl loop though.

exit [N]

This is not a modules specific command but another overloaded Tcl command and is similar to the break or continue 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.

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.

getenv variable

Returns value of environment variable. If variable is not defined _UNDEFINED_ is returned. getenv command should be preferred over Tcl global variable env to query environment variables.

append-path [-d C|–delim C|–delim=C] [–duplicates] variable value…

See prepend-path.

prepend-path [-d C|–delim C|–delim=C] [–duplicates] variable value…

Append or prepend value to environment variable. The variable is a colon, or delimiter, separated list such as PATH=directory:directory:directory. The default delimiter is a colon ‘:’, but an arbitrary one can be given by the –delim option. For example a space can be used instead (which will need to be handled in the Tcl specially by enclosing it in ” ” or { }). A space, however, can not be specified by the –delim=C form.

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.

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

Remove value from the colon, or delimiter, separated list in variable. See prepend-path or append-path for further explanation of using an arbitrary delimiter. Every string between colons, or delimiters, in variable is compared to value. If the two match, value is removed from variable if its reference counter is equal to 1 or unknown.

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. Elsewhere 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.

prereq modulefile…

See conflict.

conflict 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 loaded. Similarly, the conflict command lists modulefiles which conflict with the current modulefile. If a list contains more than one modulefile, then each member of the list acts as a Boolean OR operation. Multiple prereq and conflict 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 modulefile makes no changes to the user’s environment.

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.

is-loaded [modulefile…]

The is-loaded command returns a true value if any of the listed modulefiles has been loaded or if any modulefile is loaded in case no argument is provided. 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.

is-saved [collection…]

The is-saved command returns a true value if any of the listed collections exists or if any collection exists in case no argument is provided. If a list contains more than one collection, then each member acts as a boolean OR operation.

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.

is-used [directory…]

The is-used command returns a true value if any of the listed directories has been enabled in MODULEPATH or if any directory is enabled in case no argument is provided. If a list contains more than one directory, then each member acts as a boolean OR operation.

is-avail modulefile…

The is-avail command returns a true value if any of the listed modulefiles exists in enabled MODULEPATH. If a list contains more than one modulefile, then each member acts as a boolean OR operation. If an argument for is-avail is a directory and a modulefile exists in the directory is-avail would return a true value.

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

Contains the same sub-commands as described in the module man page in the Module Sub-Commands section. This command permits a modulefile to load or unload 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.tcl program’s state. Some of the information is specific to the internals of modulecmd.tcl. option is the type of information to be provided, and info-args are any arguments needed.

module-info type

Returns either “C” or “Tcl” to indicate which module command is being executed, either the “C” version or the Tcl-only version, to allow the modulefile writer to handle any differences between the two.

module-info mode [modetype]

Returns the current modulecmd.tcl’s mode as a string if no modetype is given.

Returns 1 if modulecmd.tcl’s mode is modetype. modetype can be: load, unload, remove, switch, display, help, test or whatis.

module-info command [commandname]

Returns the currently running modulecmd.tcl’s command as a string if no commandname is given.

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 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 [shellname]

Return the current shell under which modulecmd.tcl was invoked if no shellname is given. The current shell is the first parameter of modulecmd.tcl, which is normally hidden by the module alias.

If a shellname is given, returns 1 if modulecmd.tcl’s current shell is shellname, returns 0 elsewhere. shellname can be: sh, bash, ksh, zsh, csh, tcsh, fish, tcl, perl, python, ruby, lisp, cmake, r.

module-info shelltype [shelltypename]

Return the family of the shell under which modulefile was invoked if no shelltypename is given. As of module-info shell this depends on the first parameter of modulecmd.tcl. The output reflects a shell type determining the shell syntax of the commands produced by modulecmd.tcl.

If a shelltypename is given, returns 1 if modulecmd.tcl’s current shell type is shelltypename, returns 0 elsewhere. shelltypename can be: sh, csh, fish, tcl, perl, python, ruby, lisp, cmake, r.

module-info alias name

Returns the full modulefile name to which the modulefile alias name is assigned

module-info version modulefile

Returns the physical module name and version of the passed symbolic version modulefile. The parameter modulefile might either be a full qualified modulefile with name and version, another symbolic modulefile name or a modulefile alias.

module-info symbols modulefile

Returns a list of all symbolic versions assigned to the passed modulefile. The parameter modulefile might either be a full qualified modulefile with name and version, another symbolic modulefile name or a modulefile alias.

module-info loaded modulefile

Returns the names of currently loaded modules matching passed modulefile. The parameter modulefile might either be a full qualified modulefile with name and version or just a directory which in case all loaded modulefiles from the directory will be returned.

module-version modulefile version-name…

Assigns the symbolic version-name to the modulefile. This command should be placed in one of the modulecmd.tcl rc files in order to provide shorthand invocations of frequently used modulefile names.

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 fully or partially qualified modulefile with name / version. If name is ‘.’ then the current directory name is assumed to be the module name. (Use this for deep modulefile directories.)

a symbolic modulefile name

another modulefile alias

module-alias name modulefile

Assigns the modulefile to the alias name. This command should be placed in one of the modulecmd.tcl rc files in order to provide shorthand invocations of frequently used modulefile names.

The parameter modulefile may be either

a fully qualified modulefile with name and version

a symbolic modulefile name

another modulefile alias

module-virtual name modulefile

Assigns the modulefile to the virtual module name. This command should be placed in rc files in order to define virtual modules.

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.

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.tcl.

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. For some shells, aliases are not possible and the command has no effect. 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.

system string

Pass string to the Tcl built-in command exec(n). For the exec(n) call modulecmd.tcl 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 lookup of system information. Most field information are retrieved from the tcl_platform array (see tclvars(n) man page). Uname will return the string “unknown” if information is unavailable for the field.

uname will invoke 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:

sysname: the operating system name

nodename: the hostname

domain: the name of the domain

release: the operating system release

version: the operating system version

machine: a standard name that identifies the system’s hardware

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 filename. If the argument isn’t a valid file name, then string will be interpreted as a resource. Either filename or resource-string is then passed down to be xrdb(1) command.

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

The content of the Ileaf file 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.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 is 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 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 Tcl interpreted. 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, 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 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.

A modulefile whose name or element in its name starts with a ‘.’ dot is considered hidden. Hidden modulefile is not displayed or taken into account except if it is explicitly named. By inheritance, a symbolic version-name assigned to a hidden modulefile is displayed or taken into account only if explicitly named. Module alias targeting a hidden modulefile appears like any other module alias.

Modulefile Specific Help¶

Users can request help about a specific modulefile through the module 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 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.

ENVIRONMENT¶

MODULEPATH

Path of directories containing modulefiles.

NOTES¶

Tcl was developed by John Ousterhout at the University of California at Berkeley.

TclX was developed by Karl Lehenbauer and Mark Diekhans.

Differences between versions 3.2 and 4¶

This document lists functionality differences between Modules version 3.2 and Modules version 4. Modules version 3.2 is also referred in this document as compatibility version whereas Modules version 4 is also referred as new main version. Modules version 4 is based on what was previously called Modules-Tcl. The goal of this document is to reference the features of the compatibility version that are missing or behave differently on the new main version and the features that can only be found on this new version.

First part the of the document covers the features that are missing or that behave differently on Modules 4 than on compatibility version. The second part of the document covers the features that are specific to the Modules 4 version thus missing on compatibility version. Comparison takes as a basis version 3.2.10 of compatibility version against Modules version 4.0. Any change made past these versions will explicitly mention the release number starting from the difference appears or disappears.

Regarding missing features, this document only lists their name or the command line argument related to them. Please refer to the module and the modulefile man pages of the compatibility or main version to learn the details about these features.

Features missing or with different behavior than compatibility version¶

This section describes the features of the compatibility version that are not supported or that behave differently on Modules 4.

Package Initialization¶

MODULESBEGINENV environment snapshot functionality is not supported on version 4. Modules collection mechanism should be preferred to save and restore sets of enabled modulepaths and loaded modulefiles. Modules 4 also introduce a system configuration file etc/modulerc, located in Modules installation directory. This modulerc file is sourced by Modules shell initialization scripts and helps to setup the initial environment right after initializing the module command.

Command line switches¶

–force, -f

–human

–verbose, -v

–silent, -s

–create, -c

–icase, -i

–userlvl lvl, -u lvl

These command line switches are not supported on Modules 4. When these options are passed on the command-line, it produces an Unsupported option warning and command is ran with the unsupported switches ignored.

–ter

–lon

These intermediate-form command line switches are not supported on Modules 4. Short or long switch name should be used instead.

-h

This command line switch is short version of –help switch on Modules 4 whereas it is short version of –human switch on compatibility version.

Module Sub-Commands¶

On compatibility version, paths composing the MODULEPATH environment variable may contain reference to environment variable. These variable references are resolved dynamically when MODULEPATH is looked at during module sub-command action like avail. This feature was missing on Modules 4.0 but it has been re-introduced on Modules 4.1.

clear

update

These module sub-commands are not supported on Modules 4.

refresh

On compatibility version, only the shell aliases defined by the currently loaded modulefiles are set again on a refresh command. Whereas on new main version this command is an alias on the reload command that unload then load all the currently loaded modulefiles.

help

Compatibility version redirects output made on stdout in ModulesHelp Tcl procedure to stderr.

During an help sub-command, only the ModulesHelp Tcl procedure of a modulefile is interpreted on compatibility version. Version 4 interprets all the content of the modulefile, then call the ModulesHelp procedure if it exists.

On version 4, ModulesHelp subroutine is not ran if an error occurred during the interpretation of the modulefile main body.

display

On version 4, ModulesDisplay subroutine is not ran if an error occurred during the interpretation of the modulefile main body.

avail

On compatibility version, the same Tcl interpreter is used for the interpretation of all .modulerc or .version files during an avail command but the state of this interpreter is not reset between each interpretation. So some variable and procedure definitions may spread from one interpretation to another on this compatibility version. Modules 4 reuses the same interpreter for all .modulerc or .version interpretation but it is cleaned between each interpretation to protect from definition spread.

In case of –terse or –long mode, all enabled modulepaths will be displayed whether they hold result to display or not. Modules 4 outputs only the modulepaths where matching results are found. Modulepaths with no result to report are discarded from output.

apropos

On Modules 4, string passed as argument is always searched in a case insensitive manner.

load

On Modules 4, the value of an environment variable is set even if the new value is the same as the current value of this variable in environment.

When an already loaded modulefiles is asked for load again, compatibility version will refresh the shell alias definition this modulefile hold if any, whereas Modules 4 will ignore the new load order.

In case of modulefile loading another modulefile, if sub-modulefile load fails calling modulefile will still be loaded on compatibility version whereas Modules 4 will also abort calling modulefile load.

Starting with version 4.1, content sent to the stdout channel during a modulefile interpretation is spooled to effectively transmit this content to stdout after rendering the environment changes made by this modulefile.

unload

On Modules 4, the value of an environment variable is set even if the new value is the same as the current value of this variable in environment.

Compatibility version enables to load a modulefile by passing on the command-line the name of a module alias or symbolic version pointing to this modulefile. However this module alias or symbolic version name cannot be used to unload the modulefile once loaded. Modules 4 enables to pass a module alias or symbolic version name to unload a loaded modulefile referred by this name.

Starting with version 4.1, content sent to the stdout channel during a modulefile interpretation is spooled to effectively transmit this content to stdout after rendering the environment changes made by this modulefile.

switch

When switching on version 4 an old modulefile by a new one, no error is raised if old modulefile is not currently loaded. In this situation compatibility version throws an error and abort switch action.

When switching on Modules 4 an old modulefile by a new one, this new modulefile does not keep the position that the old modulefile had in the LOADEDMODULES list as done on compatibility version but it is appended to the end of the list. Same goes for PATH-like environment variables: replaced PATH component is appended to the end or prepended to the beginning of the relative PATH-like variable, not appended or prepended relatively to the position hold by the swapped PATH component.

When a modulefile loads another modulefile with a module load order, this sub-module is not unloaded when the top modulefile is swapped-out during a switch command on compatibility version. Version 4 interprets the swapped-out modulefile in unload mode, so the module load order is interpreted as module unload order and sub-module is unloaded.

use

When the modulepath to enable is passed as a relative path, compatibility version will set it using passed relative name whereas Modules 4 will determine the corresponding absolute path and will register it rather passed relative name.

unuse

Modules 4 provides path element counting feature which increases a reference counter each time a given path entry is added to a given environment variable. This feature also applies to the MODULEPATH environment variable. As consequence a modulepath entry element is removed from the modulepath enabled list only if the related element counter is equal to 1. When unusing a modulepath if its reference counter is greater than 1, modulepath is kept enabled and reference counter is decreased by 1.

initadd

initprepend

initswitch

On version 4 no message is displayed to give details on how list of modulefiles to load has been altered in initialization file.

initrm

No message is displayed on Modules 4 to inform of the modulefiles that have been removed from the loading list in initialization file.

Empty module load line is left on version 4 when last modulefile from a line is asked to be removed. On compatibility version module load null line is set in this case.

initclear

Empty module load lines are left on version 4 whereas module load null lines are set on compatibility version.

Modules Specific Tcl Commands¶

append-path

prepend-path

Modules 4 produces an error when adding a bare colon character : as a path element to a path-like variable, as this colon cannot be distinguished from the colon used for path separator.

Modules 4 supports adding or removing empty path element to a path-like variable, whereas compatibility version looses track of this path element when the path-like variable is modified afterward. Empty path element enables to set a leading colon character :, which has a specific meaning on some regular environment variable like MANPATH or LD_LIBRARY_PATH.

When adding a path element to the MANPATH environment variable, Modules 4 is treating this variable like any other whereas a special treatment was applied on compatibility version: a default MANPATH value, set at configure time, was appended in case MANPATH variable was unset.

remove-path

Modules 4 provides path element counting feature which increases a reference counter each time a given path entry is added to a given environment variable. As consequence a path entry element is removed from a path-like variable only if the related element counter is equal to 1. If this counter is greater than 1, path element is kept in variable and reference counter is decreased by 1.

exit

On Modules 4 code passed to the exit Modules specific Tcl command will not be thrown to be the module return value.

module-alias

module-version

In case the specified aliased module or the symbolic version introduces a resolution loop with already defined aliases or symbolic versions, this new alias or symbolic version is not registered and an error message is raised. On compatibility version, alias or symbolic version introducing loop are registered as the modulefile resolution is not computed at registration time.

module-info

module-info flags

module-info trace

module-info tracepat

module-info user

These module-info options are related to compatibility version-specific features so they are available on Modules 4 but with a dummy implementation that always returns false or an empty value.

module-info mode

During an unload sub-command, unload is returned instead of remove. However if mode is tested against remove value, true will be returned.

During a switch sub-command, unload then load is returned instead of switch1 then switch2 then switch3. However if mode is tested against switch value, true will be returned.

module-info version

Declared aliases or symbolic versions are not registered anymore if they introduce a resolution loop. As a result module-info version does not return an *undef* string value as it does not face resolution loop situation anymore.

module-info symbols

Declared aliases or symbolic versions are not registered anymore if they introduce a resolution loop. As a consequence symbolic versions introducing loop situation are not part anymore of the module-info symbols returned result as they are not registered.

A symbolic version sets on a module alias will be propagated toward the resolution path to also apply to the relative modulefile if it still correspond to the same module name.

module-log

module-trace

module-user

module-verbosity

These Modules specific Tcl commands are related to compatibility version-specific features so they are available on Modules 4 but with a dummy implementation that always displays a warning message saying the command is not implemented.

module-whatis

When multiple words are passed as argument to module-whatis but they are not enclosed in double-quotes or curly braces they will be displayed as a single line on Modules 4 whereas compatibility version displays them as one line per word.

set-alias

Whereas compatibility version sets a shell function when variables are in use in alias value on Bourne shell derivatives, Modules 4 always defines a shell alias never a shell function.

Locating Modulefiles¶

On version 4, when a module alias is set and overrides name of an existing directory, this alias is taken into account to locate the default version of this module name and the modulefiles locating in the directory are ignored.

When looking for an implicit default in a modulefile directory, aliases are taken into account in addition to modulefiles and directories to determine the highest numerically sorted element.

Modules 4 will resolve module alias or symbolic version passed to unload command to then remove the loaded modulefile pointed by the mentioned alias or symbolic version.

Modules 4 resolves module alias or symbolic version pointing to a modulefile located in another modulepath.

When locating modulefiles on Modules 4, 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. Access issue is also returned when a direct access is made to a module alias or a symbolic version targeting an unreadable modulefile.

Features specific to the new main version¶

This section describes the features of Modules version 4 that are not supported on the compatibility version. Please refer to the above section for features supported by both versions but behaving differently.

Package Initialization¶

Compatibility version does not support fish, lisp, tcl and R as code output.

On version 4 and for sh, bash, ksh, zsh and fish shells, text output, like listing from the avail command, is redirected from stderr to stdout after shell command evaluation if shell is in interactive mode. Starting version 4.1, this content redirection occurs if shell session is attached to a terminal.

Modulecmd startup¶

Starting with version 4.1, modulecmd.tcl sources upon invocation a site-specific configuration script named siteconfig.tcl. This Tcl script enables to supersede any global variable or procedure definition of modulecmd.tcl.

Command line switches¶

–debug, -D

–default, -d

–latest, -L

These command line switches are not supported on compatibility version.

–paginate

–no-pager

These command line switches appeared on version 4.1 and are not supported on compatibility version.

Module Sub-Commands¶

All module sub-commands will return a non-zero exit code in case of error whereas on compatibility version issues that occurred do not lead to an exit of the module command with a non-zero code.

Starting with version 4.1, module function for all scripting languages, like Perl or Python, always returns a value. In case of error, a false boolean value is returned instead of raising a fatal exception. For module sub-commands returning a text value, the module function will actually return this value. In all other cases a true boolean value is returned.

reload

source

search

save

restore

saverm

saveshow

savelist

path

paths

autoinit

aliases

test

These module sub-commands are not supported on compatibility version.

append-path

prepend-path

remove-path

is-loaded

is-saved

is-used

is-avail

info-loaded

These module sub-commands appeared on version 4.1 and are not supported on compatibility version.

avail

whatis

apropos

Non-critical errors are not displayed on these sub-commands. Only valid results are returned.

Module aliases are included in the result of these sub-commands. They are displayed in the module path section where they are defined or in a global/user modulerc section for aliases set in user’s or global modulerc file. A @ symbol is added in parenthesis next to their name to distinguish them from modulefiles.

Search may be performed with an alias or a symbolic version-name passed as argument.

Arguments to these avail, whatis and apropos commands may use wildcard characters to express glob patterns.

Collections¶

Modules collections are not supported on compatibility version.

Environment¶

MODULES_COLLECTION_TARGET

MODULES_USE_COMPAT_VERSION

<VAR>_modshare

These environment variables are not supported on compatibility version.

MODULES_CMD

MODULES_COLLECTION_PIN_VERSION

MODULES_PAGER

MODULES_RUNENV_<VAR>

MODULES_RUN_QUARANTINE

MODULES_SILENT_SHELL_DEBUG

<VAR>_modquar

These environment variables appeared on version 4.1 and are not supported on compatibility version.

Modules Specific Tcl Commands¶

module

In case of module load command specifying multiple modulefiles, when mode is set to unload these modulefiles will be unloaded in the reverse order to ensure correct handling of prerequisites.

module-info

module-info command

This module-info option is not supported on compatibility version.

module-info loaded

This module-info option appeared on version 4.1 and is not supported on compatibility version.

append-path

Starting with version 4.1, append-path handles being called with multiple value arguments and option --duplicates is added.

prepend-path

Starting with version 4.1, prepend-path handles being called with multiple value arguments and option --duplicates is added.

remove-path

Starting with version 4.1, remove-path handles being called with multiple value arguments and option --index is added.

is-loaded

Starting with version 4.1, is-loaded supports being called with no argument passed. In this case, it returns true if any modulefile is currently loaded, false elsewhere.

is-saved

is-used

is-avail

module-virtual

These Modules-specific Tcl commands appeared on version 4.1 and are not supported on compatibility version.

Frequently Asked Questions on Environment Modules¶

Module command¶

How does the `module` command work?¶

The command module is an alias for something like:

sh:

module ()
{
   eval `/some/path/modulecmd sh $*`
}

csh:

eval `/some/path/modulecmd csh !*`

Where the modulecmd outputs valid shell commands to stdout which manipulates the shell’s environment. Any text that is meant to be seen by the user must be sent to stderr. For example:

puts stderr "\n\tSome Text to Show\n"

I put the `module` command in a script and I run the script… it doesn’t change my environment?¶

A child process (script) can not change the parent process environment. A module load in a script only affects the environement for the script itself. The only way you can have a script change the current environment is to source the script which reads it into the current process.

sh:

. somescript

csh:

source somescript

How do I capture the module command output?¶

This ties in with the very first question. Since the module command is essentially an eval the visible output to the screen must necessarily be sent to stderr. It becomes a matter on how to capture output from stderr for the various shells. The following examples just show how to spool the output from the avail command to a file. This also works for the various other module commands like list, display, etc. There are also various tricks for piping stderr to another program.

sh:

module avail 2> spoolfile

csh: (overwrite existing file)

module avail >&! spoolfile

Modulefiles¶

I want the modulefile to source some rc script that came with some application¶

If you want to do this… you can, but that’s not what modules is all about. It is possible to have the modulefile output some text to stdout to source some script when loading. However, you lose the advantage of this tool, because you won’t be able to unload this environment. If you’re tempted to do this… don’t. However, you can craft a modulefile by capturing the environment variables created or changed by the rc script

env | sort > envbefore
. somescript
env | sort > envafter
diff envbefore envafter

Check out https://sourceforge.net/projects/env2/, which can translate the shell file into a modulefile and possibly reduce the amount of work needed to convert and maintain.

How do I specify the default modulefile for some modulefile directory?¶

Modules usually uses the the highest lexicographically sorted modulefile under the directory, unless there is a .version file in that directory which has a format like the following where “native” is a modulefile (or a sub-directory) in that directory. It’s also possible to set the default with a .modulerc file with a module-version command.

#%Module1.0#####################################################################
##
## version file for Perl
##
set ModulesVersion "native"

I don’t want a default modulefile for the directory?¶

Follow the same prescription as setting a default, but give some bogus value, say no_default. The module command will return an error message when no specific version is given.

Build Issues¶

The configure script complains about Tclx¶

...
checking for TclX configuration (tclxConfig.sh)... not found
checking for TclX version... using 8.4
checking TCLX_VERSION... 8.4
checking TCLX_LIB_SPEC... TCLX_LIB_SPEC not found, need to use --with-tclx-lib
checking TCLX_INCLUDE_SPEC... TCLX_INCLUDE_SPEC not found, need to use --with-tclx-inc
...

TclX is an optional library that can speed up some operations. You don’t need TclX for modules to compile and work, so you can add the –without-tclx option when configuring and it should proceed to completion. In fact, it should have succeeded anyways and just not attempt to use TclX.

Otherwise, you can load the TclX library package for your OS and the configure script should find it. If not then if you know where the tclxConfig.sh file or the library and include files are placed then use the following options:

--with-tclx=<dir>       directory containing TclX configuration
                        (tclxConfig.sh) [[searches]]
--with-tclx-ver=X.Y     TclX version to use [[search]]
--with-tclx-lib=<dir>   directory containing tclx libraries (libtclxX.Y)
                        [[none]]
--with-tclx-inc=<dir>   directory containing tclx include files
                        (tclExtend.h,...) [[none]]

Meta Information¶

Why does modules use Tcl?¶

The first versions of the Modules package used shell scripts to do its magic. The original authors then chose to implement the same in C to speed things up and to add features. At the time the only easily embeddable interpreter was Tcl which provided a standard language and the glue. Now that other interpreters are available they could be embedded, but haven’t so far. There is also a pure Tcl version available.

How can I help?¶

We can use help at various levels. The best way to contribute is to send in a patch file (see the FAQ on how to generate a patch file) with whatever fixes. The patch will be reviewed and tested. If you are a regular contributer then you’ll likely be invited to become a developer and to have direct source access, and the fame, power, and prestige that all entails.

How do I download the source repository?¶

Anonymously clone the git repository, view the list of branches, and set to a specific branch:

git clone git://git.code.sf.net/p/modules/git modules-myversion
cd modules-myversion
git branch -a
git checkout modules-3-X-Y
git status

How do I generate a patch file?¶

If you’re starting from a tarball¶

Unpack the tarball and it should place the sources into a directory named modules-3.X.Y , then rename the directory to modules-3.X.Y-myversion or something like that. Make whatever changes you want, and be sure to test the changes and if you can add tests to identify the bug and the fix… that will endear yourself to the developers.

Once you have the changes in your version, then unpack the original sources from the tarball in a directory side-by-side to the directory with your version, and at that parent level run the following diff command:

diff -u -r -P -N modules-3.X.Y modules-3.X.Y-myversion  > my.patch

If you’re starting from the git cloned repository:¶

From within the git repositories.

git diff > my.patch

Release notes¶

This file describes changes in recent versions of Modules. It primarily documents those changes that are of interest to users and admins.

Modules 4.1.4 (2018-08-20)¶

Doc: fix typo on getenv command description in modulefile(4) man page and clarify this command should be preferred over ::env variable to query environment variable value in modulefile.
Init: fix bash and zsh completion scripts to enable Extended Regular Expression (ERE) on sed command with -E argument (rather -r) for compatibility with OS X’s and BSDs’ sed. (fix issue#178)
Handle default version sets on an hidden modulefile (were not found previously). (fix issue#177)
Init: fix ksh initialization script for ksh88 compatibility. (fix issue#159)
Install: use sed command rather grep and cut in configure and Makefile scripts. (fix issue#175 with contribution from Michael Sternberg)
Fix typo, tab indentation and pipe opening mode on createmodule.py utility script. (contribution from Jan Synacek)
Check ModulesVersion value set from .version rc file to ensure this value refers to a version name in current directory. Report error if a nested value is detected and ignore this value. (fix issue#176)

Modules 4.1.3 (2018-06-18)¶

Make setenv command alter env Tcl global array during help, test or whatis evaluation modes. (fix issue#160)
Doc: describe MANPATH variable special treatment on compatibility version in diff_v3_v4 document.
Initialize and export _moduleraw SH shell function if stderr is attached to a terminal. Was previously checking stdout. (fix issue#169)
For csh shells, quote code generated by modulecmd.tcl to pass it to the eval shell command.
Escape special characters when producing code to define shell aliases (fix issue#165)
Correct modulefile lookup when a modulefile directory is overwritten by a module alias definition but it contains an empty sub-directory. (fix issue#170)
Doc: describe getenv command in modulefile(4) man page.
Improve SH shell detection in profile.sh initialization script to use shell variable on bash or zsh to determine current shell name. (fix issue#173)

Modules 4.1.2 (2018-03-31)¶

Add an example global rc file in contrib/etc directory that ensures MODULEPATH is always defined.
Check HOME environment variable is defined on savelist and is-saved commands or raise error if not.
Fix saving of deep module default version in collection when version pinning is disabled: if foo/bar/version is default version for foo, collection will retain just foo (was retaining foo/bar).
Enable to save and restore collections containing full path modulefiles eventually with no modulepath defined.
Run puts command not related to stderr or stdout channels in calling modulefile context to correctly get access to the targeted file channel. (fix issue#157)
Quote autoinit result for eval interpretation on SH-kind shells to avoid parameter expansion to randomly occur on generated code depending on file or directory names of current working directory. (fix RH bug#1549664)
Ignore empty elements found in MODULEPATH, LOADEDMODULES or _LMFILES_ to ensure all elements in these variables are non-empty strings.
Raise error if loaded environment is in an inconsistent state when calling commands requiring correlation of information from the LOADEDMODULES and the _LMFILES_ environment variables. Error raised on load, unload, switch, reload, purge, list, save and restore commands. May affect info-loaded or is-loaded commands if module passed as argument to these command is specified as a full path modulefile.
Fix list command to process loaded modules information before performing any content output.
Install: adapt configure script and Makefiles to support installation on Cygwin system.
Detect terminal width on Windows cmd terminal with mode command.
Improve Windows cmd shell support: error code returned, echoing text, shell alias creation and removal, working directory change.
Raise error when an empty module name is passed to module sub-commands like load, display or unload.
Raise error when an empty collection name is passed to module sub-commands like save, saveshow or restore.
Raise error when an empty path is passed to module unuse sub-command, like already done on use sub-command.
Clear argument list if an empty module command name is passed.
Fix module function definition for all shells in autoinit command to correctly handle empty-string parameters or parameters containing white-spaces, quotes, escape characters.
Fix module function definition for Python to accept being called with no argument.
Fix parameter expansion on module function for all SH-kind shells when quarantine mode is activated.
Escape \ character when producing R shell code.

Modules 4.1.1 (2018-02-17)¶

Make separator lines, used on display command result for instance, fit small screen width.
Install: give ability to build and install Modules from git repository without documentation if sphinx-build cannot be found.
Install: adapt configure script and Makefiles to support installation on FreeBSD, Solaris and OS X systems. (fix issue#147)
Rework code generated by autoinit for sh-kind shells to avoid use of local variables as those are defined differently through the sh variants. (also fix issue#147)
Init: use a default value on undefined variables in sh-kind scripts to avoid unbound variables in bash -eu mode. (fix issue#151)
Correctly detect terminal column number on Solaris.
Init: fix csh init script to get compatibility with pure csh shell
Sanitize content of MODULEPATH before using it at run-time, to make potential relative paths absolute, remove trailing slashes, etc. (fix issue#152)
Check loaded modulefiles still exists before displaying statistics on them during a list action.
Use a specific reference counter variable name (MODULES_MODSHARE_<VAR> instead of <VAR>_modshare) for DYLD-specific variables. (fix issue#153)
No error raise when updating a DYLD or LD path-like variable on OS X when System Integrity Protection (SIP) is enabled. In this situation, these variables are not exported in subshell context, so they appear undefined.
Init: protect arguments passed to the _moduleraw sh function from interfering content of current working directory. (fix issue#154)
Install: move hostname RPM requirement to the compat sub-package.
Start pager process only if some text has to be printed. (partially fix issue#146)
Ignore PAGER environment variable to configure Modules pager to avoid side effects coming from a general pager configuration not compatible with Modules pager handling. (fix issue#146)
Do not blank anymore default Modules pager options if default pager is less when the LESS environment variable is defined. (fix issue#146)

Warning

With this bugfix release, changes have been made on the pager setup to avoid side effects coming from the system general pager configuration. As a result PAGER environment variable is now ignored and MODULES_PAGER should be used instead to adapt Modules pager configuration at run-time.

Modules 4.1.0 (2018-01-15)¶

Extend stderr output redirection on sh-kind shells to all terminal-attached shell session, not only interactive shell session.
Extend shell code produced by the autoinit command to perform the same environment initialization as done in init shell scripts (default value set for module-specific environment variables, parse or source of configuration files).
Make init shell scripts rely on autoinit command to define the module command and setup its default environment.
Fix error rendering code for Tcl shell by producing a call to the error procedure.
Introduce pager support to handle informational messages, using less command with -eFKRX options by default. Environment variable MODULES_PAGER or PAGER may be used to supersede default pager command and options. --paginate and --no-pager switches enable or disable pager from the command line.
Install: add --with-pager and --with-pager-opts configure options to define default pager command and its relative command-line options.
Introduce quarantine mechanism to protect module execution against side effect coming from the current environment definition. Variables whose name has been put in MODULES_RUN_QUARANTINE will be emptied or set to the value hold by MODULES_RUNENV_<VAR> in the modulecmd.tcl run-time environment. Quarantine variable original value is then restored within modulecmd.tcl execution context once it has started.
Install: add --with-quarantine-vars configure option to define at build time the MODULES_RUN_QUARANTINE and MODULES_RUNENV_<VAR> environment variables set in initialization scripts.
Add MODULES_SILENT_SHELL_DEBUG environment variable to disable on sh shell and derivatives any xtrace or verbose debugging property for the duration of either the module command or the module shell initialization script. (fix issue#121)
Change error code produced by modulecmd.tcl for the Tcl, Perl, Python, Ruby, CMake and R scripting languages to return a ‘false’ boolean value in case of error rather raising a fatal exception.
Adapt module function definition for Tcl, Perl, Python, Ruby, CMake and R scripting languages to always return a value, result of the modulecmd.tcl run. When modulecmd.tcl run does not produce a specific status, a ‘true’ boolean value is returned. On CMake, resulting value is returned though a module_result global variable.
Spool content sent to the stdout channel with puts command during a modulefile interpretation, to effectively transmit this content to stdout after rendering the environment changes made by this modulefile. (fix issue#113)
Introduce append-path, prepend-path, remove-path and is-loaded module sub-commands, based on existing modulefile-specific Tcl commands. (fix issue#116)
Introduce is-saved, is-used and is-avail modulefile Tcl commands and module sub-commands to test availability of collection, modulepath or modulefile.
Raise error when a call to path or paths module sub-commands is attempted during a modulefile interpretation. Both commands now return text rather print text on scripting languages. An empty string is returned in no match case instead of a false boolean value.
Introduce module-info loaded modulefile command and its module sub-command counterpart info-loaded. This new command returns name of the modules currently loaded corresponding to the name passed as argument. (fix issue#3)
Fix is-loaded command to correctly handle multiple module names passed as argument (fix issue#138)
Support no argument on is-loaded, is-saved and is-used commands to return if anything is respectively loaded, saved or used.
Interpret module source command set in modulefile in unload mode when the modulefile itself is interpreted in this mode.
Consider a modulefile passed with name starting by ./ or ../ a full path name modulefile, like those starting by /. These kind of names are converted to absolute path names, for instance to register them in loaded modulefile list during a load command.
Correlate modulefile passed as full path name (starting by either ./, ../ or /) to already loaded modulefile registered with regular module name (file name without its modulepath prefix) to prevent for instance from loading twice same modulefile. Correlate in the same way regular module name to already loaded full path name modulefile.
Introduce MODULES_COLLECTION_PIN_VERSION environment variable to record modulefile version number when saving collections even if version corresponds to the default one. (fix issue#89)
Fix location of etc/rc global RC file to @prefix@/etc/rc instead of $MODULESHOME/etc/rc not to depend on MODULESHOME environment variable value.
Strengthen argument check for append-path, prepend-path and remove-path modulefile Tcl commands and module sub-commands. Raise error if argument list is not correct.
Fix support for the --delim=C argument form on append-path, prepend-path and remove-path commands.
Fix path reference counter handling in case path element is an empty string. Distinguish an empty path element from a variable set empty to clear it.
Pass multiple path elements separated by delimiter character as one string on append-path, prepend-path and remove-path commands.
Accept multiple path element arguments on append-path, prepend-path and remove-path commands.
Introduce the --duplicates argument option to append-path and prepend-path commands to add a path element already registered in variable.
Introduce the --index argument option to remove-path command to delete a path entry by passing its position index in variable.
Provide the ability to setup a site-specific configuration sourced at the start of modulecmd.tcl main procedure. This configuration is a Tcl script named siteconfig.tcl which enables to supersede any Tcl definition made in modulecmd.tcl. Location of this file is controlled at configure time with the --etcdir option.
Add the ability to handle paths containing reference to environment variable in MODULEPATH. When these kind of paths are used by module command, the variable references are converted to their corresponding value or to an empty string if they are not defined.
Enclose value set to environment variable on Tcl within curly braces rather double quotes to protect special characters in it from interpretation.
Correctly parse .modulespath initialization file to handle lines without any # character or to handle files with no content to extract.
Re-introduce the --enable-versioning configure option, which appends Modules version to installation prefix and deploy a versions modulepath shared between all versioning enabled Modules installation. A modulefile corresponding to Modules version is added to the shared modulepath and enables to switch from one Modules version to another.
Fix removal of CMake generated temporary script file by stripping newline character from script file name.
Add MODULES_CMD environment variable to expose path to the currently active module command script. This variable is set at initialization time.
Introduce modulecmd wrapper script, installed in binary directory, which executes the active module command.
Fix modulefile Tcl interpreter reset when handling list variables. (fix issue#145)
Introduce ‘module-virtual’ modulefile Tcl command to associate a virtual module name to a modulefile. This module can be located with its virtual name and the associated modulefile is the script interpreted when loading, unloading, etc.
Resolution of relative paths occurring during a modulefile interpretation to target a modulefile or a modulepath now takes the directory of the currently interpreted modulefile as the current working directory to solve the relative paths.

Modules 4.0.0 (2017-10-16)¶

Starting with this release, modules-tcl has become Modules. The following changes describe the differences with last modules-tcl release (1.923). To learn about the changes between this release and last Modules 3.2 release, please see the MIGRATING document.

Relax constraint on command-line argument position so options and switches can be passed either before or after command name.
Report unsupported option warning rather stop on error when compatibility-version specific command-line switches are passed ( --force, --human, --verbose, --silent, --create, --icase, --userlvl).
Keep empty module load line in shell configuration files after running the initrm or initclear commands.
Always return the value of tcl_platform(osVersion) for uname release
Optimize code output, for Perl to only return 1; once for a no-operation situation and for Python to not import os when there is only an error to render.
Use value of system command uname -n for uname nodename.
Add support for CMake shell
Ignore / character used as suffix in modulefile name passed on command line.
Rename Perl initialization script in perl.pm and Python in python.py.
Add support for Ruby shell (with contribution from Tammo Tjarks)
Add support for R shell (with contribution from Roy Storey)
When a default is set for a given module name, target modulefile can be referred on as modulename/default in addition to just modulename.
Locate symbolic versions on avail command even these symbols are set over a module alias or another symbolic version. In this situation the symbol spread along the resolution path until reaching a modulefile.
Define a more standard shebang on modulecmd.tcl script.
Determine modulefile corresponding to given module name using the loaded context only on unload situation.
Enable to unload mod/dir/subdir/vers when unload of mod or mod/dir asked. Was previously working only if deep module to unload was also the default version for these root names.
Make -l/-t switches mutually exclusive. Last switch mentioned on the command-line is honored.
Output parsable modulepath header when -l/-t switches are enabled.
When searching for a module in a given modulepath directory, if a module alias or a symbolic version matches searched module but the target of this alias or symbol is not found in current modulepath directory, search for this target restarting search from the first modulepath in list to ensure modulepath priority.
Solve aliases or symbolic versions looking for all modulepaths on search and paths commands. Was previously solved if their target was found in same modulepath directory.
Add support for hidden dot modulefiles. A hidden modulefile does not appear in case of wild search, it is only returned when search is about its exact name.
No table header print in –long mode on an avail command if no result are returned.
Add blank line between displayed list of elements, for instance between modulepath content on avail command.
Improve readability of error messages encountered during modulefile execution by putting Tcl error message first after the Module ERROR prefix.
Do not exit immediately when an internal error occurs in currently interpreted modulefile. Consider this interpretation as failed and continue to proceed the other modulefile arguments.
When multiple modulefiles are passed on display, help and test commands only output one separator line between 2 interpreted modulefiles.
Fix environment settings stack handling issue when restoring stack after a failed attempt to load a modulefile in a modulefile.
Failed attempt to load or unload a modulefile within a modulefile now leads to this upper modulefile load or unload failure. Previously upper modulefile were loaded respectively unloaded even if its dependent sub-modulefile failed to load or unload.
During a switch command, if the unloading part fails the loading part will not be tried. Unloading part fails if module to unload does not exist or its unload interpretation raise error.
Init: use module source rather shell command source to load modulerc system configuration in sh-kind, csh-kind and fish shell init scripts.
Install: transform configuration options to bind to an existing compatibility Modules version into option (–enable-compat-version) to build and install this compatibility version along with main version.
Init: adapt initialization scripts to handle both main and compatibility version. By default a shell script enables main version and if the environment variable MODULES_USE_COMPAT_VERSION is set to 1, the compatibility version is enabled instead of main version.
Install: import from compatibility version and install add.modules and mkroot utility scripts (scripts developed by R.K. Owen).
Install: update RPM spec file to handle compatibility version as a compat sub-package.
Add completion script for Fish shell (contribution from BEFH).
Doc: extend content of diff_v3_v4 to details all noticeable changes between v3.2 and v4.0.
Doc: introduce MIGRATING guide to learn the major changes when moving from v3.2 to v4.0.
Fix list command when full pathname modulefile is loaded (fix bug#132)
Install: handle version number though git tags in scripts, documentation and RPM spec file.
Doc: migrate documents from POD format to reStructuredText to benefit from Sphinx documentation framework and Read The Docs publishing capabilities.

Above changes describe the differences with modules-tcl release 1.923. To learn about the changes between Modules 4.0 and last Modules 3.2 release, please see the MIGRATING document.

modules-tcl-1.923 (2017-07-20)¶

Fix aliases command when a global or user RC file is set.
Find and solve global or user RC aliases and symbolic versions on search, whatis and paths commands.
Do not look at currently loaded modules to resolve the target of a module alias.
Rework default and latest versions search on avail command. Correct display when at a given level a sub-directory element is last element in directory among modulefiles. Previously sub-directory was printed but last file among modulefiles was also printed (2 latest versions at the same level). A directory tagged “default” does not appear anymore in default listing result as its content (the default version found in that directory) will be displayed.
When an alias is set and overrides name of an existing directory, take this alias into account for default and latest choice and ignore directory content.
Bad default set will lead to no result displayed for the corresponding module in case of default avail display.
Correct inclusion of aliases in output result when these aliases are not part of the exact same module path than module path of the search.
Rewrite existing shell initialization file with initadd, initprepend, initswitch, initrm and initclear commands rather than writing a new file then copying this new file to replace the existing initialization file. In addition only re-writes shell initialization file if its content need to be altered.
Raise an error on initadd, initprepend, initswitch, initrm and initclear commands when no module load line are found in shell initialization file.
Normalize error messages for the various collection-related commands when collection cannot be accessed.
Cleanup existing reference counters of a path list variable when this variable is altered by a setenv or an unsetenv command.
Init: do not pollute tab-completion with moduleraw command. (Bert Wesarg)
Make use of the same Tcl interp for each modulefile interpretation and use another one for each modulerc (but the same for each modulerc). By doing so we proceed like on C-version where same interpreter is used across modulefile or modulerc interpretation. Huge performance improvement is achieved with this change on commands making intensive use of interp like avail. Interpreter state is reset from one interpretation to another: the initial variable and procedure state is restored before each new interpretation to avoid spread of definitions from one interpretation to another. Also in case of nested interpretation each interpretation level has its own interpreter so a module loaded by another does not influence the interpretation of the module loading it.
Improve performance of aliases and symbolic versions resolution by computing these resolution at definition time. As a consequence resolution loop are not registered anymore and produce an error message when spotted not at display time.
Reduce number of access system call by trying access to modulefile when reading the content of a modulefile directory rather testing access before trying it.
No error raise on empty argument list for load. To cope with initadd behavior that requires at least an empty module load line in startup files. (fix SF bug#88)
Fix initadd to handle load line without trailing space. Was previously expecting load directive to be written “module load ” to get a match. With fix, module load line will also be matched.
Like C-version catch raised error when break or continue are called from outside of a loop to handle them as when they are called from modulefile main body. (fix SF bug#87)
Return error on module use command when an empty path string is provided rather ignoring it.
Workaround min and max functions and lreverse procedure for correct operations under Tcl version 8.4.
Install: add –with-tclsh configure option to give the ability to choose the Tcl interpreter shell to setup in initialization scripts.
Handle error raised from the ModulesDisplay, ModulesHelp and ModulesTest procedures in the same way than for the evaluation of the modulefile content. An error occurring during the evaluation of the modulefile content will lead to no evaluation of the display, help and test command specific functions.
Remove debug module command
Doc: describe path, paths and autoinit module command.
Correct use of xrdb tool when not installed in default path.
Fix init* module commands to behave more like C-version and document remaining differences in diff_with_c-version.
Init: make sh init script closer to POSIX specification to support sh flavors different than Bash or Zsh like Dash.
Fix column-mode display for very short width terminal.
Install: introduce an install non-regression testsuite which is triggered by the make testinstall command and checks modules-tcl installation is operational.
Init: fix modulerc load test on fish init script.
Init: fix interactive shell test on sh init script.
Install: add –enable-example-modulefiles configure option that install by default some modulefiles provided as example in the system modulefiles directory.
Install: when uninstalling, do not remove modulefiles directory if it is not empty.
Add completion script for Zsh shell.
Add module test command to trigger when called execution of a ModulesTest procedure in target modulefile following same kind of mechanism than module help.

modules-tcl-1.832 (2017-04-29)¶

Fix getenv sub-command to correctly return environment variable value.
Clarify in man-pages display of module alias and symbolic version-name on avail command and management of file access issue when locating modulefiles.
Distinguish access issue (permission denied) from find issue (cannot locate) when trying to access directly a directory or a modulefile as done on load, display or whatis commands. In addition on this kind of access, not readable .modulerc files are ignored rather producing a missing magic cookie error.
When mode is set to unload, module load commands in modulefile are interpreted as module unload commands. To guaranty correct behavior regarding requirements, the module list passed to the load command is reversed to unload the modulefiles in the reverse order than they have been loaded.
Correct display command to only report module commands set in modulefile and not those set in the various .modulerc on the path toward this modulefile.
Fix bash and tcsh completion scripts to eliminate symbolic version names from avail command result.
Improve avail command when a symbolic version-name is passed as argument to return the modulefile target of this symbolic version-name.
When looking for an implicit default in a directory, now a module alias is taken into account so it can be returned as the last element in it (highest numerically sorted version).
Fix list command to correctly display the default tag along loaded modules when set via a .version file.
Fix long output of list command to display the symbolic version-names associated to each loaded module if any.
Improve avail command to return alias module when an alias name is passed as argument.
On a --default listing, a modulefile does not appear anymore if a directory is set default at the same level. On a --latest listing, a directory does not appear anymore if set default but not the latest.
Read modulerc and validate its header in a single open/read/close sequence instead of two in order to reduce to number of IO operations during an avail command.
Drastically reduce grid size computation time which removes overhead when displaying module avail results in column-mode.
Translate module name to currently interpreted module name when name correspond to the last part this interpreted module only in case of symbolic version-name or alias resolution.
Avoid resetting regular path (/usr/bin) or manpath (/usr/share/man) when switching from Tcl to C version in switchml utility.
Raise error on x-resource if DISPLAY environment variable is not set.
Fix lisp init script which was broken for environment change actions.

modules-tcl-1.775 (2017-03-07)¶

Improve README with examples, requirements, links, etc. Also update INSTALL documentation with details on the new configure/make/make install process.
Add display of a release date next to the version number when calling for --help or --version.
Update diff_with_c-version document to describe the features of the Tcl-version that are not supported on the C-version. Also state that the diff takes C version 3.2.10 against Tcl version 1.729 as a basis.
Introduce switchml tool, a shell function (or alias for csh or tcsh shells) that swap currently enabled Modules version (C or Tcl) by the other version (C or Tcl). Configure option --with-cver-initdir must be defined to enable switchml in initialization script.
Define a PATH and MANPATH in shell initialization scripts that point to the defined modules-tcl installation directories.
Give ability to generate distribution tarball from the git repository with Makefile dist target.
Introduce an installation process for this software following the configure/make/make install fashion. Configure step enables to choose installation paths and init scripts features to activate. Make step mainly translates init scripts with the configuration set. Make install creates target directories and copy files into them.
Fix MODULESHOME setup in autoinit command to define it as an absolute path and set it to the upper directory when modulecmd.tcl is located in a bin or a libexec directory.
Correct alias and version resolution on avail command which was erroneous in case of a modulefile holding symbols (like default) and targeted by aliases. Avail output was showing the aliases holding the symbols instead of the modulefile.

modules-tcl-1.729 (2017-02-01)¶

Add documentation in module(1) man page on the modulefile collection concept and the relative save, restore, saverm, saveshow and savelist commands.
Add document to list the differences of the functionalities that can be found on the C-version of the Modules package compared to the Tcl-version.
Improve modulecmd.tcl shebang to only search tclsh once if found in PATH.
Add module-info mode check against remove and switch values.
Introduce module-info command Modules-specific Tcl command to distinguish complex load or unload commands that cannot be determined with module-info mode alone. For instance a modulefile can now be aware that a switch, a restore or a purge command is currently being run.
Enable usage of module-info Modules-specific Tcl command from a modulerc file.
Fix module-info specified Modules-specific Tcl command.
No exit raise on modulefile or modulerc error during avail, aliases, whatis and search commands to avoid harming results from these global commands if error exists in a few modulefiles.
Exit with error code when a critical error is encountered when interpreting a modulefile or a modulerc.
Inhibit non-critical error report raised from modulefiles during avail, aliases, whatis and search commands to avoid error flood when parsing all modulefiles or modulercs.
Handle multiple lines of module-whatis Modules-specific Tcl commands defined for the same modulefile.
Handle multiple arguments passed to the module-whatis Modules-specific Tcl commands. They are joined to get a single line of text.
Return error on whatis command if searched modulefile is not found.

modules-tcl-1.704 (2017-01-20)¶

Set path variable counter to 1 for paths without a known reference count (was previously set to 999999999).
Introduce envml utility which acts as an application launcher where module commands are instantiated to setup environment before launching the given application.
Always register paths provided to be part of MODULEPATH environment variable as absolute paths to get independent from the current working directory.
Inhibit next modulefiles interpretation with exit Modules-specific Tcl command only if current mode is load.
Add argument to module-info shell and module-info shelltype to test current shell or shelltype value.
Fix use of default version-name to not consider it as a module symbol if a modulefile is named default.
Fix path variable counters when : character is used in elements of a path-like variable.
Update module(1) and modulefile(4) man pages to clear content specific to the C version of Modules and add content specific to or adapt content that behave differently on this Tcl version.
Fix TCLSH variable issue in Python init script.

modules-tcl-1.677 (2017-01-04)¶

Make switch command handle a single argument. The modulefile to switch to is the one passed on the command-line and the modulefile to unload is assumed to be the currently loaded module with the same root name as this modulefile specified on the command-line.
Make switch command idempotent by always ending up with old unloaded and new loaded, whatever the starting situation is.
Fix exit Modules-specific Tcl command.
Add refresh command as alias on reload command.
Add dummy module-log, module-trace, module-user and module-verbosity Modules-specific Tcl commands to enable support for modulefiles using them.
Fix system Modules-specific Tcl command to behave like described on the man page.
Fix module list when module loaded with full path
Disable g_force property by default to avoid loading a modulefile already loaded. It also avoids path element reference counting to get increased when the same module is asked twice for load.
Clarify module-info mode option and set help mode on module help command.
Clarify module-info flags and user options.
Handle empty or separator path on add-path ad unload-path commands.
Delete environment variable targeted by an unsetenv command on unload mode if no value has been provided along. On display mode, print environment variable value if any has been passed to unsetenv command.
When setting Tcl variable, enclose value within double quotes.
Fix perl quoting style for variable set, escape single quotes rather double quotes.
Call unuse command instead of use command on a module unload.
Fix continue Modules-specific Tcl command.
Add chdir Modules-specific Tcl command.
Fix break Modules-specific Tcl command.

modules-tcl-1.655 (2016-11-23)¶

No display of modulepath header if no module found in it.
Remove call to module aliases on module avail command, as aliases are now directly included in the avail results.
Include module aliases in the displayed result of an avail command. Also display aliases defined in a global or user modulerc file.
Exit with error code if error occurred on display or help commands.
Fix module-info symbols resolution.
Better handling of .modulerc and .version files when searching for a modulefile.
Fix module-info version resolution.
Fix module-info alias resolution.
Register alias and version by the short module name and improve their resolution to avoid loop.
Source $MODULERCFILE/modulerc when $MODULERCFILE is dir.
Make it so you can do module avail un, wildcard * character implied.

modules-tcl-1.632 (2016-09-06)¶

Raise error if command does not receive the excepted number of arguments.
Improve column-mode display to get a denser output on avail command.
Standardize the output of Warning, Error, InternalBug and ErrorAndExit messages.
Add short option -d for –delim on prepend-path.
Introduce collection target concept to distinguish between machines, environments or domains that are incompatible with each other.
Introduce saveshow command, to display content of saved collections.
Improve save and restore commands to handle collection specified as absolute or relative file path.
Introduce saverm command, to delete saved collections.
Enable to restore collection with multiple modulefiles specified on the same line.
Fix restore command when there is no module to load in collection.
Fix restore command when collection fully rewind module paths.
Fix restore command to preserve module path order set in collection.
Raise error if try to save an empty environment in a collection.

modules-tcl-1.602 (2016-08-13)¶

Add support for Fish shell.
Import recent tests added to C-version on 10-use and 50-cmds testsuites.
Add short option -d for –delim on append-path and remove-path.
Fix load and implement unload x-resource.
Fix Python code that was broken or not Python3-compliant. Fixed code is used to define the module command, to render error and to process x-resource.
Always dictionary-sort (also called numerical-sort) list of modulefiles or list of collections.
Fix bash completion script to be compliant with bash posix mode.

modules-tcl-1.578 (2014-12-24)¶

First release to be described in this NEWS file but it does not mean this is the first version of modules-tcl as this Modules flavor is born in 2002.
At this stage, modules-tcl handles a majority of the module commands and modulefile Tcl commands available on C version.

License¶

Modules is distributed under the GNU General Public License version 2 (GPL v2).

Environment Modules¶

Quick examples¶

Installing Modules on Unix¶

Requirements¶

Installation instructions¶

Configuration¶

Build and installation options¶

MIGRATING¶

Migrating from v4.0 to v4.1¶

New features¶

Virtual modules¶

Extend module command with site-specific Tcl code¶

Quarantine mechanism to protect module execution¶

Pager support¶

Module function to return value in scripting languages¶

New modulefile commands¶

New module sub-commands¶

Further reading¶

Migrating from v3.2 to v4.0¶

New features¶

Additional shells supported¶

Non-zero exit code in case of error¶

Output redirect¶

Filtering avail output¶

Extended support for module alias and symbolic version¶

Hiding modulefiles¶

Improved modulefiles location¶

Module collection¶

Path variable element counter¶

Optimized I/O operations¶

Sourcing modulefiles¶

Removed features and substantial behavior changes¶

Package initialization¶

Command line switches¶

Module sub-commands¶

Modules specific Tcl commands¶

Further reading¶

module¶

SYNOPSIS¶

DESCRIPTION¶

Package Initialization¶

Examples of initialization¶

Modulecmd startup¶

Command line switches¶

Module Sub-Commands¶

Modulefiles¶

Collections¶

EXIT STATUS¶

ENVIRONMENT¶

FILES¶

SEE ALSO¶

modulefile¶

DESCRIPTION¶

Modules Specific Tcl Commands¶

Modules Variables¶

Locating Modulefiles¶

Modulefile Specific Help¶

Modulefile Specific Test¶

Modulefile Display¶

ENVIRONMENT¶

SEE ALSO¶

NOTES¶

Differences between versions 3.2 and 4¶

Features missing or with different behavior than compatibility version¶

Package Initialization¶

Command line switches¶

Module Sub-Commands¶

Modules Specific Tcl Commands¶

Locating Modulefiles¶

Features specific to the new main version¶

Package Initialization¶

Modulecmd startup¶

Command line switches¶

Module Sub-Commands¶

Collections¶

Environment¶

Modules Specific Tcl Commands¶

Frequently Asked Questions on Environment Modules¶

Module command¶

How does the module command work?¶

How does the `module` command work?¶

I put the `module` command in a script and I run the script… it doesn’t change my environment?¶