1.. _MIGRATING: 2 3MIGRATING 4********* 5 6This document describes the major changes occurring between versions of 7Modules. It provides an overview of the new features and changed behaviors 8that will be encountered when upgrading. 9 10 11Migrating from v4.5 to v4.6 12=========================== 13 14This new version is backward-compatible with v4.5 and primarily fixes bugs and 15adds new features. 16 17New features 18------------ 19 20Version 4.6 introduces new functionalities that are described in this section. 21 22sh-to-mod sub-command 23^^^^^^^^^^^^^^^^^^^^^ 24 25The :subcmd:`sh-to-mod` sub-command is added to output as a modulefile content 26the environment changes done by the evaluation of a shell script passed as 27argument. :subcmd:`sh-to-mod` is especially useful for software providing a 28shell script for their enablement in shell session: it can convert these 29scripts into modulefiles. 30 31Say for instance, a *foo* software has been installed and it provides a 32``foo-setup.sh`` script to activate *foo* software in user environment: 33 34.. code-block:: console 35 36 $ cat /path/to/foo-1.2/foo-setup.sh 37 #!/bin/sh 38 export FOOENV="$1" 39 export PATH=/path/to/foo-1.2/bin:$PATH 40 alias foo='foobin -q -l' 41 42Calling ``module sh-to-mod`` on this shell script outputs the environment 43changes it performs as a modulefile content: 44 45.. code-block:: console 46 47 $ module sh-to-mod sh /path/to/foo-1.2/foo-setup.sh arg1 48 #%Module 49 prepend-path PATH /path/to/foo-1.2/bin 50 set-alias foo {foobin -q -l} 51 setenv FOOENV arg1 52 53Changes on environment variables, shell aliases, shell functions and current 54working directory are tracked. The following shells are supported: *sh*, 55*dash*, *csh*, *tcsh*, *bash*, *ksh*, *ksh93*, *zsh* and *fish*. 56 57:subcmd:`sh-to-mod` acts as a full replacement for the standalone 58:command:`createmodule.sh` and :command:`createmodule.py` scripts. However 59those two scripts are currently still provided for compatibility purpose. 60 61source-sh modulefile command 62^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 63 64The :mfcmd:`source-sh` modulefile command is introduced to source environment 65changes done by the evaluation of a shell script passed as argument. With 66newly introduced :subcmd:`sh-to-mod` sub-command resulting environment changes 67done by script are output as modulefile commands. :mfcmd:`source-sh` applies 68those modulefile commands as if they were directly written in loading 69modulefile. 70 71:mfcmd:`source-sh` is useful for software providing a shell script for their 72enablement. If you want to enable such software with :command:`module` yet 73using shell script provided by software for this task, just write a modulefile 74using :mfcmd:`source-sh` command to call the shell script. 75 76Keeping the same example used to describe :subcmd:`sh-to-mod` sub-command: 77*foo* software provides a ``foo-setup.sh`` script for its activation. Create a 78modulefile ``foo/1.2`` that calls this script: 79 80.. code-block:: console 81 82 $ cat /path/to/modulefiles/foo/1.2 83 #%Module4.6 84 source-sh sh /path/to/foo-1.2/foo-setup.sh arg1 85 86Displaying this modulefile indicates the environment changes done by script: 87 88.. code-block:: console 89 90 $ module display foo/1.2 91 ------------------------------------------------------------------- 92 /path/to/modulefiles/foo/1.2: 93 94 prepend-path PATH /path/to/foo-1.2/bin 95 set-alias foo {foobin -q -l} 96 setenv FOOENV arg1 97 ------------------------------------------------------------------- 98 99Loading the modulefile applies the environment changes seen above: 100 101.. code-block:: console 102 103 $ module load -v foo/1.2 104 Loading foo/1.2 105 $ echo $FOOENV 106 arg1 107 $ alias foo 108 alias foo='foobin -q -l' 109 110Track of these changes is kept in user environment to be able to undo them 111when modulefile is unloaded: 112 113.. code-block:: console 114 115 $ module unload -v foo/1.2 116 Unloading foo/1.2 117 $ echo $FOOENV 118 119 $ alias foo 120 bash: alias: foo: not found 121 122Changes on environment variables, shell aliases, shell functions and current 123working directory are tracked. The following shells are supported: *sh*, 124*dash*, *csh*, *tcsh*, *bash*, *ksh*, *ksh93*, *zsh* and *fish*. 125 126Querying user's name and groups membership 127^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 128 129Two new sub-commands are introduced for the :mfcmd:`module-info` modulefile 130command: ``username`` and ``usergroups``. They respectively fetch the name of 131the user currently running :file:`modulecmd.tcl` or the name of all the groups 132this user is member of. 133 134These two new modulefile commands can help to adapt code to specific users or 135groups. Like for instance to instantiate a modulefile for each group the user 136is member of: 137 138.. code-block:: console 139 140 $ cat /path/to/modulefiles/foo/.modulerc 141 #%Module4.6 142 foreach grp [module-info usergroups] { 143 module-virtual foo/$grp .common 144 } 145 $ id -G -n 146 grp1 grp2 grp3 147 $ module avail 148 --------------- /path/to/modulefiles --------------- 149 foo/grp1 foo/grp2 foo/grp3 150 151``username`` and ``usergroups`` sub-commands of :mfcmd:`module-info` 152modulefile command are only supported on Unix platform. 153 154Hiding modules 155^^^^^^^^^^^^^^ 156 157The newly introduced :mfcmd:`module-hide` modulefile command enables to 158dynamically hide modulefiles, module aliases or symbolic versions specified to 159it: 160 161.. code-block:: console 162 163 $ cat /path/to/modulefiles/bar/.modulerc 164 #%Module4.6 165 module-version bar/1.0 old 166 # hide 'old' symbolic version 167 module-hide bar/old 168 # hide all version 2 and above 169 module-hide bar@2: 170 $ cat /path/to/modulefiles/.modulerc 171 #%Module4.6 172 # hide all versions of foo module 173 module-hide foo 174 175:mfcmd:`module-hide` commands should be placed in module rc files and can 176leverage the `Advanced module version specifiers`_ syntax as shown in the 177above example. 178 179Hidden modules are excluded from available module search or module selection 180unless query refers to hidden module by its exact name: 181 182.. code-block:: console 183 184 $ ml av 185 --------------- /path/to/modulefiles --------------- 186 bar/1.0 bar/2.0 187 $ module load -v foo 188 ERROR: Unable to locate a modulefile for 'foo' 189 $ module load -v foo/1.0 190 Loading foo/1.0 191 $ module avail bar/old 192 --------------- /path/to/modulefiles --------------- 193 bar/1.0(old) 194 195:mfcmd:`module-hide` command accepts a ``--soft`` option to apply a lighter of 196hiding to modules: 197 198.. code-block:: console 199 200 $ cat /path/to/modulefiles/qux/.modulerc 201 #%Module4.6 202 # softly hide all qux modules 203 module-hide --soft qux 204 205The soft hiding mode enables to hide modules from full availability listing 206yet keeping the ability to select such module for load without having to use 207module exact name: 208 209.. code-block:: console 210 211 $ ml av 212 --------------- /path/to/modulefiles --------------- 213 bar/1.0 bar/2.0 214 $ ml av qux 215 --------------- /path/to/modulefiles --------------- 216 qux/1.0 qux/2.0 217 $ module load -v qux 218 Loading qux/2.0 219 220Alternatively, a ``--hard`` option can be set on :mfcmd:`module-hide` command 221to ensure designated modules do not unveil even if referred by their exact 222name: 223 224.. code-block:: console 225 226 $ cat /path/to/modulefiles/qux/.modulerc 227 #%Module4.6 228 # softly hide all qux modules 229 module-hide --soft qux 230 # set highest version of qux hard hidden 231 module-hide --hard qux/3.0 232 $ ml av qux/3.0 233 $ ml qux/3.0 234 ERROR: Unable to locate a modulefile for 'qux/3.0' 235 236Some users or groups can be set unaffected by hiding mechanism with 237the ``--not-user`` or ``--not-group`` options: 238 239.. code-block:: console 240 241 $ cat /path/to/modulefiles/quuz/.modulerc 242 #%Module4.6 243 # hiding does not apply to grp1 and grp2 groups 244 module-hide --not-group {grp1 grp2} quuz 245 246.. code-block:: console 247 248 $ id --groups --name 249 grp1 grp7 250 $ ml av quuz 251 --------------- /path/to/modulefiles --------------- 252 quuz/1.0 quuz/2.0 253 $ ml -v quuz 254 Loading quuz/2.0 255 256Hiding mechanism can also be set effective only before or after a given date 257time with the ``--before`` and ``--after`` options. Accepted date time format 258is ``YYYY-MM-DD[THH:MM]``. 259 260.. code-block:: console 261 262 $ cat /path/to/modulefiles/fum/.modulerc 263 #%Module4.6 264 # hide only before a given date 265 module-hide --hard --before 2020-09-01T12:00 fum/1.0 266 # hide only after a given date 267 module-hide --hard --after 2020-09-01 fum/2.0 268 269.. code-block:: console 270 271 $ date 272 Fri 04 Sep 2020 06:21:48 AM CEST 273 $ ml av fum 274 --------------- /path/to/modulefiles --------------- 275 fum/1.0 276 277Hidden modules can be included in available module searches if option 278:option:`--all`/:option:`-a` is set on :subcmd:`avail`, :subcmd:`aliases`, 279:subcmd:`whatis` or :subcmd:`search` sub-commands. Hard hidden modules are 280unaffected by this option and stay hidden. 281 282.. code-block:: console 283 284 $ ml av -a 285 --------------- /path/to/modulefiles --------------- 286 bar/1.0(old) foo/1.0 fum/1.0 quuz/2.0 qux/2.0 287 bar/2.0 foo/2.0 quuz/1.0 qux/1.0 288 289Forbidding use of modules 290^^^^^^^^^^^^^^^^^^^^^^^^^ 291 292The :mfcmd:`module-forbid` modulefile command is added to dynamically forbid 293the evaluation of modulefiles it specifies. When forbidden, a module cannot be 294loaded and an access error is returned when an attempt is made to evaluate it. 295 296.. code-block:: console 297 298 $ cat /path/to/modulefiles/foo/.modulerc 299 #%Module4.6 300 module-forbid foo@1: 301 $ ml foo/1.0 302 ERROR: Access to module 'foo/1.0' is denied 303 $ ml 304 No Modulefiles Currently Loaded. 305 306:mfcmd:`module-forbid` statements can be coupled with :mfcmd:`module-hide` 307statements to hide modules in addition to forbid their use. 308:mfcmd:`module-forbid` supports the ``--not-user``, ``--not-group``, 309``--before`` and ``--after`` options to still allow some users or forbid 310modules before or after a given date time. 311 312An additional error message can be defined with the ``--message`` option 313to guide for instance users when they try to evaluate a forbidden module: 314 315.. code-block:: console 316 317 $ cat /path/to/modulefiles/bar/.modulerc 318 #%Module4.6 319 module-forbid --message {Software bar/1.0 is decommissioned, please now use\ 320 bar/2.0} --after 2020-09-01 bar/1.0 321 $ ml bar/1.0 322 ERROR: Access to module 'bar/1.0' is denied 323 Software bar/1.0 is decommissioned, please now use bar/2.0 324 325When an evaluated module will soon be forbidden, a message is returned to the 326user to warn him/her of the near limit. An additional warning message can 327also be defined here with the ``--nearly-message`` option to guide users. 328 329.. code-block:: console 330 331 $ cat /path/to/modulefiles/qux/.modulerc 332 #%Module4.6 333 module-forbid --nearly-message {Version 1.0 will soon expire, please now use\ 334 version 2.0} --after 2020-09-15 qux/1.0 335 $ date 336 Tue 08 Sep 2020 06:49:43 AM CEST 337 $ ml qux/1.0 338 Loading qux/1.0 339 WARNING: Access to module will be denied starting '2020-09-15' 340 Version 1.0 will soon expire, please now use version 2.0 341 342The range of time the *nearly forbidden* warning appears can be controlled 343with the ``nearly_forbidden_days`` configuration option, whose value equals to 344the number of days prior the module starts to be forbidden. This configuration 345is set to ``14`` (days) by default and this value can be controlled at 346:file:`configure` time with ``--with-nearly-forbidden-days`` option. When the 347``nearly_forbidden_days`` configuration is set through the :subcmd:`config` 348sub-command, the :envvar:`MODULES_NEARLY_FORBIDDEN_DAYS` environment variable 349is set. 350 351Tracing module execution 352^^^^^^^^^^^^^^^^^^^^^^^^ 353 354The ``trace`` verbosity is introduced between the ``verbose`` and ``debug`` 355levels to report details on module searches, resolutions, selections and 356evaluations. Trace mode can be enabled by setting the ``verbosity`` config to 357the ``trace`` value or by using the :option:`-T`/:option:`--trace` 358command-line switches. 359 360To specifically render trace messages, the ``tr`` key is added to the color 361palette with a default value of ``2`` (decreased intensity). 362 363.. code-block:: console 364 365 $ ml -T foo 366 Evaluate modulerc: '/path/to/modulefiles/.modulerc' 367 Get modules: {foo} matching 'foo' in '/path/to/modulefiles' 368 Resolve: 'foo' into 'bar' 369 Get modules: {bar bar/1.0} matching 'bar' in '/path/to/modulefiles' 370 Select module: 'bar/1.0' (/path/to/modulefiles/bar/1.0) matching 'bar/1.0' 371 372 Loading bar/1.0 373 Evaluate modulefile: '/path/to/modulefiles/bar/1.0' as 'bar/1.0' 374 375 376Further reading 377--------------- 378 379To get a complete list of the changes between Modules v4.5 and v4.6, 380please read the :ref:`NEWS` document. 381 382 383Migrating from v4.4 to v4.5 384=========================== 385 386This new version is backward-compatible with v4.4 and primarily fixes bugs and 387adds new features. 388 389New features 390------------ 391 392Version 4.5 introduces new functionalities that are described in this section. 393 394ml command 395^^^^^^^^^^ 396 397The ``ml`` command is added to Modules. ``ml`` is a frontend to the ``module`` 398command that reduces the number of characters to type to trigger module 399actions. 400 401With no argument provided ``ml`` is equivalent to ``module list``, ``ml foo`` 402corresponds to ``module load foo`` and ``ml -foo`` means ``module unload 403foo``:: 404 405 $ ml foo 406 $ ml 407 Currently Loaded Modulefiles: 408 1) foo/2 409 $ ml -foo 410 $ ml 411 No Modulefiles Currently Loaded. 412 413Multiple modules to either load or unload can be combined on a single command. 414The unloads are first processed then the loads. 415 416``ml`` accepts all command-line switches and sub-commands accepted by 417``module`` command:: 418 419 $ ml avail -t foo 420 foo/1 421 foo/2 422 423This handy interface has been originally developed by the `Lmod`_ project. 424Having this command line interface also supported on Modules helps to provide 425a similar user experience whatever the module implementation used. 426 427.. _Lmod: https://github.com/TACC/Lmod 428 429JSON format output 430^^^^^^^^^^^^^^^^^^ 431 432The ``-j`` and ``--json`` command line switches are added for the ``avail``, 433``list``, ``savelist``, ``whatis`` and ``search`` module sub-commands. When 434set, the output result of these sub-commands is rendered in `JSON`_ format:: 435 436 $ module avail --json bar | python -mjson.tool 437 { 438 "/path/to/modulefiles": { 439 "bar/2.3": { 440 "name": "bar/2.3", 441 "pathname": "/path/to/modulefiles/bar/2.3", 442 "symbols": [ 443 "default" 444 ], 445 "type": "modulefile" 446 }, 447 "bar/3.4": { 448 "name": "bar/3.4", 449 "pathname": "/path/to/modulefiles/bar/3.4", 450 "symbols": [], 451 "type": "modulefile" 452 } 453 } 454 } 455 $ ml whatis -j foo/1.2.3 | python -mjson.tool 456 { 457 "/path/to/modulefiles": { 458 "foo/1.2.3": { 459 "name": "foo/1.2.3", 460 "whatis": [ 461 "The foo/1.2.3 modulefile" 462 ] 463 } 464 } 465 } 466 467.. _JSON: https://tools.ietf.org/html/rfc8259 468 469Improved Windows support 470^^^^^^^^^^^^^^^^^^^^^^^^ 471 472A new option to the ``./configure`` script named ``--enable-windows-support`` 473is introduced to install additional files relative to the enablement of 474Modules on the Windows platform. When set, this option installs 475``module.cmd``, ``ml.cmd`` and ``envml.cmd`` scripts in ``bindir`` and 476initialization script ``cmd.cmd`` in ``initdir``. With these four files the 477Modules installation may be used from either a Unix or a Windows platform. 478 479``module.cmd``, ``ml.cmd`` and ``envml.cmd`` scripts respectively provide the 480``module``, ``ml`` and ``envml`` commands for Windows ``cmd`` terminal shell, 481relying on ``modulecmd.tcl`` script which was already able to produce shell 482code for this Windows shell. Initialization script ``cmd.cmd`` adds the 483directory of ``module.cmd``, ``ml.cmd`` and ``envml.cmd`` to ``PATH``. 484 485These Windows-specific files are relocatable: ``module.cmd``, ``ml.cmd`` and 486``envml.cmd`` scripts expect to find initialization script ``cmd.cmd`` in the 487``init`` directory next to them (to setup Modules-specific variables in 488current environment) and ``cmd.cmd`` expects ``modulecmd.tcl`` to be found in 489``libexec`` directory and the 3 commands in ``bin`` directory next to it. 490 491Starting from this ``4.5`` release a distribution zipball is published to 492install Modules on Windows. This zip archive ships an install and an uninstall 493scripts (``INSTALL.bat`` and ``UNINSTALL.bat``). The zipball can be built 494locally from Modules sources by running ``make dist-win``. 495 496The :ref:`INSTALL-win` document describes how to install Modules on Windows 497from the distribution zipball. 498 499Error stack trace 500^^^^^^^^^^^^^^^^^ 501 502Error messages will now embed a stack trace for unknown errors to help 503localize the root cause of issues. This change applies to modulefile 504evaluation:: 505 506 Loading foo/1.2 507 Module ERROR: add-path cannot handle path equals to separator string 508 while executing 509 "append-path PATH :" 510 (file "/path/to/modulefiles/foo/1.2" line 24) 511 Please contact <root@localhost> 512 513A stack trace is also returned when an unknown error occurs in 514``modulecmd.tcl`` script, which facilitates issue report and analysis:: 515 516 $ module load bar 517 ERROR: invalid command name "badcommand" 518 while executing 519 "badcommand" 520 (procedure "module" line 14) 521 invoked from within 522 "module load bar" 523 ("eval" body line 1) 524 invoked from within 525 "eval $execcmdlist" 526 Please report this issue at https://github.com/cea-hpc/modules/issues 527 528Automatic default and latest symbolic versions 529^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 530 531When the implicit default mechanism and the `Advanced module version 532specifiers`_ are both enabled, a ``default`` and a ``latest`` symbolic 533versions are automatically defined for each module name. 534 535This new feature gives the ability to select the highest version available for 536a module, without knowing beforehand this version name:: 537 538 $ module load -v foo@latest 539 Loading foo/1.10 540 541The symbolic versions are automatically defined unless a symbolic version, an 542alias or a regular module version already exists for these ``default`` or 543``latest`` version names. 544 545Further reading 546--------------- 547 548To get a complete list of the changes between Modules v4.4 and v4.5, 549please read the :ref:`NEWS` document. 550 551 552Migrating from v4.3 to v4.4 553=========================== 554 555This new version is backward-compatible with v4.3 and primarily fixes bugs and 556adds new features. 557 558.. warning:: Modules configuration option handling has been reworked 559 internally to provide a unified way for all options to get initialized, 560 retrieved or set. Existing site-specific configuration script should be 561 reviewed to make use of the new ``getConf``, ``setConf``, ``unsetConf`` 562 and ``lappendConf`` procedures to manipulate configuration options. 563 564New features 565------------ 566 567Version 4.4 introduces new functionalities that are described in this section. 568 569Specify modules in a case insensitive manner 570^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 571 572The ability to match module name in a case insensitive manner has been added. 573This feature can be enabled at different level with the following values set 574to the ``icase`` configuration option: 575 576* ``never``: a case sensitive match is applied in any cases 577* ``search``: a case insensitive match is applied to the ``avail``, ``whatis`` 578 and ``paths`` sub-commands 579* ``always``: a case insensitive match is applied to search contexts and also 580 to the other module sub-commands and modulefile Tcl commands for the module 581 specification they receive as argument. 582 583It can help for instance to load a module without knowing the case used to 584name its relative modulefile:: 585 586 $ module config icase always 587 $ module load -v mysoftware 588 Loading MySoftware/1.0 589 590Insensitive case match activation can be controlled at configure time with 591the ``--with-icase`` option, which could be passed any of the above activation 592levels. This option could be superseded with the ``MODULES_ICASE`` environment 593variable, which could be set through the **config** sub-command with the 594``icase`` option. Command-line switch **--icase** supersedes in turns any 595other icase configurations. When this command-line switch is passed, ``icase`` 596mode equals ``always``. 597 598Extended default 599^^^^^^^^^^^^^^^^ 600 601The extended default mechanism has been introduced to help selecting a module 602when only the first numbers in its version are specified. Starting portion of 603the version, part separated from the rest of the version string by a ``.`` 604character, could be used to refer to a more precise version number. 605 606This mechanism is activated through the new configuration option 607``extended_default``. It enables to refer to a module named ``foo/1.2.3`` as 608``foo/1.2`` or ``foo/1``:: 609 610 $ module config extended_default 1 611 $ module load -v foo/1 612 Loading foo/1.2.3 613 614When multiple versions match partial version specified and only one module 615should be selected, the default version (whether implicitly or explicitly 616defined) among matches is returned. The following example shows that 617``foo/1.1.1``, the *foo* module default version, is selected when it matches 618query. Elsewhere the highest version (also called the latest version or the 619implicit default) among matching modules is returned:: 620 621 $ module av foo 622 --------------- /path/to/modulefiles --------------- 623 foo/1.1.1(default) foo/1.2.1 foo/1.10 624 foo/1.1.10 foo/1.2.3 625 $ module load -v foo/1.1 626 Loading foo/1.1.1 627 $ module purge 628 $ module load -v foo/1.2 629 Loading foo/1.2.3 630 $ module purge 631 $ module load -v foo/1 632 Loading foo/1.1.1 633 634In case ``implicit_default`` option is disabled and no explicit default is 635found among matches, an error is returned:: 636 637 $ module config implicit_default 0 638 $ module load -v foo/1.2 639 ERROR: No default version defined for 'foo/1.2' 640 641When it is enabled, extended default applies everywhere a module could be 642specified, which means it could be used with any module sub-command or any 643modulefile Tcl command receiving a module specification as argument. It may 644help for instance to declare dependencies between modules:: 645 646 $ module show bar/3 647 ---------------------------------------------------------- 648 /path/to/modulefiles/bar/3.4: 649 650 prereq foo/1.2 651 ---------------------------------------------------------- 652 $ module load --auto bar/3 653 Loading bar/3.4 654 Loading requirement: foo/1.2.3 655 656Extended default activation can be controlled at configure time with the 657``--enable-extended-default`` option. This option could be superseded with the 658``MODULES_EXTENDED_DEFAULT`` environment variable, which could be set through 659the **config** sub-command with the ``extended_default`` option. 660 661Advanced module version specifiers 662^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 663 664The ability to specify finer constraints on module version has been added to 665Modules. It enables to filter the module selection to a given version list or 666range by specifying after the module name a version constraint prefixed by the 667``@`` character. 668 669This new feature leverages the `version specifier syntax`_ of the `Spack`_ 670package manager as this syntax covers all the needs for a fine-grained 671selection of module versions. It copes very well with command-line typing, by 672avoiding characters having a special meaning on shells. Moreover the users of 673Spack that also are users of Modules may already be familiar with this syntax. 674 675.. _version specifier syntax: https://spack.readthedocs.io/en/stable/basic_usage.html#version-specifier 676.. _Spack: https://github.com/spack/spack 677 678The mechanism introduced here is called *advanced module version specifier* 679and it can be activated through the new configuration option 680``advanced_version_spec``. Constraints can be expressed to refine the 681selection of module version to: 682 683* a single version with the ``@version`` syntax, for instance ``foo@1.2.3`` 684 syntax will select module ``foo/1.2.3`` 685* a list of versions with the ``@version1,version2,...`` syntax, for instance 686 ``foo@1.2.3,1.10`` will match modules ``foo/1.2.3`` and ``foo/1.10`` 687* a range of versions with the ``@version1:``, ``@:version2`` and 688 ``@version1:version2`` syntaxes, for instance ``foo@1.2:`` will select all 689 versions of module ``foo`` greater than or equal to ``1.2``, ``foo@:1.3`` 690 will select all versions less than or equal to ``1.3`` and ``foo@1.2:1.3`` 691 matches all versions between ``1.2`` and ``1.3`` including ``1.2`` and 692 ``1.3`` versions 693 694This new feature enables for instance to list available versions of module 695``foo`` higher or equal to ``1.2``:: 696 697 $ module config advanced_version_spec 1 698 $ module av foo 699 --------------- /path/to/modulefiles --------------- 700 foo/1.1.1(default) foo/1.2.1 foo/1.10 701 foo/1.1.10 foo/1.2.3 702 $ module av foo@1.2: 703 --------------- /path/to/modulefiles --------------- 704 foo/1.2.1 foo/1.2.3 foo/1.10 705 706Then choose to load for instance a version higher than or equal to ``1.2`` and 707less than or equal to ``1.3``. Default version is selected if it corresponds 708to a version included in the range, elsewhere the highest version (also called 709latest version or implicit default) is selected:: 710 711 $ module load -v foo@1.2:1.3 712 Loading foo/1.2.3 713 714In case ``implicit_default`` option is disabled and no explicit default is 715found among version specifier matches, an error is returned:: 716 717 $ module config implicit_default 0 718 $ module load -v foo@1.2:1.3 719 ERROR: No default version defined for 'foo@1.2:1.3' 720 721When advanced module version specifier is enabled, it applies everywhere a 722module could be specified, which means it could be used with any module 723sub-command or any modulefile Tcl command receiving a module specification 724as argument. It may help for instance to declare smoother dependencies between 725modules:: 726 727 $ module show bar@:2 728 ---------------------------------------------------------- 729 /path/to/modulefiles/bar/2.3: 730 731 prereq foo@1.1.10,1.2.1 732 ---------------------------------------------------------- 733 $ module load --auto bar@:2 734 Loading bar/2.3 735 Loading requirement: foo/1.2.1 736 737Advanced specification of single version or list of versions may benefit from 738the activation of the `Extended default`_ mechanism (range of versions 739natively handles abbreviated versions):: 740 741 $ module config extended_default 1 742 $ module load -v foo@1.2 743 Loading foo/1.2.3 744 $ module unload -v foo @1.2,1.5 745 Unloading foo/1.2.3 746 747Advanced module version specifier activation can be controlled at configure 748time with the ``--enable-advanced-version-spec`` option. This option could be 749superseded with the ``MODULES_ADVANCED_VERSION_SPEC`` environment variable, 750which could be set through the **config** sub-command with the 751``advanced_version_spec`` option. 752 753Further reading 754--------------- 755 756To get a complete list of the changes between Modules v4.3 and v4.4, 757please read the :ref:`NEWS` document. 758 759 760Migrating from v4.2 to v4.3 761=========================== 762 763This new version is backward-compatible with v4.2 and primarily fixes bugs and 764adds new features. 765 766New features 767------------ 768 769Version 4.3 introduces new functionalities that are described in this section. 770 771Modulepath rc file 772^^^^^^^^^^^^^^^^^^ 773 774A ``.modulerc`` file found at the root of an enabled modulepath directory is 775now evaluated when modulepath is walked through to locate modulefiles. This 776modulepath rc file gives for instance the ability to define module alias whose 777name does not correspond to any module directory in this modulepath. Thus this 778kind of module alias would not be found unless if it is defined at the 779modulepath global scope. 780 781Further I/O operations optimization 782^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 783 784Additional work has been performed to save a significant number of filesystem 785I/O operations made to search and evaluate modulefiles. 786 787When fully read, the content of a modulefile is now cached in memory to avoid 788new I/O operations in case this modulefile should be read one more time during 789the same module command evaluation. 790 791Except for ``path``, ``paths``, ``list``, ``avail`` and ``aliases`` module 792commands always fully read a modulefile whether its full content is needed or 793just its header to verify its validity. This way modulefiles are only read 794once on commands that first check modulefile validity then read again valid 795files to get their full content. 796 797Last but not least, Modules Tcl extension library is introduced to extend the 798Tcl language in order to provide more optimized I/O commands to read a file or 799a directory content than native Tcl commands do. This library is built and 800enabled in ``modulecmd.tcl`` script with ``--enable-libtclenvmodules`` 801configure argument (it is enabled by default). As this library is written in 802C, it must be compiled and ``--with-tcl`` or ``--with-tclinclude`` configure 803arguments may be used to indicate where to find Tcl development files. 804 805Modules Tcl extension library greatly reduces the number of filesystem I/O 806operations by removing unneeded ``ioctl``, ``fcntl`` and ``lstat`` system 807calls done (by Tcl ``open`` command) to read each modulefile. Directory 808content read is also improved by fetching hidden and regular files in one 809pass. Moreover ``.modulerc`` and ``.version`` read access is tested only if 810these files are found in the directory. 811 812Colored output 813^^^^^^^^^^^^^^ 814 815The ability to graphically enhance some part of the produced output has been 816added to improve readability. Among others, error, warning and info message 817prefixes can be colored as well as modulepath, module alias and symbolic 818version. 819 820Color mode can be set to ``never``, ``auto`` or ``always``. When color mode is 821set to ``auto``, output is colored only if the standard error output channel 822is attached to a terminal. 823 824Default color mode could be controlled at configure time with the 825``--enable-color`` and the ``--disable-color`` option, which respectively 826correspond to the ``auto`` and ``never`` color mode. This default mode could 827be superseded with the ``CLICOLOR``, ``CLICOLOR_FORCE`` and ``MODULES_COLOR`` 828environment variables and the ``--color`` command-line switch. 829 830Color to apply to each element can be controlled with the ``MODULES_COLORS`` 831environment variable or the ``--with-dark-background-colors`` and 832``--with-light-background-colors`` configure options. These variable and 833options take as value a colon-separated list in the same fashion ``LS_COLORS`` 834does. In this list, output item that should be highlighted is designated by 835a key which is associated to a `Select Graphic Rendition (SGR) code`_. 836 837.. _Select Graphic Rendition (SGR) code: https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_(Select_Graphic_Rendition)_parameters 838 839The ``MODULES_TERM_BACKGROUND`` environment variable and the 840``--with-terminal-background`` configure option help Modules to determine if 841the color set for dark background or the color set for light background should 842be used to color output in case no specific color set is defined with the 843``MODULES_COLORS`` variable. 844 845Output items able to be colorized and their relative key are: highlighted 846element (``hi``), debug information (``db``), tag separator (``se``); Error 847(``er``), warning (``wa``), module error (``me``) and info (``in``) message 848prefixes; Modulepath (``mp``), directory (``di``), module alias (``al``), 849module symbolic version (``sy``), module ``default`` version (``de``) and 850modulefile command (``cm``). 851 852For instance the default color set for a terminal with dark background is 853defined to:: 854 855 hi=1:db=2:se=2:er=91:wa=93:me=95:in=94:mp=1;94:di=94:al=96:sy=95:de=4:cm=92 856 857When colored output is enabled and a specific graphical rendition is defined 858for module *default* version, the ``default`` symbol is omitted and instead 859the defined graphical rendition is applied to the relative modulefile. When 860colored output is enabled and a specific graphical rendition is defined for 861module alias, the ``@`` symbol is omitted. 862 863``CLICOLOR`` and ``CLICOLOR_FORCE`` environment variables are also honored to 864define color mode. The ``never`` mode is set if ``CLICOLOR`` equals to ``0``. 865If ``CLICOLOR`` is set to another value, it corresponds to the ``auto`` mode. 866The ``always`` mode is set if ``CLICOLOR_FORCE`` is set to a value different 867than ``0``. Color mode set with these two variables is superseded by mode set 868with ``MODULES_COLOR`` environment variable. 869 870Configure modulecmd with config sub-command 871^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 872 873The **config** sub-command has been added to ``module`` to help getting or 874setting the **modulecmd.tcl** options. With no additional command-line 875argument, this sub-command reports the current value of all existing options 876with a mention to indicate if this value has been overridden from a 877command-line switch or from an environment variable. 878 879See the description of this sub-command in the :ref:`module(1)` man page for a 880complete reference on existing configuration options. 881 882Most of the options can be altered by passing the option name and a value to 883the sub-command. Setting an option by this mean overrides its default value, 884set at installation time in **modulecmd.tcl** script, by defining the 885environment variable which supersedes this default.:: 886 887 $ module config auto_handling 1 888 $ module config auto_handling 889 Modules Release 4.3.0 (2019-07-26) 890 891 - Config. name ---------.- Value (set by if default overridden) --------------- 892 auto_handling 1 (env-var) 893 894Setting options with ``module config`` could be done in the Modules 895initialization RC file to change default value of options when ``module`` 896command is initialized. 897 898When command-line switch ``--reset`` and an option name is passed to the 899**config** sub-command, it restores default value for configuration option by 900unsetting related environment variable. 901 902With command-line switch ``--dump-state``, the **config** sub-command reports, 903in addition to currently set options, the current state of **modulecmd.tcl** 904script and Modules-related environment variables. Providing the output of the 905``module config --dump-state`` command when submitting an issue to the Modules 906project will help to analyze the situation. 907 908Control module command verbosity 909^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 910 911The ability to control message verbosity has been added so ``module`` command 912can be configured whether it should display more or less information. 913Available verbosity levels from the least to the most verbose are: 914 915* ``silent``: turn off error, warning and informational messages but does not 916 affect module command output result. 917* ``concise``: enable error and warning messages but disable informational 918 messages. 919* ``normal``: turn on informational messages, like a report of the additional 920 module evaluations triggered by loading or unloading modules, aborted 921 evaluation issues or a report of each module evaluation occurring during a 922 **restore** or **source** sub-commands. 923* ``verbose``: add additional informational messages, like a systematic report 924 of the loading or unloading module evaluations. 925* ``debug``: print debugging messages about module command execution. 926 927Default verbosity level can be controlled at configure time with the 928``--with-verbosity`` option, which could be passed any of the above level 929names. This default verbosity level could be superseded with the 930``MODULES_VERBOSITY`` environment variable, which could be set through the 931**config** sub-command with the ``verbosity`` option. Command-line switches 932**--silent**, **--verbose** and **--debug** supersede in turns any other 933verbosity configuration to respectively set module command silent, verbose or 934in debug mode. 935 936Other new sub-commands, command-line switches and environment variables 937^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 938 939* The **avail** sub-command gets two new command-line switches: **--indepth** 940 and **--no-indepth**. These options control whether search results should 941 recursively include or not modulefiles from directories matching search 942 query. Shell completion scripts have been updated to complete available 943 modulefiles in the no in depth mode. 944 945* The **MODULES_AVAIL_INDEPTH** environment variable defines if the **avail** 946 sub-command should include or exclude by default the modulefiles from 947 directories matching search query. Its value is superseded by the use of the 948 **--indepth** and **--no-indepth** command-line switches. 949 950* The **clear** sub-command, which was available on Modules version 3.2, has 951 been reintroduced. This sub-command resets the Modules runtime information 952 but does not apply further changes to the environment at all. This 953 sub-command now leverages the **--force** command-line switch to skip its 954 confirmation dialog. 955 956* The **MODULES_SITECONFIG** environment variable defines an additional 957 siteconfig script which is loaded if it exists after the siteconfig script 958 configured at build time in ``modulecmd.tcl``. This ability is enabled by 959 default and could be disabled with configure option 960 ``--with-locked-configs=extra_siteconfig``. 961 962* The **MODULES_UNLOAD_MATCH_ORDER** environment variable sets whether the 963 firstly or the lastly loaded module should be selected for unload when 964 multiple loaded modules match unload request. Configure option 965 ``--with-unload-match-order`` defines this setting which can be superseded 966 by the environment variable. By default, lastly loaded module is selected 967 and it is recommended to keep this behavior when used modulefiles express 968 dependencies between each other. 969 970* The **MODULES_IMPLICIT_DEFAULT** environment variable sets whether an 971 implicit default version should be defined for modules with no default 972 version explicitly defined. When enabled, which is the default behavior, a 973 module version is automatically selected (latest one) when the generic 974 name of the module is passed. When implicit default is disabled and no 975 default version is explicitly defined for a module, the name of this module 976 to evaluate should be fully qualified elsewhere an error is returned. 977 Configure option ``--enable-implicit-default`` defines this setting which 978 can be superseded by the environment variable. This superseding mechanism 979 can be disabled with configure option 980 ``--with-locked-configs=implicit_default``. 981 982* The **MODULES_SEARCH_MATCH** environment variable defines the matching style 983 to perform when searching for available modules. With **starts_with** value, 984 modules whose name begins by search query string are returned. When search 985 match style is set to **contains**, modules returned are those whose fully 986 qualified name contains search query string. Configure option 987 ``--with-search-match`` defines this setting which can be superseded by the 988 environment variable, which in turns can be superseded by the 989 **--starts-with** and **--contains** command-line switches of **avail** 990 module sub-command. 991 992* The **MODULES_SET_SHELL_STARTUP** environment variable controls whether or 993 not shell startup file should be set to ensure ``module`` command is defined 994 once shell has been initialized. When enabled, the ``ENV`` and ``BASH_ENV`` 995 environment variables are set, when ``module`` function is defined, to the 996 Modules bourne shell initialization script. Configure options 997 ``--enable-set-shell-startup`` and ``--disable-set-shell-startup`` define 998 this setting which can be superseded by the environment variable. 999 1000* When initializing the ``module`` command in a shell session, initialization 1001 configuration files stored in the defined configuration directory are taken 1002 into account if present instead of the configuration files stored in the 1003 initialization script directory. When they are stored in the configuration 1004 directory, these configuration files are named ``initrc`` and 1005 ``modulespath`` instead of respectively ``modulerc`` and ``.modulespath``. 1006 The location of the installation of those files can be controlled with 1007 configure option ``--with-initconf-in``, which accepts ``etcdir`` and 1008 ``initdir`` values. 1009 1010* The **MODULES_WA_277** environment variable helps to define an alternative 1011 ``module`` alias on Tcsh shell when set to *1*. It workarounds an issue on 1012 Tcsh history mechanism occurring with default ``module`` command alias: 1013 erroneous history entries are recorded each time the ``module`` command is 1014 called. However the alternative definition of the module alias weakens shell 1015 evaluation of the code produced by modulefiles. Characters with special 1016 meaning for Tcsh shell (like *{* and *}*) may not be used anymore in shell 1017 alias definition elsewhere the evaluation of the code produced by 1018 modulefiles will return a syntax error. 1019 1020 1021Further reading 1022--------------- 1023 1024To get a complete list of the changes between Modules v4.2 and v4.3, 1025please read the :ref:`NEWS` document. 1026 1027 1028Migrating from v4.1 to v4.2 1029=========================== 1030 1031This new version is backward-compatible with v4.1 and primarily fixes bugs and 1032adds new features. 1033 1034New features 1035------------ 1036 1037Version 4.2 introduces new functionalities that are described in this section. 1038 1039.. _v42-conflict-constraints-consistency: 1040 1041Modulefile conflict constraints consistency 1042^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1043 1044With the **conflict** modulefile command, a given modulefile can list the 1045other modulefiles it conflicts with. To load this modulefile, the modulefiles 1046it conflicts with cannot be loaded. 1047 1048This constraint was until now satisfied when loading the modulefile declaring 1049the **conflict** but it vanished as soon as this modulefile was loaded. In the 1050following example ``a`` modulefile declares a conflict with ``b``:: 1051 1052 $ module load b a 1053 WARNING: a cannot be loaded due to a conflict. 1054 HINT: Might try "module unload b" first. 1055 $ module list 1056 Currently Loaded Modulefiles: 1057 1) b 1058 $ module purge 1059 $ module load a b 1060 $ module list 1061 Currently Loaded Modulefiles: 1062 1) a 2) b 1063 1064Consistency of the declared **conflict** is now ensured to satisfy this 1065constraint even after the load of the modulefile declaring it. This is 1066achieved by keeping track of the conflict constraints of the loaded 1067modulefiles in an environment variable called ``MODULES_LMCONFLICT``:: 1068 1069 $ module load a b 1070 ERROR: WARNING: b cannot be loaded due to a conflict. 1071 HINT: Might try "module unload a" first. 1072 $ module list 1073 Currently Loaded Modulefiles: 1074 1) a 1075 1076An environment variable is used to keep track of this conflict information to 1077proceed the same way than used to keep track of the loaded modulefiles with 1078the ``LOADEDMODULES`` environment variable. 1079 1080In case a conflict constraint toward a modulefile is set by an already loaded 1081modulefile, loading the conflicting modulefile will lead to a load evaluation 1082attempt in order for this modulefile to get the chance to solve the constraint 1083violation. If at the end of the load evaluation, the conflict has not been 1084solved, modulefile load will be discarded. 1085 1086.. warning:: On versions ``4.2.0`` and ``4.2.1``, a conflict constraint set by 1087 an already loaded modulefile forbade the load of the conflicting 1088 modulefile. This has been changed starting version ``4.2.2`` to better cope 1089 with behaviors of previous Modules version: an evaluation attempt of the 1090 conflicting modulefile is made to give it the opportunity to solve this 1091 conflict by using **module unload** modulefile command. 1092 1093.. _v42-prereq-constraints-consistency: 1094 1095Modulefile prereq constraints consistency 1096^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1097 1098With the **prereq** modulefile command, a given modulefile can list the 1099other modulefiles it pre-requires. To load this modulefile, the modulefiles it 1100pre-requires must be loaded prior its own load. 1101 1102This constraint was until now satisfied when loading the modulefile declaring 1103the **prereq** but, as for the declared **conflict**, it vanished as soon as 1104this modulefile was loaded. In the following example ``c`` modulefile declares 1105a prereq on ``a``:: 1106 1107 $ module load c 1108 WARNING: c cannot be loaded due to missing prereq. 1109 HINT: the following module must be loaded first: a 1110 $ module list 1111 No Modulefiles Currently Loaded. 1112 $ module load a c 1113 $ module list 1114 Currently Loaded Modulefiles: 1115 1) a 2) c 1116 $ module unload a 1117 $ module list 1118 Currently Loaded Modulefiles: 1119 1) c 1120 1121Consistency of the declared **prereq** is now ensured to satisfy this 1122constraint even after the load of the modulefile declaring it. This is 1123achieved, like for the conflict consistency, by keeping track of the prereq 1124constraints of the loaded modulefiles in an environment variable called 1125``MODULES_LMPREREQ``:: 1126 1127 $ module load a c 1128 $ module list 1129 Currently Loaded Modulefiles: 1130 1) a 2) c 1131 $ module unload a 1132 ERROR: WARNING: a cannot be unloaded due to a prereq. 1133 HINT: Might try "module unload c" first. 1134 $ module list 1135 Currently Loaded Modulefiles: 1136 1) a 2) c 1137 1138.. _v42-by-passing-module-constraints: 1139 1140By-passing module defined constraints 1141^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1142 1143The ability to by-pass a **conflict** or a **prereq** constraint defined by 1144modulefiles is introduced with the ``--force`` command line switch (``-f`` for 1145short notation) for the **load**, **unload** and **switch** sub-commands. 1146 1147With this new command line switch, a given modulefile is loaded even if it 1148conflicts with other loaded modulefiles or even if the modulefiles it 1149pre-requires are not loaded. Some example reusing the same modulefiles ``a``, 1150``b`` and ``c`` than above:: 1151 1152 $ module load b 1153 $ module load --force a 1154 WARNING: a conflicts with b 1155 $ module list 1156 Currently Loaded Modulefiles: 1157 1) b 2) a 1158 $ module purge 1159 $ module load --force c 1160 WARNING: c requires a loaded 1161 $ module list 1162 Currently Loaded Modulefiles: 1163 1) c 1164 1165``--force`` also enables to unload a modulefile required by another loaded 1166modulefiles:: 1167 1168 $ module load a c 1169 $ module list 1170 Currently Loaded Modulefiles: 1171 1) a 2) c 1172 $ module unload --force a 1173 WARNING: a is required by c 1174 $ module list 1175 Currently Loaded Modulefiles: 1176 1) c 1177 1178In a situation where some of the loaded modulefiles have unsatisfied 1179constraints corresponding to the **prereq** and **conflict** they declare, the 1180**save** and **reload** sub-commands do not perform and return an error. 1181 1182.. _v42-automated-module-handling-mode: 1183 1184Automated module handling mode 1185^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1186 1187An automatic management of the dependencies between modulefiles has been added 1188and it is called *automated module handling mode*. This new mode consists in 1189additional actions triggered when loading or unloading a modulefile to satisfy 1190the constraints it declares. 1191 1192When loading a modulefile, following actions are triggered: 1193 1194* Requirement Load (ReqLo): load of the modulefiles declared as a **prereq** 1195 of the loading modulefile. 1196 1197* Dependent Reload (DepRe): reload of the modulefiles declaring a **prereq** 1198 onto loaded modulefile or declaring a **prereq** onto a modulefile part of 1199 this reloading batch. 1200 1201When unloading a modulefile, following actions are triggered: 1202 1203* Dependent Unload (DepUn): unload of the modulefiles declaring a non-optional 1204 **prereq** onto unloaded modulefile or declaring a non-optional **prereq** 1205 onto a modulefile part of this unloading batch. A **prereq** modulefile is 1206 considered optional if the **prereq** definition order is made of multiple 1207 modulefiles and at least one alternative modulefile is loaded. 1208 1209* Useless Requirement Unload (UReqUn): unload of the **prereq** modulefiles 1210 that have been automatically loaded for either the unloaded modulefile, an 1211 unloaded dependent modulefile or a modulefile part of this useless 1212 requirement unloading batch. Modulefiles are added to this unloading batch 1213 only if they are not required by any other loaded modulefiles. 1214 ``MODULES_LMNOTUASKED`` environment variable helps to keep track of these 1215 automatically loaded modulefiles and to distinguish them from modulefiles 1216 asked by user. 1217 1218* Dependent Reload (DepRe): reload of the modulefiles declaring a **conflict** 1219 or an optional **prereq** onto either the unloaded modulefile, an unloaded 1220 dependent or an unloaded useless requirement or declaring a **prereq** onto 1221 a modulefile part of this reloading batch. 1222 1223In case a loaded modulefile has some of its declared constraints unsatisfied 1224(pre-required modulefile not loaded or conflicting modulefile loaded for 1225instance), this loaded modulefile is excluded from the automatic reload 1226actions described above. 1227 1228For the specific case of the **switch** sub-command, where a modulefile is 1229unloaded to then load another modulefile. Dependent modulefiles to Unload are 1230merged into the Dependent modulefiles to Reload that are reloaded after the 1231load of the switched-to modulefile. 1232 1233This automated module handling mode integrates concepts (like the Dependent 1234Reload mechanism) of the Flavours_ extension, which was designed for Modules 1235compatibility version. As a whole, automated module handling mode can be seen 1236as a generalization and as an expansion of the Flavours_ concepts. 1237 1238.. _Flavours: https://sourceforge.net/projects/flavours/ 1239 1240This new feature can be controlled at build time with the 1241``--enable-auto-handling`` configure option. This default configuration can be 1242superseded at run-time with the ``MODULES_AUTO_HANDLING`` environment variable 1243or the command line switches ``--auto`` and ``--no-auto``. 1244 1245By default, automated module handling mode is disabled and will stay so until 1246the next major release version (5.0) where it will be enabled by default. This 1247new feature is currently considered experimental and the set of triggered 1248actions will be refined over the next feature releases. 1249 1250.. _v42-consistency-module-load-unload-commands: 1251 1252Consistency of module load/unload commands in modulefile 1253^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1254 1255With the **module load** modulefile command, a given modulefile can 1256automatically load a modulefile it pre-requires. Similarly with the **module 1257unload** modulefile command, a given modulefile can automatically unload a 1258modulefile it conflicts with. 1259 1260Both commands imply additional actions on the loaded environment (loading or 1261unloading extra modulefiles) that should cope with the constraints defined by 1262the loaded environment. 1263 1264Additionally **module load** and **module unload** modulefile commands express 1265themselves constraints on loaded environment that should stay satisfied to 1266ensure consistency. 1267 1268To ensure the consistency of **module load** modulefile command once the 1269modulefile defining it has been loaded, this command is assimilated to a 1270**prereq** command. Thus the defined constraint is recorded in the 1271``MODULES_LMPREREQ`` environment variable. Same approach is used for **module 1272unload** modulefile command which is assimilated to a **conflict** command. 1273Thus the defined constraint is recorded in the ``MODULES_LMCONFLICT`` 1274environment variable. 1275 1276To ensure the consistency of the loaded environment, the additional actions of 1277the **module load** and **module unload** modulefile commands have been 1278adapted in particular situations: 1279 1280* When unloading modulefile, **module load** command will unload the 1281 modulefile it targets only if no other loaded modulefile requires it and if 1282 this target has not been explicitly loaded by user. 1283 1284* When unloading modulefile, **module unload** command does nothing as the 1285 relative conflict registered at load time ensure environment consistency and 1286 will forbid conflicting modulefile load. 1287 1288Please note that loading and unloading results may differ than from previous 1289Modules version now that consistency is checked: 1290 1291* Modulefile targeted by a **module load** modulefile command may not be able 1292 to load due to a registered conflict in the currently loaded environment. 1293 Which in turn will break the load of the modulefile declaring the **module 1294 load** command. 1295 1296* Modulefile targeted by a **module unload** modulefile command may not be 1297 able to unload due to a registered prereq in the loaded environment. Which 1298 in turn will break the load of the modulefile declaring the **module 1299 unload** command. 1300 1301* If automated module handling mode is enabled, **module load** modulefile 1302 command is interpreted when unloading modulefile as part of the Useless 1303 Requirement Unload (UReqUn) mechanism not through modulefile evaluation. 1304 As a consequence, an error occurring when unloading the modulefile targeted 1305 by the **module load** command does not break the unload of the modulefile 1306 declaring this command. Moreover unload of the **module load** targets is 1307 done in the reverse loaded order, not in the **module load** command 1308 definition order. 1309 1310.. _v42-alias-symbolic-name-consistency: 1311 1312Modulefile alias and symbolic modulefile name consistency 1313^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1314 1315With the **module-alias** and **module-version** modulefile commands, 1316alternative names can be given to a modulefile. When these names are used to 1317load for instance a modulefile, they are resolved to the modulefile they 1318target which is then processed for the load action. 1319 1320Until now, the alias and symbolic version names were correctly resolved for 1321the **load** and **unload** actions and also for the querying sub-commands 1322(like **avail** or **whatis**). However this alternative name information 1323vanishes once the modulefile it resolves to is loaded. As a consequence there 1324was no consistency over these alternative designations. In the following 1325example ``f`` modulefile declares a conflict on ``e`` alias which resolves to 1326``d`` modulefile:: 1327 1328 $ module load e 1329 $ module list 1330 Currently Loaded Modulefiles: 1331 1) d 1332 $ module info-loaded e 1333 $ module load f 1334 $ module list 1335 Currently Loaded Modulefiles: 1336 1) d 2) f 1337 1338Consistency of the alternative names set on a modulefile with **module-alias** 1339and **module-version** commands is now ensured to enable modulefile commands 1340**prereq**, **conflict**, **is-loaded** and **module-info loaded** using these 1341alternative designations as argument. This consistency is achieved, like for 1342the conflict and prereq consistencies, by keeping track of the alternative 1343names of the loaded modulefiles in an environment variable called 1344``MODULES_LMALTNAME``:: 1345 1346 $ module load e 1347 $ module list 1348 Currently Loaded Modulefiles: 1349 1) d 1350 $ module info-loaded e 1351 d 1352 $ module load f 1353 WARNING: f cannot be loaded due to a conflict. 1354 HINT: Might try "module unload e" first. 1355 $ module list 1356 Currently Loaded Modulefiles: 1357 1) d 1358 1359.. _v42-variable-change-through-modulefile-evaluation: 1360 1361Environment variable change through modulefile evaluation context 1362^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1363 1364All environment variable edition commands (``setenv``, ``unsetenv``, 1365``append-path``, ``prepend-path`` and ``remove-path``) have been updated to: 1366 1367* Reflect environment variable value change on the environment of the current 1368 modulefile Tcl interpreter. So using ``$env(VAR)`` will return the currently 1369 defined value for environment variable ``VAR``, not the one found prior 1370 modulefile evaluation. 1371* Clear environment variable content instead of unsetting it on the 1372 environment of the current modulefile Tcl interpreter to avoid raising 1373 error about accessing an undefined element in ``$env()``. Code is still 1374 produced to purely unset environment variable in shell environment. 1375 1376Exception is made for the ``whatis`` evaluation mode: environment variables 1377targeted by variable edition commands are not set to the defined value in the 1378evaluation context during this ``whatis`` evaluation. These variables are 1379only initialized to an empty value if undefined. This exception is made to 1380save performances on this global evaluation mode. 1381 1382.. _v42-versioned-magic-cookie: 1383 1384Express Modules compatibility of modulefile with versioned magic cookie 1385^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1386 1387Any modulefile should start with the ``#%Module`` magic cookie and sometimes 1388a version number may be placed right after this string. Until now this 1389version number corresponded to a modulefile format version but it was never 1390checked. 1391 1392Starting with this new Modules release, this version number reflects the 1393minimum version of Modules required to interpret the modulefile. If the 1394version number is set along the magic cookie string it is now checked and the 1395modulefile is interpreted only if Modules version is greater or equal to this 1396version number. For instance, if a modulefile begins with the ``#%Module4.3`` 1397string, it can only be evaluated by Modules version 4.3 and above. Elsewhere 1398the modulefile is ignored like files without the ``#%Module`` magic cookie 1399set. 1400 1401.. _v42-module-message-report: 1402 1403Improved module message report 1404^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1405 1406Module sub-commands like ``load``, ``unload`` or ``switch``, may perform 1407multiple load or unload modulefile evaluations in a row. Also these kind of 1408evaluation modes may sometimes trigger additional load or unload evaluations, 1409when for instance a modulefile contains a ``module load`` command. 1410 1411To improve the readability of the module messages produced relatively to 1412a load or an unload evaluation, these messages are now stacked under a 1413*Loading* or an *Unloading* message block that gathers all the messages 1414produced for a given modulefile evaluation:: 1415 1416 $ module load --no-auto foo 1417 Loading foo/1.2 1418 ERROR: foo/1.2 cannot be loaded due to missing prereq. 1419 HINT: the following module must be loaded first: bar/4.5 1420 1421In addition, foreground ``load``, ``unload``, ``switch`` and ``restore`` 1422actions (ie. asked on the command-line) now report a summary of the 1423additional load and unload evaluations that were eventually triggered in 1424the process:: 1425 1426 $ module load --auto foo 1427 Loading foo/1.2 1428 Loading requirement: bar/4.5 1429 1430New modulefile commands 1431^^^^^^^^^^^^^^^^^^^^^^^ 1432 14332 new modulefile Tcl commands have been introduced: 1434 1435* **set-function**: define a shell function on sh-kind and fish shells. 1436* **unset-function**: unset a shell function on sh-kind and fish shells. 1437 1438Further reading 1439--------------- 1440 1441To get a complete list of the changes between Modules v4.1 and v4.2, 1442please read the :ref:`NEWS` document. 1443 1444 1445Migrating from v4.0 to v4.1 1446=========================== 1447 1448This new version is backward-compatible with v4.0 and primarily fixes bugs and 1449adds new features. 1450 1451New features 1452------------ 1453 1454Version 4.1 introduces a bunch of new functionalities. These major new 1455features are described in this section. 1456 1457Virtual modules 1458^^^^^^^^^^^^^^^ 1459 1460A virtual module stands for a module name associated to a modulefile. The 1461modulefile is the script interpreted when loading or unloading the virtual 1462module which appears or can be found with its virtual name. 1463 1464The **module-virtual** modulefile command is introduced to give the ability 1465to define these virtual modules. This new command takes a module name as 1466first argument and a modulefile location as second argument:: 1467 1468 module-virtual app/1.2.3 /path/to/virtualmod/app 1469 1470With this feature it is now possible to dynamically define modulefiles 1471depending on the context. 1472 1473Extend module command with site-specific Tcl code 1474^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1475 1476``module`` command can now be extended with site-specific Tcl 1477code. ``modulecmd.tcl`` now looks at a **siteconfig.tcl** file in an 1478``etcdir`` defined at configure time (by default ``$prefix/etc``). If 1479it finds this Tcl script file, it is sourced within ``modulecmd.tcl`` at the 1480beginning of the main procedure code. 1481 1482``siteconfig.tcl`` enables to supersede any global variable or procedure 1483definitions made in ``modulecmd.tcl`` with site-specific code. A module 1484sub-command can for instance be redefined to make it fit local needs 1485without having to touch the main ``modulecmd.tcl``. 1486 1487Quarantine mechanism to protect module execution 1488^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1489 1490To protect the module command run-time environment from side effect 1491coming from the current environment definition a quarantine mechanism 1492is introduced. This mechanism, sets within module function definition 1493and shell initialization script, modifies the ``modulecmd.tcl`` run-time 1494environment to sanitize it. 1495 1496The mechanism is piloted by environment variables. First of all 1497``MODULES_RUN_QUARANTINE``, a space-separated list of environment variable 1498names. Every variable found in ``MODULES_RUN_QUARANTINE`` will be set in 1499quarantine during the ``modulecmd.tcl`` run-time. Their value will be set 1500empty or set to the value of the corresponding ``MODULES_RUNENV_<VAR>`` 1501environment variable if defined. Once ``modulecmd.tcl`` is started it 1502restores quarantine variables to their original values. 1503 1504``MODULES_RUN_QUARANTINE`` and ``MODULES_RUNENV_<VAR>`` environment variables 1505can be defined at build time by using the following configure option:: 1506 1507 --with-quarantine-vars='VARNAME[=VALUE] ...' 1508 1509Quarantine mechanism is available for all supported shells except ``csh`` 1510and ``tcsh``. 1511 1512Pager support 1513^^^^^^^^^^^^^ 1514 1515The informational messages Modules sends on the *stderr* channel may 1516sometimes be quite long. This is especially the case for the avail 1517sub-command when hundreds of modulefiles are handled. To improve the 1518readability of those messages, *stderr* output can now be piped into a 1519paging command. 1520 1521This new feature can be controlled at build time with the ``--with-pager`` 1522and ``--with-pager-opts`` configure options. Default pager command is set 1523to ``less`` and its relative options are by default ``-eFKRX``. Default 1524configuration can be supersedes at run-time with ``MODULES_PAGER`` environment 1525variables or command-line switches (``--no-pager``, ``--paginate``). 1526 1527.. warning:: On version ``4.1.0``, the ``PAGER`` environment variable was 1528 taken in consideration to supersede pager configuration at run-time. Since 1529 version ``4.1.1``, ``PAGER`` environment variable is ignored to avoid side 1530 effects coming from the system general pager configuration. 1531 1532Module function to return value in scripting languages 1533^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1534 1535On Tcl, Perl, Python, Ruby, CMake and R scripting shells, module function 1536was not returning value and until now an occurred error led to raising a 1537fatal exception. 1538 1539To make ``module`` function more friendly to use on these scripting shells 1540it now returns a value. False in case of error, true if everything goes well. 1541 1542As a consequence, returned value of a module sub-command can be checked. For 1543instance in Python:: 1544 1545 if module('load', 'foo'): 1546 # success 1547 else: 1548 # failure 1549 1550New modulefile commands 1551^^^^^^^^^^^^^^^^^^^^^^^ 1552 15534 new modulefile Tcl commands have been introduced: 1554 1555* **is-saved**: returns true or false whether a collection, corresponding to 1556 currently set collection target, exists or not. 1557* **is-used**: returns true or false whether a given directory is currently 1558 enabled in ``MODULEPATH``. 1559* **is-avail**: returns true or false whether a given modulefile exists in 1560 currently enabled module paths. 1561* **module-info loaded**: returns the exact name of the modulefile currently 1562 loaded corresponding to the name argument. 1563 1564Multiple collections, paths or modulefiles can be passed respectively to 1565``is-saved``, ``is-used`` and ``is-avail`` in which case true is returned if 1566at least one argument matches condition (acts as a OR boolean operation). No 1567argument may be passed to ``is-loaded``, ``is-saved`` and ``is-used`` 1568commands to return if anything is respectively loaded, saved or used. 1569 1570If no loaded modulefile matches the ``module-info loaded`` query, an empty 1571string is returned. 1572 1573New module sub-commands 1574^^^^^^^^^^^^^^^^^^^^^^^ 1575 1576Modulefile-specific commands are sometimes wished to be used outside of a 1577modulefile context. Especially for the commands managing path variables 1578or commands querying current environment context. So the following 1579modulefile-specific commands have been made reachable as module sub-commands 1580with same arguments and properties as if called from within a modulefile: 1581 1582* **append-path** 1583* **prepend-path** 1584* **remove-path** 1585* **is-loaded** 1586* **info-loaded** 1587 1588The ``is-loaded`` sub-command returns a boolean value. Small Python example:: 1589 1590 if module('is-loaded', 'app'): 1591 print 'app is loaded' 1592 else: 1593 print 'app not loaded' 1594 1595``info-loaded`` returns a string value and is the sub-command counterpart 1596of the ``module-info loaded`` modulefile command:: 1597 1598 $ module load app/0.8 1599 $ module info-loaded app 1600 app/0.8 1601 1602Further reading 1603--------------- 1604 1605To get a complete list of the changes between Modules v4.0 and v4.1, 1606please read the :ref:`NEWS` document. 1607 1608 1609Migrating from v3.2 to v4.0 1610=========================== 1611 1612Major evolution occurs with this v4.0 release as the traditional *module* 1613command implemented in C is replaced by the native Tcl version. This full 1614Tcl rewrite of the Modules package was started in 2002 and has now reached 1615maturity to take over the binary version. This flavor change enables to 1616refine and push forward the *module* concept. 1617 1618This document provides an outlook of what is changing when migrating from 1619v3.2 to v4.0 by first describing the introduced new features. Both v3.2 1620and v4.0 are quite similar and transition to the new major version should 1621be smooth. Slights differences may be noticed in a few use-cases. So the 1622second part of the document will help to learn about them by listing the 1623features that have been discontinued in this new major release or the 1624features where a behavior change can be noticed. 1625 1626New features 1627------------ 1628 1629On its overall this major release brings a lot more robustness to the 1630*module* command with now more than 4000 non-regression tests crafted 1631to ensure correct operations over the time. This version 4.0 also comes 1632with fair amount of improved functionalities. The major new features are 1633described in this section. 1634 1635Additional shells supported 1636^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1637 1638Modules v4 introduces support for **fish**, **lisp**, **tcl** and **R** 1639code output. 1640 1641Non-zero exit code in case of error 1642^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1643 1644All module sub-commands will now return a non-zero exit code in case of error 1645whereas Modules v3.2 always returned zero exit code even if issue occurred. 1646 1647Output redirect 1648^^^^^^^^^^^^^^^ 1649 1650Traditionally the *module* command output text that should be seen by the 1651user on *stderr* since shell commands are output to *stdout* to change 1652shell's environment. Now on *sh*, *bash*, *ksh*, *zsh* and *fish* shells, 1653output text is redirected to *stdout* after shell command evaluation if 1654shell is in interactive mode. 1655 1656Filtering avail output 1657^^^^^^^^^^^^^^^^^^^^^^ 1658 1659Results obtained from the **avail** sub-command can now be filtered to only 1660get the default version of each module name with use of the **--default** 1661or **-d** command line switch. Default version is either the explicitly 1662set default version or the highest numerically sorted modulefile or module 1663alias if no default version set. 1664 1665It is also possible to filter results to only get the highest numerically 1666sorted version of each module name with use of the **--latest** or **-L** 1667command line switch. 1668 1669Extended support for module alias and symbolic version 1670^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1671 1672Module aliases are now included in the result of the **avail**, **whatis** 1673and **apropos** sub-commands. They are displayed in the module path 1674section where they are defined or in a *global/user modulerc* section for 1675aliases set in user's or global ``modulerc`` file. A **@** symbol is added 1676in parenthesis next to their name to distinguish them from modulefiles. 1677 1678Search may be performed with an alias or a symbolic version-name passed 1679as argument on **avail**, **whatis** and **apropos** sub-commands. 1680 1681Modules v4 resolves module alias or symbolic version passed to **unload** 1682command to then remove the loaded modulefile pointed by the mentioned 1683alias or symbolic version. 1684 1685A symbolic version sets on a module alias is now propagated toward the 1686resolution path to also apply to the relative modulefile if it still 1687correspond to the same module name. 1688 1689Hiding modulefiles 1690^^^^^^^^^^^^^^^^^^ 1691 1692Visibility of modulefiles can be adapted by use of file mode bits or file 1693ownership. If a modulefile should only be used by a given subset of persons, 1694its mode an ownership can be tailored to provide read rights to this group of 1695people only. In this situation, module only reports the modulefile, during an 1696**avail** command for instance, if this modulefile can be read by the current 1697user. 1698 1699These hidden modulefiles are simply ignored when walking through the 1700modulepath content. Access issues (permission denied) occur only when trying 1701to access directly a hidden modulefile or when accessing a symbol or an alias 1702targeting a hidden modulefile. 1703 1704Improved modulefiles location 1705^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1706 1707When looking for an implicit default in a modulefile directory, aliases 1708are now taken into account in addition to modulefiles and directories to 1709determine the highest numerically sorted element. 1710 1711Modules v4 resolves module alias or symbolic version when it points to a 1712modulefile located in another modulepath. 1713 1714Access issues (permission denied) are now distinguished from find issues 1715(cannot locate) when trying to access directly a directory or a modulefile 1716as done on **load**, **display** or **whatis** commands. In addition, 1717on this kind of access not readable ``.modulerc`` or ``.version`` files are 1718ignored rather producing a missing magic cookie error. 1719 1720Module collection 1721^^^^^^^^^^^^^^^^^ 1722 1723Modules v4 introduces support for module *collections*. Collections 1724describe a sequence of **module use** then **module load** commands that 1725are interpreted by Modules to set the user environment as described by this 1726sequence. When a collection is activated, with the **restore** sub-command, 1727modulepaths and loaded modules are unused or unloaded if they are not part 1728or if they are not ordered the same way as in the collection. 1729 1730Collections are generated by the **save** sub-command that dumps the current 1731user environment state in terms of modulepaths and loaded modules. By default 1732collections are saved under the ``$HOME/.module`` directory. Collections 1733can be listed with **savelist** sub-command, displayed with **saveshow** 1734and removed with **saverm**. 1735 1736Collections may be valid for a given target if they are suffixed. In this 1737case these collections can only be restored if their suffix correspond 1738to the current value of the ``MODULES_COLLECTION_TARGET`` environment 1739variable. Saving collection registers the target footprint by suffixing 1740the collection filename with ``.$MODULES_COLLECTION_TARGET``. 1741 1742Path variable element counter 1743^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1744 1745Modules 4 provides path element counting feature which increases a 1746reference counter each time a given path entry is added to a given 1747path-like environment variable. As consequence a path entry element is 1748removed from a path-like variable only if the related element counter is 1749equal to 1. If this counter is greater than 1, path element is kept in 1750variable and reference counter is decreased by 1. 1751 1752This feature allows shared usage of particular path elements. For instance, 1753modulefiles can append ``/usr/local/bin`` to ``PATH``, which is not unloaded 1754until all the modulefiles that loaded it unload too. 1755 1756Optimized I/O operations 1757^^^^^^^^^^^^^^^^^^^^^^^^ 1758 1759Substantial work has been done to reduce the number of I/O operations 1760done during global modulefile analysis commands like **avail** or 1761**whatis**. ``stat``, ``open``, ``read`` and ``close`` I/O operations have 1762been cut down to the minimum required when walking through the modulepath 1763directories to check if files are modulefiles or to resolve module aliases. 1764 1765Interpretation of modulefiles and modulerc are handled by the minimum 1766required Tcl interpreters. Which means a configured Tcl interpreter is 1767reused as much as possible between each modulefile interpretation or 1768between each modulerc interpretation. 1769 1770Sourcing modulefiles 1771^^^^^^^^^^^^^^^^^^^^ 1772 1773Modules 4 introduces the possibility to **source** a modulefile rather 1774loading it. When it is sourced, a modulefile is interpreted into the shell 1775environment but then it is not marked loaded in shell environment which 1776differ from **load** sub-command. 1777 1778This functionality is used in shell initialization scripts once **module** 1779function is defined. There the ``etc/modulerc`` modulefile is sourced to 1780setup the initial state of the environment, composed of *module use* 1781and *module load* commands. 1782 1783 1784Removed features and substantial behavior changes 1785------------------------------------------------- 1786 1787Following sections provide list of Modules v3.2 features that are 1788discontinued on Modules v4 or features with a substantial behavior change 1789that should be taken in consideration when migrating to v4. 1790 1791Package initialization 1792^^^^^^^^^^^^^^^^^^^^^^ 1793 1794``MODULESBEGINENV`` environment snapshot functionality is not supported 1795anymore on Modules v4. Modules collection mechanism should be used instead to 1796**save** and **restore** sets of enabled modulepaths and loaded modulefiles. 1797 1798Command line switches 1799^^^^^^^^^^^^^^^^^^^^^ 1800 1801Some command line switches are not supported anymore on v4.0. When still 1802using them, a warning message is displayed and the command is ran with these 1803unsupported switches ignored. Following command line switches are concerned: 1804 1805* ``--force``, ``-f`` 1806* ``--human`` 1807* ``--verbose``, ``-v`` 1808* ``--silent``, ``-s`` 1809* ``--create``, ``-c`` 1810* ``--icase``, ``-i`` 1811* ``--userlvl`` lvl, ``-u`` lvl 1812 1813Module sub-commands 1814^^^^^^^^^^^^^^^^^^^ 1815 1816During an **help** sub-command, Modules v4 does not redirect output made 1817on stdout in *ModulesHelp* Tcl procedure to stderr. Moreover when running 1818**help**, version 4 interprets all the content of the modulefile, then call 1819the *ModulesHelp* procedure if it exists, whereas Modules 3.2 only interprets 1820the *ModulesHelp* procedure and not the rest of the modulefile content. 1821 1822When **load** is asked on an already loaded modulefiles, Modules v4 ignores 1823this new load order whereas v3.2 refreshed shell alias definitions found 1824in this modulefile. 1825 1826When **switching** on version 4 an *old* modulefile by a *new* one, 1827no error is raised if *old* modulefile is not currently loaded. In this 1828situation v3.2 threw an error and abort switch action. Additionally on 1829**switch** sub-command, *new* modulefile does not keep the position held 1830by *old* modulefile in loaded modules list on Modules v4 as it was the 1831case on v3.2. Same goes for path-like environment variables: replaced 1832path component is appended to the end or prepended to the beginning of 1833the relative path-like variable, not appended or prepended relatively to 1834the position hold by the swapped path component. 1835 1836During a **switch** command, version 4 interprets the swapped-out modulefile 1837in *unload* mode, so the sub-modulefiles loaded, with ``module load`` 1838order in the swapped-out modulefile are also unloaded during the switch. 1839 1840Modules 4 provides path element counting feature which increases a reference 1841counter each time a given path entry is added to a given environment 1842variable. This feature also applies to the ``MODULEPATH`` environment 1843variable. As consequence a modulepath entry element is removed from the 1844modulepath enabled list only if the related element counter is equal to 1. 1845When **unusing** a modulepath if its reference counter is greater than 1, 1846modulepath is kept enabled and reference counter is decreased by 1. 1847 1848On Modules 3.2 paths composing the ``MODULEPATH`` environment variable 1849may contain reference to environment variable. These variable references 1850are resolved dynamically when ``MODULEPATH`` is looked at during module 1851sub-command action. This feature has been discontinued on Modules v4. 1852 1853Following Modules sub-commands are not supported anymore on v4.0: 1854 1855* ``clear`` 1856* ``update`` 1857 1858 1859Modules specific Tcl commands 1860^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1861 1862Modules v4 provides path element counting feature which increases a reference 1863counter each time a given path entry is added to a given environment 1864variable. As a consequence a path entry element is not always removed 1865from a path-like variable when calling to ``remove-path`` or calling to 1866``append-path`` or ``append-path`` at unloading time. The path element is 1867removed only if its related element counter is equal to 1. If this counter 1868is greater than 1, path element is kept in variable and reference counter 1869is decreased by 1. 1870 1871On Modules v4, **module-info mode** returns during an **unload** sub-command 1872the ``unload`` value instead of ``remove`` on Modules v3.2. However if 1873*mode* is tested against ``remove`` value, true will be returned. During a 1874**switch** sub-command on Modules v4, ``unload`` then ``load`` is returned 1875instead of ``switch1`` then ``switch2`` then ``switch3`` on Modules 1876v3.2. However if *mode* is tested against ``switch`` value, true will 1877be returned. 1878 1879When using **set-alias**, Modules v3.2 defines a shell function when 1880variables are in use in alias value on Bourne shell derivatives, Modules 18814 always defines a shell alias never a shell function. 1882 1883Some Modules specific Tcl commands are not supported anymore on v4.0. When 1884still using them, a warning message is displayed and these unsupported Tcl 1885commands are ignored. Following Modules specific Tcl commands are concerned: 1886 1887* ``module-info flags`` 1888* ``module-info trace`` 1889* ``module-info tracepat`` 1890* ``module-info user`` 1891* ``module-log`` 1892* ``module-trace`` 1893* ``module-user`` 1894* ``module-verbosity`` 1895 1896 1897Further reading 1898--------------- 1899 1900To get a complete list of the differences between Modules v3.2 and v4, 1901please read the :ref:`diff_v3_v4` document. 1902 1903A significant number of issues reported for v3.2 have been closed on v4. 1904List of these closed issues can be found at: 1905 1906https://github.com/cea-hpc/modules/milestone/1?closed=1 1907