Debian Codegraph @

doc/source/changes.rst

raw
1 .. _changes:
2
3 Changes between versions
4 ========================
5
6 This document lists functionality differences between each major version of Modules. The goal of each following section is to reference the features of previous major version that are missing or behave differently on the next major version and the features that can only be found on this newer version. For instance the `Modules 4`_ section lists the changes compared to Modules 3.2.
7
8 Regarding deprecated or newly introduced features, this document only lists their name or the command line argument related to them. Please refer to the :ref:`module(1)` and the :ref:`modulefile(5)` man pages of the previous or newer Modules version to learn the details about these removed or added features.
9
10
11 .. _Modules 4 changes:
12
13 Modules 4
14 ---------
15
16 This section provides the list of differences with Modules version 3.2. This version of Modules is also referred in this document as *compatibility version*. Modules 4 is based on what was previously called Modules-Tcl. Comparison takes as a basis version ``3.2.10`` of compatibility version against Modules version ``4.0``. Any change made past these versions will explicitly mention the release number starting from the difference appears or disappears.
17
18 .. note:: The numerous bugs or limitations spotted on Modules ``3.2`` across the years have been fixed in Modules ``4.0``. The list of reported issues that have been solved are available on `the project code forge <https://github.com/envmodules/modules/milestone/1?closed=1>`_.
19
20 Removed or changed features
21 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
22
23 This section describes the features of the compatibility version that are not supported or that behave differently on Modules 4.
24
25
26 Package Initialization
27 """"""""""""""""""""""
28
29 :envvar:`MODULESBEGINENV` environment snapshot functionality is not supported on version 4. Modules collection mechanism should be preferred to save and restore sets of enabled modulepaths and loaded modulefiles. Modules 4 also introduces a system configuration file *init/modulerc*, located in Modules installation directory. Starting version ``4.3``, this file could also be *etc/initrc*. This *modulerc*/*initrc* file is sourced by Modules shell initialization scripts and helps to setup the initial environment right after initializing the :command:`module` command.
30
31
32 Command line switches
33 """""""""""""""""""""
34
35 **--human**
36
37 **--create**, **-c**
38
39 **--userlvl** lvl, **-u** lvl
40
41 These command line switches are not supported on Modules 4. When these options are passed on the command-line, it produces an *Unsupported option* warning and command is ran with the unsupported switches ignored.
42
43 **--ter**
44
45 **--lon**
46
47 **--sil**
48
49 **--verb**
50
51 These intermediate-form command line switches are not supported on Modules 4. Short or long switch name should be used instead.
52
53 :option:`-h`
54
55 This command line switch is short version of :option:`--help` switch on Modules 4 whereas it is short version of **--human** switch on compatibility version.
56
57 :option:`--force`, :option:`-f`
58
59 This command line switch was not supported starting Modules version ``4.0`` but reintroduced starting version ``4.2`` with a different meaning: instead of enabling an active dependency resolution mechanism ``--force`` command line switch now enables to by-pass dependency consistency when loading or unloading a *modulefile*.
60
61 :option:`--verbose`, :option:`-v`
62
63 :option:`--silent`, :option:`-s`
64
65 These command line switches were not supported starting Modules version ``4.0`` but reintroduced starting version ``4.3``. However, reintroduced :option:`--silent` switch does not redirect stderr channel to ``/dev/null`` if stderr is found not to be a tty.
66
67 :option:`--icase`, :option:`-i`
68
69 This command line switch was not supported starting Modules version ``4.0`` but reintroduced starting version ``4.4``. When :option:`--icase` switch is now set it applies to search query string and module specification on all sub-commands and modulefile Tcl commands.
70
71
72 Module Sub-Commands
73 """""""""""""""""""
74 On compatibility version, paths composing the :envvar:`MODULEPATH` environment variable may contain reference to environment variable. These variable references are resolved dynamically when :envvar:`MODULEPATH` is looked at during module sub-command action like :subcmd:`avail`. This feature was missing on Modules ``4.0`` but it has been re-introduced on Modules ``4.1``.
75
76 :subcmd:`update`
77
78 This module sub-commands is not supported on Modules 4.
79
80 :subcmd:`clear`
81
82 This command line switch was not supported starting Modules version ``4.0`` but reintroduced starting version ``4.3``. It now takes into account the :option:`--force` command-line switch to skip confirmation dialog.
83
84 :subcmd:`refresh`
85
86 On compatibility version, only the shell aliases defined by the currently loaded modulefiles are set again on a :subcmd:`refresh` command. Whereas on Modules 4 this command is an alias on the :subcmd:`reload` command that :subcmd:`unload` then :subcmd:`load` all the currently loaded modulefiles.
87
88 :subcmd:`help`
89
90 Compatibility version redirects output made on stdout in ``ModulesHelp`` Tcl procedure to stderr.
91
92 During an :subcmd:`help` sub-command, only the ``ModulesHelp`` Tcl procedure of a modulefile is interpreted on compatibility version. Version 4 interprets all the content of the modulefile, then call the ``ModulesHelp`` procedure if it exists.
93
94 On version 4, ``ModulesHelp`` subroutine is not ran if an error occurred during the interpretation of the *modulefile* main body.
95
96 :subcmd:`display`
97
98 On version 4, ``ModulesDisplay`` subroutine is not ran if an error occurred during the interpretation of the *modulefile* main body.
99
100 :subcmd:`avail`
101
102 On compatibility version, the same Tcl interpreter is used for the interpretation of all *.modulerc* or *.version* files during an :subcmd:`avail` command but the state of this interpreter is not reset between each interpretation. So some variable and procedure definitions may spread from one interpretation to another on this compatibility version. Modules 4 reuses the same interpreter for all *.modulerc* or *.version* interpretation but it is cleaned between each interpretation to protect from definition spread.
103
104 In case of :option:`--terse` or :option:`--long` mode, all enabled modulepaths will be displayed whether they hold result to display or not. Modules 4 outputs only the modulepaths where matching results are found. Modulepaths with no result to report are discarded from output.
105
106 :subcmd:`apropos`
107
108 On Modules 4, *string* passed as argument is always searched in a case insensitive manner.
109
110 :subcmd:`load`
111
112 On Modules 4, the value of an environment variable is set even if the new value is the same as the current value of this variable in environment.
113
114 When an already loaded *modulefiles* is asked for load again, compatibility version will refresh the shell alias definition this modulefile hold if any, whereas Modules 4 will ignore the new load order.
115
116 In case of *modulefile* loading another modulefile, if sub-modulefile load fails calling modulefile will still be loaded on compatibility version whereas Modules 4 will also abort calling modulefile load. Compatibility version behavior could be restored by enclosing ``module load`` command and arguments within ``catch`` Tcl command.
117
118 Starting with version ``4.1``, content sent to the ``stdout`` channel during a *modulefile* interpretation is spooled to effectively transmit this content to stdout after rendering the environment changes made by this modulefile.
119
120 :subcmd:`unload`
121
122 On Modules 4, the value of an environment variable is set even if the new value is the same as the current value of this variable in environment.
123
124 Compatibility version enables to load a *modulefile* by passing on the command-line the name of a module alias or symbolic version pointing to this modulefile. However this module alias or symbolic version name cannot be used to unload the modulefile once loaded. Modules 4 enables to pass a module alias or symbolic version name to unload a loaded modulefile referred by this name.
125
126 On versions ``4.0`` and ``4.1``, unloading an nonexistent modulefile generates an *Unable to locate modulefile* error. Starting with version ``4.2``, unloading a module only looks at loaded module list and does not trigger a modulefile search. So starting version ``4.2`` the same behavior than Modules compatibility version is obtained.
127
128 Starting with version ``4.1``, content sent to the ``stdout`` channel during a *modulefile* interpretation is spooled to effectively transmit this content to stdout after rendering the environment changes made by this modulefile.
129
130 When the specified module to unload matches multiple loaded modules, Modules 4 unloads lastly loaded module whereas compatibility version unloads firstly loaded module. A configuration option ``unload_match_order`` has been introduced in version ``4.3`` and it enables to restore the behavior of compatibility version when it is set to ``returnfirst``.
131
132 :subcmd:`switch`
133
134 When switching on version 4 an *old* modulefile by a *new* one, no error is raised if *old* modulefile is not currently loaded. In this situation compatibility version throws an error and abort switch action.
135
136 When switching on Modules 4 an *old* modulefile by a *new* one, this *new* modulefile does not keep the position that the *old* modulefile had in the :envvar:`LOADEDMODULES` list as done on compatibility version but it is appended to the end of the list. Same goes for PATH-like environment variables: replaced PATH component is appended to the end or prepended to the beginning of the relative PATH-like variable, not appended or prepended relatively to the position hold by the swapped PATH component.
137
138 When a modulefile loads another modulefile with a *module load* order, this sub-module is not unloaded when the top modulefile is swapped-out during a :subcmd:`switch` command on compatibility version. Version 4 interprets the swapped-out modulefile in unload mode, so the *module load* order is interpreted as *module unload* order and sub-module is unloaded.
139
140 :subcmd:`use`
141
142 When the modulepath to enable is passed as a relative path, compatibility version will set it using passed relative name whereas Modules 4 will determine the corresponding absolute path and will register it rather passed relative name.
143
144 :subcmd:`unuse`
145
146 Modules 4 provides path element counting feature which increases a reference counter each time a given path entry is added to a given environment variable. This feature also applies to the :envvar:`MODULEPATH` environment variable. As consequence a modulepath entry element is removed from the modulepath enabled list only if the related element counter is equal to 1. When unusing a modulepath if its reference counter is greater than 1, modulepath is kept enabled and reference counter is decreased by 1.
147
148 :subcmd:`whatis`
149
150 On Modules 4, environment variable edition commands (*setenv*, *unsetenv*, *append-path*, *prepend-path* and *remove-path*) do no set variable to the defined value on the modulefile evaluation context during a :subcmd:`whatis` evaluation. Instead environment variables are initialized with an empty value if undefined, to avoid raising error when attempting access to an undefined element during the modulefile evaluation.
151
152 :subcmd:`initadd`
153
154 :subcmd:`initprepend`
155
156 :subcmd:`initswitch`
157
158 On version 4 no message is displayed to give details on how list of modulefiles to load has been altered in initialization file.
159
160 :subcmd:`initrm`
161
162 No message is displayed on Modules 4 to inform of the modulefiles that have been removed from the loading list in initialization file.
163
164 Empty ``module load`` line is left on version 4 when last modulefile from a line is asked to be removed. On compatibility version ``module load null`` line is set in this case.
165
166 :subcmd:`initclear`
167
168 Empty ``module load`` lines are left on version 4 whereas ``module load null`` lines are set on compatibility version.
169
170
171 Modules Specific Tcl Commands
172 """""""""""""""""""""""""""""
173
174 On version 4 the characters that have a special meaning when rendered in shells are escaped when used in value to set environment variables, shell alias or shell functions. Thus it is possible to set environment elements with value containing these special characters (like backticks). On version 3 these special characters were evaluated by shell when recording the environment changes implied by modulefile evaluation.
175
176 :mfcmd:`append-path`
177
178 :mfcmd:`prepend-path`
179
180 Modules 4 produces an error when adding a bare colon character *:* as a path element to a path-like variable, as this colon cannot be distinguished from the colon used for path separator.
181
182 Modules 4 supports adding or removing empty path element to a path-like variable, whereas compatibility version looses track of this path element when the path-like variable is modified afterward. Empty path element enables to set a leading colon character *:*, which has a specific meaning on some regular environment variable like :envvar:`MANPATH` or :envvar:`LD_LIBRARY_PATH`.
183
184 When adding a path element to the :envvar:`MANPATH` environment variable, Modules 4 is treating this variable like any other whereas a special treatment was applied on compatibility version: a default MANPATH value, set at configure time, was appended in case :envvar:`MANPATH` variable was unset.
185
186 :mfcmd:`remove-path`
187
188 Modules 4 provides path element counting feature which increases a reference counter each time a given path entry is added to a given environment variable. As consequence a path entry element is removed from a path-like variable only if the related element counter is equal to 1. If this counter is greater than 1, path element is kept in variable and reference counter is decreased by 1.
189
190 When unloading a modulefile, :mfcmd:`remove-path` command is not applied to environment variable on Modules 4, whereas on compatibility version it is processed the exact same way than when loading modulefile.
191
192 :mfcmd:`exit`
193
194 On Modules 4 code passed to the :mfcmd:`exit` Modules specific Tcl command will not be thrown to be the :command:`module` return value.
195
196 :mfcmd:`module-alias`
197
198 :mfcmd:`module-version`
199
200 In case the specified aliased module or the symbolic version introduces a resolution loop with already defined aliases or symbolic versions, this new alias or symbolic version is not registered and an error message is raised. On compatibility version, alias or symbolic version introducing loop are registered as the modulefile resolution is not computed at registration time.
201
202 :mfcmd:`module-info`
203
204 **module-info flags**
205
206 **module-info trace**
207
208 **module-info tracepat**
209
210 **module-info user**
211
212 These :mfcmd:`module-info` options are related to compatibility version-specific features so they are available on Modules 4 but with a dummy implementation that always returns false or an empty value.
213
214 **module-info mode**
215
216 During an :subcmd:`unload` sub-command, ``unload`` is returned instead of ``remove``. However if *mode* is tested against ``remove`` value, true will be returned.
217
218 During a :subcmd:`switch` sub-command, ``unload`` then ``load`` is returned instead of ``switch1`` then ``switch2`` then ``switch3``. However if *mode* is tested against ``switch`` value, true will be returned.
219
220 **module-info name**
221
222 If the module name passed to the command-line has been specified as a full path name, the **module-info name** used in modulefile returns this file base name on compatibility version whereas it returns on Modules 4+ the full path name as it is identified by this name once loaded.
223
224 **module-info version**
225
226 Declared aliases or symbolic versions are not registered anymore if they introduce a resolution loop. As a result **module-info version** does not return an ``*undef*`` string value as it does not face resolution loop situation anymore.
227
228 **module-info symbols**
229
230 Declared aliases or symbolic versions are not registered anymore if they introduce a resolution loop. As a consequence symbolic versions introducing loop situation are not part anymore of the **module-info symbols** returned result as they are not registered.
231
232 A symbolic version sets on a module alias will be propagated toward the resolution path to also apply to the relative *modulefile* if it still correspond to the same module name.
233
234 :mfcmd:`module-log`
235
236 :mfcmd:`module-trace`
237
238 :mfcmd:`module-user`
239
240 :mfcmd:`module-verbosity`
241
242 These Modules specific Tcl commands are related to compatibility version-specific features so they are available on Modules 4 but with a dummy implementation that always displays a warning message saying the command is not implemented.
243
244 :mfcmd:`module-whatis`
245
246 When multiple words are passed as argument to :mfcmd:`module-whatis` but they are not enclosed in double-quotes or curly braces they will be displayed as a single line on Modules 4 whereas compatibility version displays them as one line per word.
247
248 :mfcmd:`set-alias`
249
250 Whereas compatibility version sets a shell function when variables are in use in alias value on Bourne shell derivatives, Modules 4 always defines a shell alias never a shell function.
251
252 :mfcmd:`setenv`
253
254 On compatibility version the :mfcmd:`setenv` modulefile command accepts any number of argument, but ignores all arguments after the first two. An error is raised on Modules 4 when more than two arguments are passed to the :mfcmd:`setenv` modulefile command.
255
256 Locating Modulefiles
257 """"""""""""""""""""
258
259 On version 4, when a module alias is set and overrides name of an existing directory, this alias is taken into account to locate the default version of this module name and the *modulefiles* locating in the directory are ignored.
260
261 When looking for an implicit default in a *modulefile* directory, aliases are taken into account in addition to *modulefiles* and directories to determine the highest numerically sorted element.
262
263 Modules 4 will resolve module alias or symbolic version passed to :subcmd:`unload` command to then remove the loaded modulefile pointed by the mentioned alias or symbolic version.
264
265 Modules 4 resolves module alias or symbolic version pointing to a *modulefile* located in another modulepath.
266
267 When locating *modulefiles* on Modules 4, if a *.modulerc*, a *.version*, a directory or a *modulefile* cannot be read during the search it is simply ignored with no error message produced. Visibility of *modulefiles* can thus be adapted to the rights the user has been granted. Exception is made when trying to directly access a directory or a *modulefile*. In this case, the access issue is returned as an error message. Access issue is also returned when a direct access is made to a module alias or a symbolic version targeting an unreadable *modulefile*.
268
269
270 New features
271 ^^^^^^^^^^^^
272
273 This section describes the features of Modules version 4 that are not supported on the compatibility version. Please refer to the above section for features supported by both versions but behaving differently.
274
275
276 Package Initialization
277 """"""""""""""""""""""
278
279 Support for *fish*, *lisp*, *tcl* and *R* code output has been introduced on Modules ``4.0``.
280
281 On version 4 and for *sh*, *bash*, *ksh*, *zsh* and *fish* shells, text output, like listing from the :subcmd:`avail` command, is redirected from *stderr* to *stdout* after shell command evaluation if shell is in interactive mode. Starting version ``4.1``, this content redirection occurs if shell session is attached to a terminal.
282
283 Starting version ``4.5``, a new alias or function called :command:`ml` may be defined at initialization time, to provide a handy frontend to the :command:`module` command.
284
285 Starting version ``4.5``, support for Windows *cmd* shell is introduced.
286
287 Modulecmd startup
288 """""""""""""""""
289
290 Starting with version ``4.1``, :file:`modulecmd.tcl` sources upon invocation a site-specific configuration script named :file:`siteconfig.tcl`. This Tcl script enables to supersede any global variable or procedure definition of modulecmd.tcl.
291
292
293 Command line switches
294 """""""""""""""""""""
295
296 The following command line switches appeared on Modules 4.
297
298 +------------+-----------------------------------------------------------------+
299 | Introduced | New command line switches |
300 | in version | |
301 +============+=================================================================+
302 | 4.0 | :option:`--debug`, :option:`-D`, :option:`--default`, |
303 | | :option:`-d`, :option:`--latest`, :option:`-L` |
304 +------------+-----------------------------------------------------------------+
305 | 4.1 | :option:`--paginate`, :option:`--no-pager` |
306 +------------+-----------------------------------------------------------------+
307 | 4.2 | :option:`--auto`, :option:`--no-auto` |
308 +------------+-----------------------------------------------------------------+
309 | 4.3 | :option:`--indepth`, :option:`--no-indepth`, :option:`--color`, |
310 | | :option:`--starts-with`, :option:`-S`, :option:`--contains`, |
311 | | :option:`-C` |
312 +------------+-----------------------------------------------------------------+
313 | 4.5 | :option:`--json`, :option:`-j` |
314 +------------+-----------------------------------------------------------------+
315 | 4.6 | :option:`--trace`, :option:`-T`, :option:`--all`, :option:`-a`, |
316 | | :option:`-DD` |
317 +------------+-----------------------------------------------------------------+
318 | 4.7 | :option:`-vv`, :option:`--output`, :option:`-o`, |
319 | | :option:`--width`, :option:`-w` |
320 +------------+-----------------------------------------------------------------+
321
322 :option:`--long`, :option:`--terse`
323
324 Starting Modules 4.0, :subcmd:`savelist` sub-command is supported.
325
326 :option:`--all`
327
328 Starting Modules 4.7, :subcmd:`list` sub-command is supported.
329
330
331 Module Sub-Commands
332 """""""""""""""""""
333
334 The following module sub-commands appeared on Modules 4.
335
336 +------------+-----------------------------------------------------------------+
337 | Introduced | New module sub-commands |
338 | in version | |
339 +============+=================================================================+
340 | 4.0 | :subcmd:`reload`, :subcmd:`source`, :subcmd:`search`, |
341 | | :subcmd:`save`, :subcmd:`restore`, :subcmd:`saverm`, |
342 | | :subcmd:`saveshow`, :subcmd:`savelist`, :subcmd:`path`, |
343 | | :subcmd:`paths`, :subcmd:`autoinit`, :subcmd:`aliases`, |
344 | | :subcmd:`test` |
345 +------------+-----------------------------------------------------------------+
346 | 4.1 | :subcmd:`append-path`, :subcmd:`prepend-path`, |
347 | | :subcmd:`remove-path`, :subcmd:`is-loaded`, :subcmd:`is-saved` |
348 | | :subcmd:`is-used`, :subcmd:`is-avail`, :subcmd:`info-loaded` |
349 +------------+-----------------------------------------------------------------+
350 | 4.3 | :subcmd:`config` |
351 +------------+-----------------------------------------------------------------+
352 | 4.6 | :subcmd:`sh-to-mod` |
353 +------------+-----------------------------------------------------------------+
354 | 4.8 | :subcmd:`edit`, :subcmd:`try-load` |
355 +------------+-----------------------------------------------------------------+
356
357 All module sub-commands will return a non-zero exit code in case of error whereas on compatibility version issues that occurred do not lead to an exit of the :command:`module` command with a non-zero code.
358
359 Starting with version ``4.1``, :command:`module` function for all scripting languages, like Perl or Python, always returns a value. In case of error, a *false* boolean value is returned instead of raising a fatal exception. For module sub-commands returning a text value, the module function will actually return this value. In all other cases a *true* boolean value is returned.
360
361 :subcmd:`avail`, :subcmd:`whatis` and :subcmd:`apropos`
362
363 Non-critical errors are not displayed on :subcmd:`avail`, :subcmd:`whatis` and :subcmd:`apropos` sub-commands. Only valid results are returned.
364
365 Module aliases are included in the result of these sub-commands. They are displayed in the module path section where they are defined or in a *global/user modulerc* section for aliases set in user's or global modulerc file. A ``@`` symbol is added in parenthesis next to their name to distinguish them from *modulefiles*.
366
367 Search may be performed with an alias or a symbolic version-name passed as argument.
368
369 Arguments to these :subcmd:`avail`, :subcmd:`whatis` and :subcmd:`apropos` commands may use wildcard characters to express glob patterns.
370
371
372 Collections
373 """""""""""
374
375 Modules :ref:`collections` have been introduced on Modules ``4.0``.
376
377
378 Environment
379 """""""""""
380
381 The following environment variables appeared on Modules 4.
382
383 +------------+-----------------------------------------------------------------+
384 | Introduced | New environment variables |
385 | in version | |
386 +============+=================================================================+
387 | 4.0 | :envvar:`MODULECONTACT`, :envvar:`MODULES_COLLECTION_TARGET`, |
388 | | :envvar:`MODULES_USE_COMPAT_VERSION`, |
389 | | :envvar:`<VAR>_modshare<__MODULES_SHARE_\<VAR\>>` |
390 +------------+-----------------------------------------------------------------+
391 | 4.1 | :envvar:`MODULES_CMD`, :envvar:`MODULES_COLLECTION_PIN_VERSION`,|
392 | | :envvar:`MODULES_PAGER`, :envvar:`MODULES_RUNENV_\<VAR\>`, |
393 | | :envvar:`MODULES_RUN_QUARANTINE`, |
394 | | :envvar:`MODULES_SILENT_SHELL_DEBUG`, |
395 | | :envvar:`<VAR>_modquar<__MODULES_QUAR_<VAR>>` |
396 +------------+-----------------------------------------------------------------+
397 | 4.2 | :envvar:`MODULES_AUTO_HANDLING`, |
398 | | :envvar:`MODULES_LMALTNAME<__MODULES_LMALTNAME>`, |
399 | | :envvar:`MODULES_LMCONFLICT<__MODULES_LMCONFLICT>`, |
400 | | ``MODULES_LMNOTUASKED``, |
401 | | :envvar:`MODULES_LMPREREQ<__MODULES_LMPREREQ>` |
402 +------------+-----------------------------------------------------------------+
403 | 4.3 | :envvar:`MODULES_AVAIL_INDEPTH`, :envvar:`MODULES_COLOR`, |
404 | | :envvar:`MODULES_COLORS`, :envvar:`MODULES_IMPLICIT_DEFAULT`, |
405 | | :envvar:`MODULES_SEARCH_MATCH`, |
406 | | :envvar:`MODULES_SET_SHELL_STARTUP`, |
407 | | :envvar:`MODULES_SITECONFIG`, :envvar:`MODULES_TERM_BACKGROUND`,|
408 | | :envvar:`MODULES_UNLOAD_MATCH_ORDER`, |
409 | | :envvar:`MODULES_VERBOSITY`, :envvar:`MODULES_WA_277` |
410 +------------+-----------------------------------------------------------------+
411 | 4.4 | :envvar:`MODULES_ADVANCED_VERSION_SPEC`, |
412 | | :envvar:`MODULES_EXTENDED_DEFAULT`, :envvar:`MODULES_ICASE` |
413 +------------+-----------------------------------------------------------------+
414 | 4.5 | :envvar:`MODULES_ML` |
415 +------------+-----------------------------------------------------------------+
416 | 4.6 | :envvar:`MODULES_LMSOURCESH<__MODULES_LMSOURCESH>`, |
417 | | :envvar:`MODULES_NEARLY_FORBIDDEN_DAYS` |
418 +------------+-----------------------------------------------------------------+
419 | 4.7 | :envvar:`MODULES_SHELLS_WITH_KSH_FPATH`, |
420 | | :envvar:`MODULES_IMPLICIT_REQUIREMENT`, |
421 | | :envvar:`MODULES_LMTAG<__MODULES_LMTAG>`, |
422 | | :envvar:`MODULES_TAG_ABBREV`, :envvar:`MODULES_TAG_COLOR_NAME`, |
423 | | :envvar:`MODULES_MCOOKIE_VERSION_CHECK` |
424 | | :envvar:`MODULES_AVAIL_OUTPUT`, |
425 | | :envvar:`MODULES_AVAIL_TERSE_OUTPUT`, |
426 | | :envvar:`MODULES_LIST_OUTPUT`, |
427 | | :envvar:`MODULES_LIST_TERSE_OUTPUT`, |
428 | | :envvar:`MODULES_TERM_WIDTH` |
429 +------------+-----------------------------------------------------------------+
430 | 4.8 | :envvar:`MODULES_EDITOR`, :envvar:`MODULES_VARIANT_SHORTCUT`, |
431 | | :envvar:`MODULES_LMVARIANT<__MODULES_LMVARIANT>` |
432 +------------+-----------------------------------------------------------------+
433
434
435 Modules Specific Tcl Commands
436 """""""""""""""""""""""""""""
437
438 The following modulefile Tcl commands appeared on Modules 4.
439
440 +------------+-----------------------------------------------------------------+
441 | Introduced | New modulefile Tcl commands |
442 | in version | |
443 +============+=================================================================+
444 | 4.0 | :mfcmd:`module-info command<module-info>`, :mfcmd:`getenv`, |
445 | | :mfcmd:`report`, :mfcmd:`reportError`, :mfcmd:`reportWarning` |
446 +------------+-----------------------------------------------------------------+
447 | 4.1 | :mfcmd:`module-info loaded<module-info>`, :mfcmd:`is-saved`, |
448 | | :mfcmd:`is-used`, :mfcmd:`is-avail`, :mfcmd:`module-virtual` |
449 +------------+-----------------------------------------------------------------+
450 | 4.2 | :mfcmd:`set-function`, :mfcmd:`unset-function` |
451 +------------+-----------------------------------------------------------------+
452 | 4.6 | :mfcmd:`source-sh`, :mfcmd:`module-hide`, |
453 | | :mfcmd:`module-forbid`, |
454 | | :mfcmd:`module-info usergroups<module-info>`, |
455 | | :mfcmd:`module-info username<module-info>` |
456 +------------+-----------------------------------------------------------------+
457 | 4.7 | :mfcmd:`versioncmp`, :mfcmd:`module-tag`, |
458 | | :mfcmd:`module-info tags<module-info>` |
459 +------------+-----------------------------------------------------------------+
460 | 4.8 | :mfcmd:`variant`, :mfcmd:`getvariant` |
461 +------------+-----------------------------------------------------------------+
462
463 :mfcmd:`conflict` and :mfcmd:`prereq`
464
465 Starting with version ``4.2``, these Modules-specific Tcl commands support being called with a symbolic modulefile or a modulefile alias passed as argument.
466
467 :mfcmd:`getenv`
468
469 Starting with version ``4.2``, an optional *value* argument is added on :mfcmd:`getenv` to define the value to return in case environment variable is not set.
470
471 :mfcmd:`module`
472
473 In case of ``module load`` command specifying multiple *modulefiles*, when mode is set to ``unload`` these *modulefiles* will be unloaded in the reverse order to ensure correct handling of prerequisites.
474
475 Starting with version ``4.7``, the ``load``, ``unload`` and ``switch`` sub-commands support the ``--not-req`` option to avoid recording a prereq or a conflict requirement toward specified modules.
476
477 :mfcmd:`append-path` and :mfcmd:`prepend-path`
478
479 Starting with version ``4.1``, both commands handle being called with multiple *value* arguments and option ``--duplicates`` is added.
480
481 :mfcmd:`remove-path`
482
483 Starting with version ``4.1``, :mfcmd:`remove-path` handles being called with multiple *value* arguments and option ``--index`` is added.
484
485 :mfcmd:`is-loaded`
486
487 Starting with version ``4.1``, :mfcmd:`is-loaded` supports being called with no argument passed. In this case, it returns *true* if any modulefile is currently loaded, *false* otherwise.
488
489 Starting with version ``4.2``, :mfcmd:`is-loaded` supports being called with a symbolic modulefile or a modulefile alias passed as argument.
490
491 This Modules-specific Tcl command was not enabled for *modulerc* evaluation starting Modules version ``4.0`` but it has been reintroduced starting version ``4.2.1``.
492
493
494 Modules Variables
495 """""""""""""""""
496
497 The following Modules-specific Tcl variables appeared on Modules 4.
498
499 +------------+-----------------------------------------------------------------+
500 | Introduced | New Modules-specific Tcl variables |
501 | in version | |
502 +============+=================================================================+
503 | 4.7 | :mfvar:`ModuleTool`, :mfvar:`ModuleToolVersion` |
504 +------------+-----------------------------------------------------------------+
505 | 4.8 | :mfvar:`ModuleVariant` |
506 +------------+-----------------------------------------------------------------+
507
508
509 Modules configuration options
510 """""""""""""""""""""""""""""
511
512 The concept of configuration option has been introduced on Modules ``4.3``. The
513 following Modules configuration option has been introduced on Modules 4.
514
515 +------------+-----------------------------------------------------------------+
516 | Introduced | New Modules configuration options |
517 | in version | |
518 +============+=================================================================+
519 | 4.3 | :mconfig:`auto_handling`, :mconfig:`avail_indepth`, |
520 | | :mconfig:`collection_pin_version`, :mconfig:`collection_target`,|
521 | | :mconfig:`color`, :mconfig:`colors`, :mconfig:`contact`, |
522 | | :mconfig:`extra_siteconfig`, :mconfig:`implicit_default`, |
523 | | :mconfig:`locked_configs`, :mconfig:`pager`, :mconfig:`rcfile`, |
524 | | :mconfig:`run_quarantine`, :mconfig:`silent_shell_debug`, |
525 | | :mconfig:`search_match`, :mconfig:`set_shell_startup`, |
526 | | :mconfig:`term_background`, :mconfig:`unload_match_order`, |
527 | | :mconfig:`verbosity`, :mconfig:`wa_277` |
528 +------------+-----------------------------------------------------------------+
529 | 4.4 | :mconfig:`advanced_version_spec`, :mconfig:`extended_default`, |
530 | | :mconfig:`home`, :mconfig:`icase` |
531 +------------+-----------------------------------------------------------------+
532 | 4.5 | :mconfig:`ml` |
533 +------------+-----------------------------------------------------------------+
534 | 4.6 | :mconfig:`nearly_forbidden_days` |
535 +------------+-----------------------------------------------------------------+
536 | 4.7 | :mconfig:`avail_output`, :mconfig:`avail_terse_output`, |
537 | | :mconfig:`implicit_requirement`, :mconfig:`list_output`, |
538 | | :mconfig:`list_terse_output`, :mconfig:`mcookie_version_check`, |
539 | | :mconfig:`shells_with_ksh_fpath`, :mconfig:`tag_abbrev`, |
540 | | :mconfig:`tag_color_name`, :mconfig:`term_width` |
541 +------------+-----------------------------------------------------------------+
542 | 4.8 | :mconfig:`editor`, :mconfig:`variant_shortcut` |
543 +------------+-----------------------------------------------------------------+
544
545 :mconfig:`list_output`, :mconfig:`list_terse_output`
546
547 Starting version 4.8, element ``variant`` is added to the list of accepted
548 values. It is added to the default value list of :mconfig:`list_output`.
549
550
551 .. _Modules 5 changes:
552
553 Modules 5
554 ---------
555
556 This section provides the list of differences with Modules version 4.
557 Comparison takes as a basis version ``4.8`` against Modules version ``5.0``.
558 Any change made past these versions will explicitly mention the release number
559 starting from the difference appears or disappears.
560
561 Removed or changed features
562 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
563
564 This section describes the features of Modules 4 that are not supported or
565 that behave differently on Modules 5.
566
567 Package Initialization
568 """"""""""""""""""""""
569
570 The initialization configuration file :file:`initrc` and the
571 modulepath-specific configuration file :file:`modulespath` are now searched by
572 default in the ``etcdir`` instead of in the ``initdir``. Moreover these
573 configuration files are only searched in one location. Previously they were
574 searched in both ``etcdir`` and ``initdir`` locations by Modules
575 initialization process.
576
577 When initializing Modules, the :file:`initrc` configuration file is evaluated
578 in addition to the the :file:`modulespath` configuration file and not instead
579 of this file. :file:`initrc` is evaluated after :file:`modulespath` file.
580
581 Report the modules loading and unloading during the evaluation of the
582 :file:`initrc` configuration file. These report messages are disabled when the
583 :mconfig:`verbosity` configuration option is set to ``concise`` or ``silent``.
584
585 Enforce use of the Modules magic cookie (i.e., ``#%Module`` file signature) at
586 the start of :file:`initrc` configuration file. No evaluation occurs and an
587 error is produced if the magic cookie is missing or if the optional version
588 number placed after the cookie string is higher than the version of the
589 :file:`modulecmd.tcl` script in use.
590
591 Quarantine mechanism code in the Modules shell initialization scripts is now
592 always defined and mechanism always applies if some environment variables are
593 defined in :envvar:`MODULES_RUN_QUARANTINE`. Code in the :file:`modulecmd.tcl`
594 script to restore environment variables put in quarantine is now always
595 generated and applies if the :envvar:`__MODULES_QUARANTINE_SET` environment
596 variable is set to ``1``. By default on Modules 5 the :command:`module` shell
597 function definition is generated without quarantine support but it could be
598 enabled by setting :mconfig:`quarantine_support` to ``1`` in :file:`initrc`.
599
600 Code to silence shell debug properties in the Modules shell initialization
601 scripts is now always defined and mechanism applies if
602 :envvar:`MODULES_SILENT_SHELL_DEBUG` is set to ``1``. Code to silence shell
603 debug properties in the :command:`module` shell function could now be enabled
604 if :envvar:`MODULES_SILENT_SHELL_DEBUG` is set to ``1`` prior Modules
605 initialization or if the :mconfig:`silent_shell_debug` configuration option is
606 set to ``1`` in the :file:`initrc` configuration file. Option is set off by
607 default on Modules 5.
608
609 During the :subcmd:`autoinit` process, the environment variable
610 :envvar:`__MODULES_AUTOINIT_INPROGRESS` is checked and if it is found set to
611 ``1``, the initialization process immediately ends. If not, this environment
612 variable is set to ``1`` which ensures no initialization loop could occur,
613 especially when the :mconfig:`set_shell_startup` configuration option is set.
614
615 Modulecmd startup
616 """""""""""""""""
617
618 Enforce use of the Modules magic cookie (i.e., ``#%Module`` file signature) at
619 the start of global or user rc files. These files are not evaluated and an
620 error is produced if the magic cookie is missing or if the optional version
621 number placed after the cookie string is higher than the version of the
622 :file:`modulecmd.tcl` script in use.
623
624 Module Sub-Commands
625 """""""""""""""""""
626
627 :subcmd:`append-path`, :subcmd:`prepend-path`, :subcmd:`remove-path`
628
629 When sub-command is not called during a modulefile evaluation, the reference
630 counter associated with each entry in targeted environment variable is
631 ignored. In such context, a
632 :subcmd:`module append-path/prepend-path<prepend-path>` will not increase the
633 reference counter of a path entry already defined and a
634 :subcmd:`module remove-path<remove-path>` will remove specified path
635 whatever its reference counter value.
636
637 :subcmd:`display`
638
639 No error is raised when evaluating a modulefile without a value specified for
640 the :mfcmd:`variant` it defines. As a result, the unspecified variant is not
641 instantiated in the :mfvar:`ModuleVariant` array variable.
642
643 :subcmd:`load`
644
645 Reference counting mechanism is not anymore applied to the Modules-specific
646 path variables (like :envvar:`LOADEDMODULES`). As a result no
647 :envvar:`__MODULES_SHARE_\<VAR\>` variable is set in user environment for
648 these variables. Exception is made for :envvar:`MODULEPATH` environment
649 variable where the mechanism still applies.
650
651 :subcmd:`purge`
652
653 Starting with version 5.7, direct and indirect requirements of retained
654 sticky and super-sticky modules are kept loaded, even if those requirements
655 are not sticky themselves. The :mconfig:`sticky_purge` configuration
656 controls reporting for their skipped unload as well as for sticky modules.
657 With :option:`--force`, sticky modules and their requirements can be
658 unloaded, but super-sticky modules and their requirements remain loaded.
659
660 :subcmd:`refresh`
661
662 Sub-command evaluates all loaded modulefiles and re-apply the non-persistent
663 environment changes they define (i.e., shell aliases, shell functions and
664 command put on stdout channel). With this change the :subcmd:`refresh`
665 sub-command is restored to the behavior it had on Modules version 3.2.
666
667 :subcmd:`restore`, :subcmd:`source`
668
669 Only report the module load and unload directly triggered by these
670 sub-commands. Load and unload triggered by other modules are reported through
671 the automated module handling messages of the main modules.
672
673 :subcmd:`restore`
674
675 Starting Modules 5.2:
676
677 * if no argument is provided and if default collection does not exist,
678 initial environment is restored.
679 * *sticky* modules are unloaded when restoring a collection.
680
681 :subcmd:`source`
682
683 Enforce use of the Modules magic cookie (i.e., ``#%Module`` file signature) at
684 the start of any scriptfile passed for evaluation to the :subcmd:`source`
685 sub-command. These files are not evaluated and an error is produced if the
686 magic cookie is missing or if the optional version number placed after the
687 cookie string is higher than the version of the :file:`modulecmd.tcl` script
688 in use.
689
690 :subcmd:`saveshow`
691
692 Starting Modules 5.2, if no argument is provided and if default collection
693 does not exist, initial environment is displayed.
694
695 :subcmd:`use`
696
697 Non-existent modulepath is now accepted as argument.
698
699 Reference counting mechanism is ignored when sub-command is not called during
700 a modulefile evaluation. In such context, a :subcmd:`module use<use>` will
701 not increase the reference counter of a path entry already defined.
702
703 :subcmd:`unuse`
704
705 Reference counting mechanism is ignored when sub-command is not called during
706 a modulefile evaluation. In such context, a :subcmd:`module unuse<unuse>`
707 will remove specified path whatever its reference counter value.
708
709 Correctly handle several modulepaths specified as a single argument (i.e.,
710 ``/path/to/dir1:/path/to/dir2``).
711
712 Modules Specific Tcl Commands
713 """""""""""""""""""""""""""""
714
715 :mfcmd:`append-path`, :mfcmd:`prepend-path`
716
717 When an element is added to a path-like variable, add this element to the
718 associated reference counter variable (named
719 :envvar:`__MODULES_SHARE_\<VAR\>`) only when this element is added multiple
720 times to the path-like variable. When an element is removed from a path-like
721 variable, this element is removed from the reference counter variable when
722 its counter is equal to 1.
723
724 :mfcmd:`chdir`, :mfcmd:`module`, ``module-trace``, ``module-verbosity``,
725 ``module-user``, ``module-log``
726
727 These modulefile commands have been undeclared from the modulerc Tcl
728 interpreter on Modules 5. An error message is obtained if still used instead
729 of silently ignoring it.
730
731 :mfcmd:`getenv`
732
733 When passed environment variable is not defined, an empty string is returned
734 by default rather ``_UNDEFINED_``.
735
736 :mfcmd:`module`
737
738 Forbid use of :subcmd:`module source<source>` command in modulefile or in an
739 initialization rc file, the ``source`` Tcl command should be used instead.
740
741 Starting version ``5.1`` an error is raised when an unused option is set on
742 ``module use`` or ``module unuse`` commands.
743
744 :mfcmd:`unsetenv`
745
746 When running on an unload evaluation, do not unset designated environment
747 variable if no value to restore is provided.
748
749 Distinguish between being called on a unload evaluation without a value to
750 restore or with an empty string value to restore.
751
752 :mfcmd:`variant`
753
754 Starting version 5.1, :mfcmd:`variant` command accepts being called without a
755 list of accepted value defined. In this case, any value specified is
756 accepted.
757
758 Starting version 5.5, a valid variant name is only composed of the
759 ``[A-Za-z0-9_-]`` characters. It cannot start with ``-`` character and the
760 name as a whole cannot correspond to a number.
761
762 Locating Modulefiles
763 """"""""""""""""""""
764
765 As the :ref:`Advanced module version specifiers` mechanism is enabled by
766 default on Modules 5.0, several characters are made special and cannot be used
767 anymore in module name or version. These characters are ``@``, ``=``, ``~``,
768 ``+`` and ``,``. Also a module name cannot start with ``-`` character. Module
769 name is allowed to finish by one or more ``+`` character but ``+`` cannot be
770 used at the start or inside a module name.
771
772 Starting version 5.5, characters ``+`` and ``~`` may be part of module name or
773 version as long as the string part next to these character is not a valid
774 variant name.
775
776 Starting version 5.7, character ``-`` is considered a version number separator
777 for :mconfig:`extended_default` mechanism.
778
779 Environment
780 """""""""""
781
782 The following Modules environment variables have been changed on Modules 5.
783
784 +--------------------------------------+---------------------------------------------+
785 | Environment variable | Change |
786 +======================================+=============================================+
787 | :envvar:`MODULES_LMALTNAME` | Renamed to :envvar:`__MODULES_LMALTNAME` |
788 +--------------------------------------+---------------------------------------------+
789 | :envvar:`MODULES_LMCONFLICT` | Renamed to :envvar:`__MODULES_LMCONFLICT` |
790 +--------------------------------------+---------------------------------------------+
791 | :envvar:`MODULES_LMNOTUASKED` | Removed |
792 +--------------------------------------+---------------------------------------------+
793 | :envvar:`MODULES_LMPREREQ` | Renamed to :envvar:`__MODULES_LMPREREQ` |
794 +--------------------------------------+---------------------------------------------+
795 | :envvar:`MODULES_LMSOURCESH` | Renamed to :envvar:`__MODULES_LMSOURCESH` |
796 +--------------------------------------+---------------------------------------------+
797 | :envvar:`MODULES_LMTAG` | Renamed to :envvar:`__MODULES_LMTAG` |
798 +--------------------------------------+---------------------------------------------+
799 | :envvar:`MODULES_LMVARIANT` | Renamed to :envvar:`__MODULES_LMVARIANT` |
800 +--------------------------------------+---------------------------------------------+
801 | :envvar:`MODULES_USE_COMPAT_VERSION` | Removed |
802 +--------------------------------------+---------------------------------------------+
803 | :envvar:`<VAR>_modquar` | Renamed to :envvar:`__MODULES_QUAR_\<VAR\>` |
804 +--------------------------------------+---------------------------------------------+
805 | :envvar:`<VAR>_modshare` | Renamed to :envvar:`__MODULES_SHARE_\<VAR\>`|
806 +--------------------------------------+---------------------------------------------+
807
808 Modules configuration options
809 """""""""""""""""""""""""""""
810
811 The default value of the following Modules configuration option has been
812 changed on Modules 5.
813
814 +---------------------------------+------------------------+-------------------+
815 | Configuration option | Previous default value | New default value |
816 +=================================+========================+===================+
817 | :mconfig:`auto_handling` | ``0`` | ``1`` |
818 +---------------------------------+------------------------+-------------------+
819 | :mconfig:`extended_default` | ``0`` | ``1`` |
820 +---------------------------------+------------------------+-------------------+
821 | :mconfig:`advanced_version_spec`| ``0`` | ``1`` |
822 +---------------------------------+------------------------+-------------------+
823 | :mconfig:`color` | ``never`` | ``auto`` |
824 +---------------------------------+------------------------+-------------------+
825 | :mconfig:`icase` | ``never`` | ``search`` |
826 +---------------------------------+------------------------+-------------------+
827 | :mconfig:`set_shell_startup` | ``1`` | ``0`` |
828 +---------------------------------+------------------------+-------------------+
829 | :mconfig:`silent_shell_debug` | *undefined* | ``0`` |
830 +---------------------------------+------------------------+-------------------+
831
832 New features
833 ^^^^^^^^^^^^
834
835 Package Initialization
836 """"""""""""""""""""""
837
838 When initializing Modules, :subcmd:`refresh` the loaded modules in case some
839 user environment is already configured.
840
841 Starting version ``5.5``, support for Windows *pwsh* shell is introduced.
842
843 Siteconfig hooks
844 """"""""""""""""
845
846 Starting version ``5.7``, the ``add-hook`` siteconfig command is introduced
847 to register a procedure to run on a hook event, as a replacement for the
848 ``trace``/procedure-renaming techniques that bind to internal
849 implementation details.
850
851 The following hook events appeared on Modules 5.
852
853 +------------+-----------------------------------------------------------------+
854 | Introduced | New hook events |
855 | in version | |
856 +============+=================================================================+
857 | 5.7 | :mhook:`before-modulefile-eval`, :mhook:`after-modulefile-eval`,|
858 | | :mhook:`before-modulerc-eval`, :mhook:`after-modulerc-eval` |
859 +------------+-----------------------------------------------------------------+
860
861 Command line switches
862 """""""""""""""""""""
863
864 The following command line switches appeared on Modules 5.
865
866 +------------+-----------------------------------------------------------------+
867 | Introduced | New command line switches |
868 | in version | |
869 +============+=================================================================+
870 | 5.1 | :option:`--redirect`, :option:`--no-redirect`, :option:`--tag` |
871 +------------+-----------------------------------------------------------------+
872 | 5.2 | :option:`--timer` |
873 +------------+-----------------------------------------------------------------+
874 | 5.3 | :option:`--ignore-cache`, :option:`--ignore-user-rc` |
875 +------------+-----------------------------------------------------------------+
876 | 5.6 | :option:`--dumpname` |
877 +------------+-----------------------------------------------------------------+
878 | 5.7 | :option:`-p`, :option:`-P`, |
879 | | :option:`--no-modulepath-ignore` |
880 +------------+-----------------------------------------------------------------+
881
882 :option:`--output`
883
884 Starting Modules 5.3, this command line switch accepts value prefixed by
885 ``+`` or ``-`` which means value should respectively be appended to or
886 subtracted from current configuration option value.
887
888 Starting Modules 5.6, :subcmd:`spider` sub-command is supported.
889
890 :option:`--force`
891
892 Starting Modules 5.4, this command line switch by-passes *abort on error*
893 behavior. Modulefile is unloaded anyway when an evaluation error occurs if
894 :option:`--force` option is used.
895
896 :option:`--all`
897
898 Starting Modules 5.2, :subcmd:`lint` and :subcmd:`savelist` sub-commands are
899 supported.
900
901 Starting Modules 5.6, :subcmd:`spider` sub-command is supported.
902
903 :option:`--contains`, :option:`--starts-with`
904
905 Starting Modules 5.1, :subcmd:`list` sub-command is supported.
906
907 Starting Modules 5.2, :subcmd:`savelist` sub-command is supported.
908
909 Starting Modules 5.6, :subcmd:`spider` sub-command is supported.
910
911 :option:`--json`, :option:`--long`, :option:`--terse`
912
913 Starting Modules 5.2, :subcmd:`stashlist` sub-command is supported.
914
915 Starting Modules 5.6, :subcmd:`spider` sub-command is supported.
916
917 :option:`--default`, :option:`--latest`, :option:`--indepth`,
918 :option:`--no-indepth`
919
920 Starting Modules 5.6, :subcmd:`spider` sub-command is supported.
921
922 Module Sub-Commands
923 """""""""""""""""""
924
925 The following module sub-commands appeared on Modules 5.
926
927 +------------+-----------------------------------------------------------------+
928 | Introduced | New module sub-commands |
929 | in version | |
930 +============+=================================================================+
931 | 5.1 | :subcmd:`state`, :subcmd:`load-any` |
932 +------------+-----------------------------------------------------------------+
933 | 5.2 | :subcmd:`lint`, :subcmd:`mod-to-sh`, :subcmd:`reset`, |
934 | | :subcmd:`stash`, :subcmd:`stashpop`, :subcmd:`stashrm`, |
935 | | :subcmd:`stashshow`, :subcmd:`stashclear`, :subcmd:`stashlist` |
936 +------------+-----------------------------------------------------------------+
937 | 5.3 | :subcmd:`cachebuild`, :subcmd:`cacheclear` |
938 +------------+-----------------------------------------------------------------+
939 | 5.6 | :subcmd:`spider`, :subcmd:`update`, :subcmd:`disable`, |
940 | | :subcmd:`describe` |
941 +------------+-----------------------------------------------------------------+
942
943 :subcmd:`list`
944
945 Starting Modules 5.1:
946
947 * this sub-command accepts patterns to filter the loaded modules to list.
948 * the :option:`--starts-with` and :option:`--contains` options are supported
949 on this sub-command to provide the regular search match capabilities.
950
951 Starting Modules 5.3:
952
953 * Search query with just a variant set (no module name and version) is
954 accepted.
955
956 :subcmd:`refresh`
957
958 Starting Modules 5.2, only the loaded modules listed in the
959 :envvar:`__MODULES_LMREFRESH` environment variables are refreshed.
960
961 :subcmd:`restore`
962
963 Starting Modules 5.2, initial environment is restored when specified
964 collection name is ``__init__``.
965
966 :subcmd:`savelist`
967
968 Starting Modules 5.2:
969
970 * this sub-command accepts patterns to filter the named collections to list.
971 * the :option:`--starts-with` and :option:`--contains` options are supported
972 on this sub-command to provide the regular search match capabilities.
973 * the :option:`--all` option is supported on this sub-command not to limit to
974 the collection matching currently set collection target.
975
976 :subcmd:`saveshow`
977
978 Starting Modules 5.2, initial environment is displayed when specified
979 collection name is ``__init__``.
980
981 :subcmd:`sh-to-mod`
982
983 Starting Modules ``5.1``, this sub-command also tracks shell completion
984 changes for bash, tcsh and fish shells.
985
986 Shell mode ``bash-eval`` is introduced on Modules version ``5.4``.
987
988 :subcmd:`source`
989
990 Starting Modules 5.2, this sub-command accepts modulefile specification as
991 argument in addition to file path.
992
993 :subcmd:`avail`, :subcmd:`paths`, :subcmd:`whatis`
994
995 Starting Modules 5.3:
996
997 * variant specified in search query is taken into account to return available
998 modules matching the variant specification.
999 * when one variant is specified multiple times in search query, returned
1000 modules are those providing all the specified variant values.
1001 * Search query with just a variant set (no module name and version) is
1002 accepted.
1003 * :ref:`Extra specifier` is accepted in search query to query content of
1004 modulefiles.
1005
1006 Starting Modules 5.4:
1007
1008 * ``tag`` :ref:`extra specifier` is introduced.
1009 * set multiple values on extra specifier, each of them separated by comma
1010 character, to get modules matching any of these values (*OR* operator).
1011 * set multiple values on variant specification, each of them separated by
1012 comma character, to get modules providing any of these variant values (*OR*
1013 operator).
1014
1015 Starting Modules 5.5:
1016
1017 * ``not:`` prefix may be added to extra specifier criterion to select modules
1018 not matching specified values.
1019 * ``not:`` prefix may be added to variant specification to get modules not
1020 providing variant or not matching specified variant values.
1021
1022 Starting Modules 5.6:
1023
1024 * ``use`` :ref:`extra specifier` is introduced.
1025 * setting :envvar:`MODULEPATH` environment variable with :mfcmd:`append-path`
1026 or :mfcmd:`prepend-path` may also be queried with ``use`` extra specifier.
1027 * ``depends-on-any`` :ref:`extra specifier` is introduced.
1028 * result of a multi pattern search is consolidated under a single output
1029 * ``provide`` and ``provided-alias`` :ref:`extra specifier` are introduced.
1030
1031 :subcmd:`reload`
1032
1033 Starting Modules 5.4, support for :option:`--force` option is added on this
1034 sub-command.
1035
1036 :subcmd:`autoinit`
1037
1038 Starting Modules 5.5, definition of :command:`mogui` shell alias or function
1039 is added on this sub-command.
1040
1041 Starting Modules 5.7, directory where the ``env_modules`` Python module is
1042 installed (initialization directory by default, which can be changed with
1043 the :instopt:`--with-pythondir` installation option) is added to
1044 ``PYTHONPATH`` environment variable unless installation option
1045 :instopt:`--disable-set-pythonpath<--enable-set-pythonpath>` is used.
1046
1047 :subcmd:`lint`
1048
1049 Starting Modules 5.6, readable modulecache files are also linted when no
1050 module specification is provided as argument or if :file:`.modulecache` file
1051 is specifically linted.
1052
1053 :subcmd:`cachebuild`
1054
1055 Starting Modules 5.6, the minimal Modules version specified in the cache file
1056 header indicates the oldest Modules version compatible with this cache file
1057 (5.3), rather than the version that generated the cache file.
1058
1059 :subcmd:`update`
1060
1061 This sub-command is reintroduced (was part of Modules v3) as a simple alias
1062 of :subcmd:`reload` sub-command. No more support from ``MODULESBEGINENV``,
1063 initial environment handling now covers this use case.
1064
1065 Environment
1066 """""""""""
1067
1068 The following environment variables appeared on Modules 5.
1069
1070 +------------+-----------------------------------------------------------------+
1071 | Introduced | New environment variables |
1072 | in version | |
1073 +============+=================================================================+
1074 | 5.0 | :envvar:`MODULES_QUARANTINE_SUPPORT`, |
1075 | | :envvar:`__MODULES_QUARANTINE_SET`, |
1076 | | :envvar:`__MODULES_AUTOINIT_INPROGRESS` |
1077 +------------+-----------------------------------------------------------------+
1078 | 5.1 | :envvar:`MODULES_REDIRECT_OUTPUT`, |
1079 | | :envvar:`MODULES_MCOOKIE_CHECK`, |
1080 | | :envvar:`MODULES_FAMILY_\<NAME\>`, |
1081 | | :envvar:`__MODULES_PUSHENV_\<VAR\>`, |
1082 | | :envvar:`__MODULES_LMEXTRATAG`, |
1083 | | :envvar:`MODULES_COLLECTION_PIN_TAG` |
1084 +------------+-----------------------------------------------------------------+
1085 | 5.2 | :envvar:`MODULES_PROTECTED_ENVVARS`, |
1086 | | :envvar:`MODULES_TCL_LINTER`, |
1087 | | :envvar:`__MODULES_LMINIT`, |
1088 | | :envvar:`MODULES_RESET_TARGET_STATE`, |
1089 | | :envvar:`__MODULES_LMREFRESH` |
1090 +------------+-----------------------------------------------------------------+
1091 | 5.3 | :envvar:`MODULES_IGNORE_CACHE`, |
1092 | | :envvar:`MODULES_CACHE_BUFFER_BYTES`, |
1093 | | :envvar:`MODULES_CACHE_EXPIRY_SECS` |
1094 | | :envvar:`MODULES_IGNORE_USER_RC` |
1095 +------------+-----------------------------------------------------------------+
1096 | 5.4 | :envvar:`MODULES_STICKY_PURGE`, |
1097 | | :envvar:`MODULES_UNIQUE_NAME_LOADED`, |
1098 | | :envvar:`MODULES_ABORT_ON_ERROR`, |
1099 | | :envvar:`__MODULES_LMSTICKYRULE`, |
1100 | | :envvar:`MODULES_SOURCE_CACHE` |
1101 +------------+-----------------------------------------------------------------+
1102 | 5.5 | :envvar:`MODULES_HIDE_AUTO_LOADED`, :envvar:`MODULES_LOGGER`, |
1103 | | :envvar:`MODULES_LOGGED_EVENTS`, |
1104 | | :envvar:`MODULES_CONFLICT_UNLOAD`, |
1105 | | :envvar:`__MODULES_LMPREREQPATH` |
1106 +------------+-----------------------------------------------------------------+
1107 | 5.6 | :envvar:`MODULES_SPIDER_OUTPUT`, |
1108 | | :envvar:`MODULES_SPIDER_TERSE_OUTPUT`, |
1109 | | :envvar:`MODULES_SPIDER_INDEPTH`, |
1110 | | :envvar:`__MODULES_LMUSE`, |
1111 | | :envvar:`MODULES_REQUIRE_VIA` |
1112 +------------+-----------------------------------------------------------------+
1113 | 5.7 | :envvar:`MODULES_PATH_ENTRY_REORDER`, |
1114 | | :envvar:`MODULES_PAGINATE`, |
1115 | | :envvar:`MODULES_NON_EXPORTABLE_TAGS`, |
1116 | | :envvar:`MODULES_INFO_EXTENSION`, |
1117 | | :envvar:`MODULES_LINKED_ENVVARS`, |
1118 | | :envvar:`MODULES_INIT_ENVVARS`, |
1119 | | :envvar:`MODULES_DOMAINNAME`, |
1120 | | :envvar:`MODULES_MODULEPATH_IGNORE`, |
1121 | | :envvar:`MODULES_IGNORE_CACHE_SUBCMDS` |
1122 +------------+-----------------------------------------------------------------+
1123
1124 Modules Specific Tcl Commands
1125 """""""""""""""""""""""""""""
1126
1127 The following modulefile Tcl commands appeared on Modules 5.
1128
1129 +------------+-----------------------------------------------------------------+
1130 | Introduced | New modulefile Tcl commands |
1131 | in version | |
1132 +============+=================================================================+
1133 | 5.1 | :mfcmd:`add-property`, :mfcmd:`remove-property`, |
1134 | | :mfcmd:`extensions`, :mfcmd:`prereq-any`, |
1135 | | :mfcmd:`require-fullname`, :mfcmd:`depends-on`, |
1136 | | :mfcmd:`prereq-all`, :mfcmd:`always-load`, |
1137 | | :mfcmd:`module load-any<module>`, :mfcmd:`family`, |
1138 | | :mfcmd:`complete`, :mfcmd:`uncomplete`, :mfcmd:`pushenv` |
1139 +------------+-----------------------------------------------------------------+
1140 | 5.4 | :mfcmd:`modulepath-label` |
1141 +------------+-----------------------------------------------------------------+
1142 | 5.5 | :mfcmd:`hide-modulefile`, :mfcmd:`hide-version`, |
1143 | | :mfcmd:`lsb-release` |
1144 +------------+-----------------------------------------------------------------+
1145 | 5.6 | :mfcmd:`depends-on-any`, :mfcmd:`module-help`, |
1146 | | :mfcmd:`module-warn`, :mfcmd:`haveDynamicMPATH`, |
1147 | | :mfcmd:`provide` |
1148 +------------+-----------------------------------------------------------------+
1149 | 5.7 | :mfcmd:`modulepath-ignore` |
1150 +------------+-----------------------------------------------------------------+
1151
1152 :mfcmd:`system`, :mfcmd:`is-used`
1153
1154 Starting Modules 5.0, these modulefile commands are available from a modulerc
1155 evaluation context.
1156
1157 :mfcmd:`getenv`
1158
1159 Starting version 5.1, the ``--return-value`` option is added to return
1160 environment variable value or its fallback when modulefile is evaluated in
1161 *display* mode.
1162
1163 Starting version 5.7, this command is also available from module rc file
1164 context.
1165
1166 :mfcmd:`prereq`, :mfcmd:`module load/try-load/load-any/switch<module>`
1167
1168 Starting Modules 5.1, these modulefile commands accept the :option:`--tag`
1169 option.
1170
1171 :mfcmd:`prereq`, :mfcmd:`prereq-all`, :mfcmd:`always-load`,
1172 :mfcmd:`depends-on`
1173
1174 Starting Modules 5.2, these modulefile commands accept the ``--optional``
1175 option.
1176
1177 Starting Modules 5.5, these modulefile commands accept the ``--modulepath``
1178 option.
1179
1180 :mfcmd:`module try-load/load-any<module>`
1181
1182 Starting Modules 5.1, these modulefile commands accept the ``--not-req``
1183 option.
1184
1185 :mfcmd:`module unload<module>`
1186
1187 Starting version ``5.5`` all matching modules loaded and their dependent are
1188 unloaded if both :mconfig:`auto_handling` and :mconfig:`conflict_unload`
1189 configuration options are enabled.
1190
1191 Starting version ``5.6`` unloading a module that enables a modulepath unloads
1192 all loaded modules stored in this modulepath if :mconfig:`require_via`
1193 configuration option is enabled.
1194
1195 :mfcmd:`module unuse<module>`
1196
1197 Starting version ``5.1`` options ``--*-on-unload`` added to the
1198 :mfcmd:`remove-path` command are also added to the ``module unuse`` command.
1199
1200 :mfcmd:`puts`
1201
1202 Starting Modules 5.1, if content is sent to the ``prestdout`` channel, it is
1203 rendered as command to evaluate in current shell session and prior any other
1204 environment changes.
1205
1206 Starting Modules 5.5, if content is sent to the ``log`` channel, it is sent
1207 to the defined :mconfig:`logger` command.
1208
1209 :mfcmd:`remove-path`
1210
1211 Starting with version ``5.1``:
1212
1213 * the ``--remove-on-unload`` option is added to also remove value when
1214 modulefile is unloaded.
1215 * the ``--append-on-unload`` and ``--prepend-on-unload`` options are added to
1216 restore when modulefile is unloaded the value list unset at load time.
1217 * the ``--noop-on-unload`` option is added to perform no operation when
1218 modulefile is unloaded.
1219
1220 Starting with version ``5.4``, the ``--glob`` option is added to remove value
1221 matching a glob-style pattern.
1222
1223 :mfcmd:`setenv`
1224
1225 Starting with version ``5.1``, the ``--set-if-undef`` option is added to set
1226 environment variable when modulefile is loaded only if not yet defined.
1227
1228 Starting with version ``5.6``, value set can contain newline character.
1229 Exception for csh shell family where such character is chopped from value.
1230
1231 :mfcmd:`source-sh`
1232
1233 Starting Modules ``5.1``, this modulefile command also tracks shell
1234 completion changes for bash, tcsh and fish shells.
1235
1236 Shell mode ``bash-eval`` is introduced on Modules version ``5.4``.
1237
1238 ``--ignore`` option is introduced on Modules version ``5.4``.
1239
1240 :mfcmd:`unsetenv`
1241
1242 Starting with version ``5.1``:
1243
1244 * the ``--noop-on-unload`` option is added to perform no operation when
1245 modulefile is unloaded.
1246 * the ``--unset-on-unload`` option is added to also unset variable when
1247 modulefile is unloaded.
1248
1249 :mfcmd:`getvariant`
1250
1251 Starting version 5.1, the ``--return-value`` option is added to return
1252 variant value or its fallback when modulefile is evaluated in *display* mode.
1253
1254 :mfcmd:`module-tag`, :mfcmd:`module-hide`, :mfcmd:`module-forbid`
1255
1256 Starting with version 5.4:
1257
1258 * module can be specified with its full path file name to precisely target
1259 one modulefile.
1260 * module specification on which stickiness applies is recorded in loaded
1261 environment to determine if it is still satisfied when updating
1262 environment.
1263 * options ``--user`` and ``--group`` are added.
1264
1265 :mfcmd:`break`
1266
1267 Starting with version 5.4, a modulefile using :mfcmd:`break` may be unloaded
1268 anyway if forced. To forbid unload of a modulefile, it is now advised to tag
1269 it ``super-sticky`` with :mfcmd:`module-tag` command.
1270
1271 :mfcmd:`conflict`, :mfcmd:`family`
1272
1273 Starting with version ``5.5``, if :mconfig:`conflict_unload` and
1274 :mconfig:`auto_handling` configuration options are enabled, all matching
1275 loaded modules are unloaded.
1276
1277 :mfcmd:`modulepath-label`
1278
1279 Starting version 5.6, label is also used on :subcmd:`whatis` and
1280 :subcmd:`search` sub-command output.
1281
1282 :mfcmd:`module use<module>`, :mfcmd:`append-path MODULEPATH<append-path>`,
1283 :mfcmd:`prepend-path MODULEPATH<prepend-path>`
1284
1285 Starting with version 5.6, if :mconfig:`require_via` configuration option is
1286 enabled, modulefile enabling a modulepath is considered a requirement of the
1287 loaded modules stored in this path.
1288
1289 :mfcmd:`extensions`
1290
1291 Starting with version 5.6, :mfcmd:`extensions` becomes an alias of
1292 :mfcmd:`provide` modulefile command.
1293
1294 Modules Variables
1295 """""""""""""""""
1296
1297 The following Modules-specific Tcl variables appeared on Modules 5.
1298
1299 +------------+-----------------------------------------------------------------+
1300 | Introduced | New Modules-specific Tcl variables |
1301 | in version | |
1302 +============+=================================================================+
1303 | 5.1 | :mfvar:`ModuleVersion` |
1304 +------------+-----------------------------------------------------------------+
1305
1306
1307 Modules configuration options
1308 """""""""""""""""""""""""""""
1309
1310 The following Modules configuration option has been introduced on Modules 5.
1311
1312 +------------+-----------------------------------------------------------------+
1313 | Introduced | New Modules configuration options |
1314 | in version | |
1315 +============+=================================================================+
1316 | 5.0 | :mconfig:`quarantine_support` |
1317 +------------+-----------------------------------------------------------------+
1318 | 5.1 | :mconfig:`redirect_output`, :mconfig:`mcookie_check`, |
1319 | | :mconfig:`collection_pin_tag` |
1320 +------------+-----------------------------------------------------------------+
1321 | 5.2 | :mconfig:`tcl_linter`, :mconfig:`protected_envvars`, |
1322 | | :mconfig:`reset_target_state` |
1323 +------------+-----------------------------------------------------------------+
1324 | 5.3 | :mconfig:`ignore_cache`, :mconfig:`cache_buffer_bytes`, |
1325 | | :mconfig:`cache_expiry_secs`, :mconfig:`ignore_user_rc` |
1326 +------------+-----------------------------------------------------------------+
1327 | 5.4 | :mconfig:`sticky_purge`, :mconfig:`unique_name_loaded`, |
1328 | | :mconfig:`abort_on_error`, :mconfig:`source_cache` |
1329 +------------+-----------------------------------------------------------------+
1330 | 5.5 | :mconfig:`hide_auto_loaded`, :mconfig:`logger`, |
1331 | | :mconfig:`logged_events`, :mconfig:`conflict_unload` |
1332 +------------+-----------------------------------------------------------------+
1333 | 5.6 | :mconfig:`spider_output`, :mconfig:`spider_terse_output`, |
1334 | | :mconfig:`spider_indepth`, :mconfig:`require_via` |
1335 +------------+-----------------------------------------------------------------+
1336 | 5.7 | :mconfig:`path_entry_reorder`, :mconfig:`paginate`, |
1337 | | :mconfig:`non_exportable_tags`, :mconfig:`info_extension`, |
1338 | | :mconfig:`linked_envvars`, :mconfig:`init_envvars`, |
1339 | | :mconfig:`domainname`, :mconfig:`modulepath_ignore`, |
1340 | | :mconfig:`ignore_cache_subcmds` |
1341 +------------+-----------------------------------------------------------------+
1342
1343 :mconfig:`auto_handling`
1344
1345 Starting version 5.1, modules tagged ``keep-loaded`` are excluded from
1346 Useless Requirement Unload mechanism.
1347
1348 Starting version 5.5:
1349
1350 * Modules tagged ``sticky`` or ``super-sticky`` are excluded from Useless
1351 Requirement Unload mechanism.
1352 * No attempt to reload a Dependent Reload module is made if this module is
1353 not loadable (requirement not loaded or conflict found with loaded
1354 environment), even if force mode is enabled. Reload is attempted when
1355 module is not loadable if it is sticky (tagged super-sticky or sticky and
1356 force mode not enabled).
1357 * All reload of Dependent Reload modules are now performed on the top load,
1358 unload or switch evaluation rather right after the load, unload or switch
1359 that triggered the unload phase of the Dependent Reload mechanism.
1360 * Dependent Unload modules of Conflict Unload modules are merged into the
1361 Dependent Reload module list.
1362
1363 Starting version 5.6:
1364
1365 * No attempt to reload a Dependent Reload module is made if the modulepath
1366 where this module is stored is not enabled anymore and module cannot be
1367 found in other enabled modulepaths. Even if force mode is enabled. Reload
1368 is attempted when module is not loadable if it is sticky (tagged
1369 super-sticky or sticky and force mode not enabled).
1370
1371 :mconfig:`avail_output`, :mconfig:`avail_terse_output`
1372
1373 Starting version 5.3, element ``variant`` is added to the list of accepted
1374 values.
1375
1376 Starting version 5.3, element ``variantifspec`` is added to the list of
1377 accepted values. It is added to the default value list of both configuration
1378 options.
1379
1380 Starting Modules 5.3, these configuration options accept value prefixed by
1381 ``+`` or ``-`` which means value should respectively be appended to or
1382 subtracted from current configuration option value.
1383
1384 Starting version 5.3.1, element ``indesym`` is added to the list of accepted
1385 values.
1386
1387 Starting version 5.6, elements ``hidden``, ``provided-alias`` and ``via`` are
1388 added to the list of accepted values. ``via`` is only supported on
1389 :mconfig:`avail_output`.
1390
1391 :mconfig:`list_output`, :mconfig:`list_terse_output`
1392
1393 Starting Modules 5.3, these configuration options accept value prefixed by
1394 ``+`` or ``-`` which means value should respectively be appended to or
1395 subtracted from current configuration option value.
1396
1397 Starting version 5.4, elements ``alias`` and ``indesym`` are added to the
1398 list of accepted values.
1399
1400 Starting version 5.6, element ``hidden`` is added to the list of accepted
1401 values.
1402
1403 :mconfig:`colors`, :mconfig:`protected_envvars`,
1404 :mconfig:`shells_with_ksh_fpath`, :mconfig:`tag_abbrev`,
1405 :mconfig:`tag_color_name`, :mconfig:`variant_shortcut`
1406
1407 Starting Modules 5.3, these configuration options accept value prefixed by
1408 ``+`` or ``-`` which means value should respectively be appended to or
1409 subtracted from current configuration option value.
1410
1411 :mconfig:`rcfile`
1412
1413 Starting Modules 5.4, this configuration option accepts more than one global
1414 rc file location. A colon character separates each of these locations.
1415
1416 :mconfig:`pager`
1417
1418 Starting Modules 5.5, pager is not launched if :file:`modulecmd.tcl` program
1419 is run for scripting language.