Debian Codegraph @

doc/build/MIGRATING.txt

raw
1 New features
2 ************
3
4 This document describes the major changes occurring between versions
5 of Modules. It provides an overview of the new features and changed
6 behaviors that will be encountered when upgrading.
7
8
9 v5.6
10 ====
11
12 This new version is backward-compatible with previous version 5
13 release. It fixes bugs but also introduces new functionalities that
14 are described in this section. See the 5.6 release notes for a
15 complete list of the changes between Modules v5.5 and v5.6.
16
17
18 spider sub-command
19 ------------------
20
21 Support has been added for the "spider" sub-command introduced by the
22 Lmod project. This sub-command lists available modules found in
23 enabled modulepaths and recursively found in modulepaths enabled by
24 available modules.
25
26 $ module avail
27 --------------------- /path/to/modulefiles ---------------------
28 foo/1 foo/2
29 $ module show foo/1
30 -------------------------------------------------------------------
31 /path/to/modulefiles/foo/1:
32
33 conflict foo
34 module use /path/to/modulefiles.2
35 -------------------------------------------------------------------
36 $ module show foo/2
37 -------------------------------------------------------------------
38 /path/to/modulefiles/foo/2:
39
40 conflict foo
41 append-path MODULEPATH /path/to/modulefiles.3
42 -------------------------------------------------------------------
43 $ module spider
44 --------------------- /path/to/modulefiles ---------------------
45 foo/1 foo/2
46
47 -------------- /path/to/modulefiles.2 (via foo/1) --------------
48 bar/1 bar/2 bar/3
49
50 -------------- /path/to/modulefiles.3 (via foo/2) --------------
51 bar/3 bar/4
52
53 -------------- /path/to/modulefiles.3 (via bar/1) --------------
54 qux/1 qux/2
55
56 The "spider" sub-command relies on the Extra match search mechanism to
57 scan modulefiles and identify the modulepaths they enable. Since all
58 modulefiles are evaluated during this scan, it is recommended to build
59 and use a Module cache to improve search performance.
60
61 The output of "spider" is similar to that of the "avail" sub-command
62 and supports the same set of options and queries.
63
64 $ module spider -t bar@2:
65 /path/to/modulefiles.2:
66 bar/2
67 bar/3
68
69 /path/to/modulefiles.3:
70 bar/3
71 bar/4
72
73 The "spider" sub-command has its own configuration options to control
74 the content of its output: "spider_indepth", "spider_output", and
75 "spider_terse_output".
76
77 These settings make it possible to define output for "spider" that
78 differs from the "avail" sub-command.
79
80 $ module config spider_output -modulepath
81 $ module config spider_indepth 0
82 $ module spider
83 bar/ foo/ qux/
84
85 When a modulepath is enabled by a specific module, that modulepath is
86 considered available *via* that module. When the module is loaded,
87 this *via* information is stored in the "__MODULES_LMUSE" environment
88 variable to track which modules enable which modulepaths.
89
90 By default, the *via* information is included in the standard output
91 of the "spider" sub-command. Additionally, the JSON output for both
92 the "avail" and "spider" sub-commands has been updated to include
93 *via* details for each modulefile.
94
95 $ module spider -j bar@2:
96 {"/path/to/modulefiles.2": {
97 "bar/2": { "name": "bar/2", "type": "modulefile", "symbols": [], "tags": [], "pathname": "/path/to/modulefiles.2/bar/2", "via": "foo/1"}
98 "bar/2": { "name": "bar/3", "type": "modulefile", "symbols": [], "tags": [], "pathname": "/path/to/modulefiles.2/bar/3", "via": "foo/1"}
99 },
100 "/path/to/modulefiles.3": {
101 "bar/3": { "name": "bar/3", "type": "modulefile", "symbols": [], "tags": [], "pathname": "/path/to/modulefiles.3/bar/3", "via": "foo/2"},
102 "bar/4": { "name": "bar/4", "type": "modulefile", "symbols": [], "tags": [], "pathname": "/path/to/modulefiles.3/bar/4", "via": "foo/2"}
103 }}
104
105
106 Requiring *via* module
107 ----------------------
108
109 A loaded module that enables a modulepath is considered the *via*
110 module of other loaded modules whose modulefiles are stored in this
111 modulepath. The "require_via" configuration option is introduced to
112 consider a *via* module a requirement for the loaded module stored in
113 the modulepath it enables.
114
115 A *module hierarchy* mechanism, as introduced by the Lmod project, is
116 now supported with this feature. It allows organizing modulefiles
117 through a primary modulepath, where loading certain modules enables
118 additional modulepaths. "require_via" maintains a link between
119 modulefiles in these additional paths and the *via* module that
120 activated them.
121
122 The "require_via" setting is disabled by default to maintain
123 compatibility with previous Modules 5 releases. However, users are
124 encouraged to enable this feature if they want to use the *module
125 hierarchy* mechanism.
126
127 $ module config require_via 1
128
129 When unloading a *via* module, all the modules stored in its enabled
130 modulepath are automatically unloaded thanks to the *Dependent Unload*
131 mechanism of the Automated module handling mode.
132
133 $ module load foo/1 bar/2
134 $ module avail
135 -------------- /path/to/modulefiles.2 (via foo/1) --------------
136 bar/1 bar/2 bar/3
137
138 --------------------- /path/to/modulefiles ---------------------
139 foo/1 foo/2
140
141 Key:
142 loaded modulepath
143 $ module unload foo
144 Unloading foo/1
145 Unloading dependent: bar/2
146
147 When a *via* module is replaced by another, any modulepaths it enabled
148 are updated accordingly. If the newly enabled modulepath provides
149 alternatives to modules previously loaded from the original path,
150 those modules are reloaded from the new location. If no alternatives
151 are found, the dependent modules are unloaded.
152
153 $ module config conflict_unload 1
154 $ module load foo/1 bar/3
155 $ module load foo/2
156 Loading foo/2
157 Unloading dependent: bar/3
158 Unloading conflict: foo/1
159 Reloading dependent: bar/3
160 $ module avail
161 -------------- /path/to/modulefiles.3 (via foo/2) --------------
162 bar/3 bar/4
163
164 --------------------- /path/to/modulefiles ---------------------
165 foo/1 foo/2
166
167 Key:
168 loaded modulepath
169
170
171 Always see hidden modules
172 -------------------------
173
174 The "hidden" element is a new allowed value for the "avail_output",
175 "avail_terse_output", "list_output", "list_terse_output",
176 "spider_output" and "spider_terse_output" configuration options. When
177 set into the value list of these options hidden modules are shown on
178 the output of corresponding commands ("avail", "list" and "spider").
179
180 --------------- /path/to/modulefiles ---------------
181 bar/1.0
182 $ module config avail_output +hidden
183 $ ml av
184 --------------- /path/to/modulefiles ---------------
185 bar/1.0 foo/1.0 <H>
186
187 When set, this is equivalent to always adding the "--all" command-line
188 option.
189
190
191 Issue warning upon module evaluation
192 ------------------------------------
193
194 The mfcmd:*module-warn* modulefile Tcl command is introduced to define
195 warning message to print when loading specified modulefiles.
196
197 $ cat /path/to/modulefiles/foo/1.0
198 #%Module
199 module-warn --message {Please consider using "bar" module instead} foo
200 $ module load foo
201 Loading foo/1.0
202 WARNING: Please consider using "bar" module instead
203
204 The warning message is printed when targeted modulefile is evaluated
205 in *load*, *display*, *help* or *test* mode.
206
207 "module-warn" supports the same kind of options than "module-tag" or
208 "module-hide": it is possible to specify a list of affected or
209 unaffected users or groups. Warning may also be only effective before
210 or after a particular date.
211
212 The "warning" tag is set on modules targeted by a mfcmd:*module-warn*
213 command.
214
215
216 Simplified way to define module help message
217 --------------------------------------------
218
219 Until now module help message was defined through a specific Tcl
220 procedure that outputs text to *stderr* channel:
221
222 #%Module
223 proc ModulesHelp {} {
224 puts stderr {Module Name: foo, Version: 1.0}
225 puts stderr {This modulefile does this and that}
226 }
227
228 A new modulefile Tcl command is introduced, "module-help", to simplify
229 a bit the definition of help message:
230
231 #%Module
232 module-help {Module Name: foo, Version: 1.0}
233 module-help {This modulefile does this and that}
234
235 With this modulefile command there is no need to define the
236 "ModulesHelp" procedure anymore. As "module-help" is reported on
237 module *display* evaluation, help message will also be visible there.
238
239
240 Support for newline character in environment variable value
241 -----------------------------------------------------------
242
243 It is now possible on *sh*, *bash*, *ksh*, *zsh* and *fish* shells to
244 set value for environment variable that contains newline character:
245
246 $ cat /path/to/modulefiles/bar/1.0
247 #%Module
248 setenv BAR "multinlinenvalue"
249 $ module load bar
250 $ echo "$BAR"
251 multi
252 line
253 value
254
255 Generated shell code on these shells has been changed to enclose value
256 within single quotes rather escaping each special characters:
257
258 $ module mod-to-sh bash bar/1.0
259 BAR='multi
260 line
261 value'; export BAR;
262
263
264 Declare additional elements provided by a module
265 ------------------------------------------------
266
267 New "provide" modulefile command is added to declare additional
268 elements included in a modulefile. When the modulefile is loaded, each
269 argument specified in the "provide" command is registered as an alias
270 for the module.
271
272 $ module show foo
273 -------------------------------------------------------------------
274 /path/to/modulefiles/foo/1:
275
276 provide liba/1.2 libb/2.1
277 conflict foo
278 conflict liba libb
279 -------------------------------------------------------------------
280 $ module load foo
281
282 It is advised to define "conflict" over the name of these additional
283 elements to ensure only one provider is found loaded in user
284 environment.
285
286 $ module show bar/1
287 -------------------------------------------------------------------
288 /path/to/modulefiles/bar/1:
289
290 provide liba/1.2 libb/2.1
291 conflict bar
292 conflict liba libb
293 -------------------------------------------------------------------
294 $ module load bar
295 Loading bar/1
296 ERROR: Module cannot be loaded due to a conflict.
297 HINT: Might try "module unload foo/1" first.
298
299 Once a module with a provided alias is loaded, it fulfills any
300 requirements declared by other modules for that name and version, just
301 like any other type of module alias.
302
303 $ module show qux
304 -------------------------------------------------------------------
305 /path/to/modulefiles/qux/1:
306
307 prereq liba/1.2
308 -------------------------------------------------------------------
309 $ module load qux
310 $ module list
311 Currently Loaded Modulefiles:
312 1) foo/1 2) qux/1
313
314 Module aliases defined via the "provide" command are not available
315 during module resolution, as modulefiles are not evaluated in that
316 context. Therefore, it is recommended to define a global module alias
317 in a "modulerc" file using the "module-alias" command to specify a
318 default target for the alias.
319
320 $ cat /path/to/modulefiles/.modulerc
321 #%Module
322 module-alias liba/1.2 bar/1
323 $ module purge
324 $ module load qux
325 Loading qux/1
326 Loading requirement: bar/1
327
328 The "provide" modulefile command also serves as an alias for the
329 "extensions" command, ensuring compatibility with modulefiles written
330 for Lmod.
331
332 By default an "avail" command includes module aliases defined in
333 "modulerc" files. To also get aliases defined within modulefiles with
334 "provide" or "family", output element "provided-alias" has to be
335 included. It is supported on "avail_output", "avail_terse_output",
336 "spider_output" and "spider_terse_output" configuration options.
337
338 Having "provided-alias" included in output triggers Extra match search
339 mechanism that scans all modulefiles to find these aliases. It is thus
340 advised to have Module cache built and used to improve search speed.
341
342 $ module avail
343 --------------------- /path/to/modulefiles ---------------------
344 bar/1 foo/1 liba/1.2 qux/1
345
346 Key:
347 modulepath module-alias
348 $ module avail -o +provided-alias
349 --------------------- /path/to/modulefiles ---------------------
350 bar/1 foo/1 liba/1.2 libb/2.1 qux/1
351
352 Key:
353 modulepath module-alias
354
355 The "provided-alias" Extra specifier is also introduced to find
356 modules that define such alias with "provide" or "family" modulefile
357 commands.
358
359 $ module avail provided-alias:liba/1.2
360 --------------------- /path/to/modulefiles ---------------------
361 bar/1 foo/1
362
363 Key:
364 modulepath
365
366
367 v5.5
368 ====
369
370 This new version is backward-compatible with previous version 5
371 release. It fixes bugs but also introduces new functionalities that
372 are described in this section. See the 5.5 release notes for a
373 complete list of the changes between Modules v5.4 and v5.5.
374
375
376 Logging activity
377 ----------------
378
379 The ability to log module command activity is now available out of the
380 box. It could be enabled on previous versions by using a specific
381 "siteconfig.tcl" configuration script as described in the Log module
382 command cookbook recipe.
383
384 Integrated logging feature relies on two configuration options:
385
386 * "logger", the command run to transmit messages to the log system
387
388 * "logged_events", list of module event to log
389
390 "logger" option relies on the **logger** command by default, which is
391 usually available and already installed on most systems.
392
393 The "logged_events" option is empty by default, so no content is sent
394 to logs by default. It recognizes the following events:
395
396 * "requested_cmd": record module commands typed by users
397
398 * "requested_eval": record modulefile evaluations requested by users
399
400 * "auto_eval": record modulefile evaluations automatically triggered
401
402 $ module config logged_events +requested_cmd:requested_eval
403 $ ml av
404 --------------- /path/to/modulefiles ---------------
405 bar/1.0 foo/1.0 qux/1.0
406 $ module load bar
407 Loading bar/1.0
408 Loading requirement: qux/1.0
409 $ module purge
410
411 In the above example the module command and modulefile evaluations
412 directly requested by users are sent to the system log:
413
414 $ journalctl -q -t modules
415 Apr 29 07:47:42 hostname modules[3777797]: user="username" command="avail" arguments=""
416 Apr 29 07:48:10 hostname modules[3777876]: user="username" command="load" arguments="bar"
417 Apr 29 07:48:10 hostname modules[3777876]: user="username" mode="load" module="bar/1.0" specified="bar" modulefile="/path/to/modulefiles/bar/1.0" requested="1"
418 Apr 29 07:48:17 hostname modules[3777914]: user="username" command="purge" arguments=""
419 Apr 29 07:48:17 hostname modules[3777914]: user="username" mode="unload" module="bar/1.0" specified="bar/1.0" modulefile="/path/to/modulefiles/bar/1.0" requested="1"
420
421 Some messages can also be sent during modulefile evaluation by using
422 the "log" channel of the "puts" command:
423
424 $ cat /path/to/modulefiles/foo/1.0
425 #%Module
426 puts log {some message sent to log}
427 $ ml foo/1.0
428 $ journalctl -q -t modules
429 Apr 29 07:47:51 hostname modules[3777835]: user="username" command="ml" arguments="foo/1.0"
430 Apr 29 07:47:51 hostname modules[3777835]: some message sent to log
431 Apr 29 07:47:51 hostname modules[3777835]: user="username" mode="load" module="foo/1.0" specified="foo/1.0" modulefile="/path/to/modulefiles/foo/1.0" requested="1"
432
433
434 Negating extra match search criteria
435 ------------------------------------
436
437 The "not:" prefix string is introduced for extra specifier and variant
438 criteria. When this prefix is used, the search criteria where it is
439 applied is negated.
440
441 $ module config avail_output +variant
442 $ module config variant_shortcut toolchain=%
443 $ module avail
444 --------------------- /path/to/modulefiles ---------------------
445 bar/1.0{%x86_64} foo/2.0{%x86_64,arm64}
446 bar/2.0{%x86_64,arm64} qux/1.0{%x86_64}
447 foo/1.0{%x86_64} qux/2.0{%x86_64,arm64}
448 $ module avail not:envvar:FOO,BAR
449 --------------------- /path/to/modulefiles ---------------------
450 qux/1.0{%x86_64} qux/2.0{%x86_64,arm64}
451
452 The above search query returns all modules not defining "FOO" and
453 "BAR" environment variables.
454
455 $ module avail not:envvar:BAR not:%arm64
456 --------------------- /path/to/modulefiles ---------------------
457 foo/1.0{%x86_64} qux/1.0{%x86_64}
458
459 The above example returns all modules not defining "BAR" environment
460 variable and not defining "toolchain" variant or defining this variant
461 without "arm64" among the possible values.
462
463 This prefix is recognized on module search context (i.e., "avail",
464 "whatis" and "paths" sub-commands).
465
466
467 PowerShell support
468 ------------------
469
470 Support for PowerShell ("pwsh") is added. This shell may be used with
471 Modules on either Unix or Windows platforms. All main kind of
472 environment changes are supported.
473
474 A "envmodule" shell function is configured on PowerShell, as "module"
475 is a reserved keyword on this shell.
476
477 The Windows-specific distribution zipball of Modules has been updated
478 to also contain the required files to setup PowerShell support.
479
480
481 Conflict unload
482 ---------------
483
484 Automated module handling is enhanced with the addition of a new
485 mechanism: *Conflict Unload*. When loading a module, this new
486 mechanism automatically unloads conflicting modules and their
487 dependent.
488
489 $ module load foo/1
490 Loading foo/1{-debug}
491 Loading requirement: qux/1 bar/1
492 $ module load foo/2
493 Loading foo/2
494 ERROR: Module cannot be loaded due to a conflict.
495 HINT: Might try "module unload foo/1" first.
496 $ module config conflict_unload 1
497 $ module load foo/2
498 Loading foo/2{-debug}
499 Unloading conflict: foo/1{-debug}
500
501 As seen in the above example, *Conflict Unload* is controlled by the
502 "conflict_unload" configuration option. It is disabled by default as
503 it changes behaviors of the "automated module handling mode". But
504 everyone is encouraged to enable this new option to benefit from an
505 highly automated experience. This option can be changed at
506 installation time with "--enable-conflict-unload" configure script
507 option.
508
509 *Conflict Unload* handles all kind of conflicts: conflicts defined by
510 already loaded modules, conflict declared by loading module through
511 "conflict", "family" or "module unload" commands. It also supports the
512 unload of a module that is loaded again but with different variant
513 values.
514
515 $ module load foo/2 +debug
516 Loading foo/2{+debug}
517 Unloading conflict: foo/2{-debug}
518
519 Along with *Conflict Unload*, the *Useless Requirement Unload*
520 mechanism is added to load evaluation. With it, auto loaded
521 requirements of modules unloaded by *Conflict Unload* mechanism are
522 automatically unloaded.
523
524 $ module load foo/3
525 Loading foo/3{-debug}
526 Unloading conflict: foo/2{+debug} bar/1
527 Loading requirement: bar/2
528 Unloading useless requirement: qux/1
529
530 Dependent modules of *Conflict Unload* modules are considered
531 *Dependent Reload* modules. They are unloaded prior unloading the
532 *Conflict Unload* module that depend on them. Reload occurs after
533 loading main module and only if the loaded environment satisfies the
534 dependencies of the module to reload.
535
536 $ module load bar/3
537 Loading bar/3
538 Loading requirement: qux/2
539 $ module load qux/1
540 Loading qux/1
541 Unloading dependent: bar/3
542 Unloading conflict: qux/2
543 Reloading dependent: bar/3
544
545
546 Improved automated module handling mechanisms
547 ---------------------------------------------
548
549 Along with the introduction of *Conflict Unload* mechanism, some of
550 the existing automated module handling mechanisms have been adapted
551 and enhanced.
552
553 *Useless Requirement Unload* (UReqUn) mechanism is moved during a
554 "switch" sub-command from the end of the unload phase to the end of
555 the load phase. Both *UReqUn* modules coming from unload and load
556 phases are this way treated jointly. If *UReqUn* modules resulting
557 from the switch unload phase are detected as conflict to the switched-
558 on module, it is advised to enable the "conflict_unload" mechanism to
559 automatically handle them.
560
561 $ module switch foo/3 foo/4
562 Loading foo/4
563 ERROR: Module cannot be loaded due to a conflict.
564 HINT: Might try "module unload bar/2" first.
565
566 Switching from foo/3{-debug} to foo/4
567 ERROR: Load of switched-on foo/4 failed
568 $ module config conflict_unload 1
569 $ module switch foo/3 foo/4
570 Switching from foo/3{-debug} to foo/4
571 Unloading conflict: bar/2
572
573 *Dependent Reload* (DepRe) modules that also are *UReqUn* modules are
574 now unloaded during the *DepRe* unload phase instead of during the
575 *UReqUn* process. As a consequence these modules are now unloaded
576 prior main module action, as they are a dependent of this main module.
577 This kind of *UReqUn* modules may not be a dependency of a module
578 unloaded in the current processing.
579
580 Modules from *Dependent Unload* (DepUn) and *Dependent Reload* (DepRe)
581 mechanisms are now mixed together to proceed to their unload. They are
582 this way unloaded in their reverse loading order. So if a module is
583 part of the *DepUn* process and one of its requirement is part of the
584 *DepRe* process, the requirement is now unloaded after its dependent.
585
586 Reload of *Dependent Reload* (DepRe) module is now skipped if this
587 module is not found loadable in environment. Either because its
588 requirements are not loaded or a conflict is spotted. Such module is
589 considered *Dependent Unload* rather *Dependent Reload*. If *DepRe*
590 module is sticky, reload is attempted anyway.
591
592 Reload of all *Dependent Reload* (DepRe) modules now occurs after main
593 module evaluation rather after each sub module evaluation that
594 triggered the *Dependent Reload* unload phase.
595
596 When a loading module requires a *Dependent Unload* (DepUn) module,
597 the unload of this module was forced when it was triggered by a
598 Conflict Unload or a switched-off module. The unload of such *DepUn*
599 module is not forced anymore by default and an error is raised if a
600 loading module requiring the *DepUn* module is detected.
601
602 When unloading *Dependent Reload* modules, do not force by default
603 this unload unless asked with "--force" option. As a result an error
604 is obtained when trying to reload Dependent Reload modules that
605 conflict with other loaded modules. This error may be by-passed with "
606 --force" command-line option.
607
608
609 Specific modulepath for requirements
610 ------------------------------------
611
612 A "--modulepath" option is introduced on the "always-load", "depends-
613 on", "prereq", "prereq-all" and "prereq-any" modulefile commands. This
614 option indicates that requirement should be specifically searched in
615 the provided list of modulepaths. Such mechanism helps to ensure
616 loaded requirements are those expected and they are not coming from an
617 unexpected module tree.
618
619 In the following example, "foo" module requires "bar". It expects the
620 "bar" module from the same modulepath than "foo". User's environment
621 has enabled another modulepath that also provides a "bar" module. Use
622 of "--modulepath" option guides the requirement load mechanism to the
623 expected module.
624
625 $ module avail
626 --------------------- /path/to/othermfiles ---------------------
627 bar/1
628
629 --------------------- /path/to/modulefiles ---------------------
630 bar/1 foo/1 foo/2
631 $ module show foo/1
632 -------------------------------------------------------------------
633 /path/to/modulefiles/foo/1:
634
635 prereq --modulepath .. bar/1
636 -------------------------------------------------------------------
637 $ module load foo/1
638 Loading foo/1
639 Loading requirement: bar/1
640 $ echo $_LMFILES_
641 /path/to/modulefiles/bar/1:/path/to/modulefiles/foo/1
642
643 Specific modulepath set may guide to a directory not necessarily
644 enabled (i.e., not defined in "MODULEPATH" environment variable):
645
646 $ module show foo/2
647 -------------------------------------------------------------------
648 /path/to/modulefiles/foo/2:
649
650 prereq --modulepath /path/to/alternatefiles bar/2
651 -------------------------------------------------------------------
652 $ module load foo/2
653 Loading foo/2
654 Loading requirement: bar/2
655 $ module list
656 Currently Loaded Modulefiles:
657 1) bar/2 2) foo/2
658 $ echo $_LMFILES_
659 /path/to/alternatefiles/bar/2:/path/to/modulefiles/foo/2
660
661 If a required module is already loaded from a modulepath that does not
662 correspond to the requirement definition, an error is obtained.
663 However if the *Conflict Unload* mechanism described above is enabled,
664 the conflicting module will automatically be unloaded.
665
666 $ module purge
667 $ module load bar/1
668 $ echo $_LMFILES_
669 /path/to/othermfiles/bar/1
670 $ module load foo/1
671 Loading bar/1
672 ERROR: Module already loaded from a different modulepath
673
674 Loading foo/1
675 ERROR: Load of requirement bar/1 (specific path) failed
676 $ module config conflict_unload 1
677 $ module load foo/1
678 Loading foo/1
679 Unloading conflict: bar/1
680 Loading requirement: bar/1
681 $ echo $_LMFILES_
682 /path/to/modulefiles/bar/1:/path/to/modulefiles/foo/1
683
684
685 v5.4
686 ====
687
688 This new version is backward-compatible with previous version 5
689 release. It fixes bugs but also introduces new functionalities that
690 are described in this section. See the 5.4 release notes for a
691 complete list of the changes between Modules v5.3 and v5.4.
692
693
694 Enhancing extra specifiers
695 --------------------------
696
697 Extra specifier "tag" is introduced to search modules based on tags
698 applied. It applies to "avail", "whatis" and "paths" sub-commands. Tag
699 abbreviation may also be used as extra specifier name.
700
701 $ module avail tag:sticky
702 --------------------- /path/to/modulefiles ---------------------
703 bar/1
704
705 Multiple names can now be specified on one extra specifier criterion
706 to select modules matching any of these names.
707
708 $ module avail tag:S,F
709 --------------------- /path/to/modulefiles ---------------------
710 bar/1 qux/1
711
712 Multiple values can now be specified on one variant criterion to
713 select modules providing any of these variant values.
714
715 $ module config variant_shortcut toolchain=%
716 $ module avail %a,c
717 --------------------- /path/to/modulefiles ---------------------
718 baz/1{%c} foo/1{%a,b,c}
719 $ module avail %a,c %b
720 --------------------- /path/to/modulefiles ---------------------
721 foo/1{%a,b,c}
722
723
724 Purging sticky modules
725 ----------------------
726
727 The "sticky_purge" configuration option is added to define the
728 behavior of "purge" sub-command when unloading a sticky or super-
729 sticky module.
730
731 By default an "error" is raised. "sticky_purge" can be changed to emit
732 a "warning" message instead or to be "silent".
733
734 $ module purge
735 Unloading foo/1.0
736 ERROR: Unload of sticky module skipped
737 $ module config sticky_purge warning
738 $ module purge
739 Unloading foo/1.0
740 WARNING: Unload of sticky module skipped
741 $ module config sticky_purge silent
742 $ module purge
743 $ module list
744 Currently Loaded Modulefiles:
745 1) foo/1.0
746
747 Key:
748 sticky
749
750
751 Specific modulepath labels
752 --------------------------
753
754 "modulepath-label" command is introduced to define a label to use to
755 designate modulepath in module "avail" output. This new command should
756 be used in global or modulepath-specific rc files.
757
758 $ cat /path/to/modulefiles/.modulerc
759 #%Module
760 modulepath-label . Tools
761 $ module avail foo
762 ---------------------- Tools ----------------------
763 foo/1.0 foo/2.0
764
765
766 Unique module name loaded
767 -------------------------
768
769 The configuration option "unique_name_loaded" is introduced to allow
770 only one module loaded per module name. It is similar to the *One name
771 rule* feature introduced by the Lmod project.
772
773 When enabled, "unique_name_loaded" produces a conflict definition at
774 the start of modulefile evaluation for each actual and alternative
775 module root name. For instance when loading a module named
776 "foo/sub/1.0" with a "qux/1.0" alias, it produces a conflict against
777 "foo" and "qux".
778
779 When loading a module that shares a name with an already loaded
780 module, an error is raised due to the conflict definition. This error
781 aborts the module load evaluation.
782
783 $ cat /path/to/modulefiles/bar/1.0
784 #%Module
785 $ cat /path/to/modulefiles/bar/2.0
786 #%Module
787 $ module config unique_name_loaded 1
788 $ module load bar/1.0
789 $ module load bar/2.0
790 Loading bar/2.0
791 ERROR: Module cannot be loaded due to a conflict.
792 HINT: Might try "module unload bar" first.
793
794 "unique_name_loaded" is disabled by default. It can be changed with
795 module "config" sub-command or at installation time with "--enable-
796 unique-name-loaded" configure script option.
797
798
799 Cache sourced files
800 -------------------
801
802 You may have gathered common Tcl code files used by all your
803 modulefiles in Tcl files that are sourced with *source(n)* Tcl
804 command. When loading multiple modulefiles at once, these sourced
805 files may be read for every loaded modules, which may induce some I/O
806 load.
807
808 The configuration option "source_cache" is introduced to cache files
809 evaluated through "source" Tcl command in order to only read them once
810 during a "modulecmd.tcl" execution. When this option is enabled,
811 sourced file read also benefits from optimized I/O calls of Modules
812 Tcl extension library.
813
814 In the following example, 20 modules are loaded, each of them sources
815 the same Tcl file:
816
817 $ syscall_list=close,fcntl,ioctl,newfstatat,openat,read,readlink
818 $ strace -f -e $syscall_list -c $MODULES_CMD bash load foo/20
819 % time seconds usecs/call calls errors syscall
820 ------ ----------- ----------- --------- --------- ----------------
821 31.48 0.000781 1 466 read
822 28.58 0.000709 5 131 16 openat
823 14.19 0.000352 2 142 3 newfstatat
824 9.71 0.000241 1 124 close
825 8.02 0.000199 0 212 211 readlink
826 4.55 0.000113 1 67 47 ioctl
827 3.47 0.000086 1 60 fcntl
828 ------ ----------- ----------- --------- --------- ----------------
829 100.00 0.002481 2 1202 277 total
830
831 When sourced file is cached, it is only read once which saves a
832 substantial amount of I/O operations:
833
834 $ module config source_cache 1
835 $ strace -f -e $syscall_list -c $MODULES_CMD bash load foo/20
836 % time seconds usecs/call calls errors syscall
837 ------ ----------- ----------- --------- --------- ----------------
838 34.41 0.000523 4 112 16 openat
839 27.37 0.000416 0 428 read
840 11.84 0.000180 1 122 3 newfstatat
841 11.51 0.000175 1 105 close
842 7.11 0.000108 2 47 27 ioctl
843 5.99 0.000091 0 92 91 readlink
844 1.78 0.000027 0 40 fcntl
845 ------ ----------- ----------- --------- --------- ----------------
846 100.00 0.001520 1 946 137 total
847
848
849 Abort on error
850 --------------
851
852 When an error occurs during the evaluation of a modulefile, several
853 module sub-commands, like "load" or "unload", continue their
854 processing. It means these sub-commands do not stop if they have
855 multiple modulefiles to evaluate. This is named the *continue on
856 error* behavior.
857
858 The "abort_on_error" configuration option is introduced to abort, for
859 the sub-commands listed in its value, the evaluation of multiple
860 modulefiles if one fails to evaluate.
861
862 The *abort on error* behavior is applied by default on **ml** command,
863 "reload" sub-command and the unload phase of "switch" sub-command.
864 This behavior may also be turned on for "load", "mod-to-sh", "purge",
865 "switch", "try-load" and "unload" sub-commands. If a command is
866 removed from "abort_on_error"'s value, it applies the *continue on
867 error* behavior.
868
869 In the following example, *abort on error* behavior is applied to
870 "load" sub-command to stop evaluation instead of loading the remaining
871 modulefile in the sequence if first modulefile fails to evaluate.
872
873 $ module load foo bar
874 Loading foo/1
875 ERROR: Module evaluation aborted
876 $ module list
877 Currently Loaded Modulefiles:
878 1) bar/1
879 $ module purge
880 $ module config abort_on_error +load
881 $ module load foo bar
882 Loading foo/1
883 ERROR: Module evaluation aborted
884 $ module list
885 No Modulefiles Currently Loaded.
886
887 When enabled for "switch" sub-command, whole action aborts if
888 switched-on modulefile fails to load. By default, "switch" only aborts
889 if switched-off modulefile fails to unload.
890
891 $ module load bar
892 $ module switch bar foo
893 Loading foo/1
894 ERROR: Module evaluation aborted
895
896 Switching from bar/1 to foo/1
897 WARNING: Load of switched-on foo/1 failed
898 $ module list
899 No Modulefiles Currently Loaded.
900 $ module load bar
901 $ module config abort_on_error +switch
902 $ module switch bar foo
903 Loading foo/1
904 ERROR: Module evaluation aborted
905
906 Switching from bar/1 to foo/1
907 WARNING: Load of switched-on foo/1 failed
908 $ module list
909 Currently Loaded Modulefiles:
910 1) bar/1
911
912 "abort_on_error" configure option has no impact on "module" commands
913 defined in modulefiles. When "--force" option is set, sub-commands
914 apply the *continue on error* behavior.
915
916 When "--enable-new-features" installation option is set, the *abort on
917 error* behavior is also enabled on "load" and "switch" sub-commands.
918
919
920 Improve error reporting
921 -----------------------
922
923 Module evaluation error reports have been tweaked to appear where
924 these errors occur rather reporting them on the message block of the
925 main action. Such change helps to better understand the module
926 evaluation flow.
927
928 $ module load baz
929 Loading baz/1
930 Loading requirement: foo/1
931 $ module switch foo bar
932 Unloading baz/1
933 Module ERROR: invalid command name "bad_command"
934 while executing
935 "bad_command"
936 (file "/path/to/modulefiles/baz/1" line 4)
937 Please contact <root@localhost>
938
939 Unloading foo/1
940 ERROR: Unload of dependent baz/1 failed
941
942 Switching from foo/1 to bar
943 ERROR: Unload of switched-off foo/1 failed
944
945 "switch" sub-command specific error messages are not reported when
946 "module switch" command is run from a modulefile (like *unload of
947 switched-off module failed*, *load of switched-on module failed*
948 messages or *Switching* block message). On "switch" sub-command, load
949 failure of switched-on module is now reported as an error.
950
951 $ module load foo
952 $ module switch foo qux
953 Loading qux/1
954 Module ERROR: invalid command name "bad_command"
955 while executing
956 "bad_command"
957 (file "/path/to/modulefiles/qux/1" line 2)
958 Please contact <root@localhost>
959
960 Switching from foo/1 to qux/1
961 ERROR: Load of switched-on qux/1 failed
962
963 Conflict error messages now describe the loaded module name and
964 version that conflicts rather the generic conflict module
965 specification.
966
967 $ cat /path/to/modulefiles/bar/1
968 #%Module
969 conflict foo
970 $ module load foo
971 $ module load bar
972 Loading bar/1
973 ERROR: Module cannot be loaded due to a conflict.
974 HINT: Might try "module unload foo/1" first.
975
976
977 New options for source-sh modulefile command
978 --------------------------------------------
979
980 Support for new *shell* mode named "bash-eval" is added to "source-sh"
981 modulefile command. With this new mode, the generated output of the
982 bash shell script is evaluated to get the environment changes instead
983 of sourcing this script.
984
985 $ cat /path/to/modulefiles/foo/foo-output.sh
986 #!/bin/bash
987 cat <<EOF
988 export FOO=value;
989 alias foo_alias='echo foo_alias;'
990 foo_function() {
991 echo foo_function;
992 }
993 EOF
994 $ cat /path/to/modulefiles/foo/1
995 #%Module
996 set foo_script [file dirname $ModulesCurrentModulefile]/foo-output.sh
997 source-sh bash-eval $foo_script
998
999 $ module show foo/1
1000 -------------------------------------------------------------------
1001 /path/to/modulefiles/foo/1:
1002
1003 set-alias foo_alias {echo foo_alias;}
1004 set-function foo_function {
1005 echo foo_function}
1006 setenv FOO value
1007 -------------------------------------------------------------------
1008 $ module load foo/1
1009 $ foo_alias
1010 foo_alias
1011
1012 "bash-eval" *shell* support is also available on "sh-to-mod" sub-
1013 command.
1014
1015 A new option is added to "source-sh" modulefile command: "--ignore".
1016 It filters shell elements changed by script, not to get these changes
1017 applied when loading modulefile. This option accepts a list, separated
1018 by colon character, of shell elements: "envvar", "alias", "function",
1019 "complete" or "chdir".
1020
1021 $ module purge
1022 $ cat /path/to/modulefiles/foo/2
1023 #%Module
1024 set foo_script [file dirname $ModulesCurrentModulefile]/foo-output.sh
1025 source-sh --ignore alias:function bash-eval $foo_script
1026
1027 $ module show foo/2
1028 -------------------------------------------------------------------
1029 /path/to/modulefiles/foo/2:
1030
1031 setenv FOO value
1032 -------------------------------------------------------------------
1033 $ module load foo/2
1034 $ foo_alias
1035 bash: foo_alias: command not found
1036
1037 This "--ignore" option can be used with any *shell* supported by
1038 "source-sh".
1039
1040
1041 v5.3
1042 ====
1043
1044 This new version is backward-compatible with previous version 5
1045 release. It fixes bugs but also introduces new functionalities that
1046 are described in this section. See the 5.3 release notes for a
1047 complete list of the changes between Modules v5.2 and v5.3.
1048
1049
1050 Module cache
1051 ------------
1052
1053 A module cache file can be created under each modulepath directory
1054 with new "cachebuild" sub-command. Cache file is named ".modulecache"
1055 and contains in one file all modulefiles and modulercs found in
1056 modulepath directory.
1057
1058 When cache file is available, module search mechanism uses this file
1059 rather walking through the content of modulepath directory. I/O
1060 operations are saved this way which reduces search processing time.
1061
1062 When searching for available modules without cache, each file
1063 contained in enabled modulepaths is opened to check if it is a
1064 modulefile or not. Such checks lead to a large number of I/O
1065 operations on large module setup like in the below example where a
1066 total of 1051 modulefiles are available:
1067
1068 $ module -o "" avail -t | wc -l
1069 1051
1070 $ syscall_list=access,close,getdents64,newfstatat,openat,read
1071 $ strace -f -e $syscall_list -c $MODULES_CMD bash avail
1072 % time seconds usecs/call calls errors syscall
1073 ------ ----------- ----------- --------- --------- ----------------
1074 31.09 0.003776 2 1424 9 openat
1075 28.56 0.003469 2 1649 3 newfstatat
1076 14.08 0.001710 1 1421 close
1077 11.85 0.001439 3 460 getdents64
1078 10.88 0.001321 0 1505 read
1079 3.54 0.000430 4 107 5 access
1080 ------ ----------- ----------- --------- --------- ----------------
1081 100.00 0.012145 1 6566 17 total
1082
1083 After building cache file for every enabled modulepaths in this
1084 example setup, a lot of I/O operations are saved when searching for
1085 available modules:
1086
1087 $ module cachebuild
1088 Creating /path/to/modulefiles/.modulecache
1089 Creating /path/to/modulefiles.2/.modulecache
1090 Creating /path/to/modulefiles.3/.modulecache
1091 $ module config cache_buffer_bytes 1000000
1092 $ strace -f -e $syscall_list -c $MODULES_CMD bash avail
1093 % time seconds usecs/call calls errors syscall
1094 ------ ----------- ----------- --------- --------- ----------------
1095 70.19 0.000544 2 255 read
1096 13.16 0.000102 2 38 9 openat
1097 8.90 0.000069 1 35 close
1098 6.06 0.000047 1 31 2 newfstatat
1099 1.68 0.000013 1 11 2 access
1100 ------ ----------- ----------- --------- --------- ----------------
1101 100.00 0.000775 2 370 13 total
1102
1103 A significant execution time drop may be noticed, especially if
1104 modulepath directories are stored on heavily loaded network
1105 filesystem.
1106
1107 To further optimize I/O operation count, the "cache_buffer_bytes"
1108 configuration option can be set like in the above example to use fewer
1109 number of "read" operation to load cache file content.
1110
1111 To build cache file, user should be granted write access on modulepath
1112 directory. Modulefiles or directories that are not accessible for
1113 everyone are not recorded in cache. An indication is saved instead to
1114 test these limited access elements when cache is loaded to determine
1115 if they are available to currently running user.
1116
1117 Cache file can be ignored with "--ignore-cache" command line switch or
1118 more permanently with "ignore_cache" configuration option.
1119
1120 Cache file is valid indefinitely by default but "cache_expiry_secs"
1121 configuration option can be used to define the number of seconds a
1122 cache file is considered valid after being generated. Expired cache
1123 file is ignored.
1124
1125 Cache file of enabled modulepaths can be deleted all at once with
1126 "cacheclear" sub-command.
1127
1128
1129 Querying available module variants
1130 ----------------------------------
1131
1132 A new mechanism named Extra match search is introduced to evaluate
1133 modulefiles during a module search to find those matching an extra
1134 query on a variant value, a dependency or an environment variable
1135 definition.
1136
1137 During this specific evaluation, modulefiles are interpreted in *scan*
1138 mode to collect the different Tcl modulefile commands they use.
1139 Special care should be given when writing modulefiles to ensure they
1140 cope with such evaluation mode.
1141
1142 Extra match search mechanism is available on "avail", "whatis" and
1143 "paths" sub-commands.
1144
1145 With this new mechanism, it is possible to list all available variant
1146 defined in modulefiles with their associated values:
1147
1148 $ module config avail_output modulepath:alias:dirwsym:sym:tag:key:variant
1149 $ module config variant_shortcut toolchain=%
1150 $ module avail
1151 --------------------- /path/to/modulefiles ---------------------
1152 bar/1.0{%a,b} foo/1.0{%a} qux/1.0{%a,b}
1153 bar/2.0{%b} foo/2.0{%a,b,c} qux/2.0{%b,c}
1154
1155 Key:
1156 modulepath {%value}={toolchain=value}
1157 default-version {variant=value}
1158
1159 You can also search for modules defining a specific variant value:
1160
1161 $ module avail %a
1162 --------------------- /path/to/modulefiles ---------------------
1163 bar/1.0{%a,b} foo/1.0{%a} foo/2.0{%a,b,c} qux/1.0{%a,b}
1164
1165 Key:
1166 modulepath {%value}={toolchain=value}
1167 default-version {variant=value}
1168
1169 Note:
1170
1171 As extra match search implies additional modulefile evaluations, it
1172 is advised to build and use Module cache to improve search speed.
1173
1174 Two new elements, "variant" and "variantifspec", are added to the
1175 allowed value list of "avail_output" and "avail_terse_output"
1176 configuration options. The latter is set in the default value list of
1177 both options. When "variant" is set, variants and their possible
1178 values are reported along module they are associated to. When
1179 "variantifspec" is set, available variants are reported only if a
1180 variant is specified in search query.
1181
1182 $ module config --reset avail_output
1183 $ module config avail_output
1184 Modules Release 5.3.0 (2023-05-14)
1185
1186 - Config. name ---------.- Value (set by if default overridden) ---------------
1187 avail_output modulepath:alias:dirwsym:sym:tag:variantifspec:key
1188 $ module avail foo
1189 --------------------- /path/to/modulefiles ---------------------
1190 foo/1.0 foo/2.0
1191
1192 Key:
1193 modulepath
1194 $ module avail foo %a
1195 --------------------- /path/to/modulefiles ---------------------
1196 foo/1.0{%a} foo/2.0{%a,b,c}
1197
1198 Key:
1199 modulepath {%value}={toolchain=value}
1200 default-version {variant=value}
1201
1202
1203 Extra specifiers
1204 ----------------
1205
1206 Extra specifiers are introduced to query content of modulefiles. They
1207 can be specified with *element:name* syntax as part of module
1208 specification on module search commands ("avail", "paths" and and
1209 "whatis").
1210
1211 Extra specifiers trigger Extra match search mechanism when found in
1212 module specification. Available modulefiles are evaluated in *scan*
1213 mode to collect the different Tcl modulefile commands they use.
1214
1215 $ module avail variant:toolchain
1216 --------------------- /path/to/modulefiles ---------------------
1217 bar/1.0 bar/2.0 foo/1.0 foo/2.0 qux/1.0 qux/2.0
1218
1219 In the above example, all modulefiles defining a "toolchain" variant
1220 are returned.
1221
1222 Most Tcl modulefile commands can be queried with extra specifiers:
1223 "variant", "setenv", "unsetenv", "append-path", "prepend-path",
1224 "remove-path", "pushenv", "complete", "uncomplete", "set-alias",
1225 "unset-alias", "set-function", "unset-function", "chdir", "family",
1226 "prereq", "prereq-any", "prereq-all", "depends-on", "always-load",
1227 "load", "load-any", "try-load", "switch", "switch-on", "switch-off",
1228 "conflict" and "unload". Commands that handle environment variables
1229 may be aliased "envvar". Commands that define a module requirement may
1230 be aliased "require" and those that define a module incompatibility
1231 may be aliased "incompat".
1232
1233 When several extra specifiers are set in query, modules returned are
1234 those matching both conditions. In the following example, all
1235 modulefiles interacting with "PATH" environment variable and requiring
1236 "foo" module are returned.
1237
1238 $ module avail envvar:PATH require:foo
1239 --------------------- /path/to/modulefiles ---------------------
1240 bar/1.0 bar/2.0
1241
1242 Extra specifiers related to module requirement or incompatibility may
1243 leverage the Advanced module version specifiers syntax. On following
1244 example, modulefiles returned are those defining a requirement on
1245 "foo" module with version higher or equal to "1.2" and variant
1246 "toolchain=a" selected.
1247
1248 $ module avail "require:[email protected]: toolchain=a"
1249 --------------------- /path/to/modulefiles ---------------------
1250 bar/1.0
1251
1252 Note:
1253
1254 Module aliases or symbolic versions used either in modulefile
1255 definitions or as extra specifier values are not resolved.
1256
1257
1258 Append or subtract elements to current option value
1259 ---------------------------------------------------
1260
1261 For command-line switches and configuration options whose value is a
1262 colon-separated list, it is now possible to append or subtract
1263 elements to the current value. With a "+" prefix elements are appended
1264 and with a "-" prefix elements are subtracted.
1265
1266 This new feature applies to "--output"/"-o" command-line switches and
1267 "avail_output", "avail_terse_output", "list_output",
1268 "list_terse_output", "colors", "protected_envvars",
1269 "shells_with_ksh_fpath", "tag_abbrev", "tag_color_name",
1270 "variant_shortcut" configuration options.
1271
1272 For instance, to output available *foo* modules without modulepath and
1273 tag information:
1274
1275 $ module -o -modulepath:tag avail foo
1276 foo/1.0 foo/2.0
1277
1278 On following example, terse output mode of *list* sub-command is
1279 permanently updated to report variant information:
1280
1281 $ module config list_terse_output
1282 Modules Release 5.3.0 (2023-05-14)
1283
1284 - Config. name ---------.- Value (set by if default overridden) ---------------
1285 list_terse_output header
1286 $ module config list_terse_output +variant
1287 $ module config list_terse_output
1288 Modules Release 5.3.0 (2023-05-14)
1289
1290 - Config. name ---------.- Value (set by if default overridden) ---------------
1291 list_terse_output header:variant (env-var)
1292
1293
1294 v5.2
1295 ====
1296
1297 This new version is backward-compatible with previous version 5
1298 release. It fixes bugs but also introduces new functionalities that
1299 are described in this section. See the 5.2 release notes for a
1300 complete list of the changes between Modules v5.1 and v5.2.
1301
1302
1303 Optional requirements
1304 ---------------------
1305
1306 The "--optional" option has been added to the "prereq", "prereq-all",
1307 "depends-on" and "always-load" modulefile commands to indicate that
1308 specified requirement is optional. An automatic load attempt is also
1309 performed for optional requirements. If requirement is not found or
1310 cannot be loaded, the dependency is yet considered satisfied as it is
1311 optional.
1312
1313 $ module show foo
1314 -------------------------------------------------------------------
1315 /path/to/modulefiles/foo:
1316
1317 prereq --optional bar
1318 -------------------------------------------------------------------
1319 $ module load foo
1320 Loading foo
1321 Loading requirement: bar
1322
1323 If the optional requirement is unloaded or loaded afterward, the
1324 dependent module is automatically reloaded thanks to the
1325 "auto_handling" mechanism.
1326
1327 $ module unload bar
1328 Unloading bar
1329 Unloading dependent: foo
1330 Reloading dependent: foo
1331 $ module list
1332 Currently Loaded Modulefiles:
1333 1) foo
1334 $ module load bar
1335 Loading bar
1336 Unloading dependent: foo
1337 Reloading dependent: foo
1338
1339 Modules loaded by other modules with the "module try-load" command are
1340 now considered optional requirements. Dependent module can be loaded
1341 without the *try-load* modules, but now it gets automatically reloaded
1342 if *try-load* module is loaded afterward, to take it into account.
1343
1344
1345 Linting modulefiles
1346 -------------------
1347
1348 Static analysis of modulefile, modulerc and global/user rc is now
1349 possible with "lint" sub-command. It relies on an external program
1350 defined with "tcl_linter" configuration option. Modules or files
1351 specified on the command-line are resolved then passed to the Tcl
1352 linter program.
1353
1354 $ cat /path/to/modulefiles/foo/1.0
1355 #%Module
1356 if {"str" eq} {
1357 else {
1358 }
1359 $ module lint foo/1.0
1360 Linting /path/to/modulefiles/foo/1.0
1361 ERROR line 2: Could not complete statement.
1362 One close brace would complete the first line
1363 One close brace would complete at end of line 4.
1364 One close brace would complete the script body at line 5.
1365 Assuming completeness for further processing.
1366 ERROR line 2: Bad expression: missing operand at _@_
1367 in expression ""str" eq_@_"
1368 WARNING line 3: Unknown command "else"
1369 NOTICE line 4: Close brace not aligned with line 3 (1 0)
1370
1371 Nagelfar is the Tcl linter recommended for Modules and set by default.
1372 This default can be changed at installation time with "--with-tcl-
1373 linter" and "--with-tcl-linter-opts" options. It can also be
1374 configured later on through "tcl_linter" config option.
1375
1376 Specific syntax databases and plugins for Nagelfar are added by
1377 Modules to precisely lint modulefile commands syntax in addition to
1378 regular Tcl syntax. The installation of these specific files is
1379 controlled with "--enable-nagelfar-addons" option (enabled by
1380 default). Their location is controlled by the "--nagelfardatadir"
1381 option.
1382
1383 $ module lint bar@:1 /path/to/modulefiles/.modulerc
1384 Linting /path/to/modulefiles/.modulerc
1385 ERROR line 35: Wrong number of arguments (3) to "module-alias"
1386 ERROR line 41: Wrong number of arguments (3) to "module-virtual"
1387
1388 Linting /path/to/modulefiles/bar/1.2
1389 WARNING line 19: Unknown command "unk"
1390 $ module lint ~/.modulerc
1391 Linting /home/user/.modulerc
1392 WARNING line 2: Command "setenv" should not be be used in global rc file
1393
1394 "lint" sub-command outputs messages returned by the Tcl linter
1395 program. Nagelfar produces NOTICE, WARNING and ERROR messages. If
1396 linter does not report a thing, "lint" sub-command will be silent,
1397 unless if the "--verbose"/"-v" is set.
1398
1399 $ module lint /path/to/modulefiles/bar/.version bar/1.4
1400 $ module lint -v /path/to/modulefiles/bar/.version bar/1.4
1401 Linting /path/to/modulefiles/bar/.version
1402 Linting /path/to/modulefiles/bar/1.4
1403
1404 When no file is specified to "lint" sub-command, all the global/user
1405 rc files and all the modulefiles and modulercs from enabled
1406 modulepaths are analyzed. If the "--all"/"-a" option is set, all
1407 hidden modulefiles are also linted.
1408
1409 $ module lint
1410 Linting /home/user/.modulerc
1411 WARNING line 2: Command "setenv" should not be be used in global rc file
1412
1413 Linting /path/to/modulefiles/.modulerc
1414 ERROR line 35: Wrong number of arguments (3) to "module-alias"
1415 ERROR line 41: Wrong number of arguments (3) to "module-virtual"
1416
1417 Linting /path/to/modulefiles/bar/1.2
1418 WARNING line 19: Unknown command "unk"
1419 ...
1420
1421 To use Nagelfar as Tcl linter for Modules, this open source tool has
1422 to be installed on your system. When installing from tarball
1423 distribution, make sure **nagelfar.tcl** command is found through a
1424 "PATH" lookup or that "tcl_linter" option is set to its full path
1425 location. Nagelfar is also made available as a RPM package in EPEL and
1426 Fedora repositories.
1427
1428
1429 mod-to-sh sub-command
1430 ---------------------
1431
1432 New sub-command is added to translate modulefile into shell code:
1433 "mod-to-sh". It evaluates modulefiles passed as argument and produces
1434 code for specified shell.
1435
1436 $ cat /path/to/modulefiles/foo
1437 #%Module
1438 setenv FOO value
1439 set-function foo {echo foo}
1440 $ module mod-to-sh bash foo
1441 FOO=value; export FOO;
1442 foo () { echo foo; }; export -f foo;
1443
1444 Designated modulefiles are evaluated as if they were loading. But
1445 instead of producing shell code that is evaluated in current shell
1446 session, **module** command outputs this shell code.
1447
1448 $ cat /path/to/modulefiles/bar
1449 #%Module
1450 setenv BAR othervalue
1451 set-alias bar {echo bar}
1452 $ module mod-to-sh fish foo bar
1453 set -xg FOO value;
1454 set -xg BAR othervalue;
1455 alias bar echobar;
1456 function foo; echo foo; end;
1457 $ module list
1458 No Modulefiles Currently Loaded.
1459
1460 All shells supported by "modulecmd.tcl" script are supported by "mod-
1461 to-sh".
1462
1463 $ module mod-to-sh python foo bar
1464 import os
1465 os.environ['FOO'] = 'value'
1466 os.environ['BAR'] = 'othervalue'
1467
1468
1469 Initial environment
1470 -------------------
1471
1472 When Modules initializes, it evaluates the "initrc" and "modulespath"
1473 configuration files to enable default modulepaths and load default
1474 modules. Initial environment corresponds to the environment state
1475 after this initialization.
1476
1477 Initial environment is now saved in an environment variable
1478 ("__MODULES_LMINIT") in current shell session to remember what are the
1479 initial modulepaths and initial modules with their tags and variants
1480 if any.
1481
1482 "reset" sub-command is introduced, in a similar fashion than on Lmod,
1483 to restore the initial environment. Here, "reset" relies on the
1484 collection mechanism based and the content of "__MODULES_LMINIT".
1485 Currently enabled modulepaths and loaded modules are respectively
1486 unused and unloaded to use the modulepaths and load the modules with
1487 tags and variants as described by initial environment.
1488
1489 $ module list
1490 Currently Loaded Modulefiles:
1491 1) foo/1.0 2) bar/1.0
1492 $ module switch bar/1.0 qux/1.0
1493 $ module reset
1494 Unloading qux/1.0
1495 Loading bar/1.0
1496
1497 "restore" sub-command has been adapted to reinitialize the environment
1498 to its initial state when no collection name is provided and no
1499 *default* collection exists or if "__init__" virtual collection name
1500 is provided.
1501
1502 It is possible to view the content of the initial environment with
1503 "saveshow" sub-command. It is displayed when no argument is provided
1504 and no collection exists or if "__init__" name is provided.
1505
1506 $ module saveshow __init__
1507 -------------------------------------------------------------------
1508 initial environment:
1509
1510 module use --append /path/to/modulefiles
1511 module load foo/1.0
1512 module load bar/1.0
1513
1514 -------------------------------------------------------------------
1515
1516 Users have the ability to define what is their initial environment
1517 state and thus adapt the behavior of "reset" sub-command with
1518 "reset_target_state" configuration option. Default value is "__init__"
1519 and it corresponds to the behavior described above. When set to
1520 "__purge__", a "purge" command is performed when resetting. Any other
1521 value corresponds to the name of a collection to restore.
1522
1523 $ module config reset_target_state __purge__
1524 $ module reset
1525 Unloading bar/1.0
1526 Unloading foo/1.0
1527
1528
1529 Stashing environment
1530 --------------------
1531
1532 The ability to stash current environment is added with the
1533 introduction of the "stash" sub-command. When called current
1534 environment is saved in a *stash* collection then initial environment
1535 is restored.
1536
1537 $ module list
1538 Currently Loaded Modulefiles:
1539 1) bar/2.0 2) foo/2.0
1540 $ module stash
1541 Unloading foo/2.0
1542 Unloading bar/2.0
1543 $ module list
1544 No Modulefiles Currently Loaded.
1545
1546 Sub-commands are added to specifically handle stash collections. Their
1547 names are prefixed with *stash*, like "stashlist" to list existing
1548 stash collections or "stashshow" to display their content.
1549
1550 $ module stashlist
1551 Stash collection list:
1552 0) stash-1665377597432 1) stash-1664946764252
1553 $ module stashshow
1554 -------------------------------------------------------------------
1555 /home/user/.module/stash-1665377597432:
1556
1557 module use --append /path/to/modulefiles
1558 module load bar
1559 module load foo
1560
1561 -------------------------------------------------------------------
1562
1563 Stash collections can be designated on sub-commands by their
1564 collection name or stash index. Most recent stash collection has index
1565 "0", the one after is designated with index "1", and so on. When no
1566 stash collection is specified, most recent one is assumed.
1567
1568 $ module stashshow 1
1569 -------------------------------------------------------------------
1570 /home/user/.module/stash-1664946764252:
1571
1572 module use --append /path/to/modulefiles
1573 module load foobar
1574
1575 -------------------------------------------------------------------
1576
1577 Stash collections are restored with the "stashpop" sub-command. It
1578 changes the user environment to match the stash definition, then it
1579 deletes the stash collection file.
1580
1581 $ module stashpop
1582 Loading bar/2.0
1583 Loading foo/2.0
1584 $ module stashlist
1585 Stash collection list:
1586 0) stash-1664946764252
1587
1588 Stash collections can be deleted one by one with "stashrm" sub-command
1589 or all together with "stashclear".
1590
1591 $ module stashrm
1592 $ module stashlist
1593 No stash collection.
1594
1595
1596 Siteconfig hook variables
1597 -------------------------
1598
1599 Several Tcl variables are introduced for Site-specific configuration
1600 script to define specific commands and variables in the evaluation
1601 context of modulefiles and modulercs. These commands and variables
1602 setup in "siteconfig.tcl" can be used in modulefile or modulerc. Sites
1603 can easily extend modulefile and modulerc syntax with specific
1604 elements.
1605
1606 "modulefile_extra_cmds" variable defines a list of commands to expose
1607 in the modulefile evaluation context and the associated procedure to
1608 run when this command is called. This variable has to be defined in
1609 "siteconfig.tcl" located for instance at "/etc/environment-
1610 modules/siteconfig.tcl".
1611
1612 In the following example "modulefile_extra_cmds" is used to define the
1613 "sys" command and bound it to the "sys" procedure that is also defined
1614 in "siteconfig.tcl".
1615
1616 proc sys {mode} {
1617 switch -- $mode {
1618 name { return myhost-$::tcl_platform(machine) }
1619 default { error "Unknown mode '$mode'" }
1620 }
1621 }
1622 set modulefile_extra_cmds {sys sys}
1623
1624 Once "siteconfig.tcl" is setup, the "sys" command can be called by
1625 modulefiles. In the following example it is used to determine the
1626 application path.
1627
1628 $ cat /path/to/modulefiles/foo/1.2
1629 #%Module
1630 append-path PATH /path/to/apps/foo-1.2/[sys name]/bin
1631
1632 $ module show foo/1.2
1633 -------------------------------------------------------------------
1634 /path/to/modulefiles/foo/1.2:
1635
1636 append-path PATH /path/to/apps/foo-1.2/myhost-x86_64/bin
1637 -------------------------------------------------------------------
1638
1639 "modulerc_extra_cmds" follows the same approach than
1640 "modulefile_extra_cmds" and makes specific commands available during
1641 modulerc evaluation.
1642
1643 "modulefile_extra_vars" variable defines a list of variables to expose
1644 in the modulefile evaluation context and their associated value. This
1645 variable has to be defined in "siteconfig.tcl".
1646
1647 In the following example "modulefile_extra_vars" is used to define the
1648 "APP_ROOT" variable with "/path/to/apps" as value.
1649
1650 set modulefile_extra_vars {APP_ROOT /path/to/apps}
1651
1652 Once "siteconfig.tcl" is setup, the "APP_ROOT" variable can be used in
1653 modulefiles.
1654
1655 $ cat /path/to/modulefiles/bar/2.1
1656 #%Module
1657 append-path PATH $APP_ROOT/bar-2.1/[sys name]/bin
1658
1659 $ module show bar/2.1
1660 -------------------------------------------------------------------
1661 /path/to/modulefiles/bar/2.1:
1662
1663 append-path PATH /path/to/apps/bar-2.1/myhost-x86_64/bin
1664 -------------------------------------------------------------------
1665
1666 "modulerc_extra_vars" follows the same approach than
1667 "modulefile_extra_vars" and makes specific variables available during
1668 modulerc evaluation.
1669
1670
1671 v5.1
1672 ====
1673
1674 This new version is backward-compatible with previous version 5
1675 release. It fixes bugs but also introduces new functionalities that
1676 are described in this section. See the 5.1 release notes for a
1677 complete list of the changes between Modules v5.0 and v5.1.
1678
1679
1680 Control output redirection
1681 --------------------------
1682
1683 Since version 4.0, the **module** function is initialized differently
1684 on *sh*, *bash*, *ksh*, *zsh* and *fish* shells when their session is
1685 found interactive. In such situation **module** redirects its output
1686 from *stderr* to *stdout*. Once initialized the redirection behavior
1687 is inherited in sub-sessions.
1688
1689 The "redirect_output" configuration option is introduced in version
1690 5.1, to supersede the default behavior set at initialization time.
1691
1692 $ module load unknown >/dev/null
1693 $ module config redirect_output 0
1694 $ module load unknown >/dev/null
1695 ERROR: Unable to locate a modulefile for 'unknown'
1696
1697 The "--redirect" and "--no-redirect" command-line switches are also
1698 added to change the output redirection behavior for a single command:
1699
1700 $ module load unknown --redirect >/dev/null
1701 $ module load unknown --no-redirect >/dev/null
1702 ERROR: Unable to locate a modulefile for 'unknown'
1703
1704
1705 Change modulefile command behavior
1706 ----------------------------------
1707
1708 Depending on the evaluation mode of the modulefile (e.g. *load*,
1709 *unload*, *display*, etc) commands have different behavior. Most
1710 common example is the "setenv" command that sets an environment
1711 variable when modulefile is loaded and unsets it when it is unloaded.
1712 A different behavior may be wished sometimes for commands. This is why
1713 options are introduced for some modulefile commands to control what
1714 happens on particular evaluation mode.
1715
1716 The "--return-value" option is added to the "getenv" and "getvariant"
1717 modulefile commands to ensure that the value of the designated
1718 environment variable or variant is returned even if modulefile is
1719 evaluated in *display* mode:
1720
1721 $ cat /path/to/modulefiles/foo/1.0
1722 #%Module5.1
1723 if {[getenv --return-value VAR] eq {}} {
1724 setenv VAR value
1725 }
1726 $ module display foo/1.0
1727 -------------------------------------------------------------------
1728 /path/to/modulefiles/foo/1.0:
1729
1730 setenv VAR value
1731 -------------------------------------------------------------------
1732
1733 "--remove-on-unload", "--append-on-unload", "--prepend-on-unload" and
1734 "--noop-on-unload" options are added to the "remove-path" and "module
1735 unuse" modulefile commands to control the behavior applied when
1736 modulefile is unloaded. With these options it is possible for instance
1737 to restore the paths unset at load time or to set other paths:
1738
1739 $ module display bar/1.0
1740 -------------------------------------------------------------------
1741 /path/to/modulefiles/bar/1.0:
1742
1743 module unuse --prepend-on-unload /path/to/dir1
1744 module use /path/to/dir2
1745 -------------------------------------------------------------------
1746 $ module use
1747 Search path for module files (in search order):
1748 /path/to/dir1
1749 /path/to/modulefiles
1750 $ module bar/1.0
1751 $ module use
1752 Search path for module files (in search order):
1753 /path/to/dir2
1754 /path/to/modulefiles
1755 $ module unload bar/1.0
1756 $ module use
1757 Search path for module files (in search order):
1758 /path/to/dir1
1759 /path/to/modulefiles
1760
1761 Following the same trend, the "--unset-on-unload" and "--noop-on-
1762 unload" options are added to the "unsetenv" modulefile command to be
1763 able to choose between unsetting variable, setting a value or
1764 performing no operation when modulefile is unloaded.
1765
1766
1767 Reducing number of I/O operations
1768 ---------------------------------
1769
1770 A new configuration option named "mcookie_check" is introduced to
1771 control the verification made to files to determine if they are
1772 modulefiles. By default this configuration option is set to "always"
1773 and when searching for modulefiles within enabled modulepaths each
1774 file below these directories is opened to check if it starts with the
1775 Modules magic cookie (i.e., "#%Module" file signature).
1776
1777 These historical checks lead to a large number of I/O operations on
1778 large module setup like in the below example where a total of 1098
1779 modulefiles are available:
1780
1781 $ module -o "" avail -t | wc -l
1782 1098
1783 $ module config mcookie_check always
1784 $ strace -f -e open,openat,read,close -c $MODULES_CMD bash avail
1785 ...
1786 % time seconds usecs/call calls errors syscall
1787 ------ ----------- ----------- --------- --------- ----------------
1788 44.29 0.044603 25 1734 166 open
1789 34.15 0.034389 16 2056 close
1790 11.87 0.011949 24 483 5 openat
1791 9.69 0.009761 4 2146 read
1792 ------ ----------- ----------- --------- --------- ----------------
1793 100.00 0.100702 6419 171 total
1794
1795 For each file, 3 I/O operations ("open", "read" and "close") are
1796 achieved to determine if it is a modulefile and include it in search
1797 results. When modulefiles are located in a shared filesystem
1798 concurrently accessed by hundreds of users, a "module avail" command
1799 may take some time to finish.
1800
1801 When setting the "mcookie_check" configuration option to the "eval"
1802 value, files are not checked anymore when searching for modulefiles,
1803 only when evaluating them. All files under modulepaths are considered
1804 modulefiles, so the content of these directories must be carefully
1805 checked to use this "mcookie_check" mode which lead to a significant
1806 reduction of I/O operations:
1807
1808 $ module config mcookie_check eval
1809 $ strace -f -e open,openat,read,close -c $MODULES_CMD bash avail
1810 ...
1811 % time seconds usecs/call calls errors syscall
1812 ------ ----------- ----------- --------- --------- ----------------
1813 30.56 0.013717 14 944 close
1814 28.76 0.012911 21 612 156 open
1815 26.41 0.011857 24 483 5 openat
1816 14.26 0.006403 6 1034 read
1817 ------ ----------- ----------- --------- --------- ----------------
1818 100.00 0.044888 3073 161 total
1819
1820 A substantial reduction of execution time may be noticed depending on
1821 the storage setup used to host the modulepath directories. A special
1822 care should be given to the content of these directories to ensure
1823 they only contain modulefiles (see "MODULES_MCOOKIE_CHECK").
1824
1825 See the Reduce I/O load cookbook recipe to learn additional features
1826 of Modules that could be leveraged to lower the number of I/O
1827 operations.
1828
1829
1830 Shell command completion
1831 ------------------------
1832
1833 New modulefile commands "complete" and "uncomplete" are added to get
1834 the ability to respectively define and unset command completion.
1835 *bash*, *tcsh* and *fish* shells are supported.
1836
1837 > module display foo
1838 -------------------------------------------------------------------
1839 /path/to/modulefiles/foo/1.0:
1840
1841 append-path PATH /path/to/foo-1.0/bin
1842 complete fish foo {-s V -l version --description 'Command version'}
1843 complete fish foo {-s h -l help --description 'Command help'}
1844 -------------------------------------------------------------------
1845 > module load foo
1846 > foo -<TAB>
1847 -h --help (Command help) -V --version (Command version)
1848
1849 "sh-to-mod" sub-command and "source-sh" modulefile command have also
1850 been updated to track shell completion changes.
1851
1852 $ module sh-to-mod bash /path/to/foo-1.0/share/setup-env.sh
1853 #%Module
1854 complete bash foo {-o default -F _foo}
1855 append-path PATH /path/to/foo-1.0/bin
1856 set-function _foo {
1857 ...bash completion code...}
1858
1859
1860 Lmod Tcl modulefile support
1861 ---------------------------
1862
1863 With this new version, Modules now supports Tcl modulefiles written
1864 for Lmod, the alternative **module** implementation developed in Lua.
1865 Such modulefiles can be safely evaluated by Modules without raising
1866 error.
1867
1868 Support has been added for the following modulefile commands
1869 introduced by Lmod: "depends-on", "prereq-any", "always-load", "module
1870 load-any", "pushenv", "require-fullname" and "family".
1871
1872 The Compatibility with Lmod Tcl modulefile section in the modulefile
1873 man page describes the differences existing between the two
1874 implementations.
1875
1876 Note that when processing a "family" command, the "LMOD_FAMILY_<NAME>"
1877 environment variable is defined by Modules to be compatible with
1878 existing modulefiles or scripts relying on such variable.
1879
1880
1881 More tagging capabilities
1882 -------------------------
1883
1884 The new "--tag" option helps to define extra tags onto a loading
1885 module. These tags comes in addition to those inherited from the
1886 module state or those associated with the "module-tag" modulefile
1887 command.
1888
1889 The "--tag" option is available on "load", "load-any", "switch" and
1890 "try-load" sub-commands and on "always-load", "depends-on", "module",
1891 "prereq", "prereq-all" and "prereq-any" modulefile commands.
1892
1893 Informational messages of module evaluation have been updated to
1894 mention in module denomination the tags applying to it, as it is done
1895 in "list" sub-command output:
1896
1897 $ module load -v --tag=sticky:bar foo/1.0
1898 Loading foo/1.0 <bar>
1899
1900 In case the designated module is already loaded, the additional tags
1901 are added to the list of tags already applied to this module.
1902
1903 $ module list
1904 Currently Loaded Modulefiles:
1905 1) foo/1.0
1906 $ module load -v --tag=sticky:bar foo/1.0
1907 Tagging foo/1.0 <bar>
1908
1909 The "keep-loaded" tag is introduced in this version. It avoids an
1910 auto-loaded module to get automatically unloaded when its dependent
1911 modules are unloaded. This new tag can be set with the "module-tag"
1912 modulefile command or when module is loaded with the "always-load"
1913 modulefile command. Default "tag_abbrev" configuration option has been
1914 updated to add the "kL" abbreviation for "keep-loaded" tag. Default
1915 dark and light color palettes have been updated too.
1916
1917 $ module show bar/1.0
1918 -------------------------------------------------------------------
1919 /path/to/modulefiles/bar/1.0:
1920
1921 always-load foo/1.0
1922 -------------------------------------------------------------------
1923 $ module load bar/1.0
1924 Loading bar/1.0
1925 Loading requirement: foo/1.0
1926 $ module unload bar/1.0
1927 $ module list
1928 Currently Loaded Modulefiles:
1929 1) foo/1.0
1930
1931 Key:
1932 auto-loaded keep-loaded
1933
1934 When saving a collection, the tags defined with "--tag" option are
1935 recorded to set them again when collection is restored. Tags resulting
1936 from module load state, like "auto-loaded" and "keep-loaded", are also
1937 recorded.
1938
1939 $ module load --tag=sticky bar/1.0
1940 Loading bar/1.0
1941 Loading requirement: foo/1.0
1942 $ module save
1943 $ module saveshow
1944 -------------------------------------------------------------------
1945 /home/user/.module/default:
1946
1947 module use --append /path/to/modulefiles
1948 module load --tag=auto-loaded:keep-loaded foo
1949 module load --tag=sticky bar
1950
1951 -------------------------------------------------------------------
1952
1953 The "collection_pin_tag" configuration option is added to record in
1954 collection all tags set on loaded modules. This configuration option
1955 is disabled by default.
1956
1957 Note:
1958
1959 Collection saved now starts with a "#%Module5.1" file signature if "
1960 --tag" option is recorded in it. Such collection could only be
1961 handled by Modules version 5.1 and above.
1962
1963
1964 v5.0
1965 ====
1966
1967 With this new major version the **module** experience has been updated
1968 to benefit by default from all the advanced behaviors and features
1969 developed over the Modules 4 versions. Modules 5.0 also introduces
1970 some breaking changes to improve the consistency of the whole
1971 solution. See the 5.0 release notes for a complete list of the changes
1972 between Modules v4.8 and v5.0. The changes document gives an in-depth
1973 view of the modified behaviors.
1974
1975
1976 Upgraded default configuration
1977 ------------------------------
1978
1979 Release after release, new advanced features were added on Modules 4.
1980 They were set off by default to avoid breaking change during the
1981 version 4 cycle. With the move to a new major release, these features
1982 are set on to improve by default usages for everybody. These features
1983 enabled by default are:
1984
1985 * Automated module handling mode which provides the automatic
1986 dependency resolution when loading and unloading modules
1987
1988 $ module load foo/1.0
1989 Loading foo/1.0
1990 Loading requirement: bar/1.0
1991
1992 * Extended default that enables to select a module when the first
1993 number in its version is specified
1994
1995 $ module load -v foo/1
1996 Loading foo/1.2.3
1997
1998 * Advanced module version specifiers, an improved syntax to designate
1999 module version in range or list and module variant
2000
2001 $ module load foo@:2.2 %gcc11
2002 Loading foo/2.1{%gcc11}
2003 Loading requirement: bar/1.2{-debug:%gcc11}
2004
2005 * Colored output to graphically enhance parts of the produced output
2006 to improve readability
2007
2008 $ ml av
2009 ------------------ /path/to/modulefiles ------------------
2010 bar/1.0 bar/2.0 foo/1.0 foo/2.0 foo/2.2
2011
2012 Key:
2013 modulepath module-alias sticky
2014 default-version forbidden
2015
2016 * Specify modules in a case insensitive manner search that matches
2017 modules using a different character case than the one expressed in
2018 search query
2019
2020 $ ml av liba
2021 ------------------ /path/to/modulefiles ------------------
2022 LibA/1.0 LibA/2.0
2023
2024 Some other features that were enabled by default during the Modules 4
2025 cycle have been turned off as they may not be useful for basic usages.
2026 Among other things setting off the following features makes the
2027 definition of the **module** function simpler. Even if off by default,
2028 these features can now be enabled once Modules is installed through
2029 the "initrc" configuration file.
2030
2031 * *Set shell startup* files to ensure the **module** command is
2032 defined once shell has been initialized. See the "set_shell_startup"
2033 configuration option to activate.
2034
2035 * *Quarantine mechanism* that protects the **module** command run-time
2036 environment from side effect coming from the current environment
2037 definition. See the "quarantine_support" configuration option to
2038 activate.
2039
2040 * *Silent shell debug* which disables the debugging property set on
2041 current shell session for the duration of the **module** command.
2042 See the "silent_shell_debug" configuration option to activate.
2043
2044
2045 Removing compatibility version
2046 ------------------------------
2047
2048 The ability to co-install version 3.2 of Modules along newer version
2049 is discontinued. The installation option "--enable-compat-version",
2050 **switchml** shell function and "MODULES_USE_COMPAT_VERSION"
2051 environment variables are thus removed.
2052
2053 The interesting features of Modules 3.2 that were missing in the
2054 initial Modules 4 release in 2017 have been reintroduced progressively
2055 (like "clear" sub-command or "--icase" search). With Modules 5.0, the
2056 "refresh" sub-command is even changed to the behavior it had on
2057 Modules 3.2. So it is a good time for the big jump.
2058
2059 If you are still using Modules 3.2, please refer to the Changes
2060 between versions document that describes the differences of this
2061 version compared to the newer releases.
2062
2063
2064 Improving Modules initialization
2065 --------------------------------
2066
2067 Modules initialization files are now installed by default in the *etc*
2068 directory designated by the "--etcdir" installation option. The
2069 initialization configuration file is named "initrc" in this directory,
2070 and the modulepath-specific configuration file is named "modulespath".
2071 When both files exist, now they are both evaluated instead of just the
2072 "modulespath" file.
2073
2074 Modules magic cookie (i.e., "#%Module" file signature) is now required
2075 at the start of "initrc". An error is produced if the magic cookie is
2076 missing or if the optional version number placed after the cookie
2077 string is higher than the version of the "modulecmd.tcl" script in
2078 use.
2079
2080 Note that "initrc" configuration file can host more than "module use"
2081 and "module load" commands. **module** configuration can also be
2082 achieved with this file through the use of "module config" commands.
2083
2084 Modules initialization has been enhanced for situations where a module
2085 environment is found already defined. In this case the loaded modules
2086 are automatically refreshed which is useful to re-apply the non-
2087 persistent environment configuration (i.e., shell alias and function
2088 that are not exported to the sub-shell). For instance when starting a
2089 sub-shell session it ensures that the loaded environment is fully
2090 inherited from parent shell:
2091
2092 $ ml show foo/1.0
2093 -------------------------------------------------------------------
2094 /path/to/modulefiles/foo/1.0:
2095
2096 set-alias foo {echo foo}
2097 -------------------------------------------------------------------
2098 $ ml foo/1.0
2099 $ alias foo
2100 alias foo='echo foo'
2101 $ bash
2102 $ ml
2103 Currently Loaded Modulefiles:
2104 1) foo/1.0
2105 $ alias foo
2106 alias foo='echo foo'
2107
2108
2109 Simplifying path-like variable reference counting
2110 -------------------------------------------------
2111
2112 The reference counting mechanism used for path-like environment
2113 variable enables to determine if a path entry has been added several
2114 times (by several loaded modules for instance) to know whether or not
2115 this path entry should be unset when unloading a module. Entry is not
2116 removed if multiple loaded modules rely on it.
2117
2118 The mechanism is not applied anymore to the Modules-specific path
2119 variables (like "LOADEDMODULES") as an element entry in these
2120 variables cannot be added multiple times without duplication. For
2121 instance, a given module name and version cannot be added twice in
2122 "LOADEDMODULES" as this module is only loaded once. With this change a
2123 thinner environment is produced by **module**. An exception is made
2124 for "MODULEPATH" environment variable where the mechanism still
2125 applies.
2126
2127 $ $MODULES_CMD bash load foo/2.0
2128 _LMFILES_=/path/to/modulefiles/foo/2.0; export _LMFILES_;
2129 LOADEDMODULES=foo/2.0; export LOADEDMODULES;
2130 __MODULES_LMTAG=foo/2.0&mytag; export __MODULES_LMTAG;
2131 test 0;
2132
2133 Reference counting mechanism has also been simplified for entries in
2134 path-like variable that are only referred once. For such entries no
2135 entry is set in the reference counting variable (which are now called
2136 "__MODULES_SHARE_<VAR>"). A reference count entry is set only if the
2137 entry in the path-like variable is referred more than one time.
2138
2139 $ ml foo/3.0
2140 $ echo $PATHVAR
2141 /path/to/dir1
2142 $ echo $__MODULES_SHARE_PATHVAR
2143
2144 $ ml bar/1.0
2145 $ echo $PATHVAR
2146 /path/to/dir1
2147 $ echo $__MODULES_SHARE_PATHVAR
2148 /path/to/dir1:2
2149 $ ml -foo/3.0
2150 $ echo $PATHVAR
2151 /path/to/dir1
2152 $ echo $__MODULES_SHARE_PATHVAR
2153
2154 $
2155
2156 When the "use" and "unuse" module sub-commands are not called during a
2157 modulefile evaluation, the reference counter associated with each
2158 entry in "MODULEPATH" environment variable is ignored. In such
2159 context, a "module use" will not increase the reference counter of a
2160 path entry already defined and a "module unuse" will remove specified
2161 path whatever its reference counter value. Same change applies for
2162 "append-path", "prepend-path" and "remove-path" module sub-commands
2163 when called from the command-line.
2164
2165 $ echo $MODULEPATH
2166 /path/to/modulefiles
2167 $ echo $__MODULES_SHARE_MODULEPATH
2168 /path/to/modulefiles:2
2169 $ ml use /path/to/modulefiles
2170 $ echo $__MODULES_SHARE_MODULEPATH
2171 /path/to/modulefiles:2
2172 $ ml unuse /path/to/modulefiles
2173 $ echo $MODULEPATH
2174
2175 $ echo $__MODULES_SHARE_MODULEPATH
2176
2177 $
2178
2179
2180 v4.8
2181 ====
2182
2183 This new version is backward-compatible with previous version 4
2184 releases. It fixes bugs but also introduces new functionalities that
2185 are described in this section. See the 4.8 release notes for a
2186 complete list of the changes between Modules v4.7 and v4.8.
2187
2188
2189 Editing modulefiles
2190 -------------------
2191
2192 "edit" sub-command is introduced to give the ability to open
2193 modulefiles in a text editor. Modulefiles can be specified like with
2194 any other sub-command: using regular, symbolic or aliased names or
2195 using advanced version specifiers.
2196
2197 $ ml edit foo
2198
2199 "edit" sub-command resolves the path toward the designated modulefile
2200 then call configured text editor to open this modulefile with it.
2201 Below, the modulefile is opened with the "vi" command:
2202
2203 #%Module
2204 module-whatis [module-info name]
2205 setenv PATH /path/to/foo-1.0/bin
2206 ~
2207 ~
2208 ~
2209 "/path/to/modulefiles/foo/1.0" 3L, 42B 1,1 All
2210
2211 The "editor" configuration option controls the editor command to use.
2212 This option can be configured at installation time with the "--with-
2213 editor" installation option. If not set, "editor" configuration option
2214 is set by default to "vi".
2215
2216 "editor" configuration option can be changed with the "config" sub-
2217 command. Which sets the "MODULES_EDITOR" environment variable.
2218
2219 The "VISUAL" or the "EDITOR" environment variables override the
2220 default value of "editor" configuration option but are overridden by
2221 the "MODULES_EDITOR" environment variable.
2222
2223
2224 Using version range in version list
2225 -----------------------------------
2226
2227 The Advanced module version specifiers mechanism has been improved to
2228 allow the use of version range (*@:version*, *@vers1:vers2* or
2229 *@version:*) within version list (*@version1,version2,...*).
2230
2231 It is now possible to write for instance "mod@:1.2,1.4:1.6,1.8:" to
2232 designate all versions of module *mod*, except versions *1.3* and
2233 *1.7*.
2234
2235 This improvement is available where the advanced version specifier
2236 syntax is supported. Thus it can be either used from the command-line
2237 or when writing modulefiles, for instance to hide or tag modules or to
2238 declare requirements.
2239
2240
2241 Try module load with no complain if not found
2242 ---------------------------------------------
2243
2244 Add the "try-load" sub-command that tries to load the modulefile
2245 passed as argument, like the "load" sub-command, but does not raise an
2246 error if this modulefile cannot be found.
2247
2248 $ module load unknown
2249 ERROR: Unable to locate a modulefile for 'unknown'
2250 $ echo $?
2251 1
2252 $ module try-load unknown
2253 $ echo $?
2254 0
2255 $ module list
2256 No Modulefiles Currently Loaded.
2257
2258 This sub-command first introduced by the Lmod project is added to
2259 Modules to improve the compatibility between the two "module"
2260 implementations.
2261
2262 "try-load" is also available within modulefile context to continue the
2263 evaluation of a modulefile in case no module is found in its attempt
2264 to load another modulefile
2265
2266 $ module display foo/1.0
2267 -------------------------------------------------------------------
2268 /path/to/modulefiles/foo/1.0:
2269
2270 module try-load unknown/1.0
2271 -------------------------------------------------------------------
2272 $ module load foo/1.0
2273 $ module list
2274 Currently Loaded Modulefiles:
2275 1) foo/1.0
2276
2277
2278 Module variants
2279 ---------------
2280
2281 Module variants is a new mechanism that allows to pass arguments to
2282 evaluated modulefiles in order to achieve different environment
2283 variable or module requirement setup with a single modulefile.
2284
2285 Variant specification relies on the Advanced module version specifiers
2286 mechanism, which leverages the variant syntax of the Spack package
2287 manager:
2288
2289 $ module config advanced_version_spec 1
2290 $ module load -v bar/1.2 toolchain=a -debug
2291 Loading bar/1.2{-debug:toolchain=a}
2292
2293 Variants are defined in modulefile with the "variant" command, which
2294 defines the variant type and its accepted values:
2295
2296 #%Module4.8
2297 variant toolchain a b c
2298 variant --boolean --default off debug
2299
2300 # select software build depending on variant values
2301 set suffix -[getvariant toolchain]
2302 if {$ModuleVariant(debug)} {
2303 append suffix -dbg
2304 }
2305
2306 prepend-path PATH /path/to/bar-1.2$suffix/bin
2307 prepend-path LD_LIBRARY_PATH /path/to/bar-1.2$suffix/lib
2308
2309 The *bar/1.2* modulefile defines a "toolchain" variant, which accepts
2310 the "a", "b" and "c" values, and a "debug" Boolean variant, which is
2311 set "off" by default. Once these two variants are declared, their
2312 value specified on module designation are instantiated in the
2313 "ModuleVariant" array variable which could also be queried with the
2314 "getvariant" modulefile command. Selected variant values enable to
2315 define a specific installation build path for the *bar/1.2* software.
2316
2317 If a variant is not specified when designating module and if this
2318 variant is not declared with a default value, an error is obtained:
2319
2320 $ module purge
2321 $ module load [email protected]
2322 Loading bar/1.2
2323 ERROR: No value specified for variant 'toolchain'
2324 Allowed values are: a b c
2325
2326 Once module is loaded, selected variants are reported on the "list"
2327 sub-command output:
2328
2329 $ module load [email protected] toolchain=b
2330 $ module list
2331 Currently Loaded Modulefiles:
2332 1) bar/1.2{-debug:toolchain=b}
2333
2334 Key:
2335 {-variant}={variant=off} {variant=value}
2336
2337 Note:
2338
2339 The default value of the "--with-list-output" installation option
2340 has been updated to include variant information.
2341
2342 Variant specification could be used where the Advanced module version
2343 specifiers is supported. For instance a module may express a
2344 dependency over a specific module variant:
2345
2346 $ module show foo/2.1 toolchain=c
2347 -------------------------------------------------------------------
2348 /path/to/modulefiles/foo/2.1:
2349
2350 variant toolchain a b c
2351 prereq [email protected] toolchain={toolchain}
2352 prepend-path PATH /path/to/foo-2.1-{toolchain}/bin
2353 prepend-path LD_LIBRARY_PATH /path/to/foo-2.1-{toolchain}/lib
2354 -------------------------------------------------------------------
2355
2356 In this example, *foo/2.1* module depends on *bar/1.2* and the same
2357 toolchain variant should be selected for both modules in order to load
2358 two software builds that are compatible between each other.
2359
2360 $ module purge
2361 $ module config auto_handling 1
2362 $ module load foo/2.1 toolchain=a
2363 Loading foo/2.1{toolchain=a}
2364 Loading requirement: bar/1.2{-debug:toolchain=a}
2365
2366
2367 Variant shortcuts
2368 -----------------
2369
2370 The "variant_shortcut" configuration option is added to define
2371 shortcut characters for easily specifying variants. Instead of writing
2372 the variant name to specify it in module designation (e.g.,
2373 *name=value*), the shortcut associated to this variant could be used
2374 (i.e., *<shortcut>value*):
2375
2376 $ module purge
2377 $ module config variant_shortcut toolchain=%
2378 $ module load foo/2.1 %a
2379 Loading foo/2.1{%a}
2380 Loading requirement: bar/1.2{-debug:%a}
2381
2382 Configured shortcuts are also used to report the loaded variant on
2383 "list" sub-command output (shortcuts are explained in key section):
2384
2385 $ module list
2386 Currently Loaded Modulefiles:
2387 1) bar/1.2{-debug:%a} 2) foo/2.1{%a}
2388
2389 Key:
2390 auto-loaded {-variant}={variant=off} {%value}={toolchain=value} {variant=value}
2391
2392
2393 v4.7
2394 ====
2395
2396 This new version is backward-compatible with previous version 4
2397 releases. It fixes bugs but also introduces new functionalities that
2398 are described in this section. See the 4.7 release notes for a
2399 complete list of the changes between Modules v4.6 and v4.7.
2400
2401
2402 Determining module implementation and version
2403 ---------------------------------------------
2404
2405 New Modules variables are introduced to determine during the
2406 evaluation of a modulefile or a modulerc what *module* implementation
2407 is currently in use. The "ModuleTool" variable corresponds to the name
2408 of the *module* implementation and is set to "Modules" for this
2409 project. The "ModuleToolVersion" variable corresponds to the version
2410 number of the implementation (e.g. "4.7.0").
2411
2412 With these new variables it is possible to precisely know what
2413 *module* command is in use then adapt modulefile code to handle a
2414 specific behavior or leverage a new feature.
2415
2416 The modulefile command "versioncmp" is also introduced to provide a
2417 simple way to compare two version strings and return if first version
2418 string is less than, equal to or greater than second one.
2419
2420 if {[info exists ModuleTool] && $ModuleTool eq {Modules}
2421 && [versioncmp $ModuleToolVersion 4.7] >= 0} {
2422 # here some code specific for Modules 4.7 and later versions
2423 }
2424
2425 The "ModuleTool" and "ModuleToolVersion" variables and the
2426 "versioncmp" modulefile command are supported by the Lmod project
2427 starting version "8.4.8".
2428
2429
2430 Symbolic version to designate module loaded version
2431 ---------------------------------------------------
2432
2433 When the Advanced module version specifiers is enabled, the "loaded"
2434 symbolic version may be used to designate the currently loaded version
2435 of specified module.
2436
2437 $ ml display foo@loaded
2438 -------------------------------------------------------------------
2439 /path/to/modulefiles/foo/1.0:
2440
2441 module-whatis foo/1.0
2442 -------------------------------------------------------------------
2443
2444 If no version of specified module can be found loaded, an error is
2445 returned.
2446
2447 $ ml display foo@loaded
2448 ERROR: No loaded version found for 'foo' module
2449
2450
2451 Module tags
2452 -----------
2453
2454 Module tags are piece of information that can be associated to
2455 individual modulefiles. Tags could be purely informational or may lead
2456 to specific behaviors.
2457
2458 Module tags may be inherited from the module state set by a modulefile
2459 command or consequence of a module action. Tags may also be associated
2460 to modules by using the new "module-tag" modulefile command.
2461
2462 Module tags are reported along the module they are associated to on
2463 "avail" and "list" sub-command results. Tags could be reported either:
2464
2465 * along the module name, all tags set within angle brackets, each tag
2466 separated from the others with a colon character (e.g., "foo/1.2
2467 <tag1:tag2>").
2468
2469 $ cat /path/to/modulefiles/foo/.modulerc
2470 #%Module
2471 module-tag mytag foo
2472 module-tag othertag foo/1.0
2473 $ ml av
2474 --------------- /path/to/modulefiles ---------------
2475 foo/1.0 <mytag:othertag> foo/2.0 <mytag>
2476 $ ml foo/1.0
2477 $ ml
2478 Currently Loaded Modulefiles:
2479 1) foo/1.0 <mytag:othertag>
2480
2481 * graphically rendered over the module name for each tag associated to
2482 a Select Graphic Rendition (SGR) code in the color palette (see
2483 "MODULES_COLORS")
2484
2485 $ # set SGR code to report 'mytag' with blue background color
2486 $ ml config colors "hi=1:di=94:L=90;47:mytag=102"
2487 $ ml av
2488 --------------- /path/to/modulefiles ---------------
2489 foo/1.0 <othertag> foo/2.0
2490 $ ml
2491 Currently Loaded Modulefiles:
2492 1) foo/1.0 <othertag>
2493
2494 The "tag_abbrev" configuration option is available to define
2495 abbreviated strings for module tags and then use these abbreviations
2496 instead of tag names when reporting tags on "avail" and "list" command
2497 results.
2498
2499 $ # add abbreviation for 'othertag' tag
2500 $ ml config tag_abbrev loaded=L:othertag=oT
2501 $ ml av
2502 --------------- /path/to/modulefiles ---------------
2503 foo/1.0 <oT> foo/2.0
2504 $ ml
2505 Currently Loaded Modulefiles:
2506 1) foo/1.0 <oT>
2507
2508 When a SGR code is set for a tag in the color palette, this graphical
2509 rendition is applied by default over the module name and the tag name
2510 or its abbreviation is not displayed. If tag name or abbreviation is
2511 added to the "tag_color_name" configuration option, graphical
2512 rendering is applied to the tag name or abbreviation rather than over
2513 the module name they are attached to.
2514
2515 $ # add SGR code for 'oT' tag and set rendition over tag name
2516 $ ml config colors "hi=1:di=94:L=90;47:mytag=44:oT=41"
2517 $ ml config tag_color_name oT
2518 $ ml av
2519 --------------- /path/to/modulefiles ---------------
2520 foo/1.0 <oT> foo/2.0
2521 $ ml
2522 Currently Loaded Modulefiles:
2523 1) foo/1.0 <oT>
2524
2525 Tags inherited from module state, consequence of a module action or
2526 set by using "module-tag" but that have a special meaning currently
2527 are:
2528
2529 +--------------------+---------------------------+--------------------------+---------+
2530 | Tag | Description | Set with | Abbr. |
2531 |====================|===========================|==========================|=========|
2532 | auto-loaded | Module has been loaded | Inherited | aL |
2533 | | automatically | | |
2534 +--------------------+---------------------------+--------------------------+---------+
2535 | forbidden | Module cannot be loaded | Inherited from "module- | F |
2536 | | | forbid" | |
2537 +--------------------+---------------------------+--------------------------+---------+
2538 | hidden | Module is not visible on | Inherited from "module- | H |
2539 | | "avail" | hide" | |
2540 +--------------------+---------------------------+--------------------------+---------+
2541 | hidden-loaded | See Hiding loaded modules | Inherited from "module- | H |
2542 | | | hide" | |
2543 +--------------------+---------------------------+--------------------------+---------+
2544 | loaded | Module is currently | Inherited | L |
2545 | | loaded | | |
2546 +--------------------+---------------------------+--------------------------+---------+
2547 | nearly-forbidden | Module will soon not be | Inherited from "module- | nL |
2548 | | able to load anymore | forbid" | |
2549 +--------------------+---------------------------+--------------------------+---------+
2550 | sticky | See Sticky modules | "module-tag" | S |
2551 +--------------------+---------------------------+--------------------------+---------+
2552 | super-sticky | See Sticky modules | "module-tag" | sS |
2553 +--------------------+---------------------------+--------------------------+---------+
2554
2555
2556 Hiding loaded modules
2557 ---------------------
2558
2559 The "--hidden-loaded" option has been added to the "module-hide"
2560 modulefile command and it indicates that designated hidden modules
2561 remain hidden after being loaded.
2562
2563 $ cat /path/to/modulefiles/foo/1.0
2564 #%Module
2565 module load bar
2566 $ cat /path/to/modulefiles/bar/.modulerc
2567 #%Module4.7
2568 module-hide --soft --hidden-loaded bar
2569
2570 In this example, *foo* depends on *bar* which is set soft hidden and
2571 hidden once loaded. As a consequence, automated load of *bar* module
2572 will not be reported and *bar/1.0* will not appear in loaded module
2573 list by default:
2574
2575 $ ml foo
2576 $ ml
2577 Currently Loaded Modulefiles:
2578 1) foo/1.0
2579
2580 However *bar/1.0* is loaded. Hidden loaded modules can be unveiled
2581 with the "--all"/"-a" option set on the "list" sub-command. "hidden-
2582 loaded" tag (abbreviated by default to "H" when colored output is
2583 disabled) applies to such modules.
2584
2585 $ ml -a
2586 Currently Loaded Modulefiles:
2587 1) bar/1.0 2) foo/1.0
2588
2589 To also get the informational messages about hidden loaded module
2590 automated load or unload, the new verbosity level "verbose2" can be
2591 used (with "-vv" option for instance):
2592
2593 $ ml purge
2594 $ ml -vv foo
2595 Loading bar/1.0
2596
2597 Loading foo/1.0
2598 Loading requirement: bar/1.0
2599
2600
2601 Sticky modules
2602 --------------
2603
2604 Module stickiness is introduced, in a similar fashion than on the Lmod
2605 project, to allow to glue modules to the loaded environment. A sticky
2606 module cannot be unloaded, unless if the unload action is forced or if
2607 the module reloads after being unloaded.
2608
2609 A modulefile is declared *sticky* by applying it the "sticky" tag with
2610 the "module-tag" modulefile command.
2611
2612 $ cat /path/to/modulefiles/foo/.modulerc
2613 #%Module4.7
2614 module-tag sticky foo/1.0
2615 $ ml
2616 Currently Loaded Modulefiles:
2617 1) foo/1.0
2618 $ ml -foo
2619 Unloading foo/1.0
2620 ERROR: Unload of sticky module 'foo/1.0' skipped
2621 $ ml
2622 Currently Loaded Modulefiles:
2623 1) foo/1.0
2624 $ ml --force -foo
2625 Unloading foo/1.0
2626 WARNING: Unload of sticky module 'foo/1.0' forced
2627 $ ml
2628 No Modulefiles Currently Loaded.
2629
2630 Modulefile can also be defined "super-sticky" by applying the
2631 corresponding module tag. *Super-sticky* module cannot be unloaded
2632 even if the unload action is forced. It can only be unloaded if the
2633 module reloads afterward.
2634
2635 $ cat /path/to/modulefiles/bar/.modulerc
2636 #%Module4.7
2637 module-tag super-sticky bar/1.0
2638 $ ml
2639 Currently Loaded Modulefiles:
2640 1) bar/1.0
2641 $ ml purge
2642 Unloading bar/1.0
2643 ERROR: Unload of super-sticky module 'bar/1.0' skipped
2644 $ ml purge -f
2645 Unloading bar/1.0
2646 ERROR: Unload of super-sticky module 'bar/1.0' skipped
2647 $ ml
2648 Currently Loaded Modulefiles:
2649 1) bar/1.0
2650
2651 Modulefiles targeted by a "sticky" or a "super-sticky" tag are colored
2652 on "avail" and "list" sub-command outputs to indicate such tag
2653 applies. If colored output is disabled a tag abbreviation is reported
2654 along module designation (respectively "S" and "sS").
2655
2656 In case the stickiness applies to the generic module name (and does
2657 not target a specific module version or version-set), one version of
2658 the sticky or super-sticky module can be swapped by another version of
2659 this same module:
2660
2661 $ cat /path/to/modulefiles/baz/.modulerc
2662 #%Module4.7
2663 module-tag sticky baz
2664 $ ml
2665 Currently Loaded Modulefiles:
2666 1) baz/2.0
2667 $ ml switch baz/1.0
2668 $ ml
2669 Currently Loaded Modulefiles:
2670 1) baz/1.0
2671
2672
2673 Explaining avail/list output
2674 ----------------------------
2675
2676 A *Key* section is added at the end of the "avail" and "list" sub-
2677 commands output to give hints on the meaning of the graphical
2678 rendition applied to elements or what the elements set in parentheses
2679 or chevrons along module name stand for.
2680
2681 $ ml av
2682 ------------------ /path/to/modulefiles ------------------
2683 foo/1.0 <oT> foo/2.0 foo/3.0
2684
2685 Key:
2686 loaded default-version sticky <oT>=othertag
2687 modulepath module-alias <module-tag>
2688
2689
2690 Configuring avail/list output
2691 -----------------------------
2692
2693 New configuration options are introduced to control what content to
2694 output in addition to modules names on the regular and terse output
2695 modes of the "avail" and "list" sub-commands.
2696
2697 These new configuration options named "avail_output",
2698 "avail_terse_output", "list_output" and "list_terse_output" can be
2699 updated using the "config" sub-command or set at installation time
2700 respectively with the "--with-avail-output", "--with-avail-terse-
2701 output", "--with-list-output" and "--with-list-terse-output" configure
2702 options.
2703
2704 The four options accept a colon separated list of elements as value.
2705 Accepted elements for the "avail"-related options are: "modulepath",
2706 "alias", "dirwsym", "sym", "tag" and "key". Accepted elements for the
2707 "list"-related options are: "header", "idx", "sym", "tag" and "key".
2708
2709 In the following example, default output configuration for the "avail"
2710 sub-command is checked then module tags and key section are removed to
2711 get a simpler output:
2712
2713 $ ml config avail_output
2714 Modules Release 4.7.0 (2021-02-19)
2715
2716 - Config. name ---------.- Value (set by if default overridden) ---------------
2717 avail_output modulepath:alias:dirwsym:sym:tag:key
2718 $ ml av
2719 ------------------ /path/to/modulefiles ------------------
2720 bar/1.0 bar/2.0 foo/1.0 foo/2.0 foo/2.2
2721
2722 Key:
2723 modulepath module-alias sticky
2724 default-version forbidden
2725 $ ml config avail_output modulepath:alias:dirwsym:sym
2726 $ ml av
2727 ------------------ /path/to/modulefiles ------------------
2728 bar/1.0 bar/2.0 foo/1.0 foo/2.0 foo/2.2
2729
2730 The "--output"/"-o" switches are added to define a specific output
2731 configuration for the duration of the associated command line. The
2732 following example shows how to limit the content reported on a module
2733 "list" to the loaded index and the symbolic versions in addition to
2734 the module names:
2735
2736 $ ml
2737 Currently Loaded Modulefiles:
2738 1) bar/1.0 2) foo/2.0
2739
2740 Key:
2741 default-version sticky
2742 $ ml -o idx:sym
2743 1) bar/1.0 2) foo/2.0
2744
2745 When the new configuration options or command line switches are set to
2746 an empty value, the module names are the sole information reported:
2747
2748 $ ml -t -o ""
2749 bar/1.0
2750 foo/2.0
2751
2752 In case the "modulepath" element is withdrawn from the "avail" sub-
2753 command output configuration, the available modules from all enabled
2754 modulepaths are reported as a single list:
2755
2756 $ ml av
2757 --------------- /path/to/other/modulefiles ---------------
2758 baz/1.0 baz/2.0
2759
2760 ------------------ /path/to/modulefiles ------------------
2761 bar/1.0 bar/2.0 foo/1.0 foo/2.0 foo/2.2
2762
2763 Key:
2764 modulepath module-alias sticky
2765 default-version forbidden
2766 $ ml av --output=alias:tag
2767 bar/1.0 baz/1.0 foo/1.0 foo/2.2
2768 bar/2.0 baz/2.0 foo/2.0
2769
2770 Note:
2771
2772 The "avail_report_dir_sym" and "avail_report_mfile_sym" locked
2773 configuration options have been removed. Their behaviors can now be
2774 obtained by respectively adding the "dirwsym" and "sym" elements to
2775 the "avail_output" or "avail_terse_output" configuration options.
2776
2777
2778 v4.6
2779 ====
2780
2781 This new version is backward-compatible with previous version 4
2782 releases. It fixes bugs but also introduces new functionalities that
2783 are described in this section. See the 4.6 release notes for a
2784 complete list of the changes between Modules v4.5 and v4.6.
2785
2786
2787 sh-to-mod sub-command
2788 ---------------------
2789
2790 The "sh-to-mod" sub-command is added to output as a modulefile content
2791 the environment changes done by the evaluation of a shell script
2792 passed as argument. "sh-to-mod" is especially useful for software
2793 providing a shell script for their enablement in shell session: it can
2794 convert these scripts into modulefiles.
2795
2796 Say for instance, a *foo* software has been installed and it provides
2797 a "foo-setup.sh" script to activate *foo* software in user
2798 environment:
2799
2800 $ cat /path/to/foo-1.2/foo-setup.sh
2801 #!/bin/sh
2802 export FOOENV="$1"
2803 export PATH=/path/to/foo-1.2/bin:$PATH
2804 alias foo='foobin -q -l'
2805
2806 Calling "module sh-to-mod" on this shell script outputs the
2807 environment changes it performs as a modulefile content:
2808
2809 $ module sh-to-mod sh /path/to/foo-1.2/foo-setup.sh arg1
2810 #%Module
2811 prepend-path PATH /path/to/foo-1.2/bin
2812 set-alias foo {foobin -q -l}
2813 setenv FOOENV arg1
2814
2815 Changes on environment variables, shell aliases, shell functions and
2816 current working directory are tracked. The following shells are
2817 supported: *sh*, *dash*, *csh*, *tcsh*, *bash*, *ksh*, *ksh93*, *zsh*
2818 and *fish*.
2819
2820 "sh-to-mod" acts as a full replacement for the standalone
2821 **createmodule.sh** and **createmodule.py** scripts. However those two
2822 scripts are currently still provided for compatibility purpose.
2823
2824
2825 source-sh modulefile command
2826 ----------------------------
2827
2828 The "source-sh" modulefile command is introduced to source environment
2829 changes done by the evaluation of a shell script passed as argument.
2830 With newly introduced "sh-to-mod" sub-command resulting environment
2831 changes done by script are output as modulefile commands. "source-sh"
2832 applies those modulefile commands as if they were directly written in
2833 loading modulefile.
2834
2835 "source-sh" is useful for software providing a shell script for their
2836 enablement. If you want to enable such software with **module** yet
2837 using shell script provided by software for this task, just write a
2838 modulefile using "source-sh" command to call the shell script.
2839
2840 Keeping the same example used to describe "sh-to-mod" sub-command:
2841 *foo* software provides a "foo-setup.sh" script for its activation.
2842 Create a modulefile "foo/1.2" that calls this script:
2843
2844 $ cat /path/to/modulefiles/foo/1.2
2845 #%Module4.6
2846 source-sh sh /path/to/foo-1.2/foo-setup.sh arg1
2847
2848 Displaying this modulefile indicates the environment changes done by
2849 script:
2850
2851 $ module display foo/1.2
2852 -------------------------------------------------------------------
2853 /path/to/modulefiles/foo/1.2:
2854
2855 prepend-path PATH /path/to/foo-1.2/bin
2856 set-alias foo {foobin -q -l}
2857 setenv FOOENV arg1
2858 -------------------------------------------------------------------
2859
2860 Loading the modulefile applies the environment changes seen above:
2861
2862 $ module load -v foo/1.2
2863 Loading foo/1.2
2864 $ echo $FOOENV
2865 arg1
2866 $ alias foo
2867 alias foo='foobin -q -l'
2868
2869 Track of these changes is kept in user environment to be able to undo
2870 them when modulefile is unloaded:
2871
2872 $ module unload -v foo/1.2
2873 Unloading foo/1.2
2874 $ echo $FOOENV
2875
2876 $ alias foo
2877 bash: alias: foo: not found
2878
2879 Changes on environment variables, shell aliases, shell functions and
2880 current working directory are tracked. The following shells are
2881 supported: *sh*, *dash*, *csh*, *tcsh*, *bash*, *ksh*, *ksh93*, *zsh*
2882 and *fish*.
2883
2884
2885 Querying user's name and groups membership
2886 ------------------------------------------
2887
2888 Two new sub-commands are introduced for the "module-info" modulefile
2889 command: "username" and "usergroups". They respectively fetch the name
2890 of the user currently running "modulecmd.tcl" or the name of all the
2891 groups this user is member of.
2892
2893 These two new modulefile commands can help to adapt code to specific
2894 users or groups. Like for instance to instantiate a modulefile for
2895 each group the user is member of:
2896
2897 $ cat /path/to/modulefiles/foo/.modulerc
2898 #%Module4.6
2899 foreach grp [module-info usergroups] {
2900 module-virtual foo/$grp .common
2901 }
2902 $ id -G -n
2903 grp1 grp2 grp3
2904 $ module avail
2905 --------------- /path/to/modulefiles ---------------
2906 foo/grp1 foo/grp2 foo/grp3
2907
2908 "username" and "usergroups" sub-commands of "module-info" modulefile
2909 command are only supported on Unix platform.
2910
2911
2912 Hiding modules
2913 --------------
2914
2915 The newly introduced "module-hide" modulefile command enables to
2916 dynamically hide modulefiles, module aliases or symbolic versions
2917 specified to it:
2918
2919 $ cat /path/to/modulefiles/bar/.modulerc
2920 #%Module4.6
2921 module-version bar/1.0 old
2922 # hide 'old' symbolic version
2923 module-hide bar/old
2924 # hide all version 2 and above
2925 module-hide bar@2:
2926 $ cat /path/to/modulefiles/.modulerc
2927 #%Module4.6
2928 # hide all versions of foo module
2929 module-hide foo
2930
2931 "module-hide" commands should be placed in module rc files and can
2932 leverage the Advanced module version specifiers syntax as shown in the
2933 above example.
2934
2935 Hidden modules are excluded from available module search or module
2936 selection unless query refers to hidden module by its exact name:
2937
2938 $ ml av
2939 --------------- /path/to/modulefiles ---------------
2940 bar/1.0 bar/2.0
2941 $ module load -v foo
2942 ERROR: Unable to locate a modulefile for 'foo'
2943 $ module load -v foo/1.0
2944 Loading foo/1.0
2945 $ module avail bar/old
2946 --------------- /path/to/modulefiles ---------------
2947 bar/1.0(old)
2948
2949 "module-hide" command accepts a "--soft" option to apply a lighter of
2950 hiding to modules:
2951
2952 $ cat /path/to/modulefiles/qux/.modulerc
2953 #%Module4.6
2954 # softly hide all qux modules
2955 module-hide --soft qux
2956
2957 The soft hiding mode enables to hide modules from full availability
2958 listing yet keeping the ability to select such module for load without
2959 having to use module exact name:
2960
2961 $ ml av
2962 --------------- /path/to/modulefiles ---------------
2963 bar/1.0 bar/2.0
2964 $ ml av qux
2965 --------------- /path/to/modulefiles ---------------
2966 qux/1.0 qux/2.0
2967 $ module load -v qux
2968 Loading qux/2.0
2969
2970 Alternatively, a "--hard" option can be set on "module-hide" command
2971 to ensure designated modules do not unveil even if referred by their
2972 exact name:
2973
2974 $ cat /path/to/modulefiles/qux/.modulerc
2975 #%Module4.6
2976 # softly hide all qux modules
2977 module-hide --soft qux
2978 # set highest version of qux hard hidden
2979 module-hide --hard qux/3.0
2980 $ ml av qux/3.0
2981 $ ml qux/3.0
2982 ERROR: Unable to locate a modulefile for 'qux/3.0'
2983
2984 Some users or groups can be set unaffected by hiding mechanism with
2985 the "--not-user" or "--not-group" options:
2986
2987 $ cat /path/to/modulefiles/quuz/.modulerc
2988 #%Module4.6
2989 # hiding does not apply to grp1 and grp2 groups
2990 module-hide --not-group {grp1 grp2} quuz
2991
2992 $ id --groups --name
2993 grp1 grp7
2994 $ ml av quuz
2995 --------------- /path/to/modulefiles ---------------
2996 quuz/1.0 quuz/2.0
2997 $ ml -v quuz
2998 Loading quuz/2.0
2999
3000 Hiding mechanism can also be set effective only before or after a
3001 given date time with the "--before" and "--after" options. Accepted
3002 date time format is "YYYY-MM-DD[THH:MM]".
3003
3004 $ cat /path/to/modulefiles/fum/.modulerc
3005 #%Module4.6
3006 # hide only before a given date
3007 module-hide --hard --before 2020-09-01T12:00 fum/1.0
3008 # hide only after a given date
3009 module-hide --hard --after 2020-09-01 fum/2.0
3010
3011 $ date
3012 Fri 04 Sep 2020 06:21:48 AM CEST
3013 $ ml av fum
3014 --------------- /path/to/modulefiles ---------------
3015 fum/1.0
3016
3017 Hidden modules can be included in available module searches if option
3018 "--all"/"-a" is set on "avail", "aliases", "whatis" or "search" sub-
3019 commands. Hard hidden modules are unaffected by this option and stay
3020 hidden.
3021
3022 $ ml av -a
3023 --------------- /path/to/modulefiles ---------------
3024 bar/1.0(old) foo/1.0 fum/1.0 quuz/2.0 qux/2.0
3025 bar/2.0 foo/2.0 quuz/1.0 qux/1.0
3026
3027
3028 Forbidding use of modules
3029 -------------------------
3030
3031 The "module-forbid" modulefile command is added to dynamically forbid
3032 the evaluation of modulefiles it specifies. When forbidden, a module
3033 cannot be loaded and an access error is returned when an attempt is
3034 made to evaluate it.
3035
3036 $ cat /path/to/modulefiles/foo/.modulerc
3037 #%Module4.6
3038 module-forbid foo@1:
3039 $ ml foo/1.0
3040 ERROR: Access to module 'foo/1.0' is denied
3041 $ ml
3042 No Modulefiles Currently Loaded.
3043
3044 "module-forbid" statements can be coupled with "module-hide"
3045 statements to hide modules in addition to forbid their use. "module-
3046 forbid" supports the "--not-user", "--not-group", "--before" and "--
3047 after" options to still allow some users or forbid modules before or
3048 after a given date time.
3049
3050 An additional error message can be defined with the "--message" option
3051 to guide for instance users when they try to evaluate a forbidden
3052 module:
3053
3054 $ cat /path/to/modulefiles/bar/.modulerc
3055 #%Module4.6
3056 module-forbid --message {Software bar/1.0 is decommissioned, please now use\
3057 bar/2.0} --after 2020-09-01 bar/1.0
3058 $ ml bar/1.0
3059 ERROR: Access to module 'bar/1.0' is denied
3060 Software bar/1.0 is decommissioned, please now use bar/2.0
3061
3062 When an evaluated module will soon be forbidden, a message is returned
3063 to the user to warn them of the near limit. An additional warning
3064 message can also be defined here with the "--nearly-message" option to
3065 guide users.
3066
3067 $ cat /path/to/modulefiles/qux/.modulerc
3068 #%Module4.6
3069 module-forbid --nearly-message {Version 1.0 will soon expire, please now use\
3070 version 2.0} --after 2020-09-15 qux/1.0
3071 $ date
3072 Tue 08 Sep 2020 06:49:43 AM CEST
3073 $ ml qux/1.0
3074 Loading qux/1.0
3075 WARNING: Access to module will be denied starting '2020-09-15'
3076 Version 1.0 will soon expire, please now use version 2.0
3077
3078 The range of time the *nearly forbidden* warning appears can be
3079 controlled with the "nearly_forbidden_days" configuration option,
3080 whose value equals to the number of days prior the module starts to be
3081 forbidden. This configuration is set to "14" (days) by default and
3082 this value can be controlled at "configure" time with "--with-nearly-
3083 forbidden-days" option. When the "nearly_forbidden_days" configuration
3084 is set through the "config" sub-command, the
3085 "MODULES_NEARLY_FORBIDDEN_DAYS" environment variable is set.
3086
3087
3088 Tracing module execution
3089 ------------------------
3090
3091 The "trace" verbosity is introduced between the "verbose" and "debug"
3092 levels to report details on module searches, resolutions, selections
3093 and evaluations. Trace mode can be enabled by setting the "verbosity"
3094 config to the "trace" value or by using the "-T"/"--trace" command-
3095 line switches.
3096
3097 To specifically render trace messages, the "tr" key is added to the
3098 color palette with a default value of "2" (decreased intensity).
3099
3100 $ ml -T foo
3101 Evaluate modulerc: '/path/to/modulefiles/.modulerc'
3102 Get modules: {foo} matching 'foo' in '/path/to/modulefiles'
3103 Resolve: 'foo' into 'bar'
3104 Get modules: {bar bar/1.0} matching 'bar' in '/path/to/modulefiles'
3105 Select module: 'bar/1.0' (/path/to/modulefiles/bar/1.0) matching 'bar/1.0'
3106
3107 Loading bar/1.0
3108 Evaluate modulefile: '/path/to/modulefiles/bar/1.0' as 'bar/1.0'
3109
3110
3111 v4.5
3112 ====
3113
3114 This new version is backward-compatible with previous version 4
3115 releases. It fixes bugs but also introduces new functionalities that
3116 are described in this section. See the 4.5 release notes for a
3117 complete list of the changes between Modules v4.4 and v4.5.
3118
3119
3120 ml command
3121 ----------
3122
3123 The "ml" command is added to Modules. "ml" is a frontend to the
3124 "module" command that reduces the number of characters to type to
3125 trigger module actions.
3126
3127 With no argument provided "ml" is equivalent to "module list", "ml
3128 foo" corresponds to "module load foo" and "ml -foo" means "module
3129 unload foo":
3130
3131 $ ml foo
3132 $ ml
3133 Currently Loaded Modulefiles:
3134 1) foo/2
3135 $ ml -foo
3136 $ ml
3137 No Modulefiles Currently Loaded.
3138
3139 Multiple modules to either load or unload can be combined on a single
3140 command. The unloads are first processed then the loads.
3141
3142 "ml" accepts all command-line switches and sub-commands accepted by
3143 "module" command:
3144
3145 $ ml avail -t foo
3146 foo/1
3147 foo/2
3148
3149 This handy interface has been originally developed by the Lmod
3150 project. Having this command line interface also supported on Modules
3151 helps to provide a similar user experience whatever the module
3152 implementation used.
3153
3154
3155 JSON format output
3156 ------------------
3157
3158 The "-j" and "--json" command line switches are added for the "avail",
3159 "list", "savelist", "whatis" and "search" module sub-commands. When
3160 set, the output result of these sub-commands is rendered in JSON
3161 format:
3162
3163 $ module avail --json bar | python -mjson.tool
3164 {
3165 "/path/to/modulefiles": {
3166 "bar/2.3": {
3167 "name": "bar/2.3",
3168 "pathname": "/path/to/modulefiles/bar/2.3",
3169 "symbols": [
3170 "default"
3171 ],
3172 "type": "modulefile"
3173 },
3174 "bar/3.4": {
3175 "name": "bar/3.4",
3176 "pathname": "/path/to/modulefiles/bar/3.4",
3177 "symbols": [],
3178 "type": "modulefile"
3179 }
3180 }
3181 }
3182 $ ml whatis -j foo/1.2.3 | python -mjson.tool
3183 {
3184 "/path/to/modulefiles": {
3185 "foo/1.2.3": {
3186 "name": "foo/1.2.3",
3187 "whatis": [
3188 "The foo/1.2.3 modulefile"
3189 ]
3190 }
3191 }
3192 }
3193
3194
3195 Improved Windows support
3196 ------------------------
3197
3198 A new option to the "./configure" script named "--enable-windows-
3199 support" is introduced to install additional files relative to the
3200 enablement of Modules on the Windows platform. When set, this option
3201 installs "module.cmd", "ml.cmd" and "envml.cmd" scripts in "bindir"
3202 and initialization script "cmd.cmd" in "initdir". With these four
3203 files the Modules installation may be used from either a Unix or a
3204 Windows platform.
3205
3206 "module.cmd", "ml.cmd" and "envml.cmd" scripts respectively provide
3207 the "module", "ml" and "envml" commands for Windows "cmd" terminal
3208 shell, relying on "modulecmd.tcl" script which was already able to
3209 produce shell code for this Windows shell. Initialization script
3210 "cmd.cmd" adds the directory of "module.cmd", "ml.cmd" and "envml.cmd"
3211 to "PATH".
3212
3213 These Windows-specific files are relocatable: "module.cmd", "ml.cmd"
3214 and "envml.cmd" scripts expect to find initialization script "cmd.cmd"
3215 in the "init" directory next to them (to setup Modules-specific
3216 variables in current environment) and "cmd.cmd" expects
3217 "modulecmd.tcl" to be found in "libexec" directory and the 3 commands
3218 in "bin" directory next to it.
3219
3220 Starting from this "4.5" release a distribution zipball is published
3221 to install Modules on Windows. This zip archive ships an install and
3222 an uninstall scripts ("INSTALL.bat" and "UNINSTALL.bat"). The zipball
3223 can be built locally from Modules sources by running "make dist-win".
3224
3225 The Installing Modules on Windows document describes how to install
3226 Modules on Windows from the distribution zipball.
3227
3228
3229 Error stack trace
3230 -----------------
3231
3232 Error messages will now embed a stack trace for unknown errors to help
3233 localize the root cause of issues. This change applies to modulefile
3234 evaluation:
3235
3236 Loading foo/1.2
3237 Module ERROR: add-path cannot handle path equals to separator string
3238 while executing
3239 "append-path PATH :"
3240 (file "/path/to/modulefiles/foo/1.2" line 24)
3241 Please contact <root@localhost>
3242
3243 A stack trace is also returned when an unknown error occurs in
3244 "modulecmd.tcl" script, which facilitates issue report and analysis:
3245
3246 $ module load bar
3247 ERROR: invalid command name "badcommand"
3248 while executing
3249 "badcommand"
3250 (procedure "module" line 14)
3251 invoked from within
3252 "module load bar"
3253 ("eval" body line 1)
3254 invoked from within
3255 "eval $execcmdlist"
3256 Please report this issue at https://github.com/envmodules/modules/issues
3257
3258
3259 Automatic default and latest symbolic versions
3260 ----------------------------------------------
3261
3262 When the implicit default mechanism and the Advanced module version
3263 specifiers are both enabled, a "default" and a "latest" symbolic
3264 versions are automatically defined for each module name.
3265
3266 This new feature gives the ability to select the highest version
3267 available for a module, without knowing beforehand this version name:
3268
3269 $ module load -v foo@latest
3270 Loading foo/1.10
3271
3272 The symbolic versions are automatically defined unless a symbolic
3273 version, an alias or a regular module version already exists for these
3274 "default" or "latest" version names.
3275
3276
3277 v4.4
3278 ====
3279
3280 This new version is backward-compatible with previous version 4
3281 releases. It fixes bugs but also introduces new functionalities that
3282 are described in this section. See the 4.4 release notes for a
3283 complete list of the changes between Modules v4.3 and v4.4.
3284
3285 Warning:
3286
3287 Modules configuration option handling has been reworked internally
3288 to provide a unified way for all options to get initialized,
3289 retrieved or set. Existing site-specific configuration script should
3290 be reviewed to make use of the new "getConf", "setConf", "unsetConf"
3291 and "lappendConf" procedures to manipulate configuration options.
3292
3293
3294 Specify modules in a case insensitive manner
3295 --------------------------------------------
3296
3297 The ability to match module name in a case insensitive manner has been
3298 added. This feature can be enabled at different level with the
3299 following values set to the "icase" configuration option:
3300
3301 * "never": a case sensitive match is applied in any cases
3302
3303 * "search": a case insensitive match is applied to the "avail",
3304 "whatis" and "paths" sub-commands
3305
3306 * "always": a case insensitive match is applied to search contexts and
3307 also to the other module sub-commands and modulefile Tcl commands
3308 for the module specification they receive as argument.
3309
3310 It can help for instance to load a module without knowing the case
3311 used to name its relative modulefile:
3312
3313 $ module config icase always
3314 $ module load -v mysoftware
3315 Loading MySoftware/1.0
3316
3317 Insensitive case match activation can be controlled at configure time
3318 with the "--with-icase" option, which could be passed any of the above
3319 activation levels. This option could be superseded with the
3320 "MODULES_ICASE" environment variable, which could be set through the
3321 **config** sub-command with the "icase" option. Command-line switch
3322 **--icase** supersedes in turns any other icase configurations. When
3323 this command-line switch is passed, "icase" mode equals "always".
3324
3325
3326 Extended default
3327 ----------------
3328
3329 The extended default mechanism has been introduced to help selecting a
3330 module when only the first numbers in its version are specified.
3331 Starting portion of the version, part separated from the rest of the
3332 version string by a "." character, could be used to refer to a more
3333 precise version number.
3334
3335 This mechanism is activated through the new configuration option
3336 "extended_default". It enables to refer to a module named "foo/1.2.3"
3337 as "foo/1.2" or "foo/1":
3338
3339 $ module config extended_default 1
3340 $ module load -v foo/1
3341 Loading foo/1.2.3
3342
3343 When multiple versions match partial version specified and only one
3344 module should be selected, the default version (whether implicitly or
3345 explicitly defined) among matches is returned. The following example
3346 shows that "foo/1.1.1", the *foo* module default version, is selected
3347 when it matches query. Elsewhere the highest version (also called the
3348 latest version or the implicit default) among matching modules is
3349 returned:
3350
3351 $ module av foo
3352 --------------- /path/to/modulefiles ---------------
3353 foo/1.1.1(default) foo/1.2.1 foo/1.10
3354 foo/1.1.10 foo/1.2.3
3355 $ module load -v foo/1.1
3356 Loading foo/1.1.1
3357 $ module purge
3358 $ module load -v foo/1.2
3359 Loading foo/1.2.3
3360 $ module purge
3361 $ module load -v foo/1
3362 Loading foo/1.1.1
3363
3364 In case "implicit_default" option is disabled and no explicit default
3365 is found among matches, an error is returned:
3366
3367 $ module config implicit_default 0
3368 $ module load -v foo/1.2
3369 ERROR: No default version defined for 'foo/1.2'
3370
3371 When it is enabled, extended default applies everywhere a module could
3372 be specified, which means it could be used with any module sub-command
3373 or any modulefile Tcl command receiving a module specification as
3374 argument. It may help for instance to declare dependencies between
3375 modules:
3376
3377 $ module show bar/3
3378 ----------------------------------------------------------
3379 /path/to/modulefiles/bar/3.4:
3380
3381 prereq foo/1.2
3382 ----------------------------------------------------------
3383 $ module load --auto bar/3
3384 Loading bar/3.4
3385 Loading requirement: foo/1.2.3
3386
3387 Extended default activation can be controlled at configure time with
3388 the "--enable-extended-default" option. This option could be
3389 superseded with the "MODULES_EXTENDED_DEFAULT" environment variable,
3390 which could be set through the **config** sub-command with the
3391 "extended_default" option.
3392
3393
3394 Advanced module version specifiers
3395 ----------------------------------
3396
3397 The ability to specify finer constraints on module version has been
3398 added to Modules. It enables to filter the module selection to a given
3399 version list or range by specifying after the module name a version
3400 constraint prefixed by the "@" character.
3401
3402 This new feature leverages the version specifier syntax of the Spack
3403 package manager as this syntax covers all the needs for a fine-grained
3404 selection of module versions. It copes very well with command-line
3405 typing, by avoiding characters having a special meaning on shells.
3406 Moreover the users of Spack that also are users of Modules may already
3407 be familiar with this syntax.
3408
3409 The mechanism introduced here is called *advanced module version
3410 specifier* and it can be activated through the new configuration
3411 option "advanced_version_spec". Constraints can be expressed to refine
3412 the selection of module version to:
3413
3414 * a single version with the "@version" syntax, for instance
3415 "[email protected]" syntax will select module "foo/1.2.3"
3416
3417 * a list of versions with the "@version1,version2,..." syntax, for
3418 instance "[email protected],1.10" will match modules "foo/1.2.3" and
3419 "foo/1.10"
3420
3421 * a range of versions with the "@version1:", "@:version2" and
3422 "@version1:version2" syntaxes, for instance "[email protected]:" will select
3423 all versions of module "foo" greater than or equal to "1.2",
3424 "foo@:1.3" will select all versions less than or equal to "1.3" and
3425 "[email protected]:1.3" matches all versions between "1.2" and "1.3" including
3426 "1.2" and "1.3" versions
3427
3428 This new feature enables for instance to list available versions of
3429 module "foo" higher or equal to "1.2":
3430
3431 $ module config advanced_version_spec 1
3432 $ module av foo
3433 --------------- /path/to/modulefiles ---------------
3434 foo/1.1.1(default) foo/1.2.1 foo/1.10
3435 foo/1.1.10 foo/1.2.3
3436 $ module av [email protected]:
3437 --------------- /path/to/modulefiles ---------------
3438 foo/1.2.1 foo/1.2.3 foo/1.10
3439
3440 Then choose to load for instance a version higher than or equal to
3441 "1.2" and less than or equal to "1.3". Default version is selected if
3442 it corresponds to a version included in the range, elsewhere the
3443 highest version (also called latest version or implicit default) is
3444 selected:
3445
3446 $ module load -v [email protected]:1.3
3447 Loading foo/1.2.3
3448
3449 In case "implicit_default" option is disabled and no explicit default
3450 is found among version specifier matches, an error is returned:
3451
3452 $ module config implicit_default 0
3453 $ module load -v [email protected]:1.3
3454 ERROR: No default version defined for '[email protected]:1.3'
3455
3456 When advanced module version specifier is enabled, it applies
3457 everywhere a module could be specified, which means it could be used
3458 with any module sub-command or any modulefile Tcl command receiving a
3459 module specification as argument. It may help for instance to declare
3460 smoother dependencies between modules:
3461
3462 $ module show bar@:2
3463 ----------------------------------------------------------
3464 /path/to/modulefiles/bar/2.3:
3465
3466 prereq [email protected],1.2.1
3467 ----------------------------------------------------------
3468 $ module load --auto bar@:2
3469 Loading bar/2.3
3470 Loading requirement: foo/1.2.1
3471
3472 Advanced specification of single version or list of versions may
3473 benefit from the activation of the Extended default mechanism (range
3474 of versions natively handles abbreviated versions):
3475
3476 $ module config extended_default 1
3477 $ module load -v [email protected]
3478 Loading foo/1.2.3
3479 $ module unload -v foo @1.2,1.5
3480 Unloading foo/1.2.3
3481
3482 Advanced module version specifier activation can be controlled at
3483 configure time with the "--enable-advanced-version-spec" option. This
3484 option could be superseded with the "MODULES_ADVANCED_VERSION_SPEC"
3485 environment variable, which could be set through the **config** sub-
3486 command with the "advanced_version_spec" option.
3487
3488
3489 v4.3
3490 ====
3491
3492 This new version is backward-compatible with previous version 4
3493 releases. It fixes bugs but also introduces new functionalities that
3494 are described in this section. See the 4.3 release notes for a
3495 complete list of the changes between Modules v4.2 and v4.3.
3496
3497
3498 Modulepath rc file
3499 ------------------
3500
3501 A ".modulerc" file found at the root of an enabled modulepath
3502 directory is now evaluated when modulepath is walked through to locate
3503 modulefiles. This modulepath rc file gives for instance the ability to
3504 define module alias whose name does not correspond to any module
3505 directory in this modulepath. Thus this kind of module alias would not
3506 be found unless if it is defined at the modulepath global scope.
3507
3508
3509 Further I/O operations optimization
3510 -----------------------------------
3511
3512 Additional work has been performed to save a significant number of
3513 filesystem I/O operations made to search and evaluate modulefiles.
3514
3515 When fully read, the content of a modulefile is now cached in memory
3516 to avoid new I/O operations in case this modulefile should be read one
3517 more time during the same module command evaluation.
3518
3519 Except for "path", "paths", "list", "avail" and "aliases" module
3520 commands always fully read a modulefile whether its full content is
3521 needed or just its header to verify its validity. This way modulefiles
3522 are only read once on commands that first check modulefile validity
3523 then read again valid files to get their full content.
3524
3525 Last but not least, Modules Tcl extension library is introduced to
3526 extend the Tcl language in order to provide more optimized I/O
3527 commands to read a file or a directory content than native Tcl
3528 commands do. This library is built and enabled in "modulecmd.tcl"
3529 script with "--enable-libtclenvmodules" configure argument (it is
3530 enabled by default). As this library is written in C, it must be
3531 compiled and "--with-tcl" or "--with-tclinclude" configure arguments
3532 may be used to indicate where to find Tcl development files.
3533
3534 Modules Tcl extension library greatly reduces the number of filesystem
3535 I/O operations by removing unneeded "ioctl", "fcntl" and "lstat"
3536 system calls done (by Tcl "open" command) to read each modulefile.
3537 Directory content read is also improved by fetching hidden and regular
3538 files in one pass. Moreover ".modulerc" and ".version" read access is
3539 tested only if these files are found in the directory.
3540
3541
3542 Colored output
3543 --------------
3544
3545 The ability to graphically enhance some part of the produced output
3546 has been added to improve readability. Among others, error, warning
3547 and info message prefixes can be colored as well as modulepath, module
3548 alias and symbolic version.
3549
3550 Color mode can be set to "never", "auto" or "always". When color mode
3551 is set to "auto", output is colored only if the standard error output
3552 channel is attached to a terminal.
3553
3554 Default color mode could be controlled at configure time with the "--
3555 enable-color" and the "--disable-color" option, which respectively
3556 correspond to the "auto" and "never" color mode. This default mode
3557 could be superseded with the "CLICOLOR", "CLICOLOR_FORCE" and
3558 "MODULES_COLOR" environment variables and the "--color" command-line
3559 switch.
3560
3561 Color to apply to each element can be controlled with the
3562 "MODULES_COLORS" environment variable or the "--with-dark-background-
3563 colors" and "--with-light-background-colors" configure options. These
3564 variable and options take as value a colon-separated list in the same
3565 fashion "LS_COLORS" does. In this list, output item that should be
3566 highlighted is designated by a key which is associated to a Select
3567 Graphic Rendition (SGR) code.
3568
3569 The "MODULES_TERM_BACKGROUND" environment variable and the "--with-
3570 terminal-background" configure option help Modules to determine if the
3571 color set for dark background or the color set for light background
3572 should be used to color output in case no specific color set is
3573 defined with the "MODULES_COLORS" variable.
3574
3575 Output items able to be colorized and their relative key are:
3576 highlighted element ("hi"), debug information ("db"), tag separator
3577 ("se"); Error ("er"), warning ("wa"), module error ("me") and info
3578 ("in") message prefixes; Modulepath ("mp"), directory ("di"), module
3579 alias ("al"), module symbolic version ("sy"), module "default" version
3580 ("de") and modulefile command ("cm").
3581
3582 For instance the default color set for a terminal with dark background
3583 is defined to:
3584
3585 hi=1:db=2:se=2:er=91:wa=93:me=95:in=94:mp=1;94:di=94:al=96:sy=95:de=4:cm=92
3586
3587 When colored output is enabled and a specific graphical rendition is
3588 defined for module *default* version, the "default" symbol is omitted
3589 and instead the defined graphical rendition is applied to the relative
3590 modulefile. When colored output is enabled and a specific graphical
3591 rendition is defined for module alias, the "@" symbol is omitted.
3592
3593 "CLICOLOR" and "CLICOLOR_FORCE" environment variables are also honored
3594 to define color mode. The "never" mode is set if "CLICOLOR" equals to
3595 "0". If "CLICOLOR" is set to another value, it corresponds to the
3596 "auto" mode. The "always" mode is set if "CLICOLOR_FORCE" is set to a
3597 value different than "0". Color mode set with these two variables is
3598 superseded by mode set with "MODULES_COLOR" environment variable.
3599
3600
3601 Configure modulecmd with config sub-command
3602 -------------------------------------------
3603
3604 The **config** sub-command has been added to "module" to help getting
3605 or setting the **modulecmd.tcl** options. With no additional command-
3606 line argument, this sub-command reports the current value of all
3607 existing options with a mention to indicate if this value has been
3608 overridden from a command-line switch or from an environment variable.
3609
3610 See the description of this sub-command in the module man page for a
3611 complete reference on existing configuration options.
3612
3613 Most of the options can be altered by passing the option name and a
3614 value to the sub-command. Setting an option by this mean overrides its
3615 default value, set at installation time in **modulecmd.tcl** script,
3616 by defining the environment variable which supersedes this default.:
3617
3618 $ module config auto_handling 1
3619 $ module config auto_handling
3620 Modules Release 4.3.0 (2019-07-26)
3621
3622 - Config. name ---------.- Value (set by if default overridden) ---------------
3623 auto_handling 1 (env-var)
3624
3625 Setting options with "module config" could be done in the Modules
3626 initialization RC file to change default value of options when
3627 "module" command is initialized.
3628
3629 When command-line switch "--reset" and an option name is passed to the
3630 **config** sub-command, it restores default value for configuration
3631 option by unsetting related environment variable.
3632
3633 With command-line switch "--dump-state", the **config** sub-command
3634 reports, in addition to currently set options, the current state of
3635 **modulecmd.tcl** script and Modules-related environment variables.
3636 Providing the output of the "module config --dump-state" command when
3637 submitting an issue to the Modules project will help to analyze the
3638 situation.
3639
3640
3641 Control module command verbosity
3642 --------------------------------
3643
3644 The ability to control message verbosity has been added so "module"
3645 command can be configured whether it should display more or less
3646 information. Available verbosity levels from the least to the most
3647 verbose are:
3648
3649 * "silent": turn off error, warning and informational messages but
3650 does not affect module command output result.
3651
3652 * "concise": enable error and warning messages but disable
3653 informational messages.
3654
3655 * "normal": turn on informational messages, like a report of the
3656 additional module evaluations triggered by loading or unloading
3657 modules, aborted evaluation issues or a report of each module
3658 evaluation occurring during a **restore** or **source** sub-
3659 commands.
3660
3661 * "verbose": add additional informational messages, like a systematic
3662 report of the loading or unloading module evaluations.
3663
3664 * "debug": print debugging messages about module command execution.
3665
3666 Default verbosity level can be controlled at configure time with the "
3667 --with-verbosity" option, which could be passed any of the above level
3668 names. This default verbosity level could be superseded with the
3669 "MODULES_VERBOSITY" environment variable, which could be set through
3670 the **config** sub-command with the "verbosity" option. Command-line
3671 switches **--silent**, **--verbose** and **--debug** supersede in
3672 turns any other verbosity configuration to respectively set module
3673 command silent, verbose or in debug mode.
3674
3675
3676 Other new sub-commands, command-line switches and environment variables
3677 -----------------------------------------------------------------------
3678
3679 * The **avail** sub-command gets two new command-line switches:
3680 **--indepth** and **--no-indepth**. These options control whether
3681 search results should recursively include or not modulefiles from
3682 directories matching search query. Shell completion scripts have
3683 been updated to complete available modulefiles in the no in depth
3684 mode.
3685
3686 * The **MODULES_AVAIL_INDEPTH** environment variable defines if the
3687 **avail** sub-command should include or exclude by default the
3688 modulefiles from directories matching search query. Its value is
3689 superseded by the use of the **--indepth** and **--no-indepth**
3690 command-line switches.
3691
3692 * The **clear** sub-command, which was available on Modules version
3693 3.2, has been reintroduced. This sub-command resets the Modules
3694 runtime information but does not apply further changes to the
3695 environment at all. This sub-command now leverages the **--force**
3696 command-line switch to skip its confirmation dialog.
3697
3698 * The **MODULES_SITECONFIG** environment variable defines an
3699 additional siteconfig script which is loaded if it exists after the
3700 siteconfig script configured at build time in "modulecmd.tcl". This
3701 ability is enabled by default and could be disabled with configure
3702 option "--with-locked-configs=extra_siteconfig".
3703
3704 * The **MODULES_UNLOAD_MATCH_ORDER** environment variable sets whether
3705 the firstly or the lastly loaded module should be selected for
3706 unload when multiple loaded modules match unload request. Configure
3707 option "--with-unload-match-order" defines this setting which can be
3708 superseded by the environment variable. By default, lastly loaded
3709 module is selected and it is recommended to keep this behavior when
3710 used modulefiles express dependencies between each other.
3711
3712 * The **MODULES_IMPLICIT_DEFAULT** environment variable sets whether
3713 an implicit default version should be defined for modules with no
3714 default version explicitly defined. When enabled, which is the
3715 default behavior, a module version is automatically selected (latest
3716 one) when the generic name of the module is passed. When implicit
3717 default is disabled and no default version is explicitly defined for
3718 a module, the name of this module to evaluate should be fully
3719 qualified elsewhere an error is returned. Configure option "--
3720 enable-implicit-default" defines this setting which can be
3721 superseded by the environment variable. This superseding mechanism
3722 can be disabled with configure option "--with-locked-
3723 configs=implicit_default".
3724
3725 * The **MODULES_SEARCH_MATCH** environment variable defines the
3726 matching style to perform when searching for available modules. With
3727 **starts_with** value, modules whose name begins by search query
3728 string are returned. When search match style is set to **contains**,
3729 modules returned are those whose fully qualified name contains
3730 search query string. Configure option "--with-search-match" defines
3731 this setting which can be superseded by the environment variable,
3732 which in turns can be superseded by the **--starts-with** and
3733 **--contains** command-line switches of **avail** module sub-
3734 command.
3735
3736 * The **MODULES_SET_SHELL_STARTUP** environment variable controls
3737 whether or not shell startup file should be set to ensure "module"
3738 command is defined once shell has been initialized. When enabled,
3739 the "ENV" and "BASH_ENV" environment variables are set, when
3740 "module" function is defined, to the Modules bourne shell
3741 initialization script. Configure options "--enable-set-shell-
3742 startup" and "--disable-set-shell-startup" define this setting which
3743 can be superseded by the environment variable.
3744
3745 * When initializing the "module" command in a shell session,
3746 initialization configuration files stored in the defined
3747 configuration directory are taken into account if present instead of
3748 the configuration files stored in the initialization script
3749 directory. When they are stored in the configuration directory,
3750 these configuration files are named "initrc" and "modulespath"
3751 instead of respectively "modulerc" and ".modulespath". The location
3752 of the installation of those files can be controlled with configure
3753 option "--with-initconf-in", which accepts "etcdir" and "initdir"
3754 values.
3755
3756 * The **MODULES_WA_277** environment variable helps to define an
3757 alternative "module" alias on Tcsh shell when set to *1*. It
3758 workarounds an issue on Tcsh history mechanism occurring with
3759 default "module" command alias: erroneous history entries are
3760 recorded each time the "module" command is called. However the
3761 alternative definition of the module alias weakens shell evaluation
3762 of the code produced by modulefiles. Characters with special meaning
3763 for Tcsh shell (like *{* and *}*) may not be used anymore in shell
3764 alias definition elsewhere the evaluation of the code produced by
3765 modulefiles will return a syntax error.
3766
3767
3768 v4.2
3769 ====
3770
3771 This new version is backward-compatible with previous version 4
3772 releases. It fixes bugs but also introduces new functionalities that
3773 are described in this section. See the 4.2 release notes for a
3774 complete list of the changes between Modules v4.1 and v4.2.
3775
3776
3777 Modulefile conflict constraints consistency
3778 -------------------------------------------
3779
3780 With the **conflict** modulefile command, a given modulefile can list
3781 the other modulefiles it conflicts with. To load this modulefile, the
3782 modulefiles it conflicts with cannot be loaded.
3783
3784 This constraint was until now satisfied when loading the modulefile
3785 declaring the **conflict** but it vanished as soon as this modulefile
3786 was loaded. In the following example "a" modulefile declares a
3787 conflict with "b":
3788
3789 $ module load b a
3790 WARNING: a cannot be loaded due to a conflict.
3791 HINT: Might try "module unload b" first.
3792 $ module list
3793 Currently Loaded Modulefiles:
3794 1) b
3795 $ module purge
3796 $ module load a b
3797 $ module list
3798 Currently Loaded Modulefiles:
3799 1) a 2) b
3800
3801 Consistency of the declared **conflict** is now ensured to satisfy
3802 this constraint even after the load of the modulefile declaring it.
3803 This is achieved by keeping track of the conflict constraints of the
3804 loaded modulefiles in an environment variable called
3805 "MODULES_LMCONFLICT":
3806
3807 $ module load a b
3808 ERROR: WARNING: b cannot be loaded due to a conflict.
3809 HINT: Might try "module unload a" first.
3810 $ module list
3811 Currently Loaded Modulefiles:
3812 1) a
3813
3814 An environment variable is used to keep track of this conflict
3815 information to proceed the same way than used to keep track of the
3816 loaded modulefiles with the "LOADEDMODULES" environment variable.
3817
3818 In case a conflict constraint toward a modulefile is set by an already
3819 loaded modulefile, loading the conflicting modulefile will lead to a
3820 load evaluation attempt in order for this modulefile to get the chance
3821 to solve the constraint violation. If at the end of the load
3822 evaluation, the conflict has not been solved, modulefile load will be
3823 discarded.
3824
3825 Warning:
3826
3827 On versions "4.2.0" and "4.2.1", a conflict constraint set by an
3828 already loaded modulefile forbade the load of the conflicting
3829 modulefile. This has been changed starting version "4.2.2" to better
3830 cope with behaviors of previous Modules version: an evaluation
3831 attempt of the conflicting modulefile is made to give it the
3832 opportunity to solve this conflict by using **module unload**
3833 modulefile command.
3834
3835
3836 Modulefile prereq constraints consistency
3837 -----------------------------------------
3838
3839 With the **prereq** modulefile command, a given modulefile can list
3840 the other modulefiles it pre-requires. To load this modulefile, the
3841 modulefiles it pre-requires must be loaded prior its own load.
3842
3843 This constraint was until now satisfied when loading the modulefile
3844 declaring the **prereq** but, as for the declared **conflict**, it
3845 vanished as soon as this modulefile was loaded. In the following
3846 example "c" modulefile declares a prereq on "a":
3847
3848 $ module load c
3849 WARNING: c cannot be loaded due to missing prereq.
3850 HINT: the following module must be loaded first: a
3851 $ module list
3852 No Modulefiles Currently Loaded.
3853 $ module load a c
3854 $ module list
3855 Currently Loaded Modulefiles:
3856 1) a 2) c
3857 $ module unload a
3858 $ module list
3859 Currently Loaded Modulefiles:
3860 1) c
3861
3862 Consistency of the declared **prereq** is now ensured to satisfy this
3863 constraint even after the load of the modulefile declaring it. This is
3864 achieved, like for the conflict consistency, by keeping track of the
3865 prereq constraints of the loaded modulefiles in an environment
3866 variable called "MODULES_LMPREREQ":
3867
3868 $ module load a c
3869 $ module list
3870 Currently Loaded Modulefiles:
3871 1) a 2) c
3872 $ module unload a
3873 ERROR: WARNING: a cannot be unloaded due to a prereq.
3874 HINT: Might try "module unload c" first.
3875 $ module list
3876 Currently Loaded Modulefiles:
3877 1) a 2) c
3878
3879
3880 By-passing module defined constraints
3881 -------------------------------------
3882
3883 The ability to by-pass a **conflict** or a **prereq** constraint
3884 defined by modulefiles is introduced with the "--force" command line
3885 switch ("-f" for short notation) for the **load**, **unload** and
3886 **switch** sub-commands.
3887
3888 With this new command line switch, a given modulefile is loaded even
3889 if it conflicts with other loaded modulefiles or even if the
3890 modulefiles it pre-requires are not loaded. Some example reusing the
3891 same modulefiles "a", "b" and "c" than above:
3892
3893 $ module load b
3894 $ module load --force a
3895 WARNING: a conflicts with b
3896 $ module list
3897 Currently Loaded Modulefiles:
3898 1) b 2) a
3899 $ module purge
3900 $ module load --force c
3901 WARNING: c requires a loaded
3902 $ module list
3903 Currently Loaded Modulefiles:
3904 1) c
3905
3906 "--force" also enables to unload a modulefile required by another
3907 loaded modulefiles:
3908
3909 $ module load a c
3910 $ module list
3911 Currently Loaded Modulefiles:
3912 1) a 2) c
3913 $ module unload --force a
3914 WARNING: a is required by c
3915 $ module list
3916 Currently Loaded Modulefiles:
3917 1) c
3918
3919 In a situation where some of the loaded modulefiles have unsatisfied
3920 constraints corresponding to the **prereq** and **conflict** they
3921 declare, the **save** and **reload** sub-commands do not perform and
3922 return an error.
3923
3924
3925 Automated module handling mode
3926 ------------------------------
3927
3928 An automatic management of the dependencies between modulefiles has
3929 been added and it is called *automated module handling mode*. This new
3930 mode consists in additional actions triggered when loading or
3931 unloading a modulefile to satisfy the constraints it declares.
3932
3933 When loading a modulefile, following actions are triggered:
3934
3935 * Requirement Load (ReqLo): load of the modulefiles declared as a
3936 **prereq** of the loading modulefile.
3937
3938 * Dependent Reload (DepRe): reload of the modulefiles declaring a
3939 **prereq** onto loaded modulefile or declaring a **prereq** onto a
3940 modulefile part of this reloading batch.
3941
3942 When unloading a modulefile, following actions are triggered:
3943
3944 * Dependent Unload (DepUn): unload of the modulefiles declaring a non-
3945 optional **prereq** onto unloaded modulefile or declaring a non-
3946 optional **prereq** onto a modulefile part of this unloading batch.
3947 A **prereq** modulefile is considered optional if the **prereq**
3948 definition order is made of multiple modulefiles and at least one
3949 alternative modulefile is loaded.
3950
3951 * Useless Requirement Unload (UReqUn): unload of the **prereq**
3952 modulefiles that have been automatically loaded for either the
3953 unloaded modulefile, an unloaded dependent modulefile or a
3954 modulefile part of this useless requirement unloading batch.
3955 Modulefiles are added to this unloading batch only if they are not
3956 required by any other loaded modulefiles. "MODULES_LMNOTUASKED"
3957 environment variable helps to keep track of these automatically
3958 loaded modulefiles and to distinguish them from modulefiles asked by
3959 user.
3960
3961 * Dependent Reload (DepRe): reload of the modulefiles declaring a
3962 **conflict** or an optional **prereq** onto either the unloaded
3963 modulefile, an unloaded dependent or an unloaded useless requirement
3964 or declaring a **prereq** onto a modulefile part of this reloading
3965 batch.
3966
3967 In case a loaded modulefile has some of its declared constraints
3968 unsatisfied (pre-required modulefile not loaded or conflicting
3969 modulefile loaded for instance), this loaded modulefile is excluded
3970 from the automatic reload actions described above.
3971
3972 For the specific case of the **switch** sub-command, where a
3973 modulefile is unloaded to then load another modulefile. Dependent
3974 modulefiles to Unload are merged into the Dependent modulefiles to
3975 Reload that are reloaded after the load of the switched-to modulefile.
3976
3977 This automated module handling mode integrates concepts (like the
3978 Dependent Reload mechanism) of the Flavours extension, which was
3979 designed for Modules compatibility version. As a whole, automated
3980 module handling mode can be seen as a generalization and as an
3981 expansion of the Flavours concepts.
3982
3983 This new feature can be controlled at build time with the "--enable-
3984 auto-handling" configure option. This default configuration can be
3985 superseded at run-time with the "MODULES_AUTO_HANDLING" environment
3986 variable or the command line switches "--auto" and "--no-auto".
3987
3988 By default, automated module handling mode is disabled and will stay
3989 so until the next major release version (5.0) where it will be enabled
3990 by default. This new feature is currently considered experimental and
3991 the set of triggered actions will be refined over the next feature
3992 releases.
3993
3994
3995 Consistency of module load/unload commands in modulefile
3996 --------------------------------------------------------
3997
3998 With the **module load** modulefile command, a given modulefile can
3999 automatically load a modulefile it pre-requires. Similarly with the
4000 **module unload** modulefile command, a given modulefile can
4001 automatically unload a modulefile it conflicts with.
4002
4003 Both commands imply additional actions on the loaded environment
4004 (loading or unloading extra modulefiles) that should cope with the
4005 constraints defined by the loaded environment.
4006
4007 Additionally **module load** and **module unload** modulefile commands
4008 express themselves constraints on loaded environment that should stay
4009 satisfied to ensure consistency.
4010
4011 To ensure the consistency of **module load** modulefile command once
4012 the modulefile defining it has been loaded, this command is
4013 assimilated to a **prereq** command. Thus the defined constraint is
4014 recorded in the "MODULES_LMPREREQ" environment variable. Same approach
4015 is used for **module unload** modulefile command which is assimilated
4016 to a **conflict** command. Thus the defined constraint is recorded in
4017 the "MODULES_LMCONFLICT" environment variable.
4018
4019 To ensure the consistency of the loaded environment, the additional
4020 actions of the **module load** and **module unload** modulefile
4021 commands have been adapted in particular situations:
4022
4023 * When unloading modulefile, **module load** command will unload the
4024 modulefile it targets only if no other loaded modulefile requires it
4025 and if this target has not been explicitly loaded by user.
4026
4027 * When unloading modulefile, **module unload** command does nothing as
4028 the relative conflict registered at load time ensure environment
4029 consistency and will forbid conflicting modulefile load.
4030
4031 Please note that loading and unloading results may differ than from
4032 previous Modules version now that consistency is checked:
4033
4034 * Modulefile targeted by a **module load** modulefile command may not
4035 be able to load due to a registered conflict in the currently loaded
4036 environment. Which in turn will break the load of the modulefile
4037 declaring the **module load** command.
4038
4039 * Modulefile targeted by a **module unload** modulefile command may
4040 not be able to unload due to a registered prereq in the loaded
4041 environment. Which in turn will break the load of the modulefile
4042 declaring the **module unload** command.
4043
4044 * If automated module handling mode is enabled, **module load**
4045 modulefile command is interpreted when unloading modulefile as part
4046 of the Useless Requirement Unload (UReqUn) mechanism not through
4047 modulefile evaluation. As a consequence, an error occurring when
4048 unloading the modulefile targeted by the **module load** command
4049 does not break the unload of the modulefile declaring this command.
4050 Moreover unload of the **module load** targets is done in the
4051 reverse loaded order, not in the **module load** command definition
4052 order.
4053
4054
4055 Modulefile alias and symbolic modulefile name consistency
4056 ---------------------------------------------------------
4057
4058 With the **module-alias** and **module-version** modulefile commands,
4059 alternative names can be given to a modulefile. When these names are
4060 used to load for instance a modulefile, they are resolved to the
4061 modulefile they target which is then processed for the load action.
4062
4063 Until now, the alias and symbolic version names were correctly
4064 resolved for the **load** and **unload** actions and also for the
4065 querying sub-commands (like **avail** or **whatis**). However this
4066 alternative name information vanishes once the modulefile it resolves
4067 to is loaded. As a consequence there was no consistency over these
4068 alternative designations. In the following example "f" modulefile
4069 declares a conflict on "e" alias which resolves to "d" modulefile:
4070
4071 $ module load e
4072 $ module list
4073 Currently Loaded Modulefiles:
4074 1) d
4075 $ module info-loaded e
4076 $ module load f
4077 $ module list
4078 Currently Loaded Modulefiles:
4079 1) d 2) f
4080
4081 Consistency of the alternative names set on a modulefile with
4082 **module-alias** and **module-version** commands is now ensured to
4083 enable modulefile commands **prereq**, **conflict**, **is-loaded** and
4084 **module-info loaded** using these alternative designations as
4085 argument. This consistency is achieved, like for the conflict and
4086 prereq consistencies, by keeping track of the alternative names of the
4087 loaded modulefiles in an environment variable called
4088 "MODULES_LMALTNAME":
4089
4090 $ module load e
4091 $ module list
4092 Currently Loaded Modulefiles:
4093 1) d
4094 $ module info-loaded e
4095 d
4096 $ module load f
4097 WARNING: f cannot be loaded due to a conflict.
4098 HINT: Might try "module unload e" first.
4099 $ module list
4100 Currently Loaded Modulefiles:
4101 1) d
4102
4103
4104 Environment variable change through modulefile evaluation context
4105 -----------------------------------------------------------------
4106
4107 All environment variable edition commands ("setenv", "unsetenv",
4108 "append-path", "prepend-path" and "remove-path") have been updated to:
4109
4110 * Reflect environment variable value change on the environment of the
4111 current modulefile Tcl interpreter. So using "$env(VAR)" will return
4112 the currently defined value for environment variable "VAR", not the
4113 one found prior modulefile evaluation.
4114
4115 * Clear environment variable content instead of unsetting it on the
4116 environment of the current modulefile Tcl interpreter to avoid
4117 raising error about accessing an undefined element in "$env()". Code
4118 is still produced to purely unset environment variable in shell
4119 environment.
4120
4121 Exception is made for the "whatis" evaluation mode: environment
4122 variables targeted by variable edition commands are not set to the
4123 defined value in the evaluation context during this "whatis"
4124 evaluation. These variables are only initialized to an empty value if
4125 undefined. This exception is made to save performances on this global
4126 evaluation mode.
4127
4128
4129 Express Modules compatibility of modulefile with versioned magic cookie
4130 -----------------------------------------------------------------------
4131
4132 Any modulefile should start with the "#%Module" file signature (also
4133 called the Modules magic cookie) and sometimes a version number may be
4134 placed right after this string. Until now this version number
4135 corresponded to a modulefile format version but it was never checked.
4136
4137 Starting with this new Modules release, this version number reflects
4138 the minimum version of Modules required to interpret the modulefile.
4139 If the version number is set along the magic cookie string it is now
4140 checked and the modulefile is interpreted only if Modules version is
4141 greater or equal to this version number. For instance, if a modulefile
4142 begins with the "#%Module4.3" string, it can only be evaluated by
4143 Modules version 4.3 and above. Elsewhere the modulefile is ignored
4144 like files without the "#%Module" magic cookie set.
4145
4146
4147 Improved module message report
4148 ------------------------------
4149
4150 Module sub-commands like "load", "unload" or "switch", may perform
4151 multiple load or unload modulefile evaluations in a row. Also these
4152 kind of evaluation modes may sometimes trigger additional load or
4153 unload evaluations, when for instance a modulefile contains a "module
4154 load" command.
4155
4156 To improve the readability of the module messages produced relatively
4157 to a load or an unload evaluation, these messages are now stacked
4158 under a *Loading* or an *Unloading* message block that gathers all the
4159 messages produced for a given modulefile evaluation:
4160
4161 $ module load --no-auto foo
4162 Loading foo/1.2
4163 ERROR: foo/1.2 cannot be loaded due to missing prereq.
4164 HINT: the following module must be loaded first: bar/4.5
4165
4166 In addition, foreground "load", "unload", "switch" and "restore"
4167 actions (i.e., asked on the command-line) now report a summary of the
4168 additional load and unload evaluations that were eventually triggered
4169 in the process:
4170
4171 $ module load --auto foo
4172 Loading foo/1.2
4173 Loading requirement: bar/4.5
4174
4175
4176 New modulefile commands
4177 -----------------------
4178
4179 2 new modulefile Tcl commands have been introduced:
4180
4181 * **set-function**: define a shell function on sh-kind and fish
4182 shells.
4183
4184 * **unset-function**: unset a shell function on sh-kind and fish
4185 shells.
4186
4187
4188 v4.1
4189 ====
4190
4191 This new version is backward-compatible with previous version 4
4192 releases. It fixes bugs but also introduces new functionalities that
4193 are described in this section. See the 4.1 release notes for a
4194 complete list of the changes between Modules v4.0 and v4.1.
4195
4196
4197 Virtual modules
4198 ---------------
4199
4200 A virtual module stands for a module name associated to a modulefile.
4201 The modulefile is the script interpreted when loading or unloading the
4202 virtual module which appears or can be found with its virtual name.
4203
4204 The **module-virtual** modulefile command is introduced to give the
4205 ability to define these virtual modules. This new command takes a
4206 module name as first argument and a modulefile location as second
4207 argument:
4208
4209 module-virtual app/1.2.3 /path/to/virtualmod/app
4210
4211 With this feature it is now possible to dynamically define modulefiles
4212 depending on the context.
4213
4214
4215 Extend module command with site-specific Tcl code
4216 -------------------------------------------------
4217
4218 "module" command can now be extended with site-specific Tcl code.
4219 "modulecmd.tcl" now looks at a **siteconfig.tcl** file in an "etcdir"
4220 defined at configure time (by default "$prefix/etc"). If it finds this
4221 Tcl script file, it is sourced within "modulecmd.tcl" at the beginning
4222 of the main procedure code.
4223
4224 "siteconfig.tcl" enables to supersede any global variable or procedure
4225 definitions made in "modulecmd.tcl" with site-specific code. A module
4226 sub-command can for instance be redefined to make it fit local needs
4227 without having to touch the main "modulecmd.tcl".
4228
4229
4230 Quarantine mechanism to protect module execution
4231 ------------------------------------------------
4232
4233 To protect the module command run-time environment from side effect
4234 coming from the current environment definition a quarantine mechanism
4235 is introduced. This mechanism, sets within module function definition
4236 and shell initialization script, modifies the "modulecmd.tcl" run-time
4237 environment to sanitize it.
4238
4239 The mechanism is piloted by environment variables. First of all
4240 "MODULES_RUN_QUARANTINE", a space-separated list of environment
4241 variable names. Every variable found in "MODULES_RUN_QUARANTINE" will
4242 be set in quarantine during the "modulecmd.tcl" run-time. Their value
4243 will be set empty or set to the value of the corresponding
4244 "MODULES_RUNENV_<VAR>" environment variable if defined. Once
4245 "modulecmd.tcl" is started it restores quarantine variables to their
4246 original values.
4247
4248 "MODULES_RUN_QUARANTINE" and "MODULES_RUNENV_<VAR>" environment
4249 variables can be defined at build time by using the following
4250 configure option:
4251
4252 --with-quarantine-vars='VARNAME[=VALUE] ...'
4253
4254 Quarantine mechanism is available for all supported shells except
4255 "csh" and "tcsh".
4256
4257
4258 Pager support
4259 -------------
4260
4261 The informational messages Modules sends on the *stderr* channel may
4262 sometimes be quite long. This is especially the case for the avail
4263 sub-command when hundreds of modulefiles are handled. To improve the
4264 readability of those messages, *stderr* output can now be piped into a
4265 paging command.
4266
4267 This new feature can be controlled at build time with the "--with-
4268 pager" and "--with-pager-opts" configure options. Default pager
4269 command is set to "less" and its relative options are by default
4270 "-eFKRX". Default configuration can be supersedes at run-time with
4271 "MODULES_PAGER" environment variables or command-line switches ("--no-
4272 pager", "--paginate").
4273
4274 Warning:
4275
4276 On version "4.1.0", the "PAGER" environment variable was taken in
4277 consideration to supersede pager configuration at run-time. Since
4278 version "4.1.1", "PAGER" environment variable is ignored to avoid
4279 side effects coming from the system general pager configuration.
4280
4281
4282 Module function to return value in scripting languages
4283 ------------------------------------------------------
4284
4285 On Tcl, Perl, Python, Ruby, CMake and R scripting shells, module
4286 function was not returning value and until now an occurred error led
4287 to raising a fatal exception.
4288
4289 To make "module" function more friendly to use on these scripting
4290 shells it now returns a value. False in case of error, true if
4291 everything goes well.
4292
4293 As a consequence, returned value of a module sub-command can be
4294 checked. For instance in Python:
4295
4296 if module('load', 'foo'):
4297 # success
4298 else:
4299 # failure
4300
4301
4302 New modulefile commands
4303 -----------------------
4304
4305 4 new modulefile Tcl commands have been introduced:
4306
4307 * **is-saved**: returns true or false whether a collection,
4308 corresponding to currently set collection target, exists or not.
4309
4310 * **is-used**: returns true or false whether a given directory is
4311 currently enabled in "MODULEPATH".
4312
4313 * **is-avail**: returns true or false whether a given modulefile
4314 exists in currently enabled module paths.
4315
4316 * **module-info loaded**: returns the exact name of the modulefile
4317 currently loaded corresponding to the name argument.
4318
4319 Multiple collections, paths or modulefiles can be passed respectively
4320 to "is-saved", "is-used" and "is-avail" in which case true is returned
4321 if at least one argument matches condition (acts as a OR boolean
4322 operation). No argument may be passed to "is-loaded", "is-saved" and
4323 "is-used" commands to return if anything is respectively loaded, saved
4324 or used.
4325
4326 If no loaded modulefile matches the "module-info loaded" query, an
4327 empty string is returned.
4328
4329
4330 New module sub-commands
4331 -----------------------
4332
4333 Modulefile-specific commands are sometimes wished to be used outside
4334 of a modulefile context. Especially for the commands managing path
4335 variables or commands querying current environment context. So the
4336 following modulefile-specific commands have been made reachable as
4337 module sub-commands with same arguments and properties as if called
4338 from within a modulefile:
4339
4340 * **append-path**
4341
4342 * **prepend-path**
4343
4344 * **remove-path**
4345
4346 * **is-loaded**
4347
4348 * **info-loaded**
4349
4350 The "is-loaded" sub-command returns a boolean value. Small Python
4351 example:
4352
4353 if module('is-loaded', 'app'):
4354 print 'app is loaded'
4355 else:
4356 print 'app not loaded'
4357
4358 "info-loaded" returns a string value and is the sub-command
4359 counterpart of the "module-info loaded" modulefile command:
4360
4361 $ module load app/0.8
4362 $ module info-loaded app
4363 app/0.8
4364
4365
4366 v4.0
4367 ====
4368
4369 Major evolution occurs with this v4.0 release as the traditional
4370 *module* command implemented in C is replaced by the native Tcl
4371 version. This full Tcl rewrite of the Modules package was started in
4372 2002 and has now reached maturity to take over the binary version.
4373 This flavor change enables to refine and push forward the *module*
4374 concept.
4375
4376 This document provides an outlook of what is changing when migrating
4377 from v3.2 to v4.0 by first describing the introduced new features.
4378 Both v3.2 and v4.0 are quite similar and transition to the new major
4379 version should be smooth. Slights differences may be noticed in a few
4380 use-cases. So the second part of the document will help to learn about
4381 them by listing the features that have been discontinued in this new
4382 major release or the features where a behavior change can be noticed.
4383
4384
4385 New features
4386 ------------
4387
4388 On its overall this major release brings a lot more robustness to the
4389 *module* command with now more than 4000 non-regression tests crafted
4390 to ensure correct operations over the time. This version 4.0 also
4391 comes with fair amount of improved functionalities. The major new
4392 features are described in this section.
4393
4394
4395 Additional shells supported
4396 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
4397
4398 Modules v4 introduces support for **fish**, **lisp**, **tcl** and
4399 **R** code output.
4400
4401
4402 Non-zero exit code in case of error
4403 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4404
4405 All module sub-commands will now return a non-zero exit code in case
4406 of error whereas Modules v3.2 always returned zero exit code even if
4407 issue occurred.
4408
4409
4410 Output redirect
4411 ~~~~~~~~~~~~~~~
4412
4413 Traditionally the *module* command output text that should be seen by
4414 the user on *stderr* since shell commands are output to *stdout* to
4415 change shell's environment. Now on *sh*, *bash*, *ksh*, *zsh* and
4416 *fish* shells, output text is redirected to *stdout* after shell
4417 command evaluation if shell is in interactive mode.
4418
4419
4420 Filtering avail output
4421 ~~~~~~~~~~~~~~~~~~~~~~
4422
4423 Results obtained from the **avail** sub-command can now be filtered to
4424 only get the default version of each module name with use of the
4425 **--default** or **-d** command line switch. Default version is either
4426 the explicitly set default version or the highest numerically sorted
4427 modulefile or module alias if no default version set.
4428
4429 It is also possible to filter results to only get the highest
4430 numerically sorted version of each module name with use of the
4431 **--latest** or **-L** command line switch.
4432
4433
4434 Extended support for module alias and symbolic version
4435 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4436
4437 Module aliases are now included in the result of the **avail**,
4438 **whatis** and **apropos** sub-commands. They are displayed in the
4439 module path section where they are defined or in a *global/user
4440 modulerc* section for aliases set in user's or global "modulerc" file.
4441 A **@** symbol is added in parenthesis next to their name to
4442 distinguish them from modulefiles.
4443
4444 Search may be performed with an alias or a symbolic version-name
4445 passed as argument on **avail**, **whatis** and **apropos** sub-
4446 commands.
4447
4448 Modules v4 resolves module alias or symbolic version passed to
4449 **unload** command to then remove the loaded modulefile pointed by the
4450 mentioned alias or symbolic version.
4451
4452 A symbolic version sets on a module alias is now propagated toward the
4453 resolution path to also apply to the relative modulefile if it still
4454 correspond to the same module name.
4455
4456
4457 Hiding modulefiles
4458 ~~~~~~~~~~~~~~~~~~
4459
4460 Visibility of modulefiles can be adapted by use of file mode bits or
4461 file ownership. If a modulefile should only be used by a given subset
4462 of persons, its mode an ownership can be tailored to provide read
4463 rights to this group of people only. In this situation, module only
4464 reports the modulefile, during an **avail** command for instance, if
4465 this modulefile can be read by the current user.
4466
4467 These hidden modulefiles are simply ignored when walking through the
4468 modulepath content. Access issues (permission denied) occur only when
4469 trying to access directly a hidden modulefile or when accessing a
4470 symbol or an alias targeting a hidden modulefile.
4471
4472
4473 Improved modulefiles location
4474 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4475
4476 When looking for an implicit default in a modulefile directory,
4477 aliases are now taken into account in addition to modulefiles and
4478 directories to determine the highest numerically sorted element.
4479
4480 Modules v4 resolves module alias or symbolic version when it points to
4481 a modulefile located in another modulepath.
4482
4483 Access issues (permission denied) are now distinguished from find
4484 issues (cannot locate) when trying to access directly a directory or a
4485 modulefile as done on **load**, **display** or **whatis** commands. In
4486 addition, on this kind of access not readable ".modulerc" or
4487 ".version" files are ignored rather producing a missing magic cookie
4488 error.
4489
4490
4491 Module collection
4492 ~~~~~~~~~~~~~~~~~
4493
4494 Modules v4 introduces support for module *collections*. Collections
4495 describe a sequence of **module use** then **module load** commands
4496 that are interpreted by Modules to set the user environment as
4497 described by this sequence. When a collection is activated, with the
4498 **restore** sub-command, modulepaths and loaded modules are unused or
4499 unloaded if they are not part or if they are not ordered the same way
4500 as in the collection.
4501
4502 Collections are generated by the **save** sub-command that dumps the
4503 current user environment state in terms of modulepaths and loaded
4504 modules. By default collections are saved under the "$HOME/.module"
4505 directory. Collections can be listed with **savelist** sub-command,
4506 displayed with **saveshow** and removed with **saverm**.
4507
4508 Collections may be valid for a given target if they are suffixed. In
4509 this case these collections can only be restored if their suffix
4510 correspond to the current value of the "MODULES_COLLECTION_TARGET"
4511 environment variable. Saving collection registers the target footprint
4512 by suffixing the collection filename with
4513 ".$MODULES_COLLECTION_TARGET".
4514
4515
4516 Path variable element counter
4517 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4518
4519 Modules 4 provides path element counting feature which increases a
4520 reference counter each time a given path entry is added to a given
4521 path-like environment variable. As consequence a path entry element is
4522 removed from a path-like variable only if the related element counter
4523 is equal to 1. If this counter is greater than 1, path element is kept
4524 in variable and reference counter is decreased by 1.
4525
4526 This feature allows shared usage of particular path elements. For
4527 instance, modulefiles can append "/usr/local/bin" to "PATH", which is
4528 not unloaded until all the modulefiles that loaded it unload too.
4529
4530
4531 Optimized I/O operations
4532 ~~~~~~~~~~~~~~~~~~~~~~~~
4533
4534 Substantial work has been done to reduce the number of I/O operations
4535 done during global modulefile analysis commands like **avail** or
4536 **whatis**. "stat", "open", "read" and "close" I/O operations have
4537 been cut down to the minimum required when walking through the
4538 modulepath directories to check if files are modulefiles or to resolve
4539 module aliases.
4540
4541 Interpretation of modulefiles and modulerc are handled by the minimum
4542 required Tcl interpreters. Which means a configured Tcl interpreter is
4543 reused as much as possible between each modulefile interpretation or
4544 between each modulerc interpretation.
4545
4546
4547 Sourcing modulefiles
4548 ~~~~~~~~~~~~~~~~~~~~
4549
4550 Modules 4 introduces the possibility to **source** a modulefile rather
4551 loading it. When it is sourced, a modulefile is interpreted into the
4552 shell environment but then it is not marked loaded in shell
4553 environment which differ from **load** sub-command.
4554
4555 This functionality is used in shell initialization scripts once
4556 **module** function is defined. There the "etc/modulerc" modulefile is
4557 sourced to setup the initial state of the environment, composed of
4558 *module use* and *module load* commands.
4559
4560
4561 Removed features and substantial behavior changes
4562 -------------------------------------------------
4563
4564 Following sections provide list of Modules v3.2 features that are
4565 discontinued on Modules v4 or features with a substantial behavior
4566 change that should be taken in consideration when migrating to v4.
4567
4568
4569 Package initialization
4570 ~~~~~~~~~~~~~~~~~~~~~~
4571
4572 "MODULESBEGINENV" environment snapshot functionality is not supported
4573 anymore on Modules v4. Modules collection mechanism should be used
4574 instead to **save** and **restore** sets of enabled modulepaths and
4575 loaded modulefiles.
4576
4577
4578 Command line switches
4579 ~~~~~~~~~~~~~~~~~~~~~
4580
4581 Some command line switches are not supported anymore on v4.0. When
4582 still using them, a warning message is displayed and the command is
4583 ran with these unsupported switches ignored. Following command line
4584 switches are concerned:
4585
4586 * "--force", "-f"
4587
4588 * "--human"
4589
4590 * "--verbose", "-v"
4591
4592 * "--silent", "-s"
4593
4594 * "--create", "-c"
4595
4596 * "--icase", "-i"
4597
4598 * "--userlvl" lvl, "-u" lvl
4599
4600
4601 Module sub-commands
4602 ~~~~~~~~~~~~~~~~~~~
4603
4604 During an **help** sub-command, Modules v4 does not redirect output
4605 made on stdout in *ModulesHelp* Tcl procedure to stderr. Moreover when
4606 running **help**, version 4 interprets all the content of the
4607 modulefile, then call the *ModulesHelp* procedure if it exists,
4608 whereas Modules 3.2 only interprets the *ModulesHelp* procedure and
4609 not the rest of the modulefile content.
4610
4611 When **load** is asked on an already loaded modulefiles, Modules v4
4612 ignores this new load order whereas v3.2 refreshed shell alias
4613 definitions found in this modulefile.
4614
4615 When **switching** on version 4 an *old* modulefile by a *new* one, no
4616 error is raised if *old* modulefile is not currently loaded. In this
4617 situation v3.2 threw an error and abort switch action. Additionally on
4618 **switch** sub-command, *new* modulefile does not keep the position
4619 held by *old* modulefile in loaded modules list on Modules v4 as it
4620 was the case on v3.2. Same goes for path-like environment variables:
4621 replaced path component is appended to the end or prepended to the
4622 beginning of the relative path-like variable, not appended or
4623 prepended relatively to the position hold by the swapped path
4624 component.
4625
4626 During a **switch** command, version 4 interprets the swapped-out
4627 modulefile in *unload* mode, so the sub-modulefiles loaded, with
4628 "module load" order in the swapped-out modulefile are also unloaded
4629 during the switch.
4630
4631 Modules 4 provides path element counting feature which increases a
4632 reference counter each time a given path entry is added to a given
4633 environment variable. This feature also applies to the "MODULEPATH"
4634 environment variable. As consequence a modulepath entry element is
4635 removed from the modulepath enabled list only if the related element
4636 counter is equal to 1. When **unusing** a modulepath if its reference
4637 counter is greater than 1, modulepath is kept enabled and reference
4638 counter is decreased by 1.
4639
4640 On Modules 3.2 paths composing the "MODULEPATH" environment variable
4641 may contain reference to environment variable. These variable
4642 references are resolved dynamically when "MODULEPATH" is looked at
4643 during module sub-command action. This feature has been discontinued
4644 on Modules v4.
4645
4646 Following Modules sub-commands are not supported anymore on v4.0:
4647
4648 * "clear"
4649
4650 * "update"
4651
4652
4653 Modules specific Tcl commands
4654 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4655
4656 Modules v4 provides path element counting feature which increases a
4657 reference counter each time a given path entry is added to a given
4658 environment variable. As a consequence a path entry element is not
4659 always removed from a path-like variable when calling to "remove-path"
4660 or calling to "append-path" or "append-path" at unloading time. The
4661 path element is removed only if its related element counter is equal
4662 to 1. If this counter is greater than 1, path element is kept in
4663 variable and reference counter is decreased by 1.
4664
4665 On Modules v4, **module-info mode** returns during an **unload** sub-
4666 command the "unload" value instead of "remove" on Modules v3.2.
4667 However if *mode* is tested against "remove" value, true will be
4668 returned. During a **switch** sub-command on Modules v4, "unload" then
4669 "load" is returned instead of "switch1" then "switch2" then "switch3"
4670 on Modules v3.2. However if *mode* is tested against "switch" value,
4671 true will be returned.
4672
4673 When using **set-alias**, Modules v3.2 defines a shell function when
4674 variables are in use in alias value on Bourne shell derivatives,
4675 Modules 4 always defines a shell alias never a shell function.
4676
4677 Some Modules specific Tcl commands are not supported anymore on v4.0.
4678 When still using them, a warning message is displayed and these
4679 unsupported Tcl commands are ignored. Following Modules specific Tcl
4680 commands are concerned:
4681
4682 * "module-info flags"
4683
4684 * "module-info trace"
4685
4686 * "module-info tracepat"
4687
4688 * "module-info user"
4689
4690 * "module-log"
4691
4692 * "module-trace"
4693
4694 * "module-user"
4695
4696 * "module-verbosity"
4697
4698
4699 Further reading
4700 ---------------
4701
4702 To get a complete list of the differences between Modules v3.2 and v4,
4703 please read the Changes between versions document.
4704
4705 A significant number of issues reported for v3.2 have been closed on
4706 v4. List of these closed issues can be found at:
4707
4708 https://github.com/envmodules/modules/milestone/1?closed=1