"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "doc/build/MIGRATING.txt" between
modules-5.1.1.tar.bz2 and modules-5.2.0.tar.bz2

About: The Environment Modules package provides for the dynamic modification of a user’s environment via modulefiles.

[ To the main modules source changes report ]

MIGRATING.txt  (modules-5.1.1.tar.bz2):MIGRATING.txt  (modules-5.2.0.tar.bz2)
New features New features
************ ************
This document describes the major changes occurring between versions This document describes the major changes occurring between versions
of Modules. It provides an overview of the new features and changed of Modules. It provides an overview of the new features and changed
behaviors that will be encountered when upgrading. behaviors that will be encountered when upgrading.
v5.2
====
This new version is backward-compatible with previous version 5
release. It fixes bugs but also introduces new functionalities that
are described in this section. See the 5.2 release notes for a
complete list of the changes between Modules v5.1 and v5.2.
Optional requirements
---------------------
The "--optional" option has been added to the "prereq", "prereq-all",
"depends-on" and "always-load" modulefile commands to indicate that
specified requirement is optional. An automatic load attempt is also
performed for optional requirements. If requirement is not found or
cannot be loaded, the dependency is yet considered satisfied as it is
optional.
$ module show foo
-------------------------------------------------------------------
/path/to/modulefiles/foo:
prereq --optional bar
-------------------------------------------------------------------
$ module load foo
Loading foo
Loading requirement: bar
If the optional requirement is unloaded or loaded afterward, the
dependent module is automatically reloaded thanks to the
"auto_handling" mechanism.
$ module unload bar
Unloading bar
Unloading dependent: foo
Reloading dependent: foo
$ module list
Currently Loaded Modulefiles:
1) foo
$ module load bar
Loading bar
Unloading dependent: foo
Reloading dependent: foo
Modules loaded by other modules with the "module try-load" command are
now considered optional requirements. Dependent module can be loaded
without the *try-load* modules, but now it gets automatically reloaded
if *try-load* module is loaded afterward, to take it into account.
Linting modulefiles
-------------------
Static analysis of modulefile, modulerc and global/user rc is now
possible with "lint" sub-command. It relies on an external program
defined with "tcl_linter" configuration option. Modules or files
specified on the command-line are resolved then passed to the Tcl
linter program.
$ cat /path/to/modulefiles/foo/1.0
#%Module
if {"str" eq} {
else {
}
$ module lint foo/1.0
Linting /path/to/modulefiles/foo/1.0
ERROR line 2: Could not complete statement.
One close brace would complete the first line
One close brace would complete at end of line 4.
One close brace would complete the script body at line 5.
Assuming completeness for further processing.
ERROR line 2: Bad expression: missing operand at _@_
in expression ""str" eq_@_"
WARNING line 3: Unknown command "else"
NOTICE line 4: Close brace not aligned with line 3 (1 0)
Nagelfar is the Tcl linter recommended for Modules and set by default.
This default can be changed at installation time with "--with-tcl-
linter" and "--with-tcl-linter-opts" options. It can also be
configured later on through "tcl_linter" config option.
Specific syntax databases and plugins for Nagelfar are added by
Modules to precisely lint modulefile commands syntax in addition to
regular Tcl syntax. The installation of these specific files is
controlled with "--enable-nagelfar-addons" option (enabled by
default). Their location is controlled by the "--nagelfardatadir"
option.
$ module lint bar@:1 /path/to/modulefiles/.modulerc
Linting /path/to/modulefiles/.modulerc
ERROR line 35: Wrong number of arguments (3) to "module-alias"
ERROR line 41: Wrong number of arguments (3) to "module-virtual"
Linting /path/to/modulefiles/bar/1.2
WARNING line 19: Unknown command "unk"
$ module lint ~/.modulerc
Linting /home/user/.modulerc
WARNING line 2: Command "setenv" should not be be used in global rc file
"lint" sub-command outputs messages returned by the Tcl linter
program. Nagelfar produces NOTICE, WARNING and ERROR messages. If
linter does not report a thing, "lint" sub-command will be silent,
unless if the "--verbose"/"-v" is set.
$ module lint /path/to/modulefiles/bar/.version bar/1.4
$ module lint -v /path/to/modulefiles/bar/.version bar/1.4
Linting /path/to/modulefiles/bar/.version
Linting /path/to/modulefiles/bar/1.4
When no file is specified to "lint" sub-command, all the global/user
rc files and all the modulefiles and modulercs from enabled
modulepaths are analyzed. If the "--all"/"-a" option is set, all
hidden modulefiles are also linted.
$ module lint
Linting /home/user/.modulerc
WARNING line 2: Command "setenv" should not be be used in global rc file
Linting /path/to/modulefiles/.modulerc
ERROR line 35: Wrong number of arguments (3) to "module-alias"
ERROR line 41: Wrong number of arguments (3) to "module-virtual"
Linting /path/to/modulefiles/bar/1.2
WARNING line 19: Unknown command "unk"
...
To use Nagelfar as Tcl linter for Modules, this open source tool has
to be installed on your system. When installing from tarball
distribution, make sure **nagelfar.tcl** command is found through a
"PATH" lookup or that "tcl_linter" option is set to its full path
location. Nagelfar is also made available as a RPM package in EPEL and
Fedora repositories.
mod-to-sh sub-command
---------------------
New sub-command is added to translate modulefile into shell code:
"mod-to-sh". It evaluates modulefiles passed as argument and produces
code for specified shell.
$ cat /path/to/modulefiles/foo
#%Module
setenv FOO value
set-function foo {echo foo}
$ module mod-to-sh bash foo
FOO=value; export FOO;
foo () { echo foo; }; export -f foo;
Designated modulefiles are evaluated as if they were loading. But
instead of producing shell code that is evaluated in current shell
session, **module** command outputs this shell code.
$ cat /path/to/modulefiles/bar
#%Module
setenv BAR othervalue
set-alias bar {echo bar}
$ module mod-to-sh fish foo bar
set -xg FOO value;
set -xg BAR othervalue;
alias bar echobar;
function foo; echo foo; end;
$ module list
No Modulefiles Currently Loaded.
All shells supported by "modulecmd.tcl" script are supported by "mod-
to-sh".
$ module mod-to-sh python foo bar
import os
os.environ['FOO'] = 'value'
os.environ['BAR'] = 'othervalue'
Initial environment
-------------------
When Modules initializes, it evaluates the "initrc" and "modulespath"
configuration files to enable default modulepaths and load default
modules. Initial environment corresponds to the environment state
after this initialization.
Initial environment is now saved in an environment variable
("__MODULES_LMINIT") in current shell session to remember what are the
initial modulepaths and initial modules with their tags and variants
if any.
"reset" sub-command is introduced, in a similar fashion than on Lmod,
to restore the initial environment. Here, "reset" relies on the
collection mechanism based and the content of "__MODULES_LMINIT".
Currently enabled modulepaths and loaded modules are respectively
unused and unloaded to use the modulepaths and load the modules with
tags and variants as described by initial environment.
$ module list
Currently Loaded Modulefiles:
1) foo/1.0 2) bar/1.0
$ module switch bar/1.0 qux/1.0
$ module reset
Unloading qux/1.0
Loading bar/1.0
"restore" sub-command has been adapted to reinitialize the environment
to its initial state when no collection name is provided and no
*default* collection exists or if "__init__" virtual collection name
is provided.
It is possible to view the content of the initial environment with
"saveshow" sub-command. It is displayed when no argument is provided
and no collection exists or if "__init__" name is provided.
$ module saveshow __init__
-------------------------------------------------------------------
initial environment:
module use --append /path/to/modulefiles
module load foo/1.0
module load bar/1.0
-------------------------------------------------------------------
Users have the ability to define what is their initial environment
state and thus adapt the behavior of "reset" sub-command with
"reset_target_state" configuration option. Default value is "__init__"
and it corresponds to the behavior described above. When set to
"__purge__", a "purge" command is performed when resetting. Any other
value corresponds to the name of a collection to restore.
$ module config reset_target_state __purge__
$ module reset
Unloading bar/1.0
Unloading foo/1.0
Stashing environment
--------------------
The ability to stash current environment is added with the
introduction of the "stash" sub-command. When called current
environment is saved in a *stash* collection then initial environment
is restored.
$ module list
Currently Loaded Modulefiles:
1) bar/2.0 2) foo/2.0
$ module stash
Unloading foo/2.0
Unloading bar/2.0
$ module list
No Modulefiles Currently Loaded.
Sub-commands are added to specifically handle stash collections. Their
names are prefixed with *stash*, like "stashlist" to list existing
stash collections or "stashshow" to display their content.
$ module stashlist
Stash collection list:
0) stash-1665377597432 1) stash-1664946764252
$ module stashshow
-------------------------------------------------------------------
/home/user/.module/stash-1665377597432:
module use --append /path/to/modulefiles
module load bar
module load foo
-------------------------------------------------------------------
Stash collections can be designated on sub-commands by their
collection name or stash index. Most recent stash collection has index
"0", the one after is designated with index "1", and so on. When no
stash collection is specified, most recent one is assumed.
$ module stashshow 1
-------------------------------------------------------------------
/home/user/.module/stash-1664946764252:
module use --append /path/to/modulefiles
module load foobar
-------------------------------------------------------------------
Stash collections are restored with the "stashpop" sub-command. It
changes the user environment to match the stash definition, then it
deletes the stash collection file.
$ module stashpop
Loading bar/2.0
Loading foo/2.0
$ module stashlist
Stash collection list:
0) stash-1664946764252
Stash collections can be deleted one by one with "stashrm" sub-command
or all together with "stashclear".
$ module stashrm
$ module stashlist
No stash collection.
Siteconfig hook variables
-------------------------
Several Tcl variables are introduced for Site-specific configuration
script to define specific commands and variables in the evaluation
context of modulefiles and modulercs. These commands and variables
setup in "siteconfig.tcl" can be used in modulefile or modulerc. Sites
can easily extend modulefile and modulerc syntax with specific
elements.
"modulefile_extra_cmds" variable defines a list of commands to expose
in the modulefile evaluation context and the associated procedure to
run when this command is called. This variable has to be defined in
"siteconfig.tcl" located for instance at "/etc/environment-
modules/siteconfig.tcl".
In the following example "modulefile_extra_cmds" is used to define the
"sys" command and bound it to the "sys" procedure that is also defined
in "siteconfig.tcl".
proc sys {mode} {
switch -- $mode {
name { return myhost-$::tcl_platform(machine) }
default { error "Unknown mode '$mode'" }
}
}
set modulefile_extra_cmds {sys sys}
Once "siteconfig.tcl" is setup, the "sys" command can be called by
modulefiles. In the following example it is used to determine the
application path.
$ cat /path/to/modulefiles/foo/1.2
#%Module
append-path PATH /path/to/apps/foo-1.2/[sys name]/bin
$ module show foo/1.2
-------------------------------------------------------------------
/path/to/modulefiles/foo/1.2:
append-path PATH /path/to/apps/foo-1.2/myhost-x86_64/bin
-------------------------------------------------------------------
"modulerc_extra_cmds" follows the same approach than
"modulefile_extra_cmds" and makes specific commands available during
modulerc evaluation.
"modulefile_extra_vars" variable defines a list of variables to expose
in the modulefile evaluation context and their associated value. This
variable has to be defined in "siteconfig.tcl".
In the following example "modulefile_extra_vars" is used to define the
"APP_ROOT" variable with "/path/to/apps" as value.
set modulefile_extra_vars {APP_ROOT /path/to/apps}
Once "siteconfig.tcl" is setup, the "APP_ROOT" variable can be used in
modulefiles.
$ cat /path/to/modulefiles/bar/2.1
#%Module
append-path PATH $APP_ROOT/bar-2.1/[sys name]/bin
$ module show bar/2.1
-------------------------------------------------------------------
/path/to/modulefiles/bar/2.1:
append-path PATH /path/to/apps/bar-2.1/myhost-x86_64/bin
-------------------------------------------------------------------
"modulerc_extra_vars" follows the same approach than
"modulefile_extra_vars" and makes specific variables available during
modulerc evaluation.
v5.1 v5.1
==== ====
This new version is backward-compatible with previous version 5 This new version is backward-compatible with previous version 5
release. It fixes bugs but also introduces new functionalities that release. It fixes bugs but also introduces new functionalities that
are described in this section. See the 5.1 release notes for a are described in this section. See the 5.1 release notes for a
complete list of the changes between Modules v5.0 and v5.1. complete list of the changes between Modules v5.0 and v5.1.
Control output redirection Control output redirection
-------------------------- --------------------------
skipping to change at line 926 skipping to change at line 1296
-------------- --------------
Module stickiness is introduced, in a similar fashion than on the Lmod Module stickiness is introduced, in a similar fashion than on the Lmod
project, to allow to glue modules to the loaded environment. A sticky project, to allow to glue modules to the loaded environment. A sticky
module cannot be unloaded, unless if the unload action is forced or if module cannot be unloaded, unless if the unload action is forced or if
the module reloads after being unloaded. the module reloads after being unloaded.
A modulefile is declared *sticky* by applying it the "sticky" tag with A modulefile is declared *sticky* by applying it the "sticky" tag with
the "module-tag" modulefile command. the "module-tag" modulefile command.
$ cat mp/foo/.modulerc $ cat /path/to/modulefiles/foo/.modulerc
#%Module4.7 #%Module4.7
module-tag sticky foo/1.0 module-tag sticky foo/1.0
$ ml $ ml
Currently Loaded Modulefiles: Currently Loaded Modulefiles:
1) foo/1.0 1) foo/1.0
$ ml -foo $ ml -foo
Unloading foo/1.0 Unloading foo/1.0
ERROR: Unload of sticky module 'foo/1.0' skipped ERROR: Unload of sticky module 'foo/1.0' skipped
$ ml $ ml
Currently Loaded Modulefiles: Currently Loaded Modulefiles:
skipping to change at line 949 skipping to change at line 1319
Unloading foo/1.0 Unloading foo/1.0
WARNING: Unload of sticky module 'foo/1.0' forced WARNING: Unload of sticky module 'foo/1.0' forced
$ ml $ ml
No Modulefiles Currently Loaded. No Modulefiles Currently Loaded.
Modulefile can also be defined "super-sticky" by applying the Modulefile can also be defined "super-sticky" by applying the
corresponding module tag. *Super-sticky* module cannot be unloaded corresponding module tag. *Super-sticky* module cannot be unloaded
even if the unload action is forced. It can only be unloaded if the even if the unload action is forced. It can only be unloaded if the
module reloads afterward. module reloads afterward.
$ cat mp/bar/.modulerc $ cat /path/to/modulefiles/bar/.modulerc
#%Module4.7 #%Module4.7
module-tag super-sticky bar/1.0 module-tag super-sticky bar/1.0
$ ml $ ml
Currently Loaded Modulefiles: Currently Loaded Modulefiles:
1) bar/1.0 1) bar/1.0
$ ml purge $ ml purge
Unloading bar/1.0 Unloading bar/1.0
ERROR: Unload of super-sticky module 'bar/1.0' skipped ERROR: Unload of super-sticky module 'bar/1.0' skipped
$ ml purge -f $ ml purge -f
Unloading bar/1.0 Unloading bar/1.0
skipping to change at line 975 skipping to change at line 1345
Modulefiles targeted by a "sticky" or a "super-sticky" tag are colored Modulefiles targeted by a "sticky" or a "super-sticky" tag are colored
on "avail" and "list" sub-command outputs to indicate such tag on "avail" and "list" sub-command outputs to indicate such tag
applies. If colored output is disabled a tag abbreviation is reported applies. If colored output is disabled a tag abbreviation is reported
along module designation (respectively "S" and "sS"). along module designation (respectively "S" and "sS").
In case the stickiness applies to the generic module name (and does In case the stickiness applies to the generic module name (and does
not target a specific module version or version-set), one version of not target a specific module version or version-set), one version of
the sticky or super-sticky module can be swapped by another version of the sticky or super-sticky module can be swapped by another version of
this same module: this same module:
$ cat mp/baz/.modulerc $ cat /path/to/modulefiles/baz/.modulerc
#%Module4.7 #%Module4.7
module-tag sticky baz module-tag sticky baz
$ ml $ ml
Currently Loaded Modulefiles: Currently Loaded Modulefiles:
1) baz/2.0 1) baz/2.0
$ ml switch baz/1.0 $ ml switch baz/1.0
$ ml $ ml
Currently Loaded Modulefiles: Currently Loaded Modulefiles:
1) baz/1.0 1) baz/1.0
 End of changes. 4 change blocks. 
3 lines changed or deleted 373 lines changed or added
To the Information Files section of the modules source changes report or the top of this page
Mainly generated by pkgdiff using rfcdiff
Home  |  About  |  Features  |  All  |  Newest  |  Dox  |  Diffs  |  RSS Feeds  |  Screenshots  |  Comments  |  Imprint  |  Privacy  |  HTTP(S)