modules/doc/source/module.pod.in

=head1 NAME

module - command interface to the Modules package

=head1 SYNOPSIS

B<module> [I<switches>] [I<sub-command> [I<sub-command-args>]]

=head1 DESCRIPTION

B<module> is a user interface to the Modules package. The Modules package
provides for the dynamic modification of the user's environment via
I<modulefiles>.

Each I<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 B<module>
command which interprets I<modulefiles>. Typically I<modulefiles> instruct
the B<module> command to alter or set shell environment variables such
as B<PATH>, B<MANPATH>, etc. I<Modulefiles> may be shared by many users
on a system and users may have their own set to supplement or replace the
shared I<modulefiles>.

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

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

=head2 Package Initialization

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

The B<module> alias or function executes the B<modulecmd.tcl> program
located in F<@libexecdir@> and has the shell evaluate the command's
output. The first argument to B<modulecmd.tcl> specifies the type of shell.

The initialization scripts are kept in F<@initdir@/E<lt>shellE<gt>>
where I<E<lt>shellE<gt>> is the name of the sourcing shell. For example,
a C Shell user sources the F<@initdir@/csh> script. The sh, csh,
tcsh, bash, ksh, zsh and fish shells are supported by B<modulecmd.tcl>. In
addition, python, perl, tcl and lisp "shells" are supported which writes
the environment changes to stdout as python, perl, tcl or lisp code.

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

=head2 Examples of initialization

C Shell initialization (and derivatives):

    source @initdir@/csh
    module load modulefile modulefile ...

Bourne Shell (sh) (and derivatives):

    . @initdir@/sh
    module load modulefile modulefile ...

Perl:

    require "@initdir@/perl";
    &module("load modulefile modulefile ...");

Python:

    import os
    exec(open('@initdir@/python').read())
    module('load modulefile modulefile ...')

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

    eval `@libexecdir@/modulecmd.tcl sh autoinit`

=head2 Modulecmd startup

Upon invocation B<modulecmd.tcl> sources rc files which contain global,
user and I<modulefile> specific setups. These files are interpreted as
I<modulefiles>. See B<modulefile>(4) for detailed information.

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

=over

=item 1.

Global RC file as specified by F<$MODULERCFILE> or F<@prefix@/etc/rc>.
If F<$MODULERCFILE> points to a directory, the F<modulerc> file in this
directory is used as global RC file.

=item 2.

User specific module RC file F<$HOME/.modulerc>

=item 3.

All F<.modulerc> and F<.version> files found during modulefile seeking.

=back

=head2 Command line switches

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

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

=over

=item B<--help>, B<-h>

Give some helpful usage information, and terminates the command.

=item B<--version>, B<-V>

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

=item B<--debug>, B<-D>

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

=item B<--terse>, B<-t>

Display B<avail>, B<list> and B<savelist> output in short format.

=item B<--long>, B<-l>

Display B<avail>, B<list> and B<savelist> output in long format.

=item B<--default>, B<-d>

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

=item B<--latest>, B<-L>

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

=back

=head2 Module Sub-Commands

=over

=item B<help> [modulefile...]

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

=item B<add> modulefile...

=item B<load> modulefile...

Load I<modulefile> into the shell environment.

=item B<rm> modulefile...

=item B<unload> modulefile...

Remove I<modulefile> from the shell environment.

=item B<swap> [modulefile1] modulefile2

=item B<switch> [modulefile1] modulefile2

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

=item B<show> modulefile...

=item B<display> modulefile...

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

=item B<list> [-t|-l]

List loaded modules.

=item B<avail> [-d|-L] [-t|-l] [path...]

List all available I<modulefiles> in the current B<MODULEPATH>. All
directories in the B<MODULEPATH> are recursively searched for files
containing the I<modulefile> magic cookie. If an argument is given, then
each directory in the B<MODULEPATH> is searched for I<modulefiles> whose
pathname, symbolic version-name or alias match the argument. Multiple
versions of an application can be supported by creating a subdirectory
for the application containing I<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
I<modulefile> they are assigned to within parenthesis. Aliases are listed
in the B<MODULEPATH> section where they have been defined. To distinguish
aliases from I<modulefiles> a B<@> symbol is added within parenthesis next
to their name. Aliases defined through a global or user specific module
RC file are listed under the B<global/user modulerc> section.

=item B<aliases>

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

=item B<use> [-a|--append] directory...

Prepend one or more I<directories> to the B<MODULEPATH> environment variable.
The I<--append> flag will append the I<directory> to B<MODULEPATH>.

=item B<unuse> directory...

Remove one or more I<directories> from the B<MODULEPATH> environment
variable.

=item B<refresh>

=item B<reload>

Unload then load all loaded I<modulefiles>.

=item B<purge>

Unload all loaded I<modulefiles>.

=item B<source> modulefile...

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

=item B<whatis> [modulefile...]

Display the information set up by the B<module-whatis> commands inside
the specified I<modulefiles>. If no I<modulefile> is specified, all
B<module-whatis> lines will be shown.

=item B<apropos> string

=item B<keyword> string

=item B<search> string

Seeks through the B<module-whatis> informations of all I<modulefiles>
for the specified I<string>. All I<module-whatis> informations matching
the I<string> will be displayed.

=item B<test> modulefile...

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

=item B<save> [collection]

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

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

=item B<restore> [collection]

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

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

=item B<saverm> [collection]

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

=item B<saveshow> [collection]

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

=item B<savelist> [-t|-l]

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

=item B<initadd> modulefile...

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

=over

=item C Shell

F<.modules>, F<.cshrc>, F<.csh_variables> and F<.login>

=item TENEX C Shell

F<.modules>, F<.tcshrc>, F<.cshrc>, F<.csh_variables> and F<.login>

=item Bourne and Korn Shells

F<.modules>, F<.profile>

=item GNU Bourne Again Shell

F<.modules>, F<.bash_profile>, F<.bash_login>, F<.profile> and F<.bashrc>

=item Z Shell

F<.modules>, F<.zshrc>, F<.zshenv> and F<.zlogin>

=item Friendly Interactive Shell

F<.modules>, F<.config/fish/config.fish>

=back

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

=item B<initprepend> modulefile...

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

=item B<initrm> modulefile...

Remove I<modulefile> from the shell's initialization files.

=item B<initswitch> modulefile1 modulefile2

Switch I<modulefile1> with I<modulefile2> in the shell's initialization
files.

=item B<initlist>

List all of the I<modulefiles> loaded from the shell's initialization file.

=item B<initclear>

Clear all of the I<modulefiles> from the shell's initialization files.

=item B<path> modulefile

Print path to I<modulefile>.

=item B<paths> modulefile

Print path of available I<modulefiles> matching argument.

=back

=head2 Modulefiles

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

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

=head2 Collections

Collections describe a sequence of B<module use> then B<module load> commands
that are interpreted by B<modulecmd.tcl> to set the user environment as
described by this sequence. When a collection is activated, with the
B<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 B<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 F<$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 B<MODULES_COLLECTION_TARGET> environment variable
(see the dedicated section of this topic below).

=head1 ENVIRONMENT

=over

=item B<MODULESHOME>

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

=item B<MODULEPATH>

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

=item B<LOADEDMODULES>

A colon separated list of all loaded I<modulefiles>.

=item B<_LMFILES_>

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

=item B<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 B<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 B<restore>, B<savelist>, B<saveshow> and B<saverm>
sub-commands. Saving collection registers the target footprint by suffixing
the collection filename with ".B<$MODULES_COLLECTION_TARGET>". Collection
target is not involved when collection is specified as file path on the
B<saveshow>, B<restore> and B<save> sub-commands.

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

=back

=head1 FILES

=over

=item B<@prefix@>

The B<MODULESHOME> directory.

=item B<@prefix@/etc/rc>

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

=item B<$HOME/.modulerc>

The user specific modules rc file.

=item B<$HOME/.module>

The user specific collection directory.

=item B<@modulefilesdir@>

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

=item B<@libexecdir@/modulecmd.tcl>

The I<modulefile> interpreter that gets executed upon each invocation
of B<module>.

=item B<@initdir@/<shell>>

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

=back

=head1 SEE ALSO

B<modulefile>(4)