Debian Codegraph @

doc/build/changes.txt

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