"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "MIGRATING.rst" 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.rst  (modules-5.1.1.tar.bz2):MIGRATING.rst  (modules-5.2.0.tar.bz2)
.. _MIGRATING: .. _MIGRATING:
New features New features
************ ************
This document describes the major changes occurring between versions of This document describes the major changes occurring between versions of
Modules. It provides an overview of the new features and changed behaviors Modules. It provides an overview of the new features and changed behaviors
that will be encountered when upgrading. 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 :ref:`5.2 release notes<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 :mfcmd:`prereq`,
:mfcmd:`prereq-all`, :mfcmd:`depends-on` and :mfcmd:`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.
.. parsed-literal::
:ps:`$` module show foo
-------------------------------------------------------------------
:sgrhi:`/path/to/modulefiles/foo`:
:sgrcm:`prereq` --optional bar
-------------------------------------------------------------------
:ps:`$` module load foo
Loading :sgrhi:`foo`
:sgrin:`Loading requirement`: bar
If the optional requirement is unloaded or loaded afterward, the dependent
module is automatically reloaded thanks to the :mconfig:`auto_handling`
mechanism.
.. parsed-literal::
:ps:`$` module unload bar
Unloading :sgrhi:`bar`
:sgrin:`Unloading dependent`: foo
:sgrin:`Reloading dependent`: foo
:ps:`$` module list
Currently Loaded Modulefiles:
1) foo
:ps:`$` module load bar
Loading :sgrhi:`bar`
:sgrin:`Unloading dependent`: foo
:sgrin:`Reloading dependent`: foo
Modules loaded by other modules with the :mfcmd:`module try-load<module>`
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 :subcmd:`lint` sub-command. It relies on an external program defined with
:mconfig:`tcl_linter` configuration option. Modules or files specified on the
command-line are resolved then passed to the Tcl linter program.
.. parsed-literal::
:ps:`$` cat /path/to/modulefiles/foo/1.0
#%Module
if {"str" eq} {
else {
}
:ps:`$` module lint foo/1.0
Linting :sgrhi:`/path/to/modulefiles/foo/1.0`
:sgrer:`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.
:sgrer:`ERROR line 2`: Bad expression: missing operand at _@_
in expression ""str" eq_@_"
:sgrwa:`WARNING line 3`: Unknown command "else"
:sgrin:`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 :instopt:`--with-tcl-linter`
and :instopt:`--with-tcl-linter-opts` options. It can also be configured later
on through :mconfig:`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
:instopt:`--enable-nagelfar-addons` option (enabled by default). Their
location is controlled by the :instopt:`--nagelfardatadir` option.
.. parsed-literal::
:ps:`$` module lint bar@:1 /path/to/modulefiles/.modulerc
Linting :sgrhi:`/path/to/modulefiles/.modulerc`
:sgrer:`ERROR line 35`: Wrong number of arguments (3) to "module-alias"
:sgrer:`ERROR line 41`: Wrong number of arguments (3) to "module-virtual
"
Linting :sgrhi:`/path/to/modulefiles/bar/1.2`
:sgrwa:`WARNING line 19`: Unknown command "unk"
:ps:`$` module lint ~/.modulerc
Linting :sgrhi:`/home/user/.modulerc`
:sgrwa:`WARNING line 2`: Command "setenv" should not be be used in global
rc file
:subcmd:`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, :subcmd:`lint` sub-command will be silent, unless if the
:option:`--verbose`/:option:`-v` is set.
.. parsed-literal::
:ps:`$` module lint /path/to/modulefiles/bar/.version bar/1.4
:ps:`$` module lint -v /path/to/modulefiles/bar/.version bar/1.4
Linting :sgrhi:`/path/to/modulefiles/bar/.version`
Linting :sgrhi:`/path/to/modulefiles/bar/1.4`
When no file is specified to :subcmd:`lint` sub-command, all the global/user
rc files and all the modulefiles and modulercs from enabled modulepaths are
analyzed. If the :option:`--all`/:option:`-a` option is set, all hidden
modulefiles are also linted.
.. parsed-literal::
:ps:`$` module lint
Linting :sgrhi:`/home/user/.modulerc`
:sgrwa:`WARNING line 2`: Command "setenv" should not be be used in global
rc file
Linting :sgrhi:`/path/to/modulefiles/.modulerc`
:sgrer:`ERROR line 35`: Wrong number of arguments (3) to "module-alias"
:sgrer:`ERROR line 41`: Wrong number of arguments (3) to "module-virtual
"
Linting :sgrhi:`/path/to/modulefiles/bar/1.2`
:sgrwa:`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
:command:`nagelfar.tcl` command is found through a :envvar:`PATH` lookup or
that :mconfig:`tcl_linter` option is set to its full path location.
`Nagelfar`_ is also made available as a RPM package in `EPEL and Fedora
repositories`_.
.. _Nagelfar: http://nagelfar.sourceforge.net/
.. _EPEL and Fedora repositories: https://src.fedoraproject.org/rpms/nagelfar
mod-to-sh sub-command
---------------------
New sub-command is added to translate modulefile into shell code:
:subcmd:`mod-to-sh`. It evaluates modulefiles passed as argument and produces
code for specified shell.
.. parsed-literal::
:ps:`$` cat /path/to/modulefiles/foo
#%Module
setenv FOO value
set-function foo {echo foo}
:ps:`$` 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,
:command:`module` command outputs this shell code.
.. parsed-literal::
:ps:`$` cat /path/to/modulefiles/bar
#%Module
setenv BAR othervalue
set-alias bar {echo bar}
:ps:`$` module mod-to-sh fish foo bar
set -xg FOO value;
set -xg BAR othervalue;
alias bar echo\ bar;
function foo; echo foo; end;
:ps:`$` module list
No Modulefiles Currently Loaded.
All shells supported by :file:`modulecmd.tcl` script are supported by
:subcmd:`mod-to-sh`.
.. parsed-literal::
:ps:`$` 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 :file:`initrc` and
:file:`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
(:envvar:`__MODULES_LMINIT`) in current shell session to remember what are the
initial modulepaths and initial modules with their tags and variants if any.
:subcmd:`reset` sub-command is introduced, in a similar fashion than on
`Lmod`_, to restore the initial environment. Here, :subcmd:`reset` relies on
the :ref:`collection<collections>` mechanism based and the content of
:envvar:`__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.
.. parsed-literal::
:ps:`$` module list
Currently Loaded Modulefiles:
1) foo/1.0 2) bar/1.0
:ps:`$` module switch bar/1.0 qux/1.0
:ps:`$` module reset
Unloading :sgrhi:`qux/1.0`
Loading :sgrhi:`bar/1.0`
:subcmd:`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
:subcmd:`saveshow` sub-command. It is displayed when no argument is provided
and no collection exists or if ``__init__`` name is provided.
.. parsed-literal::
:ps:`$` module saveshow __init__
-------------------------------------------------------------------
:sgrhi:`initial environment`:
:sgrcm:`module` use --append /path/to/modulefiles
:sgrcm:`module` load foo/1.0
:sgrcm:`module` load bar/1.0
-------------------------------------------------------------------
Users have the ability to define what is their initial environment state and
thus adapt the behavior of :subcmd:`reset` sub-command with
:mconfig:`reset_target_state` configuration option. Default value is
``__init__`` and it corresponds to the behavior described above. When set to
``__purge__``, a :subcmd:`purge` command is performed when resetting. Any
other value corresponds to the name of a collection to restore.
.. parsed-literal::
:ps:`$` module config reset_target_state __purge__
:ps:`$` 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
:subcmd:`stash` sub-command. When called current environment is saved in a
*stash* collection then initial environment is restored.
.. parsed-literal::
:ps:`$` module list
Currently Loaded Modulefiles:
1) bar/2.0 2) foo/2.0
:ps:`$` module stash
Unloading :sgrhi:`foo/2.0`
Unloading :sgrhi:`bar/2.0`
:ps:`$` module list
No Modulefiles Currently Loaded.
Sub-commands are added to specifically handle stash collections. Their names
are prefixed with *stash*, like :subcmd:`stashlist` to list existing stash
collections or :subcmd:`stashshow` to display their content.
.. parsed-literal::
:ps:`$` module stashlist
Stash collection list:
0) stash-1665377597432 1) stash-1664946764252
:ps:`$` module stashshow
-------------------------------------------------------------------
:sgrhi:`/home/user/.module/stash-1665377597432:`
:sgrcm:`module` use --append /path/to/modulefiles
:sgrcm:`module` load bar
:sgrcm:`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.
.. parsed-literal::
:ps:`$` module stashshow 1
-------------------------------------------------------------------
:sgrhi:`/home/user/.module/stash-1664946764252:`
:sgrcm:`module` use --append /path/to/modulefiles
:sgrcm:`module` load foobar
-------------------------------------------------------------------
Stash collections are restored with the :subcmd:`stashpop` sub-command. It
changes the user environment to match the stash definition, then it deletes
the stash collection file.
.. parsed-literal::
:ps:`$` module stashpop
Loading :sgrhi:`bar/2.0`
Loading :sgrhi:`foo/2.0`
:ps:`$` module stashlist
Stash collection list:
0) stash-1664946764252
Stash collections can be deleted one by one with :subcmd:`stashrm` sub-command
or all together with :subcmd:`stashclear`.
.. parsed-literal::
:ps:`$` module stashrm
:ps:`$` module stashlist
No stash collection.
Siteconfig hook variables
-------------------------
Several Tcl variables are introduced for :ref:`Site-specific configuration`
script to define specific commands and variables in the evaluation context of
modulefiles and modulercs. These commands and variables setup in
:file:`siteconfig.tcl` can be used in modulefile or modulerc. Sites can easily
extend modulefile and modulerc syntax with specific elements.
:sitevar:`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
:file:`siteconfig.tcl` located for instance at |file etcdir_siteconfig|.
In the following example :sitevar:`modulefile_extra_cmds` is used to define
the ``sys`` command and bound it to the ``sys`` procedure that is also defined
in :file:`siteconfig.tcl`.
.. code-block:: tcl
proc sys {mode} {
switch -- $mode {
name { return myhost-$::tcl_platform(machine) }
default { error "Unknown mode '$mode'" }
}
}
set modulefile_extra_cmds {sys sys}
Once :file:`siteconfig.tcl` is setup, the ``sys`` command can be called by
modulefiles. In the following example it is used to determine the application
path.
.. parsed-literal::
:ps:`$` cat /path/to/modulefiles/foo/1.2
#%Module
append-path PATH /path/to/apps/foo-1.2/[sys name]/bin
:ps:`$` module show foo/1.2
-------------------------------------------------------------------
:sgrhi:`/path/to/modulefiles/foo/1.2`:
:sgrcm:`append-path` PATH /path/to/apps/foo-1.2/myhost-x86_64/bin
-------------------------------------------------------------------
:sitevar:`modulerc_extra_cmds` follows the same approach than
:sitevar:`modulefile_extra_cmds` and makes specific commands available during
modulerc evaluation.
:sitevar:`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 :file:`siteconfig.tcl`.
In the following example :sitevar:`modulefile_extra_vars` is used to define
the ``APP_ROOT`` variable with ``/path/to/apps`` as value.
.. code-block:: tcl
set modulefile_extra_vars {APP_ROOT /path/to/apps}
Once :file:`siteconfig.tcl` is setup, the ``APP_ROOT`` variable can be used in
modulefiles.
.. parsed-literal::
:ps:`$` cat /path/to/modulefiles/bar/2.1
#%Module
append-path PATH $APP_ROOT/bar-2.1/[sys name]/bin
:ps:`$` module show bar/2.1
-------------------------------------------------------------------
:sgrhi:`/path/to/modulefiles/bar/2.1`:
:sgrcm:`append-path` PATH /path/to/apps/bar-2.1/myhost-x86_64/bin
-------------------------------------------------------------------
:sitevar:`modulerc_extra_vars` follows the same approach than
:sitevar:`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 release. It This new version is backward-compatible with previous version 5 release. It
fixes bugs but also introduces new functionalities that are described in this fixes bugs but also introduces new functionalities that are described in this
section. See the :ref:`5.1 release notes<5.1 release notes>` for a complete section. See the :ref:`5.1 release notes<5.1 release notes>` for a complete
list of the changes between Modules v5.0 and v5.1. list of the changes between Modules v5.0 and v5.1.
Control output redirection Control output redirection
-------------------------- --------------------------
skipping to change at line 1007 skipping to change at line 1415
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 module 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 the module cannot be unloaded, unless if the unload action is forced or if the module
reloads after being unloaded. reloads after being unloaded.
A modulefile is declared *sticky* by applying it the ``sticky`` tag with the A modulefile is declared *sticky* by applying it the ``sticky`` tag with the
:mfcmd:`module-tag` modulefile command. :mfcmd:`module-tag` modulefile command.
.. parsed-literal:: .. parsed-literal::
:ps:`$` cat mp/foo/.modulerc :ps:`$` cat /path/to/modulefiles/foo/.modulerc
#%Module4.7 #%Module4.7
module-tag sticky foo/1.0 module-tag sticky foo/1.0
:ps:`$` ml :ps:`$` ml
Currently Loaded Modulefiles: Currently Loaded Modulefiles:
1) :sgrs:`foo/1.0` 1) :sgrs:`foo/1.0`
:ps:`$` ml -foo :ps:`$` ml -foo
Unloading :sgrhi:`foo/1.0` Unloading :sgrhi:`foo/1.0`
:sgrer:`ERROR`: Unload of sticky module 'foo/1.0' skipped :sgrer:`ERROR`: Unload of sticky module 'foo/1.0' skipped
:ps:`$` ml :ps:`$` ml
Currently Loaded Modulefiles: Currently Loaded Modulefiles:
skipping to change at line 1031 skipping to change at line 1439
:sgrwa:`WARNING`: Unload of sticky module 'foo/1.0' forced :sgrwa:`WARNING`: Unload of sticky module 'foo/1.0' forced
:ps:`$` ml :ps:`$` ml
No Modulefiles Currently Loaded. No Modulefiles Currently Loaded.
Modulefile can also be defined ``super-sticky`` by applying the corresponding Modulefile can also be defined ``super-sticky`` by applying the corresponding
module tag. *Super-sticky* module cannot be unloaded even if the unload action module tag. *Super-sticky* module cannot be unloaded even if the unload action
is forced. It can only be unloaded if the module reloads afterward. is forced. It can only be unloaded if the module reloads afterward.
.. parsed-literal:: .. parsed-literal::
:ps:`$` cat mp/bar/.modulerc :ps:`$` cat /path/to/modulefiles/bar/.modulerc
#%Module4.7 #%Module4.7
module-tag super-sticky bar/1.0 module-tag super-sticky bar/1.0
:ps:`$` ml :ps:`$` ml
Currently Loaded Modulefiles: Currently Loaded Modulefiles:
1) :sgrss:`bar/1.0` 1) :sgrss:`bar/1.0`
:ps:`$` ml purge :ps:`$` ml purge
Unloading :sgrhi:`bar/1.0` Unloading :sgrhi:`bar/1.0`
:sgrer:`ERROR`: Unload of super-sticky module 'bar/1.0' skipped :sgrer:`ERROR`: Unload of super-sticky module 'bar/1.0' skipped
:ps:`$` ml purge -f :ps:`$` ml purge -f
Unloading :sgrhi:`bar/1.0` Unloading :sgrhi:`bar/1.0`
skipping to change at line 1058 skipping to change at line 1466
:subcmd:`avail` and :subcmd:`list` sub-command outputs to indicate such tag :subcmd:`avail` and :subcmd:`list` sub-command outputs to indicate such tag
applies. If colored output is disabled a tag abbreviation is reported along applies. If colored output is disabled a tag abbreviation is reported along
module designation (respectively ``S`` and ``sS``). module designation (respectively ``S`` and ``sS``).
In case the stickiness applies to the generic module name (and does not target In case the stickiness applies to the generic module name (and does not target
a specific module version or version-set), one version of the sticky or a specific module version or version-set), one version of the sticky or
super-sticky module can be swapped by another version of this same module: super-sticky module can be swapped by another version of this same module:
.. parsed-literal:: .. parsed-literal::
:ps:`$` cat mp/baz/.modulerc :ps:`$` cat /path/to/modulefiles/baz/.modulerc
#%Module4.7 #%Module4.7
module-tag sticky baz module-tag sticky baz
:ps:`$` ml :ps:`$` ml
Currently Loaded Modulefiles: Currently Loaded Modulefiles:
1) :sgrs:`baz/2.0` 1) :sgrs:`baz/2.0`
:ps:`$` ml switch baz/1.0 :ps:`$` ml switch baz/1.0
:ps:`$` ml :ps:`$` ml
Currently Loaded Modulefiles: Currently Loaded Modulefiles:
1) :sgrs:`baz/1.0` 1) :sgrs:`baz/1.0`
 End of changes. 4 change blocks. 
3 lines changed or deleted 415 lines changed or added
To the RST 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)