Debian Codegraph @

doc/source/module.rst

raw
1 .. _module(1):
2
3 module
4 ======
5
6
7 SYNOPSIS
8 --------
9
10 **module** [*switches*] [*sub-command* [*sub-command-args*]]
11
12 .. _module DESCRIPTION:
13
14 DESCRIPTION
15 -----------
16
17 :command:`module` is a user interface to the Modules package. The Modules
18 package provides for the dynamic modification of the user's environment
19 via *modulefiles*.
20
21 Each *modulefile* contains the information needed to configure the
22 shell for an application. Once the Modules package is initialized, the
23 environment can be modified on a per-module basis using the :command:`module`
24 command which interprets *modulefiles*. Typically *modulefiles* instruct
25 the :command:`module` command to alter or set shell environment variables such
26 as :envvar:`PATH`, :envvar:`MANPATH`, etc. *Modulefiles* may be shared by many
27 users on a system and users may have their own set to supplement or replace
28 the shared *modulefiles*.
29
30 The *modulefiles* are added to and removed from the current environment
31 by the user. The environment changes contained in a *modulefile* can be
32 summarized through the :command:`module` command as well. If no arguments are
33 given, a summary of the :command:`module` usage and *sub-commands* are shown.
34
35 The action for the :command:`module` command to take is described by the
36 *sub-command* and its associated arguments.
37
38
39 .. _Package Initialization:
40
41 Package Initialization
42 ^^^^^^^^^^^^^^^^^^^^^^
43
44 The Modules package and the :command:`module` command are initialized when a
45 shell-specific initialization script is sourced into the shell. The script
46 executes the :subcmd:`autoinit` sub-command of the :file:`modulecmd.tcl`
47 program located in |file libexecdir| for the corresponding shell. The output
48 of this execution is evaluated by shell which creates the :command:`module`
49 command as either an alias or function and creates Modules environment
50 variables.
51
52 During this initialization process, if the Modules environment is found
53 undefined (when both :envvar:`MODULEPATH` and :envvar:`LOADEDMODULES` are
54 found either unset or empty), the :file:`modulespath` and :file:`initrc`
55 configuration files located in |file etcdir| are evaluated if present and
56 following this order. :file:`modulespath` file contains the list of
57 modulepaths to enable during initialization. In this file, the modulepaths are
58 separated by newline or colon characters. :file:`initrc` is a modulefile that
59 defines during initialization the modulepaths to enable, the modules to load
60 and the :command:`module` configuration to apply.
61
62 During the initialization process, if the Modules environment is found defined
63 a :subcmd:`module refresh<refresh>` is automatically applied to restore in the
64 current environment all non-persistent components set by loaded modules.
65
66 The :command:`module` alias or function executes the :file:`modulecmd.tcl`
67 program and has the shell evaluate the command's output. The first argument to
68 :file:`modulecmd.tcl` specifies the type of shell.
69
70 The initialization scripts are kept in |file initdir_shell| where
71 *<shell>* is the name of the sourcing shell. For example, a C Shell user
72 sources the |file initdir_csh| script. The sh, csh, tcsh, bash, ksh,
73 zsh, fish and cmd shells are supported by :file:`modulecmd.tcl`. In addition,
74 python, perl, ruby, tcl, cmake, r and lisp "shells" are supported which
75 writes the environment changes to stdout as python, perl, ruby, tcl, lisp,
76 r or cmake code.
77
78 Initialization may also be performed by directly calling the
79 :subcmd:`autoinit` sub-command of the :file:`modulecmd.tcl` program.
80
81 A :command:`ml` alias or function may also be defined at initialization time
82 if enabled (see :envvar:`MODULES_ML` section). :command:`ml` is a handy
83 frontend leveraging all :command:`module` command capabilities with less
84 character typed. See :ref:`ml(1)` for detailed information.
85
86 A :command:`mogui` alias or function may also be defined at initialization
87 time if :command:`mogui-cmd` command is found in :envvar:`PATH`.
88 :command:`mogui` is the Graphical User Interface for Modules. Environment
89 changes performed in the GUI is applied onto the shell session that executed
90 :command:`mogui`.
91
92 .. only:: html
93
94 .. versionchanged:: 5.5
95 Definition of :command:`mogui` alias or function added
96
97
98 Examples of initialization
99 ^^^^^^^^^^^^^^^^^^^^^^^^^^
100
101 C Shell initialization (and derivatives):
102
103 .. parsed-literal::
104
105 source \ |initdir|\ /csh
106 module load modulefile modulefile ...
107
108 Bourne Shell (sh) (and derivatives):
109
110 .. parsed-literal::
111
112 . \ |initdir|\ /sh
113 module load modulefile modulefile ...
114
115 PowerShell (pwsh):
116
117 .. parsed-literal::
118
119 . \ |initdir|\ /pwsh.ps1
120 envmodule load modulefile modulefile ...
121
122 Perl:
123
124 .. parsed-literal::
125
126 require "\ |initdir|\ /perl.pm";
127 &module('load', 'modulefile', 'modulefile', '...');
128
129 Python:
130
131 .. parsed-literal::
132
133 import os
134 exec(open("\ |initdir|\ /python.py").read(), globals())
135 module("load", "modulefile", "modulefile", "...")
136
137 Ruby:
138
139 .. parsed-literal::
140
141 require '\ |initdir|\ /ruby.rb'
142 ENVModule.module('load', 'modulefile', 'modulefile', '...')
143
144 Bourne Shell (sh) (and derivatives) with :subcmd:`autoinit` sub-command:
145
146 .. parsed-literal::
147
148 eval "$(\ |libexecdir|\ /modulecmd.tcl sh autoinit)"
149
150
151 .. _Modulecmd startup:
152
153 Modulecmd startup
154 ^^^^^^^^^^^^^^^^^
155
156 Upon invocation :file:`modulecmd.tcl` sources a site-specific configuration
157 script if it exists. Siteconfig script is a Tcl script located at
158 |file etcdir_siteconfig|. It enables to supersede any global variable or
159 procedure definition of :file:`modulecmd.tcl`. See :ref:`Site-specific
160 configuration` for detailed information.
161
162 Afterward, :file:`modulecmd.tcl` sources rc files which contain global,
163 user and *modulefile* specific setups. These files are interpreted as
164 *modulefiles*. See :ref:`modulefile(5)` for detailed information.
165
166 Upon invocation of :file:`modulecmd.tcl` module run-command files are sourced
167 in the following order:
168
169 1. Global RC file(s) as specified by :envvar:`MODULERCFILE` variable or
170 |file etcdir_rc|. If a path element in :envvar:`MODULERCFILE` points to a
171 directory, the :file:`modulerc` file in this directory is used as a global
172 RC file.
173
174 2. User specific module RC file :file:`$HOME/.modulerc`
175
176 3. All :file:`.modulerc` and :file:`.version` files found during modulefile
177 seeking.
178
179 These module run-command files must begins like *modulefiles* with the
180 ``#%Module`` file signature, also called the Modules magic cookie. A version
181 number may be placed after this string. The version number reflects the
182 minimum version of :file:`modulecmd.tcl` required to interpret the run-command
183 file. If a version number doesn't exist, then :file:`modulecmd.tcl` will
184 assume the run-command file is compatible. Files without the magic cookie or
185 with a version number greater than the current version of
186 :file:`modulecmd.tcl` will not be interpreted and an error is reported. Such
187 error does not abort the whole :command:`module` evaluation. If the
188 :mconfig:`mcookie_version_check` configuration is disabled the version number
189 set is not checked.
190
191 .. note:: Run-command files are intended to set parameters for modulefiles,
192 not to configure the :command:`module` command itself.
193
194 Command line switches
195 ^^^^^^^^^^^^^^^^^^^^^
196
197 The :command:`module` command accepts command line switches as its first
198 parameter. These may be used to control output format of all information
199 displayed and the :command:`module` behavior in case of locating and
200 interpreting *modulefiles*.
201
202 All switches may be entered either in short or long notation. The following
203 switches are accepted:
204
205 .. option:: --all, -a
206
207 Include hidden modules in search performed with :subcmd:`avail`,
208 :subcmd:`aliases`, :subcmd:`list`, :subcmd:`lint`, :subcmd:`savelist`,
209 :subcmd:`search`, :subcmd:`spider` or :subcmd:`whatis` sub-commands.
210 Hard-hidden modules are not affected by this option.
211
212 .. only:: html
213
214 .. versionadded:: 4.6
215
216 .. versionchanged:: 4.7
217 Support for :subcmd:`list` sub-command added
218
219 .. versionchanged:: 5.2
220 Support for :subcmd:`lint` and :subcmd:`savelist` sub-commands added
221
222 .. versionchanged:: 5.6
223 Support for :subcmd:`spider` sub-command added
224
225 .. option:: --auto
226
227 Enable automated module handling mode on sub-commands that load or unload
228 modulefiles. See also :envvar:`MODULES_AUTO_HANDLING` section.
229
230 .. only:: html
231
232 .. versionadded:: 4.2
233
234 .. option:: --color=<WHEN>
235
236 Colorize the output. *WHEN* defaults to ``always`` or can be ``never`` or
237 ``auto``. See also :envvar:`MODULES_COLOR` section.
238
239 .. only:: html
240
241 .. versionadded:: 4.3
242
243 .. option:: --contains, -C
244
245 On :subcmd:`avail`, :subcmd:`list`, :subcmd:`savelist` and :subcmd:`spider`
246 sub-commands, return modules or collections whose fully qualified name
247 contains search query string.
248
249 .. only:: html
250
251 .. versionadded:: 4.3
252
253 .. versionchanged:: 5.1
254 Support for :subcmd:`list` sub-command added
255
256 .. versionchanged:: 5.2
257 Support for :subcmd:`savelist` sub-command added
258
259 .. versionchanged:: 5.6
260 Support for :subcmd:`spider` sub-command added
261
262 .. option:: --debug, -D, -DD
263
264 Debug mode. Causes :command:`module` to print debugging messages about its
265 progress. Multiple :option:`-D` options increase the debug verbosity. The
266 maximum is 2.
267
268 .. only:: html
269
270 .. versionadded:: 4.0
271
272 .. versionchanged:: 4.6
273 Option form :option:`-DD` added
274
275 .. option:: --default, -d
276
277 On :subcmd:`avail` and :subcmd:`spider` sub-commands, display only the
278 default version of each module name. Default version is the explicitly set
279 default version or also the implicit default version if the configuration
280 option :mconfig:`implicit_default` is enabled (see :ref:`Locating
281 Modulefiles` section in the :ref:`modulefile(5)` man page for further details
282 on implicit default version).
283
284 .. only:: html
285
286 .. versionadded:: 4.0
287
288 .. versionchanged:: 5.6
289 Support for :subcmd:`spider` sub-command added
290
291 .. option:: --dumpname
292
293 Report the name of the current implementation of the :command:`module`
294 command. This option returns ``Modules`` for this implementation. The command
295 then terminates without further processing.
296
297 .. only:: html
298
299 .. versionadded:: 5.6
300
301 .. option:: --force, -f
302
303 On :subcmd:`load`, :subcmd:`unload`, :subcmd:`switch`, :subcmd:`load-any`,
304 :subcmd:`try-load`, :subcmd:`mod-to-sh` and :subcmd:`source` sub-commands
305 by-pass any unsatisfied modulefile constraint corresponding to the declared
306 :mfcmd:`prereq`, :ref:`via requirement<MODULES_REQUIRE_VIA>` and
307 :mfcmd:`conflict`. Which means for instance that a *modulefile* will be
308 loaded even if it comes in conflict with another loaded *modulefile* or that
309 a *modulefile* will be unloaded even if it is a requirement of another
310 *modulefile*.
311
312 On :subcmd:`load`, :command:`ml`, :subcmd:`mod-to-sh`, :subcmd:`purge`,
313 :subcmd:`reload`, :subcmd:`switch`, :subcmd:`try-load` and :subcmd:`unload`
314 sub-commands applies *continue on error* behavior when an error occurs even
315 if :mconfig:`abort_on_error` option is enabled.
316
317 On :command:`ml`, :subcmd:`purge`, :subcmd:`reload`, :subcmd:`reset`,
318 :subcmd:`restore`, :subcmd:`stash`, :subcmd:`stashpop`, :subcmd:`switch` and
319 :subcmd:`unload` sub-commands, unloads modulefile anyway even if an
320 evaluation error occurs.
321
322 On :subcmd:`clear` sub-command, skip the confirmation dialog and proceed.
323
324 On :subcmd:`purge` sub-command also unload `sticky modules`_ and modulefiles
325 that are depended by non-unloadable modules.
326
327 .. only:: html
328
329 .. versionadded:: 4.3
330 :option:`--force`/:option:`-f` support was dropped on version `4.0`
331 but reintroduced starting version `4.2` with a different meaning:
332 instead of enabling an active dependency resolution mechanism
333 :option:`--force` command line switch now enables to by-pass dependency
334 consistency when loading or unloading a *modulefile*.
335
336 .. versionchanged:: 4.7
337 Support for :subcmd:`purge` sub-command added
338
339 .. versionchanged:: 4.8
340 Support for :subcmd:`try-load` sub-command added
341
342 .. versionchanged:: 5.1
343 Support for :subcmd:`load-any` sub-command added
344
345 .. versionchanged:: 5.2
346 Support for :subcmd:`mod-to-sh` sub-command added
347
348 .. versionchanged:: 5.4
349 Unloads modulefile anyway even if an evaluation error occurs
350
351 .. versionchanged:: 5.4
352 Disables :mconfig:`abort_on_error` configuration option
353
354 .. option:: --help, -h
355
356 Give some helpful usage information, and terminates the command.
357
358 .. option:: --icase, -i
359
360 Match module specification arguments in a case insensitive manner.
361
362 .. only:: html
363
364 .. versionadded:: 4.4
365 :option:`--icase`/:option:`-i` support was dropped on version `4.0`
366 but reintroduced starting version `4.4`. When set, it now applies to
367 search query string and module specification on all sub-commands and
368 modulefile Tcl commands.
369
370 .. option:: --ignore-cache
371
372 Ignore module cache.
373
374 .. only:: html
375
376 .. versionadded:: 5.3
377
378 .. option:: --ignore-user-rc
379
380 Skip evaluation of user-specific module rc file (:file:`$HOME/.modulerc`).
381
382 .. only:: html
383
384 .. versionadded:: 5.3
385
386 .. option:: --indepth
387
388 On :subcmd:`avail` and :subcmd:`spider` sub-commands, include in search
389 results the matching modulefiles and directories and recursively the
390 modulefiles and directories contained in these matching directories.
391
392 .. only:: html
393
394 .. versionadded:: 4.3
395
396 .. versionchanged:: 5.6
397 Support for :subcmd:`spider` sub-command added
398
399 .. option:: --json, -j
400
401 Display :subcmd:`avail`, :subcmd:`list`, :subcmd:`savelist`,
402 :subcmd:`search`, :subcmd:`spider`, :subcmd:`stashlist` and :subcmd:`whatis`
403 output in JSON format.
404
405 .. only:: html
406
407 .. versionadded:: 4.5
408
409 .. versionchanged:: 5.2
410 Support for :subcmd:`stashlist` sub-command added
411
412 .. versionchanged:: 5.6
413 Support for :subcmd:`spider` sub-command added
414
415
416 .. option:: --latest, -L
417
418 On :subcmd:`avail` and :subcmd:`spider` sub-commands, display only the
419 highest numerically sorted version of each module name (see :ref:`Locating
420 Modulefiles` section in the :ref:`modulefile(5)` man page).
421
422 .. only:: html
423
424 .. versionadded:: 4.0
425
426 .. versionchanged:: 5.6
427 Support for :subcmd:`spider` sub-command added
428
429 .. option:: --long, -l
430
431 Display :subcmd:`avail`, :subcmd:`list`, :subcmd:`savelist`, :subcmd:`spider`
432 and :subcmd:`stashlist` output in long format.
433
434 .. only:: html
435
436 .. versionchanged:: 4.0
437 Support for :subcmd:`savelist` sub-command added
438
439 .. versionchanged:: 5.2
440 Support for :subcmd:`stashlist` sub-command added
441
442 .. versionchanged:: 5.6
443 Support for :subcmd:`spider` sub-command added
444
445 .. option:: --no-auto
446
447 Disable automated module handling mode on sub-commands that load or unload
448 modulefiles. See also :envvar:`MODULES_AUTO_HANDLING` section.
449
450 .. only:: html
451
452 .. versionadded:: 4.2
453
454 .. option:: --no-indepth
455
456 On :subcmd:`avail` and :subcmd:`spider` sub-commands, limit search results to
457 the matching modulefiles and directories found at the depth level expressed
458 by the search query. Thus modulefiles contained in directories part of the
459 result are excluded.
460
461 .. only:: html
462
463 .. versionadded:: 4.3
464
465 .. versionchanged:: 5.6
466 Support for :subcmd:`spider` sub-command added
467
468 .. option:: --no-pager
469
470 Do not pipe message output into a pager.
471
472 .. only:: html
473
474 .. versionadded:: 4.1
475
476 .. option:: --no-redirect
477
478 Do not send message output to stdout. Keep it on stderr.
479
480 .. only:: html
481
482 .. versionadded:: 5.1
483
484 .. _--output:
485
486 .. option:: --output=LIST, -o LIST
487
488 Define the content to report in addition to module names. This option is
489 supported by :subcmd:`avail`, :subcmd:`list` and :subcmd:`spider`
490 sub-commands on their regular or terse output modes. Accepted values are a
491 *LIST* of elements to report separated by colon character (``:``). The order
492 of the elements in *LIST* does not matter.
493
494 Accepted elements in *LIST* for :subcmd:`avail` and :subcmd:`spider`
495 sub-command are: *modulepath*, *alias*, *provided-alias*, *dirwsym*,
496 *indesym*, *sym*, *tag*, *key*, *hidden*, *variant*, *variantifspec* and
497 *via*. *via* element is not accepted on terse output mode.
498
499 Accepted elements in *LIST* for :subcmd:`list` sub-command are: *header*,
500 *idx*, *variant*, *alias*, *indesym*, *sym*, *tag*, *hidden* and *key*.
501
502 The order of the elements in *LIST* does not matter. Module names are the
503 only content reported when *LIST* is set to an empty value.
504
505 *LIST* may be prefixed by ``+`` or ``-`` character to indicate respectively
506 to append it to or subtract it from current configuration option value.
507
508 See also :envvar:`MODULES_AVAIL_OUTPUT`, :envvar:`MODULES_LIST_OUTPUT` and
509 :envvar:`MODULES_SPIDER_OUTPUT`.
510
511 .. only:: html
512
513 .. versionadded:: 4.7
514
515 .. versionchanged:: 4.8
516 Element *variant* added for :subcmd:`list` sub-command
517
518 .. versionchanged:: 5.3
519 Elements *variant* and *variantifspec* added for :subcmd:`avail`
520 sub-command
521
522 .. versionchanged:: 5.3
523 Prefixes ``+`` and ``-`` added to append and subtract elements
524
525 .. versionchanged:: 5.3.1
526 Element *indesym* added for :subcmd:`avail` sub-command
527
528 .. versionchanged:: 5.4
529 Elements *alias* and *indesym* added for :subcmd:`list` sub-command
530
531 .. versionchanged:: 5.6
532 Sub-command :subcmd:`spider` supported
533
534 .. versionchanged:: 5.6
535 Element *hidden* added for :subcmd:`avail`, :subcmd:`list` and
536 :subcmd:`spider` sub-commands
537
538 .. versionchanged:: 5.6
539 Elements *provided-alias* and *via* added for :subcmd:`avail` and
540 :subcmd:`spider` sub-commands
541
542 .. option:: --paginate
543
544 Pipe all message output into :command:`less` (or if set, to the command
545 referred in :envvar:`MODULES_PAGER` variable) if error output stream is a
546 terminal. See also :envvar:`MODULES_PAGER` section.
547
548 .. only:: html
549
550 .. versionadded:: 4.1
551
552 .. option:: --redirect
553
554 Send message output to stdout instead of stderr. Only supported on sh, bash,
555 ksh, zsh and fish shells.
556
557 .. only:: html
558
559 .. versionadded:: 5.1
560
561 .. option:: --silent, -s
562
563 Turn off error, warning and informational messages. :command:`module` command
564 output result is not affected by silent mode.
565
566 .. only:: html
567
568 .. versionadded:: 4.3
569 :option:`--silent`/:option:`-s` support was dropped on version `4.0`
570 but reintroduced starting version `4.3`.
571
572 .. option:: --starts-with, -S
573
574 On :subcmd:`avail`, :subcmd:`list`, :subcmd:`savelist` and :subcmd:`spider`
575 sub-commands, return modules or collections whose name starts with search
576 query string.
577
578 .. only:: html
579
580 .. versionadded:: 4.3
581
582 .. versionchanged:: 5.1
583 Support for :subcmd:`list` sub-command added
584
585 .. versionchanged:: 5.2
586 Support for :subcmd:`savelist` sub-command added
587
588 .. versionchanged:: 5.6
589 Support for :subcmd:`spider` sub-command added
590
591 .. option:: --tag=LIST
592
593 On :subcmd:`load`, :subcmd:`load-any`, :subcmd:`switch` and
594 :subcmd:`try-load` sub-commands, apply LIST of module tags to the loading
595 *modulefile*. *LIST* corresponds to the concatenation of multiple tags
596 separated by colon character (``:``). *LIST* should not contain tags
597 inherited from *modulefile* state or from other modulefile commands. If
598 module is already loaded, tags from *LIST* are added to the list of tags
599 already applied to this module.
600
601 .. only:: html
602
603 .. versionadded:: 5.1
604
605 .. option:: --terse, -t
606
607 Display :subcmd:`avail`, :subcmd:`list`, :subcmd:`savelist`, :subcmd:`spider`
608 and :subcmd:`stashlist` output in short format.
609
610 .. only:: html
611
612 .. versionchanged:: 4.0
613 Support for :subcmd:`savelist` sub-command added
614
615 .. versionchanged:: 5.2
616 Support for :subcmd:`stashlist` sub-command added
617
618 .. versionchanged:: 5.6
619 Support for :subcmd:`spider` sub-command added
620
621 .. option:: --timer
622
623 Prints at the end of the output an evaluation of the total execution time of
624 the :command:`module` command. When mixed with a single or multiple
625 :option:`--debug` options, replaces regular debug messages by reports of the
626 execution time of every internal procedure calls.
627
628 .. only:: html
629
630 .. versionadded:: 5.2
631
632 .. option:: --trace, -T
633
634 Trace mode. Report details on module searches, resolutions, selections and
635 evaluations in addition to printing verbose messages.
636
637 .. only:: html
638
639 .. versionadded:: 4.6
640
641 .. option:: --verbose, -v, -vv
642
643 Enable verbose messages during :command:`module` command execution. Multiple
644 :option:`-v` options increase the verbosity level. The maximum is 2.
645
646 .. only:: html
647
648 .. versionadded:: 4.3
649 :option:`--verbose`/:option:`-v` support was dropped on version `4.0`
650 but reintroduced starting version `4.3`.
651
652 .. versionchanged:: 4.7
653 Option form :option:`-vv` added
654
655 .. option:: --version, -V
656
657 Lists the current version of the :command:`module` command. The command then
658 terminates without further processing.
659
660 .. option:: --width=COLS, -w COLS
661
662 Set the width of the output to *COLS* columns. See also
663 :envvar:`MODULES_TERM_WIDTH` section.
664
665 .. only:: html
666
667 .. versionadded:: 4.7
668
669
670 .. _Module Sub-Commands:
671
672 Module Sub-Commands
673 ^^^^^^^^^^^^^^^^^^^
674
675 .. subcmd:: add [options] modulefile...
676
677 See :subcmd:`load`.
678
679 .. subcmd:: add-any [options] modulefile...
680
681 See :subcmd:`load-any`.
682
683 .. only:: html
684
685 .. versionadded:: 5.1
686
687 .. subcmd:: aliases [-a]
688
689 List all available symbolic version-names and aliases in the current
690 :envvar:`MODULEPATH`. All directories in the :envvar:`MODULEPATH` are
691 recursively searched in the same manner than for the :subcmd:`avail`
692 sub-command. Only the symbolic version-names and aliases found in the search
693 are displayed.
694
695 .. only:: html
696
697 .. versionadded:: 4.0
698
699 .. versionchanged:: 4.6
700 Option :option:`--all`/:option:`-a` added
701
702 .. subcmd:: append-path [options] variable value...
703
704 Append *value* to environment *variable*. The *variable* is a colon, or
705 *delimiter*, separated list. See :mfcmd:`append-path` in the
706 :ref:`modulefile(5)` man page for *options* description and further
707 explanation.
708
709 When :subcmd:`append-path` is called as a module sub-command, the reference
710 counter variable, which denotes the number of times *value* has been added to
711 environment *variable*, is not updated unless if the ``--duplicates`` option
712 is set.
713
714 .. only:: html
715
716 .. versionadded:: 4.1
717
718 .. versionchanged:: 5.0
719 Reference counter environment variable is not updated anymore unless if
720 the ``--duplicates`` option is set
721
722 .. subcmd:: apropos [-a] [-j] string
723
724 See :subcmd:`search`.
725
726 .. subcmd:: avail [-d|-L] [-t|-l|-j] [-a] [-o LIST] [-S|-C] [--indepth|--no-indepth] [pattern...]
727
728 List all available *modulefiles* in the current :envvar:`MODULEPATH`. All
729 directories in the :envvar:`MODULEPATH` are recursively searched for files
730 containing the Modules magic cookie. If a *pattern* argument is given, then
731 each directory in the :envvar:`MODULEPATH` is searched for *modulefiles*
732 whose pathname, symbolic version-name or alias match *pattern* in a case
733 insensitive manner by default. *pattern* may contain wildcard characters.
734 Multiple versions of an application can be supported by creating a
735 subdirectory for the application containing *modulefiles* for each version.
736
737 Symbolic version-names and aliases found in the search are displayed in the
738 result of this sub-command. Symbolic version-names are displayed next to
739 the *modulefile* they are assigned to within parenthesis. Aliases are listed
740 in the :envvar:`MODULEPATH` section where they have been defined. To
741 distinguish aliases from *modulefiles* a ``@`` symbol is added within
742 parenthesis next to their name. Aliases defined through a global or user
743 specific module RC file are listed under the **global/user modulerc**
744 section.
745
746 When colored output is enabled and a specific graphical rendition is defined
747 for module *default* version, the ``default`` symbol is omitted and instead
748 the defined graphical rendition is applied to the relative modulefile. When
749 colored output is enabled and a specific graphical rendition is defined for
750 module alias, the ``@`` symbol is omitted. The defined graphical rendition
751 applies to the module alias name. See :envvar:`MODULES_COLOR` and
752 :envvar:`MODULES_COLORS` sections for details on colored output.
753
754 Module tags applying to the available *modulefiles* returned by the
755 :subcmd:`avail` sub-command are reported along the module name they are
756 associated to (see `Module tags`_ section).
757
758 Module variants and their available values may be reported along the module
759 name they belong to (see `Module variants`_ section) if defined in avail
760 output configuration option (see :option:`--output`/:option:`-o` option). The
761 :ref:`extra match search` process is triggered to collect variant
762 information.
763
764 A *Key* section is added at the end of the output in case some elements are
765 reported in parentheses or chevrons along module name or if some graphical
766 rendition is made over some output elements. This *Key* section gives hints
767 on the meaning of such elements.
768
769 The parameter *pattern* may also refer to a symbolic modulefile name or a
770 modulefile alias. It may also leverage a specific syntax to finely select
771 module version (see `Advanced module version specifiers`_ section below).
772
773 If *pattern* contains variant specification or :ref:`extra specifier`, the
774 :ref:`extra match search` process is triggered to collect command information
775 used in modulefiles. Modules are included in results only if they match
776 *pattern* variant specification and extra specifier. *pattern* may be a bare
777 variant specification or extra specifier without mention of a module name.
778
779 When several *patterns* are provided all modulefiles matching at least one of
780 these *patterns* are listed.
781
782 .. only:: html
783
784 .. versionchanged:: 4.0
785 Options :option:`--default`/:option:`-d`,
786 :option:`--latest`/:option:`-L` added
787
788 .. versionchanged:: 4.3
789 Options :option:`--starts-with`/:option:`-S`,
790 :option:`--contains`/:option:`-C`, :option:`--indepth`,
791 :option:`--no-indepth` added
792
793 .. versionchanged:: 4.5
794 Option :option:`--json`/:option:`-j` added
795
796 .. versionchanged:: 4.6
797 Option :option:`--all`/:option:`-a` added
798
799 .. versionchanged:: 4.7
800 *Key* section added at end of output
801
802 .. versionchanged:: 4.7
803 Option :option:`--output`/:option:`-o` added, compatible with regular
804 and terse output modes
805
806 .. versionchanged:: 5.3
807 Module variants may be reported if defined in avail output
808 configuration
809
810 .. versionchanged:: 5.3
811 *pattern* may include variant specification or extra specifier to
812 filter results
813
814 .. versionchanged:: 5.6
815 Results from a multi *pattern* search are consolidated under a single
816 output
817
818 .. subcmd:: cachebuild [modulepath...]
819
820 Build module cache file for designated modulepaths. If no argument is
821 provided cache file is built for every modulepath currently enabled. Cache
822 file creation is skipped for modulepaths where user cannot write in.
823
824 The name and content of every readable modulefiles and rc files are recorded
825 into cache file. Also last modification time of modulefiles and invalid
826 modulefile error messages are recorded. With all these information, the sole
827 cache file is evaluated to know what is available within modulepath.
828
829 See :ref:`Module cache` section for more details on module cache mechanism.
830
831 .. only:: html
832
833 .. versionadded:: 5.3
834
835 .. subcmd:: cacheclear
836
837 Delete module cache file in every modulepath currently enabled. If user
838 cannot write in a modulepath directory, cache file deletion is skipped for
839 this modulepath.
840
841 See :ref:`Module cache` section for more details on module cache mechanism.
842
843 .. only:: html
844
845 .. versionadded:: 5.3
846
847 .. subcmd:: clear [-f]
848
849 Force the Modules package to believe that no modules are currently loaded. A
850 confirmation is requested if command-line switch :option:`-f` (or
851 :option:`--force`) is not passed. Typed confirmation should equal to ``yes``
852 or ``y`` in order to proceed.
853
854 .. only:: html
855
856 .. versionadded:: 4.3
857 :subcmd:`clear` support was dropped on version `4.0` but reintroduced
858 starting version `4.3`.
859
860 .. subcmd:: config [--dump-state|name [value]|--reset name]
861
862 Gets or sets :file:`modulecmd.tcl` options. Reports the currently set value
863 of passed option *name* or all existing options if no *name* passed. If a
864 *name* and a *value* are provided, the value of option *name* is set to
865 *value*. If command-line switch ``--reset`` is passed in addition to a
866 *name*, overridden value for option *name* is cleared.
867
868 When a reported option value differs from default value a mention is added
869 to indicate whether the overridden value is coming from a command-line switch
870 (``cmd-line``) or from an environment variable (``env-var``). When a reported
871 option value is locked and cannot be altered a (``locked``) mention is added.
872
873 If no value is currently set for an option *name*, the mention ``<undef>`` is
874 reported.
875
876 For options whose value is a colon-separated list, *value* may be prefixed by
877 ``+`` or ``-`` character. It indicates respectively to append it to or
878 subtract it from current option value.
879
880 When command-line switch ``--dump-state`` is passed, current
881 :file:`modulecmd.tcl` state and Modules-related environment variables are
882 reported in addition to currently set :file:`modulecmd.tcl` options.
883
884 Existing option *names* are:
885
886 .. mconfig:: abort_on_error
887
888 List of module sub-commands that abort evaluation sequence when an error is
889 raised by an evaluated module. Evaluations already performed are withdrawn
890 and remaining modules to evaluate are skipped.
891
892 This configuration option can be changed at installation time with
893 :instopt:`--with-abort-on-error` option. The
894 :envvar:`MODULES_ABORT_ON_ERROR` environment variable is defined by
895 :subcmd:`config` sub-command when changing this configuration option from
896 its default value. See :envvar:`MODULES_ABORT_ON_ERROR` description for
897 details.
898
899 .. only:: html
900
901 .. versionadded:: 5.4
902
903 .. mconfig:: advanced_version_spec
904
905 Advanced module version specification to finely select modulefiles.
906
907 Default value is ``1``. It can be changed at installation time with
908 :instopt:`--disable-advanced-version-spec<--enable-advanced-version-spec>`
909 option. The :envvar:`MODULES_ADVANCED_VERSION_SPEC` environment variable is
910 defined by :subcmd:`config` sub-command when changing this configuration
911 option from its default value. See :envvar:`MODULES_ADVANCED_VERSION_SPEC`
912 description for details.
913
914 .. only:: html
915
916 .. versionadded:: 4.4
917
918 .. mconfig:: auto_handling
919
920 Automated module handling mode.
921
922 Default value is ``1``. It can be changed at installation time with
923 :instopt:`--disable-auto-handling<--enable-auto-handling>` option. The
924 :envvar:`MODULES_AUTO_HANDLING` environment variable is defined by
925 :subcmd:`config` sub-command when changing this configuration option from
926 its default value. The :option:`--auto` and :option:`--no-auto`
927 command line switches change the value of this configuration option. See
928 :envvar:`MODULES_AUTO_HANDLING` description for details.
929
930 .. mconfig:: avail_indepth
931
932 :subcmd:`avail` sub-command in depth search mode.
933
934 Default value is ``1``. It can be changed at installation time with
935 :instopt:`--disable-avail-indepth<--enable-avail-indepth>` option. The
936 :envvar:`MODULES_AVAIL_INDEPTH` environment variable is defined by
937 :subcmd:`config` sub-command when changing this configuration option from
938 its default value. The :option:`--indepth` and :option:`--no-indepth`
939 command line switches change the value of this configuration option. See
940 :envvar:`MODULES_AVAIL_INDEPTH` description for details.
941
942 .. mconfig:: avail_output
943
944 Content to report in addition to module names on :subcmd:`avail` sub-command
945 regular output mode.
946
947 Default value is ``modulepath:alias:dirwsym:sym:tag:variantifspec:key``. It
948 can be changed at installation time with :instopt:`--with-avail-output`
949 option. The :envvar:`MODULES_AVAIL_OUTPUT` environment variable is defined
950 by :subcmd:`config` sub-command when changing this configuration option from
951 its default value. The :option:`--output`/:option:`-o` command line switches
952 change the value of this configuration option. See
953 :envvar:`MODULES_AVAIL_OUTPUT` description for details.
954
955 .. only:: html
956
957 .. versionadded:: 4.7
958
959 .. mconfig:: avail_terse_output
960
961 Content to report in addition to module names on :subcmd:`avail` sub-command
962 terse output mode.
963
964 Default value is ``modulepath:alias:dirwsym:sym:tag:variantifspec``. It can
965 be changed at installation time with :instopt:`--with-avail-terse-output`
966 option. The :envvar:`MODULES_AVAIL_TERSE_OUTPUT` environment variable is
967 defined by :subcmd:`config` sub-command when changing this configuration
968 option from its default value. The :option:`--output`/:option:`-o` command
969 line switches change the value of this configuration option. See
970 :envvar:`MODULES_AVAIL_TERSE_OUTPUT` description for details.
971
972 .. only:: html
973
974 .. versionadded:: 4.7
975
976 .. mconfig:: cache_buffer_bytes
977
978 Size of the buffer used when reading or writing cache files.
979
980 Default value is ``32768``. Values between 4096 and 1000000 are accepted.
981 The :envvar:`MODULES_CACHE_BUFFER_BYTES` environment variable is defined by
982 :subcmd:`config` sub-command when changing this configuration option from
983 its default value.
984
985 .. only:: html
986
987 .. versionadded:: 5.3
988
989 .. mconfig:: cache_expiry_secs
990
991 Number of seconds a cache file is considered valid after being generated.
992
993 Default value is ``0``. Values between 0 and 31536000 are accepted.
994 The :envvar:`MODULES_CACHE_EXPIRY_SECS` environment variable is defined by
995 :subcmd:`config` sub-command when changing this configuration option from
996 its default value.
997
998 .. only:: html
999
1000 .. versionadded:: 5.3
1001
1002 .. mconfig:: collection_pin_version
1003
1004 Register exact modulefile version in collection.
1005
1006 Default value is ``0``. The :envvar:`MODULES_COLLECTION_PIN_VERSION`
1007 environment variable is defined by :subcmd:`config` sub-command when
1008 changing this configuration option from its default value. See
1009 :envvar:`MODULES_COLLECTION_PIN_VERSION` description for details.
1010
1011 .. mconfig:: collection_pin_tag
1012
1013 Register full tag list applying to modulefiles in collection.
1014
1015 Default value is ``0``. The :envvar:`MODULES_COLLECTION_PIN_TAG`
1016 environment variable is defined by :subcmd:`config` sub-command when
1017 changing this configuration option from its default value. See
1018 :envvar:`MODULES_COLLECTION_PIN_TAG` description for details.
1019
1020 .. only:: html
1021
1022 .. versionadded:: 5.1
1023
1024 .. mconfig:: collection_target
1025
1026 Collection target which is valid for current system.
1027
1028 This configuration option is unset by default. The
1029 :envvar:`MODULES_COLLECTION_TARGET` environment variable is defined by
1030 :subcmd:`config` sub-command when changing this configuration option from
1031 its default value. See :envvar:`MODULES_COLLECTION_TARGET` description for
1032 details.
1033
1034 .. mconfig:: color
1035
1036 Colored output mode.
1037
1038 Default value is ``auto``. It can be changed at installation time with
1039 :instopt:`--disable-color<--enable-color>` option. The
1040 :envvar:`MODULES_COLOR` environment variable is defined by
1041 :subcmd:`config` sub-command when changing this configuration option from
1042 its default value. The :option:`--color` command line switches changes the
1043 value of this configuration option. See :envvar:`MODULES_COLOR` description
1044 for details.
1045
1046 .. mconfig:: colors
1047
1048 Chosen colors to highlight output items.
1049
1050 Default value is ``hi=1:db=2:tr=2:se=2:er=91:wa=93:me=95:in=94:mp=1;94:di=94:al=96:va=93:sy=95:de=4:cm=92:aL=100:L=90;47:H=2:F=41:nF=31;43:S=46:sS=44:kL=30;48;5;109:W=30;43``.
1051 It can be changed at installation time with
1052 :instopt:`--with-dark-background-colors` or
1053 :instopt:`--with-light-background-colors` options in conjunction with
1054 :instopt:`--with-terminal-background`. The :envvar:`MODULES_COLORS`
1055 environment variable is defined by :subcmd:`config` sub-command when
1056 changing this configuration option from its default value. See
1057 :envvar:`MODULES_COLORS` description for details.
1058
1059 .. mconfig:: conflict_unload
1060
1061 Automated unload of conflicting modules when loading a module. This
1062 mechanism is part of the :ref:`automated module handling
1063 mode<MODULES_AUTO_HANDLING>` and also requires enablement of
1064 :mconfig:`auto_handling` configuration option.
1065
1066 Default value is ``0``. It can be changed at installation time with
1067 :instopt:`--enable-conflict-unload` option. The
1068 :envvar:`MODULES_CONFLICT_UNLOAD` environment variable is defined by
1069 :subcmd:`config` sub-command when changing this configuration option from
1070 its default value. See :envvar:`MODULES_CONFLICT_UNLOAD` description for
1071 details.
1072
1073 .. only:: html
1074
1075 .. versionadded:: 5.5
1076
1077 .. mconfig:: contact
1078
1079 Modulefile contact address.
1080
1081 Default value is ``root@localhost``. The :envvar:`MODULECONTACT` environment
1082 variable is defined by :subcmd:`config` sub-command when changing this
1083 configuration option from its default value. See :envvar:`MODULECONTACT`
1084 description for details.
1085
1086 .. mconfig:: extended_default
1087
1088 Allow partial module version specification.
1089
1090 Default value is ``1``. It can be changed at installation time with
1091 :instopt:`--disable-extended-default<--enable-extended-default>` option. The
1092 :envvar:`MODULES_EXTENDED_DEFAULT` environment variable is defined by
1093 :subcmd:`config` sub-command when changing this configuration option from
1094 its default value. See :envvar:`MODULES_EXTENDED_DEFAULT` description for
1095 details.
1096
1097 .. only:: html
1098
1099 .. versionadded:: 4.4
1100
1101 .. mconfig:: editor
1102
1103 Text editor command to open modulefile with through :subcmd:`edit`
1104 sub-command.
1105
1106 Default value is ``vi``. It can be changed at installation time with
1107 :instopt:`--with-editor` option. The :envvar:`MODULES_EDITOR` environment
1108 variable is defined by :subcmd:`config` sub-command when changing this
1109 configuration option from its default value. See :envvar:`MODULES_EDITOR`
1110 description for details.
1111
1112 .. only:: html
1113
1114 .. versionadded:: 4.8
1115
1116 .. mconfig:: extra_siteconfig
1117
1118 Additional site-specific configuration script location. See
1119 :ref:`Site-specific configuration` section for details.
1120
1121
1122 This configuration option is unset by default. The
1123 :envvar:`MODULES_SITECONFIG` environment variable is defined by
1124 :subcmd:`config` sub-command when changing this configuration option from
1125 its default value. See :envvar:`MODULES_SITECONFIG` description for details.
1126
1127 .. mconfig:: hide_auto_loaded
1128
1129 Tag automatically loaded modules ``hidden-loaded``
1130
1131 Default is ``0``. The :envvar:`MODULES_HIDE_AUTO_LOADED` environment
1132 variable is defined by :subcmd:`config` sub-command when changing this
1133 configuration option from its default value.
1134
1135 .. only:: html
1136
1137 .. versionadded:: 5.5
1138
1139 .. mconfig:: home
1140
1141 Location of Modules package main directory.
1142
1143 Default value is |file prefix|. It can be changed at installation time with
1144 :instopt:`--prefix` or :instopt:`--with-moduleshome` options. The
1145 :envvar:`MODULESHOME` environment variable is defined by :subcmd:`config`
1146 sub-command when changing this configuration option from its default value.
1147 See :envvar:`MODULESHOME` description for details.
1148
1149 .. only:: html
1150
1151 .. versionadded:: 4.4
1152
1153 .. mconfig:: icase
1154
1155 Enable case insensitive match.
1156
1157 Default value is ``search``. It can be changed at installation time with
1158 :instopt:`--with-icase` option. The :envvar:`MODULES_ICASE` environment
1159 variable is defined by :subcmd:`config` sub-command when changing this
1160 configuration option from its default value. The
1161 :option:`--icase`/:option:`-i` command line switches change the value of
1162 this configuration option. See :envvar:`MODULES_ICASE` description for
1163 details.
1164
1165 .. only:: html
1166
1167 .. versionadded:: 4.4
1168
1169 .. mconfig:: ignore_cache
1170
1171 Ignore module cache.
1172
1173 Default is ``0``. The :envvar:`MODULES_IGNORE_CACHE` environment variable
1174 is defined by :subcmd:`config` sub-command when changing this configuration
1175 option from its default value. The :option:`--ignore-cache` command line
1176 switch changes the value of this configuration option.
1177
1178 .. only:: html
1179
1180 .. versionadded:: 5.3
1181
1182 .. mconfig:: ignore_user_rc
1183
1184 Skip evaluation of user-specific module rc file (:file:`$HOME/.modulerc`).
1185
1186 Default is ``0``. The :envvar:`MODULES_IGNORE_USER_RC` environment variable
1187 is defined by :subcmd:`config` sub-command when changing this configuration
1188 option from its default value. The :option:`--ignore-user-rc` command line
1189 switch changes the value of this configuration option.
1190
1191 .. only:: html
1192
1193 .. versionadded:: 5.3
1194
1195 .. mconfig:: ignored_dirs
1196
1197 Directories ignored when looking for modulefiles.
1198
1199 Default value is ``CVS RCS SCCS .svn .git .SYNC .sos``. The value of this
1200 option cannot be altered.
1201
1202 .. mconfig:: implicit_default
1203
1204 Set an implicit default version for modules.
1205
1206 Default value is ``1``. It can be changed at installation time with
1207 :instopt:`--disable-implicit-default<--enable-implicit-default>` option. The
1208 :envvar:`MODULES_IMPLICIT_DEFAULT` environment variable is defined by
1209 :subcmd:`config` sub-command when changing this configuration option from
1210 its default value. See :envvar:`MODULES_IMPLICIT_DEFAULT` description for
1211 details.
1212
1213 .. mconfig:: implicit_requirement
1214
1215 Implicitly define a requirement onto modules specified on :mfcmd:`module`
1216 commands in modulefile.
1217
1218 Default value is ``1``. It can be changed at installation time with
1219 :instopt:`--disable-implicit-requirement<--enable-implicit-requirement>`
1220 option. The :envvar:`MODULES_IMPLICIT_REQUIREMENT` environment variable is
1221 defined by :subcmd:`config` sub-command when changing this configuration
1222 option from its default value. See :envvar:`MODULES_IMPLICIT_REQUIREMENT`
1223 description for details.
1224
1225 .. only:: html
1226
1227 .. versionadded:: 4.7
1228
1229 .. mconfig:: list_output
1230
1231 Content to report in addition to module names on :subcmd:`list` sub-command
1232 regular output mode.
1233
1234 Default value is ``header:idx:variant:sym:tag:key``. It can be changed at
1235 installation time with :instopt:`--with-list-output` option. The
1236 :envvar:`MODULES_LIST_OUTPUT` environment variable is defined by
1237 :subcmd:`config` sub-command when changing this configuration option from
1238 its default value. The :option:`--output`/:option:`-o` command line switches
1239 change the value of this configuration option. See
1240 :envvar:`MODULES_LIST_OUTPUT` description for details.
1241
1242 .. only:: html
1243
1244 .. versionadded:: 4.7
1245
1246 .. mconfig:: list_terse_output
1247
1248 Content to report in addition to module names on :subcmd:`list` sub-command
1249 terse output mode.
1250
1251 Default value is ``header``. It can be changed at installation time with
1252 :instopt:`--with-list-terse-output` option. The
1253 :envvar:`MODULES_LIST_TERSE_OUTPUT` environment variable is defined by
1254 :subcmd:`config` sub-command when changing this configuration option from
1255 its default value. The :option:`--output`/:option:`-o` command line switches
1256 change the value of this configuration option. See
1257 :envvar:`MODULES_LIST_TERSE_OUTPUT` description for details.
1258
1259 .. only:: html
1260
1261 .. versionadded:: 4.7
1262
1263 .. mconfig:: locked_configs
1264
1265 Configuration options that cannot be superseded. All options referred in
1266 :mconfig:`locked_configs` value are locked, thus their value cannot be
1267 altered.
1268
1269 This configuration option is set to an empty value by default. It can be
1270 changed at installation time with :instopt:`--with-locked-configs` option.
1271 The value of this option cannot be altered.
1272
1273 .. mconfig:: logged_events
1274
1275 List of the events to log.
1276
1277 This configuration option is set to an empty value by default. It can be
1278 changed at installation time with :instopt:`--with-logged-events` option.
1279 The :envvar:`MODULES_LOGGED_EVENTS` environment variable is defined by
1280 :subcmd:`config` sub-command when changing this configuration option from
1281 its default value. See :envvar:`MODULES_LOGGED_EVENTS` description for
1282 details.
1283
1284 .. only:: html
1285
1286 .. versionadded:: 5.5
1287
1288 .. mconfig:: logger
1289
1290 Command to log messages.
1291
1292 Default value is ``logger -t modules``. It can be changed at installation
1293 time with :instopt:`--with-logger` and :instopt:`--with-logger-opts`
1294 options. The :envvar:`MODULES_LOGGER` environment variable is defined by
1295 :subcmd:`config` sub-command when changing this configuration option from
1296 its default value. See :envvar:`MODULES_LOGGER` description for details.
1297
1298 .. only:: html
1299
1300 .. versionadded:: 5.5
1301
1302 .. mconfig:: mcookie_check
1303
1304 Defines if the Modules magic cookie (i.e., ``#%Module`` file signature)
1305 should be checked to determine if a file is a modulefile.
1306
1307 Default value is ``always``. The :envvar:`MODULES_MCOOKIE_CHECK` environment
1308 variable is defined by :subcmd:`config` sub-command when changing this
1309 configuration option from its default value. See
1310 :envvar:`MODULES_MCOOKIE_CHECK` description for details.
1311
1312 .. only:: html
1313
1314 .. versionadded:: 5.1
1315
1316 .. mconfig:: mcookie_version_check
1317
1318 Defines if the version set in the Modules magic cookie used in modulefile
1319 should be checked against the version of :file:`modulecmd.tcl` to determine
1320 if the modulefile could be evaluated or not.
1321
1322 Default value is ``1``. It can be changed at installation time with
1323 :instopt:`--disable-mcookie-version-check<--enable-mcookie-version-check>`
1324 option. The :envvar:`MODULES_MCOOKIE_VERSION_CHECK` environment variable is
1325 defined by :subcmd:`config` sub-command when changing this configuration
1326 option from its default value. See :envvar:`MODULES_MCOOKIE_VERSION_CHECK`
1327 description for details.
1328
1329 .. only:: html
1330
1331 .. versionadded:: 4.7
1332
1333 .. mconfig:: ml
1334
1335 Define :command:`ml` command at initialization time.
1336
1337 Default value is ``1``. It can be changed at installation time with
1338 :instopt:`--disable-ml<--enable-ml>` option. The :envvar:`MODULES_ML`
1339 environment variable is defined by :subcmd:`config` sub-command when
1340 changing this configuration option from its default value. See
1341 :envvar:`MODULES_ML` description for details.
1342
1343 .. only:: html
1344
1345 .. versionadded:: 4.5
1346
1347 .. mconfig:: nearly_forbidden_days
1348
1349 Set the number of days a module should be considered *nearly forbidden*
1350 prior reaching its expiry date.
1351
1352 Default value is ``14``. It can be changed at installation time with
1353 :instopt:`--with-nearly-forbidden-days` option. The
1354 :envvar:`MODULES_NEARLY_FORBIDDEN_DAYS` environment variable is defined by
1355 :subcmd:`config` sub-command when changing this configuration option from
1356 its default value. See :envvar:`MODULES_NEARLY_FORBIDDEN_DAYS` description
1357 for details.
1358
1359 .. only:: html
1360
1361 .. versionadded:: 4.6
1362
1363 .. mconfig:: pager
1364
1365 Text viewer to paginate message output.
1366
1367 Default value is ``less -eFKRX``. It can be changed at installation time
1368 with :instopt:`--with-pager` and :instopt:`--with-pager-opts` options. The
1369 :envvar:`MODULES_PAGER` environment variable is defined by :subcmd:`config`
1370 sub-command when changing this configuration option from its default value.
1371 See :envvar:`MODULES_PAGER` description for details.
1372
1373 .. mconfig:: protected_envvars
1374
1375 Prevents any modification of listed environment variables (colon `:`
1376 separator).
1377
1378 This configuration option is unset by default. The
1379 :envvar:`MODULES_PROTECTED_ENVVARS` environment variable is defined by
1380 :subcmd:`config` sub-command when changing this configuration option from
1381 its default value. See :envvar:`MODULES_PROTECTED_ENVVARS` description for
1382 details.
1383
1384 .. only:: html
1385
1386 .. versionadded:: 5.2
1387
1388 .. mconfig:: quarantine_support
1389
1390 Defines if code for quarantine mechanism support should be generated in
1391 :command:`module` shell function definition.
1392
1393 Default value is ``0``. It can be changed at installation time with
1394 :instopt:`--enable-quarantine-support` option. The
1395 :envvar:`MODULES_QUARANTINE_SUPPORT` environment variable is defined by
1396 :subcmd:`config` sub-command when changing this configuration option from
1397 its default value. See :envvar:`MODULES_QUARANTINE_SUPPORT` description for
1398 details.
1399
1400 .. only:: html
1401
1402 .. versionadded:: 5.0
1403
1404 .. mconfig:: rcfile
1405
1406 Location of global run-command file(s).
1407
1408 This configuration option is unset by default. The :envvar:`MODULERCFILE`
1409 environment variable is defined by :subcmd:`config` sub-command when
1410 changing this configuration option from its default value. See
1411 :envvar:`MODULERCFILE` description for details.
1412
1413 .. mconfig:: redirect_output
1414
1415 Control whether or not the output of module command should be redirected
1416 from stderr to stdout.
1417
1418 Default value is ``1``. The :envvar:`MODULES_REDIRECT_OUTPUT` environment
1419 variable is defined by :subcmd:`config` sub-command when changing this
1420 configuration option from its default value. The :option:`--redirect` and
1421 :option:`--no-redirect` command line switches change the value of this
1422 configuration option. See :envvar:`MODULES_REDIRECT_OUTPUT` description for
1423 details.
1424
1425 .. only:: html
1426
1427 .. versionadded:: 5.1
1428
1429 .. mconfig:: require_via
1430
1431 Consider loaded module enabling a modulepath a requirement for loaded
1432 modules stored in this modulepath.
1433
1434 Default value is ``0``. It can be changed at installation time with
1435 :instopt:`--enable-require-via` option. The :envvar:`MODULES_REQUIRE_VIA`
1436 environment variable is defined by :subcmd:`config` sub-command when
1437 changing this configuration option from its default value. See
1438 :envvar:`MODULES_REQUIRE_VIA` description for details.
1439
1440 .. only:: html
1441
1442 .. versionadded:: 5.6
1443
1444 .. mconfig:: reset_target_state
1445
1446 Control behavior of :subcmd:`reset` sub-command. Whether environment should
1447 be purged (``__purge__``), initial environment (``__init__``) or a named
1448 collection (any other value) should restored.
1449
1450 Default value is ``__init__``. The :envvar:`MODULES_RESET_TARGET_STATE`
1451 environment variable is defined by :subcmd:`config` sub-command when
1452 changing this configuration option from its default value. See
1453 :envvar:`MODULES_RESET_TARGET_STATE` description for details.
1454
1455 .. only:: html
1456
1457 .. versionadded:: 5.2
1458
1459 .. mconfig:: run_quarantine
1460
1461 Environment variables to indirectly pass to :file:`modulecmd.tcl`.
1462
1463 This configuration option is set to an empty value by default. It can be
1464 changed at installation time with :instopt:`--with-quarantine-vars` option
1465 that sets :envvar:`MODULES_RUN_QUARANTINE`. This environment variable is
1466 also defined by :subcmd:`config` sub-command when changing this
1467 configuration option. See :envvar:`MODULES_RUN_QUARANTINE` description for
1468 details.
1469
1470 .. mconfig:: search_match
1471
1472 Module search match style.
1473
1474 Default value is ``starts_with``. It can be changed at installation time
1475 with :instopt:`--with-search-match` option. The
1476 :envvar:`MODULES_SEARCH_MATCH` environment variable is defined by
1477 :subcmd:`config` sub-command when changing this configuration option from
1478 its default value. The :option:`--contains` and :option:`--starts-with`
1479 command line switches change the value of this configuration option. See
1480 :envvar:`MODULES_SEARCH_MATCH` description for details.
1481
1482 .. mconfig:: set_shell_startup
1483
1484 Ensure module command definition by setting shell startup file.
1485
1486 Default value is ``0``. It can be changed at installation time with
1487 :instopt:`--enable-set-shell-startup` option. The
1488 :envvar:`MODULES_SET_SHELL_STARTUP` environment variable is defined by
1489 :subcmd:`config` sub-command when changing this configuration option from
1490 its default value. See :envvar:`MODULES_SET_SHELL_STARTUP` description for
1491 details.
1492
1493 .. mconfig:: shells_with_ksh_fpath
1494
1495 Ensure module command is defined in ksh when it is started as a sub-shell
1496 from the listed shells.
1497
1498 This configuration option is set to an empty value by default. The
1499 :envvar:`MODULES_SHELLS_WITH_KSH_FPATH` environment variable is defined by
1500 :subcmd:`config` sub-command when changing this configuration option from
1501 its default value. See :envvar:`MODULES_SHELLS_WITH_KSH_FPATH` description
1502 for details.
1503
1504 .. only:: html
1505
1506 .. versionadded:: 4.7
1507
1508 .. mconfig:: silent_shell_debug
1509
1510 Disablement of shell debugging property for the module command. Also defines
1511 if code to silence shell debugging property should be generated in
1512 :command:`module` shell function definition.
1513
1514 Default value is ``0``. It can be changed at installation time with
1515 :instopt:`--enable-silent-shell-debug-support` option. The
1516 :envvar:`MODULES_SILENT_SHELL_DEBUG` environment variable is defined by
1517 :subcmd:`config` sub-command when changing this configuration option from
1518 its default value. See :envvar:`MODULES_SILENT_SHELL_DEBUG` description for
1519 details.
1520
1521 .. mconfig:: siteconfig
1522
1523 Primary site-specific configuration script location. See
1524 :ref:`Site-specific configuration` section for details.
1525
1526
1527 Default value is |file etcdir_siteconfig|. It can be changed at installation
1528 time with :instopt:`--prefix` or :instopt:`--etcdir` options. The value of
1529 this option cannot be altered.
1530
1531 .. mconfig:: source_cache
1532
1533 Cache content of files evaluated in modulefile through :manpage:`source(n)`
1534 Tcl command.
1535
1536 Default value is ``0``. It can be changed at installation time with
1537 :instopt:`--enable-source-cache` option. The :envvar:`MODULES_SOURCE_CACHE`
1538 environment variable is defined by :subcmd:`config` sub-command when
1539 changing this configuration option from its default value. See
1540 :envvar:`MODULES_SOURCE_CACHE` description for details.
1541
1542 .. only:: html
1543
1544 .. versionadded:: 5.4
1545
1546 .. mconfig:: spider_indepth
1547
1548 :subcmd:`spider` sub-command in depth search mode.
1549
1550 Default value is ``1``. It can be changed at installation time with
1551 :instopt:`--disable-spider-indepth<--enable-spider-indepth>` option. The
1552 :envvar:`MODULES_SPIDER_INDEPTH` environment variable is defined by
1553 :subcmd:`config` sub-command when changing this configuration option from
1554 its default value. The :option:`--indepth` and :option:`--no-indepth`
1555 command line switches change the value of this configuration option. See
1556 :envvar:`MODULES_SPIDER_INDEPTH` description for details.
1557
1558 .. only:: html
1559
1560 .. versionadded:: 5.6
1561
1562 .. mconfig:: spider_output
1563
1564 Content to report in addition to module names on :subcmd:`spider`
1565 sub-command regular output mode.
1566
1567 Default value is ``modulepath:alias:dirwsym:sym:tag:variantifspec:via:key``.
1568 It can be changed at installation time with :instopt:`--with-spider-output`
1569 option. The :envvar:`MODULES_SPIDER_OUTPUT` environment variable is defined
1570 by :subcmd:`config` sub-command when changing this configuration option from
1571 its default value. The :option:`--output`/:option:`-o` command line switches
1572 change the value of this configuration option. See
1573 :envvar:`MODULES_SPIDER_OUTPUT` description for details.
1574
1575 .. only:: html
1576
1577 .. versionadded:: 5.6
1578
1579 .. mconfig:: spider_terse_output
1580
1581 Content to report in addition to module names on :subcmd:`spider`
1582 sub-command terse output mode.
1583
1584 Default value is ``modulepath:alias:dirwsym:sym:tag:variantifspec``. It can
1585 be changed at installation time with :instopt:`--with-spider-terse-output`
1586 option. The :envvar:`MODULES_SPIDER_TERSE_OUTPUT` environment variable is
1587 defined by :subcmd:`config` sub-command when changing this configuration
1588 option from its default value. The :option:`--output`/:option:`-o` command
1589 line switches change the value of this configuration option. See
1590 :envvar:`MODULES_SPIDER_TERSE_OUTPUT` description for details.
1591
1592 .. only:: html
1593
1594 .. versionadded:: 5.6
1595
1596 .. mconfig:: sticky_purge
1597
1598 Error behavior when unloading sticky or super-sticky module during a module
1599 :subcmd:`purge`.
1600
1601 Raise an ``error`` (default) or emit a ``warning`` or be ``silent``. It can
1602 be changed at installation time with :instopt:`--with-sticky-purge` option.
1603 The :envvar:`MODULES_STICKY_PURGE` environment variable is defined by
1604 :subcmd:`config` sub-command when changing this configuration option from
1605 its default value. See :envvar:`MODULES_STICKY_PURGE` description for
1606 details.
1607
1608 .. only:: html
1609
1610 .. versionadded:: 5.4
1611
1612 .. mconfig:: tag_abbrev
1613
1614 Abbreviations to use to report module tags.
1615
1616 Default value is ``auto-loaded=aL:loaded=L:hidden=H:hidden-loaded=H:forbidden=F:nearly-forbidden=nF:sticky=S:super-sticky=sS:keep-loaded=kL:warning=W``.
1617 It can be changed at installation time with :instopt:`--with-tag-abbrev`
1618 option. The :envvar:`MODULES_TAG_ABBREV` environment variable is defined by
1619 :subcmd:`config` sub-command when changing this configuration option from
1620 its default value. See :envvar:`MODULES_TAG_ABBREV` description for details.
1621
1622 .. only:: html
1623
1624 .. versionadded:: 4.7
1625
1626 .. mconfig:: tag_color_name
1627
1628 Tags whose name should be colored instead of module name.
1629
1630 This configuration option is set to an empty value by default. It can be
1631 changed at installation time with :instopt:`--with-tag-color-name` option.
1632 The :envvar:`MODULES_TAG_COLOR_NAME` environment variable is defined by
1633 :subcmd:`config` sub-command when changing this configuration option from
1634 its default value. See :envvar:`MODULES_TAG_COLOR_NAME` description for
1635 details.
1636
1637 .. only:: html
1638
1639 .. versionadded:: 4.7
1640
1641 .. mconfig:: tcl_ext_lib
1642
1643 Modules Tcl extension library location.
1644
1645 Default value is |file libdir_tcl_ext_lib|. It can be changed at
1646 installation time with :instopt:`--prefix` or :instopt:`--libdir` options.
1647 The value of this option cannot be altered.
1648
1649 .. mconfig:: tcl_linter
1650
1651 Command to check syntax of modulefiles with through :subcmd:`lint`
1652 sub-command.
1653
1654 Default value is ``nagelfar.tcl``. It can be changed at installation time
1655 with :instopt:`--with-tcl-linter` and :instopt:`--with-tcl-linter-opts`
1656 options. The :envvar:`MODULES_TCL_LINTER` environment variable is defined by
1657 :subcmd:`config` sub-command when changing this configuration option from
1658 its default value. See :envvar:`MODULES_TCL_LINTER` description for details.
1659
1660 .. only:: html
1661
1662 .. versionadded:: 5.2
1663
1664 .. mconfig:: term_background
1665
1666 Terminal background color kind.
1667
1668 Default value is ``dark``. It can be changed at installation time with
1669 :instopt:`--with-terminal-background` option. The
1670 :envvar:`MODULES_TERM_BACKGROUND` environment variable is defined by
1671 :subcmd:`config` sub-command when changing this configuration option from
1672 its default value. See :envvar:`MODULES_TERM_BACKGROUND` description for
1673 details.
1674
1675 .. mconfig:: term_width
1676
1677 Set the width of the output.
1678
1679 Default value is ``0``. The :envvar:`MODULES_TERM_WIDTH` environment
1680 variable is defined by :subcmd:`config` sub-command when changing this
1681 configuration option from its default value. The
1682 :option:`--width`/:option:`-w` command line switches change the value of
1683 this configuration option. See :envvar:`MODULES_TERM_WIDTH` description for
1684 details.
1685
1686 .. only:: html
1687
1688 .. versionadded:: 4.7
1689
1690 .. mconfig:: unique_name_loaded
1691
1692 Only one module loaded per module name.
1693
1694 Default value is ``0``. It can be changed at installation time with
1695 :instopt:`--enable-unique-name-loaded` option. The
1696 :envvar:`MODULES_UNIQUE_NAME_LOADED` environment variable is defined by
1697 :subcmd:`config` sub-command when changing this configuration option from
1698 its default value. See :envvar:`MODULES_UNIQUE_NAME_LOADED` description for
1699 details.
1700
1701 .. only:: html
1702
1703 .. versionadded:: 5.4
1704
1705 .. mconfig:: unload_match_order
1706
1707 Unload firstly loaded or lastly loaded module matching request.
1708
1709 Default value is ``returnlast``. It can be changed at installation time with
1710 :instopt:`--with-unload-match-order` option. The
1711 :envvar:`MODULES_UNLOAD_MATCH_ORDER` environment variable is defined by
1712 :subcmd:`config` sub-command when changing this configuration option from
1713 its default value. See :envvar:`MODULES_UNLOAD_MATCH_ORDER` description for
1714 details.
1715
1716 .. mconfig:: variant_shortcut
1717
1718 Shortcut characters that could be used to specify or report module variants.
1719
1720 This configuration option is set to an empty value by default. It can be
1721 changed at installation time with :instopt:`--with-variant-shortcut` option.
1722 The :envvar:`MODULES_VARIANT_SHORTCUT` environment variable is defined by
1723 :subcmd:`config` sub-command when changing this configuration option from
1724 its default value. See :envvar:`MODULES_VARIANT_SHORTCUT` description for
1725 details.
1726
1727 .. only:: html
1728
1729 .. versionadded:: 4.8
1730
1731 .. mconfig:: verbosity
1732
1733 Module command verbosity level.
1734
1735 Default value is ``normal``. It can be changed at installation time with
1736 :instopt:`--with-verbosity` option. The :envvar:`MODULES_VERBOSITY`
1737 environment variable is defined by :subcmd:`config` sub-command when
1738 changing this configuration option from its default value. The
1739 :option:`--debug`/:option:`-D`, :option:`--silent`/:option:`-s`,
1740 :option:`--trace`/:option:`-T` and :option:`--verbose`/:option:`-v`
1741 command line switches change the value of this configuration option. See
1742 :envvar:`MODULES_VERBOSITY` description for details.
1743
1744 .. mconfig:: wa_277
1745
1746 Workaround for Tcsh history issue.
1747
1748 Default value is ``0``. It can be changed at installation time with
1749 :instopt:`--enable-wa-277` option. The :envvar:`MODULES_WA_277` environment
1750 variable is defined by :subcmd:`config` sub-command when changing this
1751 configuration option from its default value. See :envvar:`MODULES_WA_277`
1752 description for details.
1753
1754 .. only:: html
1755
1756 .. versionadded:: 4.3
1757
1758 .. versionchanged:: 5.3
1759 *Value* prefixes ``+`` and ``-`` added to append and subtract elements
1760 to list-value options
1761
1762 .. subcmd:: describe [collection]
1763
1764 See :subcmd:`saveshow`.
1765
1766 .. only:: html
1767
1768 .. versionadded:: 5.6
1769
1770 .. subcmd:: disable [collection]
1771
1772 See :subcmd:`saverm`.
1773
1774 .. only:: html
1775
1776 .. versionadded:: 5.6
1777
1778 .. subcmd:: display modulefile...
1779
1780 Display information about one or more *modulefiles*. The display sub-command
1781 will list the full path of the *modulefile* and the environment changes
1782 the *modulefile* will make if loaded. (Note: It will not display any
1783 environment changes found within conditional statements.)
1784
1785 The parameter *modulefile* may also be a symbolic modulefile name or a
1786 modulefile alias. It may also leverage a specific syntax to finely select
1787 module version (see `Advanced module version specifiers`_ section below).
1788
1789 When several *modulefiles* are passed, they are evaluated sequentially in the
1790 specified order. If one modulefile evaluation raises an error, display
1791 sequence continues.
1792
1793 .. subcmd:: edit modulefile
1794
1795 Open *modulefile* for edition with text editor command designated by the
1796 :mconfig:`editor` configuration option.
1797
1798 The parameter *modulefile* may also be a symbolic modulefile name or a
1799 modulefile alias. It may also leverage a specific syntax to finely select
1800 module version (see `Advanced module version specifiers`_ section below).
1801
1802 .. only:: html
1803
1804 .. versionadded:: 4.8
1805
1806 .. subcmd:: help [modulefile...]
1807
1808 Print the usage of each sub-command. If an argument is given, print the
1809 Module-specific help information for the *modulefile*.
1810
1811 The parameter *modulefile* may also be a symbolic modulefile name or a
1812 modulefile alias. It may also leverage a specific syntax to finely select
1813 module version (see `Advanced module version specifiers`_ section below).
1814
1815 When several *modulefiles* are passed, they are evaluated sequentially in the
1816 specified order. If one modulefile evaluation raises an error, help sequence
1817 continues.
1818
1819 .. subcmd:: info-loaded modulefile
1820
1821 Returns the names of currently loaded modules matching passed *modulefile*.
1822 Returns an empty string if passed *modulefile* does not match any loaded
1823 modules. See :mfcmd:`module-info loaded<module-info>` in the
1824 :ref:`modulefile(5)` man page for further explanation.
1825
1826 .. only:: html
1827
1828 .. versionadded:: 4.1
1829
1830 .. subcmd:: initadd modulefile...
1831
1832 Add *modulefile* to the shell's initialization file in the user's home
1833 directory. The startup files checked (in order) are:
1834
1835 C Shell
1836
1837 :file:`.modules`, :file:`.cshrc`, :file:`.csh_variables` and :file:`.login`
1838
1839 TENEX C Shell
1840
1841 :file:`.modules`, :file:`.tcshrc`, :file:`.cshrc`, :file:`.csh_variables`
1842 and :file:`.login`
1843
1844 Bourne and Korn Shells
1845
1846 :file:`.modules`, :file:`.profile`
1847
1848 GNU Bourne Again Shell
1849
1850 :file:`.modules`, :file:`.bash_profile`, :file:`.bash_login`,
1851 :file:`.profile` and :file:`.bashrc`
1852
1853 Z Shell
1854
1855 :file:`.modules`, :file:`.zshrc`, :file:`.zshenv` and :file:`.zlogin`
1856
1857 Friendly Interactive Shell
1858
1859 :file:`.modules`, :file:`.config/fish/config.fish`
1860
1861 If a ``module load`` line is found in any of these files, the *modulefiles*
1862 are appended to any existing list of *modulefiles*. The ``module load``
1863 line must be located in at least one of the files listed above for any of
1864 the :subcmd:`init<initadd>` sub-commands to work properly. If the
1865 ``module load`` line is found in multiple shell initialization files, all of
1866 the lines are changed.
1867
1868 .. subcmd:: initclear
1869
1870 Clear all of the *modulefiles* from the shell's initialization files.
1871
1872 .. subcmd:: initlist
1873
1874 List all of the *modulefiles* loaded from the shell's initialization file.
1875
1876 .. subcmd:: initprepend modulefile...
1877
1878 Does the same as :subcmd:`initadd` but prepends the given modules to the
1879 beginning of the list.
1880
1881 .. subcmd:: initrm modulefile...
1882
1883 Remove *modulefile* from the shell's initialization files.
1884
1885 .. subcmd:: initswitch modulefile1 modulefile2
1886
1887 Switch *modulefile1* with *modulefile2* in the shell's initialization files.
1888
1889 .. subcmd:: is-avail modulefile...
1890
1891 Returns a true value if any of the listed *modulefiles* exists in enabled
1892 :envvar:`MODULEPATH`. Returns a false value otherwise. See :mfcmd:`is-avail`
1893 in the :ref:`modulefile(5)` man page for further explanation.
1894
1895 The parameter *modulefile* may also be a symbolic modulefile name or a
1896 modulefile alias. It may also leverage a specific syntax to finely select
1897 module version (see `Advanced module version specifiers`_ section below).
1898
1899 .. only:: html
1900
1901 .. versionadded:: 4.1
1902
1903 .. subcmd:: is-loaded [modulefile...]
1904
1905 Returns a true value if any of the listed *modulefiles* has been loaded or if
1906 any *modulefile* is loaded in case no argument is provided. Returns a false
1907 value otherwise. See :mfcmd:`is-loaded` in the :ref:`modulefile(5)` man page
1908 for further explanation.
1909
1910 The parameter *modulefile* may also be a symbolic modulefile name or a
1911 modulefile alias. It may also leverage a specific syntax to finely select
1912 module version (see `Advanced module version specifiers`_ section below).
1913
1914 .. only:: html
1915
1916 .. versionadded:: 4.1
1917
1918 .. subcmd:: is-saved [collection...]
1919
1920 Returns a true value if any of the listed *collections* exists or if any
1921 *collection* exists in case no argument is provided. Returns a false value
1922 otherwise. See :mfcmd:`is-saved` in the :ref:`modulefile(5)` man page for
1923 further explanation.
1924
1925 .. only:: html
1926
1927 .. versionadded:: 4.1
1928
1929 .. subcmd:: is-used [directory...]
1930
1931 Returns a true value if any of the listed *directories* has been enabled in
1932 :envvar:`MODULEPATH` or if any *directory* is enabled in case no argument is
1933 provided. Returns a false value otherwise. See :mfcmd:`is-used` in the
1934 :ref:`modulefile(5)` man page for further explanation.
1935
1936 .. only:: html
1937
1938 .. versionadded:: 4.1
1939
1940 .. subcmd:: keyword [-a] [-j] string
1941
1942 See :subcmd:`search`.
1943
1944 .. subcmd:: lint [-a] [modulefile...]
1945
1946 Analyze syntax of one or more *modulefiles* with the linter command
1947 designated by the :mconfig:`tcl_linter` configuration option.
1948
1949 The parameter *modulefile* may also be a symbolic modulefile name or a
1950 modulefile alias. It may also leverage a specific syntax to finely select
1951 module version (see `Advanced module version specifiers`_ section below).
1952
1953 If no *modulefile* is specified, all the *modulefiles* and modulerc
1954 available in enabled modulepaths are analyzed as well as global rc, user rc
1955 and modulecache files . Hidden modulefiles are also analyzed when
1956 :option:`--all`/:option:`-a` option is set.
1957
1958 When :command:`nagelfar.tcl` is the selected linter command, a static Tcl
1959 syntax analysis is performed. In addition, syntax of modulefile commands are
1960 checked in these files based on their kind (global/user rc, modulerc,
1961 modulecache or modulefile).
1962
1963 .. only:: html
1964
1965 .. versionadded:: 5.2
1966
1967 .. versionchanged:: 5.6
1968 Also lint :file:`.modulecache` files
1969
1970 .. subcmd:: list [-t|-l|-j] [-a] [-o LIST] [-S|-C] [pattern...]
1971
1972 List loaded modules. If a *pattern* is given, then the loaded modules are
1973 filtered to only list those whose name matches this *pattern*. It may contain
1974 wildcard characters. *pattern* is matched in a case insensitive manner by
1975 default. If multiple *patterns* are given, loaded module has to match at
1976 least one of them to be listed.
1977
1978 Module tags applying to the loaded modules are reported along the module name
1979 they are associated to (see `Module tags`_ section).
1980
1981 Module variants selected on the loaded modules are reported along the module
1982 name they belong to (see `Module variants`_ section).
1983
1984 A *Key* section is added at the end of the output in case some elements are
1985 reported in parentheses or chevrons along module name or if some graphical
1986 rendition is made over some output elements. This *Key* section gives hints
1987 on the meaning of such elements.
1988
1989 The parameter *pattern* may also refer to a symbolic modulefile name or a
1990 modulefile alias. It may also leverage a specific syntax to finely select
1991 module version (see `Advanced module version specifiers`_ section below).
1992
1993 If *pattern* contains variant specification, loaded modules are included in
1994 results only if they match it. *pattern* may be a bare variant specification
1995 without mention of a module name.
1996
1997 .. only:: html
1998
1999 .. versionchanged:: 4.5
2000 Option :option:`--json`/:option:`-j` added
2001
2002 .. versionchanged:: 4.7
2003 Option :option:`--all`/:option:`-a` added
2004
2005 .. versionchanged:: 4.7
2006 *Key* section added at end of output
2007
2008 .. versionchanged:: 4.7
2009 Option :option:`--output`/:option:`-o` added, compatible with regular
2010 and terse output modes.
2011
2012 .. versionchanged:: 4.8
2013 Report if enabled the variants selected on loaded modules
2014
2015 .. versionchanged:: 5.1
2016 *pattern* search to filter loaded modules added
2017
2018 .. versionchanged:: 5.1
2019 Options :option:`--starts-with`/:option:`-S` and
2020 :option:`--contains`/:option:`-C` added
2021
2022 .. versionchanged:: 5.3
2023 *pattern* may include variant specification to filter results
2024
2025 .. subcmd:: load [options] modulefile...
2026
2027 Load *modulefile* into the shell environment.
2028
2029 :subcmd:`load` command accepts the following options:
2030
2031 * ``--auto|--no-auto``
2032 * ``-f|--force``
2033 * ``--tag=taglist``
2034
2035 Once loaded, the ``loaded`` module tag is associated to the loaded module. If
2036 module has been automatically loaded by another module, the ``auto-loaded``
2037 tag is associated instead (see `Module tags`_ section).
2038
2039 The parameter *modulefile* may also be a symbolic modulefile name or a
2040 modulefile alias. It may also leverage a specific syntax to finely select
2041 module version (see `Advanced module version specifiers`_ section below).
2042
2043 When several *modulefiles* are passed, they are loaded sequentially in the
2044 specified order. If one modulefile evaluation raises an error, load sequence
2045 continues: loaded modules prior the evaluation error are kept loaded and
2046 sequence is resumed with the load of remaining modulefile in list.
2047 Conversely, load sequence is aborted and already loaded modulefiles are
2048 withdrawn if :subcmd:`load` sub-command is defined in
2049 :mconfig:`abort_on_error` configuration option and :option:`--force` option
2050 is not set.
2051
2052 The :option:`--tag` option accepts a list of module tags to apply to
2053 *modulefile* once loaded. If module is already loaded, tags from *taglist*
2054 are added to the list of tags already applied to this module.
2055
2056 .. only:: html
2057
2058 .. versionchanged:: 4.2
2059 Options :option:`--auto`, :option:`--no-auto`,
2060 :option:`--force`/:option:`-f` added
2061
2062 .. versionchanged:: 5.1
2063 Option :option:`--tag` added
2064
2065 .. versionchanged:: 5.4
2066 Support for :mconfig:`abort_on_error` configuration option added
2067
2068 .. subcmd:: load-any [options] modulefile...
2069
2070 Load into the shell environment one of the *modulefile* specified. Try to
2071 load each *modulefile* specified in list from the left to the right until
2072 one got loaded or is found already loaded. Do not complain if *modulefile*
2073 cannot be found. But if its evaluation fails, an error is reported and next
2074 modulefile in list is evaluated.
2075
2076 :subcmd:`load-any` command accepts the following options:
2077
2078 * ``--auto|--no-auto``
2079 * ``-f|--force``
2080 * ``--tag=taglist``
2081
2082 Once loaded, the ``loaded`` module tag is associated to the loaded module. If
2083 module has been automatically loaded by another module, the ``auto-loaded``
2084 tag is associated instead (see `Module tags`_ section).
2085
2086 The parameter *modulefile* may also be a symbolic modulefile name or a
2087 modulefile alias. It may also leverage a specific syntax to finely select
2088 module version (see `Advanced module version specifiers`_ section below).
2089
2090 The :option:`--tag` option accepts a list of module tags to apply to
2091 *modulefile* once loaded. If module is already loaded, tags from *taglist*
2092 are added to the list of tags already applied to this module.
2093
2094 .. only:: html
2095
2096 .. versionadded:: 5.1
2097
2098 .. subcmd:: mod-to-sh [options] shell modulefile...
2099
2100 Evaluate *modulefile* and report resulting environment changes as code for
2101 *shell*.
2102
2103 :subcmd:`mod-to-sh` command accepts the following options:
2104
2105 * ``--auto|--no-auto``
2106 * ``-f|--force``
2107
2108 An attempt to load *modulefile* is made to get its environment changes. This
2109 evaluation does not change the current shell environment. Like for
2110 :subcmd:`load` sub-command, no evaluation occurs if *modulefile* is found
2111 loaded in current environment.
2112
2113 Changes made on environment variable intended for Modules private use (e.g.,
2114 :envvar:`LOADEDMODULES`, :envvar:`_LMFILES_`, ``__MODULES_*``) are ignored.
2115
2116 *Shell* could be any shell name supported by :file:`modulecmd.tcl`.
2117
2118 Produced *shell* code is returned on the message output channel by
2119 :file:`modulecmd.tcl`. Thus it is not rendered in current environment by the
2120 :command:`module` shell function.
2121
2122 :subcmd:`mod-to-sh` automatically set :mconfig:`verbosity` to the ``silent``
2123 mode, to avoid messages to mix with the produced shell code. Verbosity is not
2124 changed if set to the ``trace`` mode or any higher debugging level.
2125
2126 The parameter *modulefile* may also be a symbolic modulefile name or a
2127 modulefile alias. It may also leverage a specific syntax to finely select
2128 module version (see `Advanced module version specifiers`_ section below).
2129
2130 When several *modulefiles* are passed, they are evaluated sequentially in the
2131 specified order. If one modulefile evaluation raises an error, mod-to-sh
2132 sequence continues: environment change from modules evaluated prior the
2133 error are preserved and sequence is resumed with the evaluation of remaining
2134 modulefile in list. Conversely, mod-to-sh sequence is aborted and changes
2135 from already evaluated modules are withdrawn if :subcmd:`mod-to-sh`
2136 sub-command is defined in :mconfig:`abort_on_error` configuration option and
2137 :option:`--force` option is not set.
2138
2139 .. only:: html
2140
2141 .. versionadded:: 5.2
2142
2143 .. versionchanged:: 5.4
2144 Support for :mconfig:`abort_on_error` configuration option added
2145
2146 .. subcmd:: path modulefile
2147
2148 Print path to *modulefile*.
2149
2150 The parameter *modulefile* may also be a symbolic modulefile name or a
2151 modulefile alias. It may also leverage a specific syntax to finely select
2152 module version (see `Advanced module version specifiers`_ section below).
2153
2154 .. only:: html
2155
2156 .. versionadded:: 4.0
2157
2158 .. subcmd:: paths pattern
2159
2160 Print path of available *modulefiles* matching *pattern*.
2161
2162 The parameter *pattern* may also be a symbolic modulefile name or a
2163 modulefile alias. It may also leverage a specific syntax to finely select
2164 module version (see `Advanced module version specifiers`_ section below).
2165
2166 If *pattern* contains variant specification or :ref:`extra specifier`, the
2167 :ref:`extra match search` process is triggered to collect command information
2168 used in modulefiles. Modules are included in results only if they match
2169 *pattern* variant specification and extra specifier. *pattern* may be a bare
2170 variant specification or extra specifier without mention of a module name.
2171
2172 .. only:: html
2173
2174 .. versionadded:: 4.0
2175
2176 .. versionchanged:: 5.3
2177 *pattern* may include variant specification or extra specifier to
2178 filter results
2179
2180 .. subcmd:: prepend-path [options] variable value...
2181
2182 Prepend *value* to environment *variable*. The *variable* is a colon, or
2183 *delimiter*, separated list. See :mfcmd:`prepend-path` in the
2184 :ref:`modulefile(5)` man page for *options* description and further
2185 explanation.
2186
2187 When :subcmd:`prepend-path` is called as a module sub-command, the reference
2188 counter variable, which denotes the number of times *value* has been added to
2189 environment *variable*, is not updated unless if the ``--duplicates`` option
2190 is set.
2191
2192 .. only:: html
2193
2194 .. versionadded:: 4.1
2195
2196 .. versionchanged:: 5.0
2197 Reference counter environment variable is not updated anymore unless if
2198 the ``--duplicates`` option is set
2199
2200 .. subcmd:: purge [-f]
2201
2202 Unload all loaded *modulefiles*.
2203
2204 When the :option:`--force` option is set, also unload `sticky modules`_,
2205 modulefiles that are depended by non-unloadable modules and modulefiles
2206 raising an evaluation error.
2207
2208 If one modulefile unload evaluation raises an error, purge sequence
2209 continues: unloaded modules prior the evaluation error are kept unloaded and
2210 sequence is resumed with the unload of remaining modulefiles. Conversely,
2211 purge sequence is aborted and already unloaded modulefiles are restored if
2212 :subcmd:`purge` sub-command is defined in :mconfig:`abort_on_error`
2213 configuration option and :option:`--force` option is not set.
2214
2215 .. only:: html
2216
2217 .. versionchanged:: 4.7
2218 Option :option:`--force`/:option:`-f` added
2219
2220 .. versionchanged:: 5.4
2221 Support for :mconfig:`abort_on_error` configuration option added
2222
2223 .. subcmd:: refresh
2224
2225 Force a refresh of all non-persistent components of currently loaded modules.
2226 This should be used on derived shells where shell completions, shell aliases
2227 or shell functions need to be reinitialized but the environment variables
2228 have already been set by the currently loaded modules.
2229
2230 Loaded modules are evaluated in ``refresh`` mode following their load order.
2231 In this evaluation mode only the :mfcmd:`complete`, :mfcmd:`set-alias`,
2232 :mfcmd:`set-function` and :mfcmd:`puts` modulefile commands will produce
2233 environment changes. Other modulefile commands that produce environment
2234 changes (like :mfcmd:`setenv` or :mfcmd:`append-path`) are ignored during a
2235 ``refresh`` evaluation as their changes should already be applied.
2236
2237 Only the loaded modules defining non-persistent environment changes are
2238 evaluated in ``refresh`` mode. Such loaded modules are listed in the
2239 :envvar:`__MODULES_LMREFRESH` environment variable.
2240
2241 If one modulefile evaluation raises an error, refresh sequence continues:
2242 environment changes from refreshed modules prior the evaluation error are
2243 preserved and sequence is resumed with the refresh of remaining modulefiles.
2244
2245 .. only:: html
2246
2247 .. versionchanged:: 4.0
2248 Sub-command made as an alias of :subcmd:`reload` sub-command
2249
2250 .. versionchanged:: 5.0
2251 Behavior of version 3.2 :subcmd:`refresh` sub-command restored
2252
2253 .. versionchanged:: 5.2
2254 Only evaluate modules listed in :envvar:`__MODULES_LMREFRESH`
2255
2256 .. subcmd:: reload [-f]
2257
2258 Unload then load all loaded *modulefiles*.
2259
2260 No unload then load is performed and an error is returned if the loaded
2261 *modulefiles* have unsatisfied constraint corresponding to the
2262 :mfcmd:`prereq` and :mfcmd:`conflict` they declare.
2263
2264 When the :option:`--force` option is set, unload modulefiles anyway even if
2265 an evaluation error occurs.
2266
2267 If one modulefile load or unload evaluation raises an error, reload sequence
2268 aborts: environment changes coming from already evaluated modulefiles are
2269 withdrawn and remaining modulefile evaluations are skipped. Conversely, if
2270 :subcmd:`reload` is removed from :mconfig:`abort_on_error` configuration
2271 option list or if :option:`--force` option is set, reload sequence continues:
2272 already achieved module evaluations are kept and reload sequence is resumed
2273 with the remaining modulefiles.
2274
2275 .. only:: html
2276
2277 .. versionadded:: 4.0
2278
2279 .. versionchanged:: 5.4
2280 Support for :mconfig:`abort_on_error` configuration option added
2281
2282 .. versionchanged:: 5.4
2283 Option :option:`--force`/:option:`-f` added
2284
2285 .. subcmd:: remove-path [options] variable value...
2286
2287 Remove *value* from the colon, or *delimiter*, separated list in environment
2288 *variable*. See :mfcmd:`remove-path` in the :ref:`modulefile(5)` man page for
2289 *options* description and further explanation.
2290
2291 When :subcmd:`remove-path` is called as a module sub-command, the reference
2292 counter variable, which denotes the number of times *value* has been added to
2293 environment *variable*, is ignored and *value* is removed whatever the
2294 reference counter value set.
2295
2296 .. only:: html
2297
2298 .. versionadded:: 4.1
2299
2300 .. versionchanged:: 5.0
2301 *value* is removed whatever its reference counter value
2302
2303 .. subcmd:: reset [-f]
2304
2305 Restore initial environment, which corresponds to the loaded state after
2306 :ref:`Modules initialization<Package Initialization>`.
2307
2308 :subcmd:`reset` sub-command restores the environment definition found in
2309 :envvar:`__MODULES_LMINIT` environment variable.
2310
2311 When the :option:`--force` option is set, unload modulefiles anyway even if
2312 an evaluation error occurs.
2313
2314 :subcmd:`reset` behavior can be changed with :mconfig:`reset_target_state`.
2315 This configuration option is set by default to ``__init__``, which
2316 corresponds to the above behavior description. When set to ``__purge__``,
2317 :subcmd:`reset` performs a :subcmd:`purge` of the environment. When set to
2318 any other value, :subcmd:`reset` performs a :subcmd:`restore` of
2319 corresponding name collection.
2320
2321 .. only:: html
2322
2323 .. versionadded:: 5.2
2324
2325 .. versionchanged:: 5.4
2326 Option :option:`--force`/:option:`-f` added
2327
2328 .. subcmd:: restore [-f] [collection]
2329
2330 Restore the environment state as defined in *collection*. If *collection*
2331 name is not specified, then it is assumed to be the *default* collection if
2332 it exists, ``__init__`` special collection otherwise. If *collection* is a
2333 fully qualified path, it is restored from this location rather than from a
2334 file under the user's collection directory. If
2335 :envvar:`MODULES_COLLECTION_TARGET` is set, a suffix equivalent to the value
2336 of this variable is appended to the *collection* file name to restore.
2337
2338 If *collection* name is ``__init__``, initial environment state defined in
2339 :envvar:`__MODULES_LMINIT` environment variable is restored.
2340
2341 When restoring a *collection*, the currently set :envvar:`MODULEPATH`
2342 directory list and the currently loaded *modulefiles* are unused and
2343 unloaded then used and loaded to exactly match the :envvar:`MODULEPATH` and
2344 loaded *modulefiles* lists saved in this *collection* file. The order
2345 of the paths and modulefiles set in *collection* is preserved when
2346 restoring. It means that currently loaded modules are unloaded to get
2347 the same :envvar:`LOADEDMODULES` root than collection and currently used
2348 module paths are unused to get the same :envvar:`MODULEPATH` root. Then
2349 missing module paths are used and missing modulefiles are loaded.
2350
2351 If a module, without a default version explicitly defined, is recorded in a
2352 *collection* by its bare name: loading this module when restoring the
2353 collection will fail if the configuration option :mconfig:`implicit_default`
2354 is disabled.
2355
2356 If one modulefile load or unload evaluation raises an error, restore sequence
2357 continues: environment changes from modules unloaded or loaded prior the
2358 evaluation error are preserved and sequence is resumed with the unload or
2359 load of remaining modulefiles.
2360
2361 When the :option:`--force` option is set, unload modulefiles anyway even if
2362 an evaluation error occurs.
2363
2364 .. only:: html
2365
2366 .. versionadded:: 4.0
2367
2368 .. versionchanged:: 5.2
2369 Restore initial environment when *collection* name is ``__init__`` or
2370 when no collection name is specified and no *default* collection exists
2371
2372 .. versionchanged:: 5.4
2373 Option :option:`--force`/:option:`-f` added
2374
2375 .. subcmd:: rm [--auto|--no-auto] [-f] modulefile...
2376
2377 See :subcmd:`unload`.
2378
2379 .. subcmd:: save [collection]
2380
2381 Record the currently set :envvar:`MODULEPATH` directory list and the
2382 currently loaded *modulefiles* in a *collection* file under the user's
2383 collection directory :file:`$HOME/.module`. If *collection* name is not
2384 specified, then it is assumed to be the ``default`` collection. If
2385 *collection* is a fully qualified path, it is saved at this location rather
2386 than under the user's collection directory.
2387
2388 If :envvar:`MODULES_COLLECTION_TARGET` is set, a suffix equivalent to the
2389 value of this variable will be appended to the *collection* file name.
2390
2391 By default, if a loaded modulefile corresponds to the explicitly defined
2392 default module version, the bare module name is recorded. If the
2393 configuration option :mconfig:`implicit_default` is enabled, the bare module
2394 name is also recorded for the implicit default module version. If
2395 :envvar:`MODULES_COLLECTION_PIN_VERSION` is set to ``1``, module version is
2396 always recorded even if it is the default version.
2397
2398 By default, only the module tags specifically set with the :option:`--tag`
2399 option or resulting from a specific module state (like ``auto-loaded`` and
2400 ``keep-loaded`` tags) are recorded in collection. If
2401 :envvar:`MODULES_COLLECTION_PIN_TAG` is set to ``1``, all tags are recorded
2402 in collection except ``nearly-forbidden`` tag.
2403
2404 No *collection* is recorded and an error is returned if the loaded
2405 *modulefiles* have unsatisfied constraint corresponding to the
2406 :mfcmd:`prereq` and :mfcmd:`conflict` they declare.
2407
2408 .. only:: html
2409
2410 .. versionadded:: 4.0
2411
2412 .. subcmd:: savelist [-t|-l|-j] [-a] [-S|-C] [pattern...]
2413
2414 List collections that are currently saved under the user's collection
2415 directory. If :envvar:`MODULES_COLLECTION_TARGET` is set, only collections
2416 matching the target suffix will be displayed unless if the
2417 :option:`--all`/:option:`-a` option is set.
2418
2419 If a *pattern* is given, then the collections are filtered to only list
2420 those whose name matches this *pattern*. It may contain wildcard characters.
2421 *pattern* is matched in a case insensitive manner by default. If multiple
2422 *patterns* are given, collection has to match at least one of them to be
2423 listed.
2424
2425 Stash collections are not listed unless if the :option:`--all`/:option:`-a`
2426 option is set. Stash collections can be listed with :subcmd:`stashlist`
2427 sub-command.
2428
2429 .. only:: html
2430
2431 .. versionadded:: 4.0
2432
2433 .. versionchanged:: 4.5
2434 Option :option:`--json`/:option:`-j` added
2435
2436 .. versionchanged:: 5.2
2437 *pattern* search to filter collections added
2438
2439 .. versionchanged:: 5.2
2440 Options :option:`--starts-with`/:option:`-S`,
2441 :option:`--contains`/:option:`-C` and :option:`--all`/:option:`-a`
2442 added
2443
2444 .. subcmd:: saverm [collection]
2445
2446 Delete the *collection* file under the user's collection directory. If
2447 *collection* name is not specified, then it is assumed to be the *default*
2448 collection. If :envvar:`MODULES_COLLECTION_TARGET` is set, a suffix
2449 equivalent to the value of this variable will be appended to the *collection*
2450 file name.
2451
2452 .. only:: html
2453
2454 .. versionadded:: 4.0
2455
2456 .. subcmd:: saveshow [collection]
2457
2458 Display the content of *collection*. If *collection* name is not specified,
2459 then it is assumed to be the *default* collection if it exists, ``__init__``
2460 special collection otherwise. If *collection* is a fully qualified path, this
2461 location is displayed rather than a collection file under the user's
2462 collection directory. If :envvar:`MODULES_COLLECTION_TARGET` is set, a suffix
2463 equivalent to the value of this variable will be appended to the *collection*
2464 file name.
2465
2466 If *collection* name is ``__init__``, initial environment content defined in
2467 :envvar:`__MODULES_LMINIT` environment variable is displayed.
2468
2469 .. only:: html
2470
2471 .. versionadded:: 4.0
2472
2473 .. versionchanged:: 5.2
2474 Display content of initial environment when *collection* name is
2475 ``__init__`` or when no collection name is specified and no *default*
2476 collection exists
2477
2478 .. subcmd:: search [-a] [-j] string
2479
2480 Seeks through the :mfcmd:`module-whatis` information of all *modulefiles*
2481 for the specified *string*. All *module-whatis* information matching the
2482 *string* in a case insensitive manner will be displayed. *string* may contain
2483 wildcard characters.
2484
2485 .. only:: html
2486
2487 .. versionadded:: 4.0
2488 Prior version `4.0` :mfcmd:`module-whatis` information search was
2489 performed with :subcmd:`apropos` or :subcmd:`keyword` sub-commands.
2490
2491 .. versionchanged:: 4.5
2492 Option :option:`--json`/:option:`-j` added
2493
2494 .. versionchanged:: 4.6
2495 Option :option:`--all`/:option:`-a` added
2496
2497 .. subcmd:: sh-to-mod shell script [arg...]
2498
2499 Evaluate with *shell* the designated *script* with defined *arguments* to
2500 find out the environment changes it does. Environment prior and after
2501 *script* evaluation are compared to determine these changes. They are
2502 translated into *modulefile* commands to output the modulefile content
2503 equivalent to the evaluation of shell script.
2504
2505 Changes on environment variables, shell aliases, shell functions, shell
2506 completions and current working directory are tracked.
2507
2508 Changes made on environment variable intended for Modules private use (e.g.,
2509 :envvar:`LOADEDMODULES`, :envvar:`_LMFILES_`, ``__MODULES_*``) are ignored.
2510
2511 *Shell* could be specified as a command name or a fully qualified pathname.
2512 The following shells are supported: sh, dash, csh, tcsh, bash, ksh, ksh93,
2513 zsh and fish.
2514
2515 *Shell* could also be set to ``bash-eval``. In this mode, bash shell *script*
2516 is not sourced but the output resulting from its execution is evaluated to
2517 determine the environment changes it does.
2518
2519 .. only:: html
2520
2521 .. versionadded:: 4.6
2522
2523 .. versionchanged:: 5.1
2524 Changes on Modules private environment variable are ignored
2525
2526 .. versionchanged:: 5.1
2527 Support for tracking shell completion changes on bash, tcsh and fish
2528 shells added
2529
2530 .. versionchanged:: 5.4
2531 Support for ``bash-eval`` shell mode added
2532
2533 .. subcmd:: show modulefile...
2534
2535 See :subcmd:`display`.
2536
2537 .. subcmd:: source [options] modulefile...
2538
2539 Execute *modulefile* into the shell environment. Once executed *modulefile*
2540 is not marked loaded in shell environment which differ from :subcmd:`load`
2541 sub-command.
2542
2543 :subcmd:`source` command accepts the following options:
2544
2545 * ``--auto|--no-auto``
2546 * ``-f|--force``
2547
2548 If *modulefile* corresponds to a fully qualified path, this file is executed.
2549 Otherwise *modulefile* is searched among the available modulefiles.
2550
2551 The parameter *modulefile* may also be a symbolic modulefile name or a
2552 modulefile alias. It may also leverage a specific syntax to finely select
2553 module version (see `Advanced module version specifiers`_ section below).
2554
2555 When several *modulefiles* are passed, they are evaluated sequentially in the
2556 specified order. If one modulefile evaluation raises an error, source
2557 sequence continues: environment changes from modules sourced prior the
2558 evaluation error are preserved and sequence is resumed with the source of
2559 remaining modulefile in list.
2560
2561 .. only:: html
2562
2563 .. versionadded:: 4.0
2564
2565 .. versionchanged:: 5.2
2566 Accept modulefile specification as argument
2567
2568 .. subcmd:: spider [-d|-L] [-t|-l|-j] [-a] [-o LIST] [-S|-C] [--indepth|--no-indepth] [pattern...]
2569
2570 List all available *modulefiles* found in enabled modulepaths and recursively
2571 found in modulepaths enabled by available *modulefiles*.
2572
2573 :subcmd:`spider` sub-command first performs an :ref:`extra match search` to
2574 get all modulepaths to look at. These modulepaths are collected from the
2575 directory arguments set to the :mfcmd:`module use<module>`,
2576 :mfcmd:`append-path MODULEPATH<append-path>` or :mfcmd:`prepend-path
2577 MODULEPATH<prepend-path>` modulefile commands. Collecting modulepaths is
2578 first achieved in the global/user rc section and modulepaths defined in
2579 :envvar:`MODULEPATH` then in each modulepath collected from modulefiles, and
2580 so on. As collecting modulepaths implies evaluating every available
2581 modulefiles, it is advised to build and use :ref:`Module cache` to improve
2582 search speed.
2583
2584 Once modulepaths are gathered, :subcmd:`spider` proceeds and reports like
2585 :subcmd:`avail` sub-command. The same set of options are supported.
2586
2587 If a *pattern* argument is given, then each collected modulepath is searched
2588 for *modulefiles* whose pathname, symbolic version-name or alias
2589 match *pattern* in a case insensitive manner by default. *pattern* may
2590 contain wildcard characters.i
2591
2592 Symbolic version-names and aliases found in the search are displayed in the
2593 result of this sub-command. Symbolic version-names are displayed next to
2594 the *modulefile* they are assigned to within parenthesis. Aliases are listed
2595 in the modulepath section where they have been defined. To distinguish
2596 aliases from *modulefiles* a ``@`` symbol is added within parenthesis next to
2597 their name. Aliases defined through a global or user specific module RC file
2598 are listed under the **global/user modulerc** section.
2599
2600 When colored output is enabled and a specific graphical rendition is defined
2601 for module *default* version, the ``default`` symbol is omitted and instead
2602 the defined graphical rendition is applied to the relative modulefile. When
2603 colored output is enabled and a specific graphical rendition is defined for
2604 module alias, the ``@`` symbol is omitted. The defined graphical rendition
2605 applies to the module alias name. See :envvar:`MODULES_COLOR` and
2606 :envvar:`MODULES_COLORS` sections for details on colored output.
2607
2608 Module tags applying to the available *modulefiles* returned by the
2609 :subcmd:`spider` sub-command are reported along the module name they are
2610 associated to (see `Module tags`_ section).
2611
2612 Module variants and their available values may be reported along the module
2613 name they belong to (see `Module variants`_ section) if defined in spider
2614 output configuration option (see :option:`--output`/:option:`-o` option). The
2615 :ref:`extra match search` process is triggered to collect variant
2616 information.
2617
2618 A *Key* section is added at the end of the output in case some elements are
2619 reported in parentheses or chevrons along module name or if some graphical
2620 rendition is made over some output elements. This *Key* section gives hints
2621 on the meaning of such elements.
2622
2623 The parameter *pattern* may also refer to a symbolic modulefile name or a
2624 modulefile alias. It may also leverage a specific syntax to finely select
2625 module version (see `Advanced module version specifiers`_ section below).
2626
2627 If *pattern* contains variant specification or :ref:`extra specifier`, the
2628 :ref:`extra match search` process is triggered to collect command information
2629 used in modulefiles. Modules are included in results only if they match
2630 *pattern* variant specification and extra specifier. *pattern* may be a bare
2631 variant specification or extra specifier without mention of a module name.
2632
2633 When several *patterns* are provided all modulefiles matching at least one of
2634 these *patterns* are listed.
2635
2636 .. only:: html
2637
2638 .. versionadded:: 5.6
2639
2640 .. subcmd:: stash [-f]
2641
2642 :subcmd:`Save<save>` current environment in a stash collection then
2643 :subcmd:`reset` to initial environment.
2644
2645 A collection is created only if current environment state differs from
2646 initial environment. Stash collection is named
2647 *stash-<unix_millis_timestamp>* where *<unix_millis_timestamp>* is the number
2648 of milliseconds between Unix Epoch and when this command is run.
2649
2650 If :envvar:`MODULES_COLLECTION_TARGET` is set, a suffix equivalent to the
2651 value of this variable will be appended to the stash collection file name.
2652
2653 When the :option:`--force` option is set, unload modulefiles anyway even if
2654 an evaluation error occurs.
2655
2656 .. only:: html
2657
2658 .. versionadded:: 5.2
2659
2660 .. versionchanged:: 5.4
2661 Option :option:`--force`/:option:`-f` added
2662
2663 .. subcmd:: stashclear
2664
2665 Remove all stash collection files of current :mconfig:`collection_target`. If
2666 no collection target is currently set, remove stash collection files without
2667 a target suffix.
2668
2669 .. only:: html
2670
2671 .. versionadded:: 5.2
2672
2673 .. subcmd:: stashlist [-t|-l|-j]
2674
2675 List all stash collection files of current :mconfig:`collection_target`. If
2676 no collection target is currently set, list stash collection files without a
2677 target suffix.
2678
2679 .. only:: html
2680
2681 .. versionadded:: 5.2
2682
2683 .. subcmd:: stashpop [-f] [stash]
2684
2685 :subcmd:`Restore<restore>` *stash* collection then delete corresponding
2686 collection file.
2687
2688 *stash* is either a full stash collection name (i.e.,
2689 *stash-<unix_millis_timestamp>*) or a stash index. Most recent stash
2690 collection has index *0*, *1* is the one before it. When no *stash* is given
2691 the latest stash collection is assumed (that is stash index *0*).
2692
2693 If :envvar:`MODULES_COLLECTION_TARGET` is set, a suffix equivalent to the
2694 value of this variable will be appended to the stash collection file name to
2695 restore.
2696
2697 When the :option:`--force` option is set, unload modulefiles anyway even if
2698 an evaluation error occurs.
2699
2700 .. only:: html
2701
2702 .. versionadded:: 5.2
2703
2704 .. versionchanged:: 5.4
2705 Option :option:`--force`/:option:`-f` added
2706
2707 .. subcmd:: stashrm [stash]
2708
2709 :subcmd:`Remove<saverm>` *stash* collection file.
2710
2711 *stash* is either a full stash collection name (i.e.,
2712 *stash-<unix_millis_timestamp>*) or a stash index. Most recent stash
2713 collection has index *0*, *1* is the one before it. When no *stash* is given
2714 the latest stash collection is assumed (that is stash index *0*).
2715
2716 If :envvar:`MODULES_COLLECTION_TARGET` is set, a suffix equivalent to the
2717 value of this variable will be appended to the stash collection file name to
2718 delete.
2719
2720 .. only:: html
2721
2722 .. versionadded:: 5.2
2723
2724 .. subcmd:: stashshow [stash]
2725
2726 :subcmd:`Display<saveshow>` the content of *stash* collection file.
2727
2728 *stash* is either a full stash collection name (i.e.,
2729 *stash-<unix_millis_timestamp>*) or a stash index. Most recent stash
2730 collection has index *0*, *1* is the one before it. When no *stash* is given
2731 the latest stash collection is assumed (that is stash index *0*).
2732
2733 If :envvar:`MODULES_COLLECTION_TARGET` is set, a suffix equivalent to the
2734 value of this variable will be appended to the stash collection file name to
2735 display.
2736
2737 .. only:: html
2738
2739 .. versionadded:: 5.2
2740
2741 .. subcmd:: state [name]
2742
2743 Gets :file:`modulecmd.tcl` states. Reports the currently set value
2744 of passed state *name* or all existing states if no *name* passed.
2745
2746 .. only:: html
2747
2748 .. versionadded:: 5.1
2749
2750 .. subcmd:: swap [options] [modulefile1] modulefile2
2751
2752 See :subcmd:`switch`.
2753
2754 .. subcmd:: switch [options] [modulefile1] modulefile2
2755
2756 Switch loaded *modulefile1* with *modulefile2*. If *modulefile1* is not
2757 specified, it is assumed to be the currently loaded module that shares the
2758 same root name as *modulefile2*. The root name is defined as the initial part
2759 of a module name, i.e., all characters preceding the first ``/``.
2760
2761 :subcmd:`switch` command accepts the following options:
2762
2763 * ``--auto|--no-auto``
2764 * ``-f|--force``
2765 * ``--tag=taglist``
2766
2767 The parameter *modulefile* may also be a symbolic modulefile name or a
2768 modulefile alias. It may also leverage a specific syntax to finely select
2769 module version (see `Advanced module version specifiers`_ section below).
2770
2771 The :option:`--tag` option accepts a list of module tags to apply to
2772 *modulefile* once loaded. If module is already loaded, tags from *taglist*
2773 are added to the list of tags already applied to this module.
2774
2775 When the :option:`--force` option is set, unload modulefiles anyway even if
2776 an evaluation error occurs.
2777
2778 If unload evaluation of *modulefile1* raises an error, switch sequence
2779 aborts: no environment change from *modulefile1* unload is applied and load
2780 of *modulefile2* is skipped. Conversely, if ``switch_unload`` value is
2781 removed from :mconfig:`abort_on_error` configuration option list (and
2782 ``switch`` value is not set there) or if :option:`--force` option is set,
2783 switch sequence continues. If *modulefile1* is tagged ``super-sticky``,
2784 switch sequence aborts in any case.
2785
2786 If load evaluation of *modulefile2* raises an error, switch sequence
2787 continues: environment changes from *modulefile1* unload are applied but not
2788 those from failed *modulefile2* load. Conversely, whole switch sequence is
2789 aborted and unloaded *modulefile1* is restored if :subcmd:`switch`
2790 sub-command is defined in :mconfig:`abort_on_error` configuration option and
2791 :option:`--force` option is not set.
2792
2793 .. only:: html
2794
2795 .. versionchanged:: 4.2
2796 Options :option:`--auto`, :option:`--no-auto`,
2797 :option:`--force`/:option:`-f` added
2798
2799 .. versionchanged:: 5.1
2800 Option :option:`--tag` added
2801
2802 .. versionchanged:: 5.4
2803 Support for :mconfig:`abort_on_error` configuration option added
2804
2805 .. subcmd:: test modulefile...
2806
2807 Execute and display results of the Module-specific tests for the
2808 *modulefile*.
2809
2810 The parameter *modulefile* may also be a symbolic modulefile name or a
2811 modulefile alias. It may also leverage a specific syntax to finely select
2812 module version (see `Advanced module version specifiers`_ section below).
2813
2814 When several *modulefiles* are passed, they are evaluated sequentially in the
2815 specified order. If one modulefile evaluation raises an error, test sequence
2816 continues.
2817
2818 .. only:: html
2819
2820 .. versionadded:: 4.0
2821
2822 .. subcmd:: try-add [options] modulefile...
2823
2824 See :subcmd:`try-load`.
2825
2826 .. only:: html
2827
2828 .. versionadded:: 4.8
2829
2830 .. subcmd:: try-load [options] modulefile...
2831
2832 Like :subcmd:`load` sub-command, load *modulefile* into the shell
2833 environment, but do not complain if *modulefile* cannot be found. If
2834 *modulefile* is found but its evaluation fails, error is still reported.
2835
2836 :subcmd:`try-load` command accepts the following options:
2837
2838 * ``--auto|--no-auto``
2839 * ``-f|--force``
2840 * ``--tag=taglist``
2841
2842 Once loaded, the ``loaded`` module tag is associated to the loaded module. If
2843 module has been automatically loaded by another module, the ``auto-loaded``
2844 tag is associated instead (see `Module tags`_ section).
2845
2846 The parameter *modulefile* may also be a symbolic modulefile name or a
2847 modulefile alias. It may also leverage a specific syntax to finely select
2848 module version (see `Advanced module version specifiers`_ section below).
2849
2850 The :option:`--tag` option accepts a list of module tags to apply to
2851 *modulefile* once loaded. If module is already loaded, tags from *taglist*
2852 are added to the list of tags already applied to this module.
2853
2854 When several *modulefiles* are passed, they are try-loaded sequentially in
2855 the specified order. If one modulefile evaluation raises an error, try-load
2856 sequence continues: loaded modules prior the evaluation error are kept loaded
2857 and sequence is resumed with the load of remaining modulefile in list.
2858 Conversely, try-load sequence is aborted and already loaded modulefiles are
2859 withdrawn if :subcmd:`try-load` sub-command is defined in
2860 :mconfig:`abort_on_error` configuration option and :option:`--force` option
2861 is not set.
2862
2863 .. only:: html
2864
2865 .. versionadded:: 4.8
2866
2867 .. versionchanged:: 5.1
2868 Option :option:`--tag` added
2869
2870 .. versionchanged:: 5.4
2871 Support for :mconfig:`abort_on_error` configuration option added
2872
2873 .. subcmd:: unload [--auto|--no-auto] [-f] modulefile...
2874
2875 Remove *modulefile* from the shell environment.
2876
2877 The parameter *modulefile* may also be a symbolic modulefile name or a
2878 modulefile alias. It may also leverage a specific syntax to finely select
2879 module version (see `Advanced module version specifiers`_ section below).
2880
2881 When the :option:`--force` option is set, unload modulefiles anyway even if
2882 an evaluation error occurs.
2883
2884 When several *modulefiles* are passed, they are unloaded sequentially in the
2885 specified order. If one modulefile evaluation raises an error, unload
2886 sequence continues: unloaded modules prior the evaluation error are kept
2887 unloaded and sequence is resumed with the unload of remaining modulefile in
2888 list. Conversely, unload sequence is aborted and already unloaded modulefiles
2889 are restored if :subcmd:`unload` sub-command is defined in
2890 :mconfig:`abort_on_error` configuration option and :option:`--force` option
2891 is not set.
2892
2893 .. only:: html
2894
2895 .. versionchanged:: 4.2
2896 Options :option:`--auto`, :option:`--no-auto`,
2897 :option:`--force`/:option:`-f` added
2898
2899 .. versionchanged:: 5.4
2900 Support for :mconfig:`abort_on_error` configuration option added
2901
2902 .. subcmd:: unuse directory...
2903
2904 Remove one or more *directories* from the :envvar:`MODULEPATH` environment
2905 variable.
2906
2907 If :mfcmd:`module unuse<module>` is called during a modulefile evaluation,
2908 the reference counter environment variable
2909 :envvar:`__MODULES_SHARE_MODULEPATH<__MODULES_SHARE_\<VAR\>>`, which denotes
2910 the number of times *directory* has been enabled, is checked and *directory*
2911 is removed only if its relative counter is equal to 1 or not defined.
2912 Otherwise *directory* is kept and reference counter is decreased by 1. When
2913 :subcmd:`module unuse<unuse>` is called from the command-line or within an
2914 initialization modulefile script *directory* is removed whatever the
2915 reference counter value set.
2916
2917 If *directory* corresponds to the concatenation of multiple paths separated
2918 by colon character, each path is treated separately.
2919
2920 .. only:: html
2921
2922 .. versionchanged:: 5.0
2923 *directory* is removed whatever its reference counter value if
2924 :subcmd:`module unuse<unuse>` is called from the command-line or within
2925 an initialization modulefile script
2926
2927 .. versionchanged:: 5.0
2928 Accept several modulepaths passed as a single string
2929
2930 .. subcmd:: update [-f]
2931
2932 See :subcmd:`reload`.
2933
2934 .. only:: html
2935
2936 .. versionadded:: 5.6
2937
2938 .. subcmd:: use [-a|--append] directory...
2939
2940 Prepend one or more *directories* to the :envvar:`MODULEPATH` environment
2941 variable. The ``--append`` flag will append the *directory* to
2942 :envvar:`MODULEPATH`.
2943
2944 When *directory* is already defined in :envvar:`MODULEPATH`, it is not added
2945 again or moved at the end or at the beginning of the environment variable.
2946
2947 If :mfcmd:`module use<module>` is called during a modulefile evaluation, the
2948 reference counter environment variable
2949 :envvar:`__MODULES_SHARE_MODULEPATH<__MODULES_SHARE_\<VAR\>>` is also set to
2950 increase the number of times *directory* has been added to
2951 :envvar:`MODULEPATH`. Reference counter is not updated when
2952 :subcmd:`module use<use>` is called from the command-line or within an
2953 initialization modulefile script.
2954
2955 A *directory* that does not exist yet can be specified as argument and then
2956 be added to :envvar:`MODULEPATH`.
2957
2958 .. only:: html
2959
2960 .. versionchanged:: 5.0
2961 Accept non-existent modulepath
2962
2963 .. versionchanged:: 5.0
2964 Reference counter value of *directory* is not anymore increased if
2965 :subcmd:`module use<use>` is called from the command-line or within an
2966 initialization modulefile script
2967
2968 .. subcmd:: whatis [-a] [-j] [pattern...]
2969
2970 Display the information set up by the :mfcmd:`module-whatis` commands inside
2971 *modulefiles* matching *pattern*. *pattern* may contain wildcard characters.
2972 If no *pattern* is specified, all :mfcmd:`module-whatis` lines will be shown.
2973
2974 The parameter *pattern* may also be a symbolic modulefile name or a
2975 modulefile alias. It may also leverage a specific syntax to finely select
2976 module version (see `Advanced module version specifiers`_ section below).
2977
2978 If *pattern* contains variant specification or :ref:`extra specifier`, the
2979 :ref:`extra match search` process is triggered to collect command information
2980 used in modulefiles. Modules are included in results only if they match
2981 *pattern* variant specification and extra specifier. *pattern* may be a bare
2982 variant specification or extra specifier without mention of a module name.
2983
2984 .. only:: html
2985
2986 .. versionchanged:: 4.5
2987 Option :option:`--json`/:option:`-j` added
2988
2989 .. versionchanged:: 4.6
2990 Option :option:`--all`/:option:`-a` added
2991
2992 .. versionchanged:: 5.3
2993 *pattern* may include variant specification or extra specifier to
2994 filter results
2995
2996 .. versionchanged:: 5.6
2997 Results from a multi *pattern* search are consolidated under a single
2998 output
2999
3000
3001 Modulefiles
3002 ^^^^^^^^^^^
3003
3004 *modulefiles* are written in the Tool Command Language (Tcl) and are
3005 interpreted by :file:`modulecmd.tcl`. *modulefiles* can use conditional
3006 statements. Thus the effect a *modulefile* will have on the environment
3007 may change depending upon the current state of the environment.
3008
3009 Environment variables are unset when unloading a *modulefile*. Thus, it is
3010 possible to :subcmd:`load` a *modulefile* and then :subcmd:`unload` it without
3011 having the environment variables return to their prior state.
3012
3013
3014 .. _Advanced module version specifiers:
3015
3016 Advanced module version specifiers
3017 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3018
3019 When the advanced module version specifiers mechanism is enabled (see
3020 :envvar:`MODULES_ADVANCED_VERSION_SPEC`), the specification of modulefile
3021 passed on Modules sub-commands changes. After the module name a version
3022 constraint and variants may be added.
3023
3024 Version specifiers
3025 """"""""""""""""""
3026
3027 After the module name a version constraint prefixed by the ``@`` character may
3028 be added. It could be directly appended to the module name or separated from
3029 it with a space character.
3030
3031 Constraints can be expressed to refine the selection of module version to:
3032
3033 * a single version with the ``@version`` syntax, for instance ``[email protected]``
3034 syntax will select module ``foo/1.2.3``
3035 * a list of versions with the ``@version1,version2,...`` syntax, for instance
3036 ``[email protected],1.10`` will match modules ``foo/1.2.3`` and ``foo/1.10``
3037 * a range of versions with the ``@version1:``, ``@:version2`` and
3038 ``@version1:version2`` syntaxes, for instance ``[email protected]:`` will select all
3039 versions of module ``foo`` greater than or equal to ``1.2``, ``foo@:1.3``
3040 will select all versions less than or equal to ``1.3`` and ``[email protected]:1.3``
3041 matches all versions between ``1.2`` and ``1.3`` including ``1.2`` and
3042 ``1.3`` versions
3043
3044 Advanced specification of single version or list of versions may benefit from
3045 the activation of the extended default mechanism (see
3046 :envvar:`MODULES_EXTENDED_DEFAULT`) to use an abbreviated notation like ``@1``
3047 to refer to more precise version numbers like ``1.2.3``. Range of versions on
3048 its side natively handles abbreviated versions.
3049
3050 In order to be specified in a range of versions or compared to a range of
3051 versions, the version major element should corresponds to a number. For
3052 instance ``10a``, ``1.2.3``, ``1.foo`` are versions valid for range
3053 comparison whereas ``default`` or ``foo.2`` versions are invalid for range
3054 comparison.
3055
3056 Range of versions can be specified in version list, for instance
3057 ``foo@:1.2,1.4:1.6,1.8:``. Such specification helps to exclude specific
3058 versions, like versions ``1.3`` and ``1.7`` in previous example.
3059
3060 If the implicit default mechanism is also enabled (see
3061 :envvar:`MODULES_IMPLICIT_DEFAULT`), a ``default`` and ``latest`` symbolic
3062 versions are automatically defined for each module name (also at each
3063 directory level for deep *modulefiles*). These automatic version symbols are
3064 defined unless a symbolic version, alias, or regular module version already
3065 exists for these ``default`` or ``latest`` version names. Using the
3066 ``mod@latest`` (or ``mod/latest``) syntax ensures highest available version
3067 will be selected.
3068
3069 The symbolic version ``loaded`` may be used over loaded module name to
3070 designate the loaded version of the module with associated selected variants.
3071 This version symbol should be specified using the ``@`` prefix notation (e.g.,
3072 ``foo@loaded``). An error is returned if no version of designated module is
3073 currently loaded.
3074
3075 .. only:: html
3076
3077 .. versionadded:: 4.4
3078
3079 .. versionchanged:: 4.8
3080 Use of version range is allowed in version list
3081
3082 Variants
3083 """"""""
3084
3085 After the module name, variants can be specified. :ref:`Module variants` are
3086 alternative evaluation of the same *modulefile*. A variant is specified by
3087 associating a value to its name. This specification is then transmitted to the
3088 evaluating *modulefile* which instantiates the variant in the
3089 :mfvar:`ModuleVariant` array variable when reaching the :mfcmd:`variant`
3090 modulefile command declaring this variant.
3091
3092 Variant can be specified with the ``name=value`` syntax where *name* is the
3093 declared variant name and *value*, the value this variant is set to when
3094 evaluating the *modulefile*.
3095
3096 Boolean variants can be specified with the ``+name`` syntax to set this
3097 variant on and with the ``-name`` or ``~name`` syntaxes to set this variant
3098 off. The ``-name`` syntax is not supported on :ref:`ml(1)` command as the
3099 minus sign already means to unload designated module. The ``~name`` and
3100 ``+name`` syntaxes could also be defined appended to another specification
3101 word (e.g., the module name, version or another variant specification),
3102 whereas ``-name`` syntax must be the start of a new specification word.
3103
3104 Boolean variants may also be specified with the ``name=value`` syntax. *value*
3105 should be set to ``1``, ``true``, ``t``, ``yes``, ``y`` or ``on`` to enable
3106 the variant or it should be set to ``0``, ``false``, ``f``, ``no``, ``n`` or
3107 ``off`` to disable the variant.
3108
3109 Shortcuts may be used to abbreviate variant specification. The
3110 :mconfig:`variant_shortcut` configuration option associates shortcut character
3111 to variant name. With a shortcut defined, variant could be specified with the
3112 ``<shortcut>value`` syntax. For instance if character ``%`` is set as a
3113 shortcut for variant ``foo``, the ``%value`` syntax is equivalent to the
3114 ``foo=value`` syntax.
3115
3116 A variant shortcut must be of one character length and must avoid characters
3117 used for other concerns or in module names or version specifications (i.e.,
3118 *[-+~/@=:,a-zA-Z0-9]*).
3119
3120 Variant *name* should only be composed of characters part of the
3121 ``A-Za-z0-9_-`` range. Also, a variant name cannot start with ``-`` (minus)
3122 character and the overall name cannot just be a number.
3123
3124 Specific characters used in variant specification syntax cannot be used as
3125 part of the name or version of a module. These specific characters are ``+``,
3126 ``~``, ``=`` and all characters set as variant shortcut. Exception is made for
3127 ``+`` and ``~`` characters if string that follows after does not correspond to
3128 a valid variant name (e.g., *name+*, *name++*, *name/version+1*).
3129
3130 .. only:: html
3131
3132 .. versionadded:: 4.8
3133
3134 .. versionchanged:: 5.5
3135 Stricter variant name naming rule adopted
3136
3137 .. versionchanged:: 5.5
3138 ``+`` and ``~`` characters are allowed in module name or version if not
3139 followed by a valid variant name
3140
3141 .. _Extra specifier:
3142
3143 Extra specifier
3144 """""""""""""""
3145
3146 After the module name, extra specifiers can be defined in module search
3147 context. Extra specifiers are an extra query to list available modulefiles
3148 based on their content definition. They rely on the :ref:`Extra match search`
3149 mechanism that collects content of available modulefiles.
3150
3151 Extra specifier can be set with the ``element:name[,name,...]`` syntax where
3152 *element* is a Tcl modulefile command and *name* an item defined by this
3153 command. Depending on the kind of Tcl modulefile command, *name* can refer to
3154 an environment variable, a shell alias, a module specification, etc.
3155
3156 Supported extra specifier *elements* are:
3157
3158 * ``variant``, ``complete``, ``uncomplete``, ``set-alias``, ``unset-alias``,
3159 ``set-function``, ``unset-function``, ``chdir``, ``tag``
3160 * ``setenv``, ``unsetenv``, ``append-path``, ``prepend-path``, ``remove-path``
3161 and ``pushenv``: these elements related to environment variable handling may
3162 also be aliased ``envvar``
3163 * ``family`` and ``provide``: these elements related to module alias may also
3164 be aliases ``provided-alias``
3165 * ``prereq``, ``prereq-any``, ``prereq-all``, ``depends-on``,
3166 ``depends-on-any``, ``always-load``, ``load``, ``load-any``, ``try-load``,
3167 ``switch`` and ``switch-on``: these elements related to module requirement
3168 definition accept a module specification as value *name* and may be aliased
3169 ``require``
3170 * ``conflict``, ``unload``, ``switch`` and ``switch-off``: these elements
3171 related to module incompatibility definition accept a module specification
3172 as value *name* and may be aliased ``incompat``
3173 * ``use``
3174
3175 Each of the above supported *elements* corresponds to a Tcl modulefile
3176 command. ``load``, ``load-any``, ``try-load``, ``switch``, ``unload`` and
3177 ``use`` match corresponding module sub-commands. ``prereq-any`` is an alias on
3178 ``prereq``, ``depends-on-any`` and vice versa as both Tcl modulefile commands
3179 are the same. Following the same trend ``prereq-all`` is an alias on
3180 ``depends-on`` and vice versa. Regarding ``switch-off`` and ``switch-on``
3181 elements they correspond respectively to the module to unload (if specified)
3182 and the module to load on a ``module switch`` command. ``switch`` is an alias
3183 that matches both ``switch-off`` and ``switch-on`` elements. ``require`` and
3184 ``incompat`` *elements* do not match module commands where ``--not-req``
3185 option is set. Setting the ``MODULEPATH`` environment variable with
3186 ``append-path`` or ``prepend-path`` commands can be queried with ``use``
3187 element.
3188
3189 When several *names* are set on one *element* criterion (e.g.,
3190 ``env:PATH,LD_LIBRARY_PATH``), they act as an *OR* operation. Which means
3191 modules listed in result are those matching any of the *element* *names*
3192 defined.
3193
3194 When several extra specifiers are set on a module search query (e.g.,
3195 ``env:PATH env:LD_LIBRARY_PATH``), they act as an *AND* operation. Which means
3196 modules listed in result are those matching all extra specifiers defined.
3197
3198 When an extra specifier is prefixed by ``not:`` (e.g., ``not:env:PATH``), it
3199 acts as a *NOT* operation. Which means modules listed in result are those not
3200 matching the extra specifier defined.
3201
3202 Module specification used as *name* value for some extra specifier *elements*
3203 may leverage :ref:`Advanced module version specifiers` syntax. However if a
3204 module version range or list is implied, it is currently resolved to existing
3205 modules. Thus it may not match modulefile definitions targeting modules that
3206 do not exist. In addition, module aliases and symbolic versions are not
3207 resolved to their target either if set in extra specifier query or in
3208 modulefile definition.
3209
3210 Extra specifier can only be set in a module search context (:subcmd:`avail`,
3211 :subcmd:`spider`, :subcmd:`whatis` and :subcmd:`paths` sub-commands). An error
3212 is raised if used on a module specification query in another context. An error
3213 is also raised if an unknown extra specifier *element* is defined in search
3214 query.
3215
3216 .. only:: html
3217
3218 .. versionadded:: 5.3
3219
3220 .. versionchanged:: 5.4
3221 Extra specifier ``tag`` added
3222
3223 .. versionchanged:: 5.4
3224 Multiple names may be set on one extra specifier criterion to select
3225 modules matching any of these names
3226
3227 .. versionchanged:: 5.5
3228 ``not:`` prefix for extra specifier criterion added to select modules
3229 not matching specified names
3230
3231 .. versionchanged:: 5.6
3232 Extra specifiers ``use`` and ``depends-on-any`` added
3233
3234 .. versionchanged:: 5.6
3235 Support for :subcmd:`spider` sub-command added
3236
3237 .. versionchanged:: 5.6
3238 Extra specifiers ``provide`` and ``provided-alias`` added
3239
3240
3241 .. _Module tags:
3242
3243 Module tags
3244 ^^^^^^^^^^^
3245
3246 Module tags are piece of information that can be associated to individual
3247 modulefiles. Tags could be purely informational or may lead to specific
3248 behaviors.
3249
3250 Module tags may be inherited from the module state set by a modulefile command
3251 or consequence of a module action. The inherited tags are:
3252
3253 * ``auto-loaded``: module has been automatically loaded by another module
3254 * ``forbidden``: module has been set *forbidden* through the use of the
3255 :mfcmd:`module-forbid` command and thus this module cannot be loaded.
3256 * ``hidden``: module has been set *hidden* through the use of the
3257 :mfcmd:`module-hide` command and thus it is not reported by default among
3258 the result of :subcmd:`avail` or :subcmd:`spider` sub-commands.
3259 * ``hidden-loaded``: module has been set *hidden once loaded* through the use
3260 of the :mfcmd:`module-hide --hidden-loaded<module-hide>` command thus it is
3261 not reported by default among the result of a :subcmd:`list` sub-command.
3262 * ``loaded``: module is currently loaded
3263 * ``nearly-forbidden``: module will soon be *forbidden*, which has been set
3264 through the use of the :mfcmd:`module-forbid` command. Thus this module
3265 will soon not be able to load anymore.
3266 * ``warning``: a warning message for the use of the module is set through the
3267 use of the :mfcmd:`module-warn` command.
3268
3269 Tags may also be associated to modules by using the :mfcmd:`module-tag`
3270 modulefile command. Among tags that could be set this way, some have a special
3271 meaning:
3272
3273 * ``keep-loaded``: auto-loaded module cannot be automatically unloaded. This
3274 tag is also set through the use of the :mfcmd:`always-load` command.
3275 * ``sticky``: module once loaded cannot be unloaded unless forced or reloaded
3276 (see `Sticky modules`_ section)
3277 * ``super-sticky``: module once loaded cannot be unloaded unless reloaded,
3278 module cannot be unloaded even if forced (see `Sticky modules`_ section)
3279
3280 The :option:`--tag` option helps to apply additional tags to modules. It is
3281 available on :subcmd:`load`, :subcmd:`load-any`, :subcmd:`switch` and
3282 :subcmd:`try-load` sub-commands and on :mfcmd:`always-load`,
3283 :mfcmd:`depends-on`, :mfcmd:`depends-on-any`, :mfcmd:`module`,
3284 :mfcmd:`prereq`, :mfcmd:`prereq-all` and :mfcmd:`prereq-any` modulefile
3285 commands. In case the designated module is already loaded, the additional tags
3286 are added to the list of tags already applied to this module.
3287
3288 Module tags are reported along the module they are associated to on
3289 :subcmd:`avail`, :subcmd:`list` and :subcmd:`spider` sub-command results and
3290 also when module's loading, unloading, refreshing or tagging evaluation is
3291 mentioned. Tags could be reported either:
3292
3293 * along the module name, all tags set within angle brackets, each tag
3294 separated from the others with a colon character (e.g.,
3295 ``foo/1.2 <tag1:tag2>``).
3296 * graphically rendered over the module name for each tag associated to a
3297 Select Graphic Rendition (SGR) code in the color palette (see
3298 :envvar:`MODULES_COLORS`)
3299
3300 When an abbreviated string is associated to a tag name (see
3301 :envvar:`MODULES_TAG_ABBREV`), this abbreviation is used to report tag along
3302 the module name or the tag is graphically rendered over the module name if a
3303 SGR code is associated with tag abbreviation in the color palette. With an
3304 abbreviation set, the SGR code associated to the tag full name is ignored thus
3305 an SGR code should be associated to the abbreviation to get a graphical
3306 rendering of tag. If the abbreviation associated to a tag corresponds to the
3307 empty string, tag is not reported.
3308
3309 Graphical rendering is made over the tag name or abbreviation instead of over
3310 the module name for each tag name or abbreviation set in the
3311 :envvar:`MODULES_TAG_COLOR_NAME` environment variable.
3312
3313 When several tags have to be rendered graphically over the same module name,
3314 each tag is rendered over a sub-part of the module name. In case more tags
3315 need to be rendered than the total number of characters in the module name,
3316 the remaining tags are graphically rendered over the tag name instead of over
3317 the module name.
3318
3319 When the JSON output mode is enabled (with :option:`--json`), tags are
3320 reported by their name under the ``tags`` attribute. Tag abbreviation and
3321 color rendering do not apply on JSON output.
3322
3323 Module tags cannot be used in search query to designate a modulefile.
3324
3325 .. only:: html
3326
3327 .. versionadded:: 4.7
3328
3329 .. versionchanged:: 5.1
3330 Tag ``keep-loaded`` added
3331
3332 .. versionchanged:: 5.6
3333 Support for :subcmd:`spider` sub-command added
3334
3335 .. versionchanged:: 5.6
3336 Tag ``warning`` added
3337
3338 .. _Sticky modules:
3339
3340 Sticky modules
3341 ^^^^^^^^^^^^^^
3342
3343 Modules are said *sticky* when they cannot be unloaded (they stick to the
3344 loaded environment). Two kind of stickiness can be distinguished:
3345
3346 * ``sticky`` module: cannot be unloaded unless if the unload is forced or if
3347 the module is reloaded after being unloaded or if restoring a collection.
3348 * ``super-sticky`` module: cannot be unloaded unless if the module is reloaded
3349 after being unloaded; super-sticky modules cannot be unloaded even if the
3350 unload is forced.
3351
3352 Modules are designated sticky by associating them the ``sticky`` or the
3353 ``super-sticky`` :ref:`module tag<Module tags>` with the :mfcmd:`module-tag`
3354 modulefile command.
3355
3356 When stickiness is defined over the generic module name (and not over a
3357 specific module version, a version list or a version range), sticky or
3358 super-sticky module can be swapped by another version of module. For instance
3359 if the ``sticky`` tag is defined over *foo* module, loaded module *foo/1.2*
3360 can be swapped by *foo/2.0*. Such stickiness definition means one version of
3361 module should stay loaded whatever version it is.
3362
3363 When restoring a :ref:`collection<Collections>` or resetting to the initial
3364 environment, sticky modules are unloaded to ensure :subcmd:`restore` or
3365 :subcmd:`reset` sub-commands fully set the environment in target collection or
3366 initial state. Super-sticky modules still cannot be unloaded with
3367 :subcmd:`restore` and :subcmd:`reset` sub-commands.
3368
3369 .. only:: html
3370
3371 .. versionadded:: 4.7
3372
3373 .. versionchanged:: 5.2
3374 Unload sticky modules when restoring a collection or resetting to the
3375 initial environment
3376
3377
3378 .. _Module variants:
3379
3380 Module variants
3381 ^^^^^^^^^^^^^^^
3382
3383 Module variants are alternative evaluation of the same *modulefile*. A variant
3384 is specified by associating a value to its name when designating module.
3385 Variant specification relies on the :ref:`Advanced module version specifiers`
3386 mechanism.
3387
3388 Once specified, variant's value is transmitted to the evaluating *modulefile*
3389 which instantiates the variant in the :mfvar:`ModuleVariant` array variable
3390 when reaching the :mfcmd:`variant` modulefile command declaring this variant.
3391 For instance the ``module load foo/1.2 bar=value1`` command leads to the
3392 evaluation of *foo/1.2* modulefile with *bar=value1* variant specification.
3393 When reaching the ``variant bar value1 value2 value3`` command in modulefile
3394 during its evaluation, the ``ModuleVariant(bar)`` array element is set to
3395 the ``value1`` string.
3396
3397 Once variants are instantiated, modulefile's code could check the variant
3398 values to adapt the evaluation and define for instance different module
3399 requirements or produce different environment variable setup.
3400
3401 Variants are interpreted in contexts where *modulefiles* are evaluated.
3402 Variants specified on module designation are ignored by the
3403 :subcmd:`is-avail` or :subcmd:`path` sub-commands. On search sub-commands
3404 (:subcmd:`avail`, :subcmd:`spider`, :subcmd:`whatis` and :subcmd:`paths`),
3405 variants are interpreted and trigger the :ref:`extra match search` process to
3406 filter results.
3407
3408 When modulefile is evaluated a value should be specified for each variant this
3409 modulefile declares. When reaching the :mfcmd:`variant` modulefile command
3410 declaring a variant, an error is raised if no value is specified for this
3411 variant and if no default value is declared. Specified variant value should
3412 match a value from the declared accepted value list if such list is defined
3413 otherwise an error is raised. Additionally if a variant is specified but does
3414 not correspond to a variant declared in modulefile, an error is raised.
3415
3416 When searching for modules with variants specified in search query, the
3417 :ref:`extra match search` process triggers a specific *scan* modulefile
3418 evaluation. Variants defined in modulefile are collected during this
3419 evaluation then compared to the variants specified in search query. If there
3420 is a match, module is included in search results otherwise it is withdrawn.
3421
3422 When searching for available modules, if one variant is specified multiple
3423 times, matching modules are those providing all specified variant values. For
3424 instance ``bar=value1 bar=value2`` will return modules defining a ``bar``
3425 variant with ``value1`` and ``value2`` as available values. On a module
3426 selection context, only the last specified value is retained. Which means on
3427 previous example that ``bar`` variant is set to ``value2``.
3428
3429 When searching for available modules, multiple values may be set on one
3430 variant criterion, which matches modules that provide any of these variant
3431 values. For instance ``bar=value1,value2`` will return modules defining a
3432 ``bar`` variant with either ``value1`` or ``value2`` as available value.
3433
3434 When searching for available modules, ``not:`` prefix may be added on variant
3435 criterion, which matches modules that do not provide these variant values. For
3436 instance ``not:bar=value1`` will return modules not defining a ``bar`` variant
3437 or defining a ``bar`` variant but without ``value1`` among available values.
3438
3439 Module variants are reported along the module they are associated to on
3440 :subcmd:`list` sub-command results. They are also reported on :subcmd:`avail`
3441 and :subcmd:`spider` sub-commands if specified in search query or added to the
3442 element to report in sub-command output (see :option:`--output`/:option:`-o`
3443 option).
3444
3445 Variants are reported within curly braces next to module name, each variant
3446 definition separated from the others with a colon character (e.g.,
3447 ``foo/1.2{variant1=value:+variant2}``). Boolean variants are reported with the
3448 ``+name`` or ``-name`` syntaxes on :subcmd:`list` sub-command or with the
3449 ``name=on,off`` syntax on :subcmd:`avail` and :subcmd:`spider` sub-commands.
3450 When a shortcut character is defined for a variant (see
3451 :envvar:`MODULES_VARIANT_SHORTCUT`) it is reported with the
3452 ``<shortcut>value`` syntax. For instance if ``%`` character is defined as a
3453 shortcut for *variant1*: ``foo/1.2{%value:+variant2}``.
3454
3455 When the JSON output mode is enabled (with :option:`--json`), variants are
3456 reported under the ``variants`` JSON object as name/value pairs. Values of
3457 Boolean variant are set as JSON Boolean. Other values are set as JSON strings.
3458 Variant shortcut and color rendering do not apply on JSON output.
3459
3460 .. only:: html
3461
3462 .. versionadded:: 4.8
3463
3464 .. versionchanged:: 5.3
3465 Variants specified in :subcmd:`avail`, :subcmd:`whatis` or
3466 :subcmd:`paths` search query interpreted to filter results
3467
3468 .. versionchanged:: 5.4
3469 Multiple values may be set on one variant search criterion to select
3470 modules providing any of these variant values
3471
3472 .. versionchanged:: 5.5
3473 ``not:`` prefix for variant search criterion added to select modules not
3474 matching specified variant values
3475
3476 .. versionchanged:: 5.6
3477 Variants specified in :subcmd:`spider` search query interpreted to
3478 filter results
3479
3480 .. _Extra match search:
3481
3482 Extra match search
3483 ^^^^^^^^^^^^^^^^^^
3484
3485 Extra match search is a mechanism that evaluates available modulefiles during
3486 a module search to find those matching an extra query or to report additional
3487 information. After selecting modulefiles that match the module name and
3488 version specified in search query, these remaining modulefiles are evaluated
3489 to collect their content.
3490
3491 Extra match search is available on the following module search sub-commands:
3492 :subcmd:`avail`, :subcmd:`spider`, :subcmd:`whatis` and :subcmd:`paths`.
3493
3494 Extra match search is triggered when:
3495
3496 * :ref:`Module variants` and their available values have to be reported in
3497 avail and spider outputs (see :option:`--output`/:option:`-o` option): extra
3498 match search is triggered to collect variant information
3499 * Provided module aliases have to be reported in avail and spider outputs (see
3500 :option:`--output`/:option:`-o` option): extra match search is triggered to
3501 collect these module aliases defined within modulefiles
3502 * Module variant is specified in search query: extra match search is triggered
3503 to collect variant information then match them against variant specified in
3504 query
3505 * :ref:`Extra specifier` is specified in search query: extra match search is
3506 triggered to collect commands used in modulefiles or modulercs then match
3507 them against extra specifier query
3508
3509 If search query does not contain an extra query and if variant or provided
3510 alias information should not be reported, no extra match search is performed.
3511 If search query does not contain any module name and version but contains an
3512 extra query or if variant information should be reported, extra match search
3513 is applied to all available modulefiles. If provided alias information should
3514 be reported, extra match search is applied to all available modulefiles even
3515 if search query contains a module specification.
3516
3517 During this specific evaluation, modulefiles are interpreted in *scan* mode.
3518 This mode aims to collect the different Tcl modulefile commands used. Special
3519 care should be given when writing modulefiles to ensure they cope with such
3520 evaluation mode.
3521
3522 Modulefiles tagged *forbidden* are excluded from extra match search
3523 evaluation. Thus they are excluded from result when this mechanism is
3524 triggered.
3525
3526 No *scan* modulefile evaluation is performed if search query is only composed
3527 of ``tag`` extra specifier. Module tags are defined in modulercs thus no
3528 modulefile evaluation is required to get tags applying to a modulefile.
3529
3530 As extra match search implies additional modulefile evaluations, it is advised
3531 to build and use :ref:`Module cache` to improve search speed.
3532
3533 .. only:: html
3534
3535 .. versionadded:: 5.3
3536
3537 .. versionchanged:: 5.6
3538 Support for :subcmd:`spider` sub-command added
3539
3540 .. versionchanged:: 5.6
3541 Extra match search triggered when reporting provided module aliases
3542
3543 .. _collections:
3544
3545 Collections
3546 ^^^^^^^^^^^
3547
3548 Collections describe a sequence of :subcmd:`module use<use>` then
3549 :subcmd:`module load<load>` commands that are interpreted by
3550 :file:`modulecmd.tcl` to set the user environment as described by this
3551 sequence.
3552
3553 Collections are generated by the :subcmd:`save` sub-command that dumps the
3554 current user environment state in terms of module paths and loaded modules. By
3555 default collections are saved under the :file:`$HOME/.module` directory.
3556
3557 .. parsed-literal::
3558
3559 :ps:`$` module list
3560 Currently Loaded Modulefiles:
3561 1) foo/1.2 2) bar/2.0 3) qux/3.5
3562 :ps:`$` module save foo
3563 :ps:`$` cat $HOME/.module/foo
3564 module use --append /path/to/modulefiles
3565 module load foo
3566 module load bar/2.0
3567 module load qux/3.5
3568
3569 The content of a collection can also be displayed with the :subcmd:`saveshow`
3570 sub-command. Note that in the above example, bare module name is recorded for
3571 ``foo`` modulefile as loaded version is the implicit default. Loaded version
3572 recording can be enforced by enabling :mconfig:`collection_pin_version`
3573 configuration option.
3574
3575 .. parsed-literal::
3576
3577 :ps:`$` module config collection_pin_version 1
3578 :ps:`$` module save foo
3579 :ps:`$` module saveshow foo
3580 -------------------------------------------------------------------
3581 :sgrhi:`/home/user/.module/foo`:
3582
3583 :sgrcm:`module` use --append /path/to/modulefiles
3584 :sgrcm:`module` load foo/1.2
3585 :sgrcm:`module` load bar/2.0
3586 :sgrcm:`module` load qux/3.5
3587
3588 -------------------------------------------------------------------
3589
3590 When a collection is activated, with the :subcmd:`restore`
3591 sub-command, module paths and loaded modules are unused or unloaded if they
3592 are not part or if they are not ordered the same way as in the collection.
3593
3594 .. parsed-literal::
3595
3596 :ps:`$` module list
3597 Currently Loaded Modulefiles:
3598 1) foo/1.2 2) bar/2.1 3) qux/3.5
3599 :ps:`$` module restore foo
3600 Unloading :sgrhi:`qux/3.5`
3601 Unloading :sgrhi:`bar/2.1`
3602 Loading :sgrhi:`bar/2.0`
3603 Loading :sgrhi:`qux/3.5`
3604 :ps:`$` module list
3605 Currently Loaded Modulefiles:
3606 1) foo/1.2 2) bar/2.0 3) qux/3.5
3607
3608 In the above example, second and third module loaded are changed. First loaded
3609 module is not changed or reloaded as it is the same module between current
3610 environment and collection. As second loaded module was different, this module
3611 and all those loaded afterward are unloaded to then load the sequence
3612 described by collection. As a result, third loaded module is reloaded, even if
3613 is was the same module between current environment and collection.
3614
3615 Existing collections can be listed with :subcmd:`savelist` sub-command. They
3616 can be deleted with :subcmd:`saverm` sub-command.
3617
3618 .. parsed-literal::
3619
3620 :ps:`$` module savelist
3621 Named collection list:
3622 1) default 2) foo
3623 :ps:`$` module saverm default
3624 :ps:`$` module savelist
3625 Named collection list:
3626 1) foo
3627
3628 When no argument is provided to :subcmd:`save`, :subcmd:`restore`,
3629 :subcmd:`saveshow` or :subcmd:`saverm` sub-commands, the ``default``
3630 collection is assumed.
3631
3632 Collection can also be specified as a full pathname:
3633
3634 .. parsed-literal::
3635
3636 :ps:`$` module save /path/to/collections/bar
3637 :ps:`$` module saveshow /path/to/collections/bar
3638 -------------------------------------------------------------------
3639 :sgrhi:`/path/to/collections/bar`:
3640
3641 :sgrcm:`module` use --append /path/to/modulefiles
3642 :sgrcm:`module` load foo/1.2
3643 :sgrcm:`module` load bar/2.0
3644 :sgrcm:`module` load qux/3.5
3645
3646 -------------------------------------------------------------------
3647
3648 Initial environment
3649 """""""""""""""""""
3650
3651 Initial environment state, which corresponds to modulepaths enabled and
3652 modules loaded during :ref:`Modules initialization<Package Initialization>`,
3653 is referred as the ``__init__`` collection. This collection is virtual as
3654 its content is stored in the :envvar:`__MODULES_LMINIT` and not in a file. It
3655 can be displayed with :subcmd:`saveshow` and restored with :subcmd:`restore`
3656 sub-command.
3657
3658 .. parsed-literal::
3659
3660 :ps:`$` module saveshow __init__
3661 -------------------------------------------------------------------
3662 :sgrhi:`initial environment`:
3663
3664 :sgrcm:`module` use --append /path/to/modulefiles
3665 :sgrcm:`module` load foo/1.2
3666
3667 -------------------------------------------------------------------
3668
3669 If the ``default`` collection does not exist, :subcmd:`saveshow` and
3670 :subcmd:`restore` sub-commands assume ``__init__`` collection when no argument
3671 provided to them.
3672
3673 .. parsed-literal::
3674
3675 :ps:`$` module list
3676 Currently Loaded Modulefiles:
3677 1) foo/1.2 2) bar/2.1 3) qux/3.5
3678 :ps:`$` module savelist
3679 Named collection list:
3680 1) foo
3681 :ps:`$` module restore
3682 Unloading :sgrhi:`qux/3.5`
3683 Unloading :sgrhi:`bar/2.1`
3684
3685 Initial environment state can also be restored with the :subcmd:`reset`
3686 sub-command. This sub-command behavior can be changed with
3687 :mconfig:`reset_target_state` configuration option to choose to just purge
3688 loaded modules or to restore a specific collection.
3689
3690 Collection targets
3691 """"""""""""""""""
3692
3693 A collection target can be defined for current environment session with the
3694 :mconfig:`collection_target` configuration option. When set, available
3695 collections are reduced to those suffixed with target name. Which means
3696 :subcmd:`restore`, :subcmd:`saveshow`, :subcmd:`savelist` and :subcmd:`saverm`
3697 only find collections matching currently set target.
3698
3699 .. parsed-literal::
3700
3701 :ps:`$` module savelist
3702 Named collection list:
3703 1) foo
3704 :ps:`$` module config collection_target mytarget
3705 :ps:`$` module savelist
3706 No named collection (for target "mytarget").
3707 :ps:`$` module restore foo
3708 :sgrer:`ERROR`: Collection foo (for target "mytarget") cannot be found
3709
3710 When saving a new collection, generated file is suffixed with currently set
3711 target name.
3712
3713 .. parsed-literal::
3714
3715 :ps:`$` module save bar
3716 :ps:`$` module savelist
3717 Named collection list (for target "mytarget"):
3718 1) bar
3719 :ps:`$` ls $HOME/.module
3720 bar.mytarget foo
3721
3722 Collection targets help to distinguish contexts and make collection reachable
3723 only from the context they have been made for. For instance the same user
3724 account may be used to access different OSes or machine architectures. With a
3725 target set, users are ensured to only access collections built for the context
3726 they are currently connected to. See also :envvar:`MODULES_COLLECTION_TARGET`
3727 section.
3728
3729 Stash collections
3730 """""""""""""""""
3731
3732 Current user environment can be stashed with :subcmd:`stash` sub-command. When
3733 this sub-command is called, current module environment is saved in a stash
3734 collection then `initial environment`_ is restored.
3735
3736 .. parsed-literal::
3737
3738 :ps:`$` module list
3739 Currently Loaded Modulefiles:
3740 1) foo/1.2 2) qux/4.2
3741 :ps:`$` module stash
3742 Unloading :sgrhi:`qux/4.2`
3743
3744 Specific sub-commands are available to handle stash collections:
3745 :subcmd:`stashpop`, :subcmd:`stashlist`, :subcmd:`stashshow`,
3746 :subcmd:`stashrm` and :subcmd:`stashclear`. A stash collection is restored
3747 with :subcmd:`stashpop` which also deletes the collection once restored.
3748
3749 .. parsed-literal::
3750
3751 :ps:`$` module stashlist
3752 Stash collection list (for target "mytarget"):
3753 0) stash-1667669750191
3754 :ps:`$` module stashpop
3755 Loading :sgrhi:`qux/4.2`
3756 :ps:`$` module stashlist
3757 No stash collection (for target "mytarget").
3758
3759 Stash collections have same format and are saved in the same location than
3760 other collections. Collection target also applies to stash collection.
3761 Creation timestamp is saved in stash collection name.
3762
3763 Stash collection can be designated by their full collection name (i.e.,
3764 *stash-<creation_timestamp>*) or a stash index. Most recent stash
3765 collection has index *0*, *1* is the one before it. When no argument is
3766 provided on stash sub-commands, the latest stash collection is assumed (that
3767 is stash index *0*).
3768
3769 .. parsed-literal::
3770
3771 :ps:`$` module stashlist
3772 Stash collection list (for target "mytarget"):
3773 0) stash-1667669750783 1) stash-1667669750253
3774 :ps:`$` module stashshow 1
3775 -------------------------------------------------------------------
3776 :sgrhi:`/home/user/.module/stash-1667669750253.mytarget:`
3777
3778 :sgrcm:`module` use --append /path/to/modulefiles
3779 :sgrcm:`module` load foo/1.2
3780 :sgrcm:`module` load bar/2.0
3781
3782 -------------------------------------------------------------------
3783
3784 .. only:: html
3785
3786 .. versionadded:: 4.0
3787
3788 .. versionchanged:: 5.2
3789 Initial environment state introduced
3790
3791 .. versionchanged:: 5.2
3792 Stash collection introduced
3793
3794 .. _Site-specific configuration:
3795
3796 Site-specific configuration
3797 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
3798
3799 Siteconfig, the site-specific configuration script, is a way to extend
3800 :file:`modulecmd.tcl`. Siteconfig is a Tcl script. Its location is
3801 |file etcdir_siteconfig|.
3802
3803 When :file:`modulecmd.tcl` is invoked it sources siteconfig script if it
3804 exists. Any global variable or procedure of :file:`modulecmd.tcl` can be
3805 redefined in siteconfig.
3806
3807 An additional siteconfig script may be specified through the
3808 :mconfig:`extra_siteconfig` configuration option. The
3809 :envvar:`MODULES_SITECONFIG` environment variable is defined by
3810 :subcmd:`config` sub-command when setting :mconfig:`extra_siteconfig`. If it
3811 exists the extra siteconfig is sourced by :file:`modulecmd.tcl` right after
3812 main siteconfig script.
3813
3814 Hooks
3815 """""
3816
3817 Siteconfig relies on the ability of the Tcl language to overwrite previously
3818 defined variables and procedures. Sites may deploy their own Tcl code in
3819 siteconfig to adapt :file:`modulecmd.tcl` to their specific needs. The
3820 ``trace`` Tcl command may especially be used to define hooks that are run when
3821 entering or leaving a given procedure, or when a variable is read or written.
3822 See :manpage:`trace(n)` man page for detailed information. The following
3823 example setup a procedure that is executed before each modulefile evaluation:
3824
3825 .. code-block:: tcl
3826
3827 proc beforeEval {cmdstring code result op} {
3828 # code to run right before each modulefile evaluation
3829 }
3830 trace add execution execute-modulefile enter beforeEval
3831
3832 Another possibility is to override the definition of an existing procedure by
3833 first renaming its original version then creating a new procedure that will add
3834 specific code and rely on the renamed original procedure for the rest. See
3835 :manpage:`rename(n)` man page for details. As an example, the following code
3836 adds a new query option to the :mfcmd:`module-info` modulefile command:
3837
3838 .. code-block:: tcl
3839
3840 rename module-info __module-info
3841 proc module-info {what {more {}}} {
3842 switch -- $what {
3843 platform { return myhost-$::tcl_platform(machine) }
3844 default { return [__module-info $what $more] }
3845 }
3846 }
3847
3848 If a hook procedure needs to execute modulefile commands (for example, to
3849 define environment variables), these commands should be run through the
3850 current modulefile Tcl interpreter. This ensures that the commands behave
3851 consistently with the current modulefile evaluation mode.
3852
3853 .. code-block:: tcl
3854
3855 proc hook_procedure {value} {
3856 # get the name of the current modulefile Tcl interpreter
3857 set modfile_interp [getCurrentModfileInterpName]
3858
3859 # execute a modulefile command in the current interpreter context
3860 interp eval $modfile_interp setenv MYVAR $value
3861 }
3862
3863 Siteconfig hook variables
3864 """""""""""""""""""""""""
3865
3866 Some Tcl variables can be defined in siteconfig script with special hook
3867 meaning. The following variables are recognized:
3868
3869 .. sitevar:: modulefile_extra_vars
3870
3871 List of variable names and associated values to setup in modulefile
3872 evaluation context. These variables can be accessed when modulefile is
3873 executed. In case code in a modulefile changes the value of such variable,
3874 its value is reset to the one defined in :sitevar:`modulefile_extra_vars`
3875 prior the evaluation of the next modulefile.
3876
3877 .. code-block:: tcl
3878
3879 set modulefile_extra_vars {myvar 1 othervar {some text}}
3880
3881 In the above siteconfig example, :sitevar:`modulefile_extra_vars` sets the
3882 ``myvar`` and ``othervar`` variables in the modulefile evaluation context
3883 with respectively ``1`` and ``some text`` as value.
3884
3885 .. only:: html
3886
3887 .. versionadded:: 5.2
3888
3889 .. sitevar:: modulefile_extra_cmds
3890
3891 List of command and associated local procedure to setup in modulefile
3892 evaluation context. These commands can be called from the modulefile to
3893 execute associated procedure. In case a modulefile changes the definition
3894 of such command, its definition is bound again on the procedure defined in
3895 :sitevar:`modulefile_extra_cmds` prior the evaluation of the next modulefile.
3896
3897 .. code-block:: tcl
3898
3899 proc mycmd {} {
3900 # Tcl code
3901 }
3902 proc anotherproc {args} {
3903 # Tcl code
3904 }
3905 set modulefile_extra_cmds {mycmd mycmd othercmd anotherproc}
3906
3907 In the above siteconfig example, :sitevar:`modulefile_extra_cmds` sets the
3908 ``mycmd`` and ``othercmd`` commands in the modulefile evaluation context and
3909 bind them respectively to the ``mycmd`` and ``anotherproc`` procedures
3910 defined in siteconfig script.
3911
3912 .. only:: html
3913
3914 .. versionadded:: 5.2
3915
3916 .. sitevar:: modulerc_extra_vars
3917
3918 List of variable names and associated values to setup in modulerc evaluation
3919 context. These variables can be accessed when modulerc is executed. In case
3920 code in a modulerc changes the value of such variable, its value
3921 is reset to the one defined in :sitevar:`modulerc_extra_vars` prior the
3922 evaluation of the next modulerc.
3923
3924 .. code-block:: tcl
3925
3926 set modulerc_extra_vars {myvar 1 othervar {some text}}
3927
3928 In the above siteconfig example, :sitevar:`modulerc_extra_vars` sets the
3929 ``myvar`` and ``othervar`` variables in the modulerc evaluation context with
3930 respectively ``1`` and ``some text`` as value.
3931
3932 .. only:: html
3933
3934 .. versionadded:: 5.2
3935
3936 .. sitevar:: modulerc_extra_cmds
3937
3938 List of command and associated local procedure to setup in modulerc
3939 evaluation context. These commands can be called from the modulerc to execute
3940 associated procedure. In case a modulerc changes the definition of such
3941 command, its definition is bound again on the procedure defined in
3942 :sitevar:`modulerc_extra_cmds` prior the evaluation of the next modulerc.
3943
3944 .. code-block:: tcl
3945
3946 proc mycmd {} {
3947 # Tcl code
3948 }
3949 proc anotherproc {args} {
3950 # Tcl code
3951 }
3952 set modulerc_extra_cmds {mycmd mycmd othercmd anotherproc}
3953
3954 In the above siteconfig example, :sitevar:`modulerc_extra_cmds` sets the
3955 ``mycmd`` and ``othercmd`` commands in the modulerc evaluation context and
3956 bind them respectively to the ``mycmd`` and ``anotherproc`` procedures
3957 defined in siteconfig script.
3958
3959
3960 .. only:: html
3961
3962 .. versionadded:: 5.2
3963
3964 .. only:: html
3965
3966 .. versionadded:: 4.1
3967
3968 .. versionchanged:: 4.3
3969 Additional site-specific configuration script introduced
3970
3971 .. _Module cache:
3972
3973 Module cache
3974 ^^^^^^^^^^^^
3975
3976 To improve module search efficiency, a module cache can be setup in each
3977 modulepath. A module cache is represented by a :file:`.modulecache` file
3978 stored at the root of modulepath directory. This file aggregates contents of
3979 all valid modulercs and modulefiles and issue description of all
3980 non-modulefiles stored in modulepath directory.
3981
3982 When cache file is available, a module search analyzes this file rather
3983 walking through the content of modulepath directory to check if files are
3984 modulefiles or not. Cache file reduces module search processing time
3985 especially when hundreds of modulefiles are available and if these files are
3986 located on busy storage systems. Having one file to read per modulepath rather
3987 walking through a whole directory content extremely reduces the number of
3988 required I/O operations.
3989
3990 When modulefiles or directories in the modulepath are not accessible for
3991 everyone, a *limited access* indication is recorded in cache file rather
3992 content of these modulefiles and content of these directories. When cache file
3993 containing such indication is processed, the limited access modulefiles are
3994 tested to check if they are available to the current running user. Limited
3995 access directories are walked down to find all available modulefiles and
3996 modulercs.
3997
3998 Cache files are generated with :subcmd:`cachebuild` sub-command. This command
3999 has to be run by someone who owns write access in modulepath directory to
4000 create cache file.
4001
4002 Cache files are used any time a module search occurs in modulepaths. They are
4003 analyzed for instance during :subcmd:`avail`, :subcmd:`spider`,
4004 :subcmd:`load`, :subcmd:`display` or :subcmd:`whatis` sub-commands.
4005
4006 Cache files are removed with :subcmd:`cacheclear` sub-command. This command
4007 has to be run by someone who own write access in modulepath directory to
4008 effectively delete cache file.
4009
4010
4011 EXIT STATUS
4012 -----------
4013
4014 The :command:`module` command exits with ``0`` if its execution succeed.
4015 Otherwise ``1`` is returned.
4016
4017
4018 .. _module ENVIRONMENT:
4019
4020 ENVIRONMENT
4021 -----------
4022
4023 .. envvar:: __MODULES_AUTOINIT_INPROGRESS
4024
4025 If set to ``1``, the :subcmd:`autoinit` sub-command process is skipped.
4026
4027 This environment variable is set to ``1`` by the :subcmd:`autoinit`
4028 sub-command after checking it is not set. It ensures no nested initialization
4029 of Modules occur. At the end of the processing of the :subcmd:`autoinit`
4030 sub-command, :envvar:`__MODULES_AUTOINIT_INPROGRESS` is unset.
4031
4032 .. only:: html
4033
4034 .. versionadded:: 5.0
4035
4036 .. envvar:: __MODULES_LMALTNAME
4037
4038 A colon separated list of the alternative names set through
4039 :mfcmd:`module-version` and :mfcmd:`module-alias` statements corresponding to
4040 all loaded *modulefiles*. Each element in this list starts by the name of the
4041 loaded *modulefile* followed by all alternative names resolving to it. The
4042 loaded modulefile and its alternative names are separated by the ampersand
4043 character.
4044
4045 Each alternative name stored in :envvar:`__MODULES_LMALTNAME` is prefixed by
4046 the ``al|`` string if it corresponds to a module alias or prefixed by the
4047 ``as|`` string if it corresponds to an automatic version symbol. These
4048 prefixes help to distinguish the different kind of alternative name.
4049
4050 This environment variable is intended for :command:`module` command internal
4051 use to get knowledge of the alternative names matching loaded *modulefiles*
4052 in order to keep environment consistent when conflicts or pre-requirements
4053 are set over these alternative designations. It also helps to find a match
4054 after *modulefiles* being loaded when :subcmd:`unload`, :subcmd:`is-loaded`
4055 or :subcmd:`info-loaded` actions are run over these names.
4056
4057 Starting version 4.7 of Modules, :envvar:`__MODULES_LMALTNAME` is also used
4058 on :subcmd:`list` sub-command to report the symbolic versions associated with
4059 the loaded modules.
4060
4061 .. only:: html
4062
4063 .. versionadded:: 4.2
4064
4065 .. versionchanged:: 5.0
4066 Variable renamed from ``MODULES_LMALTNAME`` to ``__MODULES_LMALTNAME``
4067
4068 .. envvar:: __MODULES_LMCONFLICT
4069
4070 A colon separated list of the :mfcmd:`conflict` statements defined by all
4071 loaded *modulefiles*. Each element in this list starts by the name of the
4072 loaded *modulefile* declaring the conflict followed by the name of all
4073 modulefiles it declares a conflict with. These loaded modulefiles and
4074 conflicting modulefile names are separated by the ampersand character.
4075
4076 This environment variable is intended for :command:`module` command internal
4077 use to get knowledge of the conflicts declared by the loaded *modulefiles*
4078 in order to keep environment consistent when a conflicting module is asked
4079 for load afterward.
4080
4081 .. only:: html
4082
4083 .. versionadded:: 4.2
4084
4085 .. versionchanged:: 5.0
4086 Variable renamed from ``MODULES_LMCONFLICT`` to
4087 ``__MODULES_LMCONFLICT``
4088
4089 .. envvar:: __MODULES_LMEXTRATAG
4090
4091 A colon separated list of the tags corresponding to all loaded *modulefiles*
4092 that have been set through the :option:`--tag` option. Each element in this
4093 list starts by the name of the loaded *modulefile* followed by all explicitly
4094 set tags applying to it. The loaded modulefile and its tags are separated by
4095 the ampersand character.
4096
4097 This environment variable is intended for :command:`module` command internal
4098 use to distinguish from all tags those that have been specifically set with
4099 :option:`--tag` option.
4100
4101 .. only:: html
4102
4103 .. versionadded:: 5.1
4104
4105 .. envvar:: __MODULES_LMINIT
4106
4107 A colon separated list describing the modulepaths that have been enabled and
4108 the *modulefiles* that have been loaded with their tags during :ref:`Modules
4109 initialization<Package Initialization>`. Each element in this list
4110 corresponds to a :ref:`collection<collections>` definition line.
4111
4112 This environment variable is intended for :command:`module` command internal
4113 use to get knowledge of the initial loaded state after initialization.
4114
4115 This initial environment state can then be restored with :subcmd:`reset`
4116 sub-command. It can also be restored with :subcmd:`restore` sub-command when
4117 ``__init__`` collection name is specified or when no collection name is
4118 specified and no *default* collection exists.
4119
4120 The content of the initial environment can be displayed with
4121 :subcmd:`saveshow` sub-command when ``__init__`` collection name is specified
4122 or when no collection name is specified and no *default* collection exists.
4123
4124 .. only:: html
4125
4126 .. versionadded:: 5.2
4127
4128 .. envvar:: __MODULES_LMPREREQ
4129
4130 A colon separated list of the :mfcmd:`prereq` statements defined by all
4131 loaded *modulefiles*. Each element in this list starts by the name of the
4132 loaded *modulefile* declaring the pre-requirement followed by the name of all
4133 modulefiles it declares a :mfcmd:`prereq` with. These loaded modulefiles and
4134 pre-required modulefile names are separated by the ampersand character. When
4135 a :mfcmd:`prereq` statement is composed of multiple modulefiles, these
4136 modulefile names are separated by the pipe character.
4137
4138 This environment variable is intended for :command:`module` command internal
4139 use to get knowledge of the pre-requirement declared by the loaded
4140 *modulefiles* in order to keep environment consistent when a pre-required
4141 module is asked for unload afterward.
4142
4143 .. only:: html
4144
4145 .. versionadded:: 4.2
4146
4147 .. versionchanged:: 5.0
4148 Variable renamed from ``MODULES_LMPREREQ`` to ``__MODULES_LMPREREQ``
4149
4150 .. envvar:: __MODULES_LMPREREQPATH
4151
4152 A colon separated list of the :mfcmd:`prereq` statements set with a specific
4153 ``--modulepath`` option defined by all loaded *modulefiles*. Each element in
4154 this list starts by the name of the loaded *modulefile* declaring the
4155 pre-requirement followed by the name of all modulefiles it declares a
4156 :mfcmd:`prereq` with and their specific modulepath. These loaded modulefiles,
4157 pre-required modulefile names and specific modulepaths set are separated by
4158 the ampersand character. When a :mfcmd:`prereq` statement is composed of
4159 multiple modulefiles or multiple specific modulepaths, these names are
4160 separated by the pipe character.
4161
4162 This environment variable is intended for :command:`module` command internal
4163 use to get knowledge of the pre-requirement declared by the loaded
4164 *modulefiles* in order to keep environment consistent.
4165
4166 .. only:: html
4167
4168 .. versionadded:: 5.5
4169
4170 .. envvar:: __MODULES_LMREFRESH
4171
4172 A colon separated list of the loaded modules that are qualified for refresh
4173 evaluation. Loaded modules listed in this variable are those defining
4174 volatile environment changes like shell completion, alias and function.
4175
4176 .. only:: html
4177
4178 .. versionadded:: 5.2
4179
4180 .. envvar:: __MODULES_LMSOURCESH
4181
4182 A colon separated list of the :mfcmd:`source-sh` statements defined by all
4183 loaded *modulefiles*. Each element in this list starts by the name of the
4184 loaded *modulefile* declaring the environment changes made by the evaluation
4185 of :mfcmd:`source-sh` scripts. This name is followed by each
4186 :mfcmd:`source-sh` statement call and corresponding result achieved in
4187 modulefile. The loaded modulefile name and each :mfcmd:`source-sh` statement
4188 description are separated by the ampersand character. The :mfcmd:`source-sh`
4189 statement call and each resulting modulefile command (corresponding to the
4190 environment changes done by sourced script) are separated by the pipe
4191 character.
4192
4193 This environment variable is intended for :command:`module` command internal
4194 use to get knowledge of the modulefile commands applied for each
4195 :mfcmd:`source-sh` command when loading the modulefile. In order to reverse
4196 these modulefile commands when modulefile is unloaded to undo the environment
4197 changes.
4198
4199 .. only:: html
4200
4201 .. versionadded:: 4.6
4202
4203 .. versionchanged:: 5.0
4204 Variable renamed from ``MODULES_LMSOURCESH`` to
4205 ``__MODULES_LMSOURCESH``
4206
4207 .. envvar:: __MODULES_LMSTICKYRULE
4208
4209 A colon separated list of the sticky or super-sticky tag definitions applying
4210 to loaded *modulefiles*. Each element in this list starts by the name of the
4211 loaded *modulefile* followed by the sticky tag name and the module
4212 specifications on which the tag applies. These loaded modulefiles and sticky
4213 tag definitions are separated by the ampersand character. Tag name and module
4214 specifications on which it applies are separated by the pipe character.
4215
4216 When stickiness applies specifically to the loaded module name and version,
4217 sticky rule is not recorded in ``__MODULES_LMSTICKYRULE``.
4218
4219 This environment variable is intended for :command:`module` command internal
4220 use to get knowledge of the stickiness scope when sticky module is changed.
4221
4222 .. only:: html
4223
4224 .. versionadded:: 5.4
4225
4226 .. envvar:: __MODULES_LMTAG
4227
4228 A colon separated list of the tags corresponding to all loaded *modulefiles*
4229 that have been set through :mfcmd:`module-tag` statements or from other
4230 modulefile statements like :mfcmd:`module-forbid` (that may apply the
4231 `nearly-forbidden` tag in specific situation) (see `Module tags`_ section).
4232 Each element in this list starts by the name of the loaded *modulefile*
4233 followed by all tags applying to it. The loaded modulefile and its tags are
4234 separated by the ampersand character.
4235
4236 This environment variable is intended for :command:`module` command internal
4237 use to get knowledge of the tags applying to loaded *modulefiles* in order
4238 to report these tags on :subcmd:`list` sub-command output or to apply
4239 specific behavior when unloading *modulefile*.
4240
4241 .. only:: html
4242
4243 .. versionadded:: 4.7
4244
4245 .. versionchanged:: 5.0
4246 Variable renamed from ``MODULES_LMTAG`` to ``__MODULES_LMTAG``
4247
4248 .. envvar:: __MODULES_LMUSE
4249
4250 A colon separated list of the modulepaths enabled by all loaded
4251 *modulefiles*. Each element in this list starts by the name of the loaded
4252 *modulefile* enabling modulepath followed by all modulepaths it enables.
4253 These loaded modulefiles and enabled modulepaths are separated by the
4254 ampersand character.
4255
4256 This environment variable is intended for :command:`module` command internal
4257 use to get knowledge of the modulepath enabled by the loaded *modulefiles*
4258 in order to keep environment consistent when unloading these modules whereas
4259 modulefiles from the enabled modulepaths are loaded.
4260
4261 .. only:: html
4262
4263 .. versionadded:: 5.6
4264
4265 .. envvar:: __MODULES_LMVARIANT
4266
4267 A colon separated list of the variant instantiated through :mfcmd:`variant`
4268 statements by all loaded *modulefiles* (see :ref:`Module variants` section).
4269 Each element in this list starts by the name of the loaded *modulefile*
4270 followed by all the variant definitions set during the load of this module.
4271 The loaded modulefile and each of its variant definition are separated by the
4272 ampersand character. Each variant definition starts with the variant name,
4273 followed by the variant value set, then a flag to know if variant is of the
4274 Boolean type and last element in this definition is a flag to know if the
4275 chosen value is the default one for this variant and if it has been
4276 automatically set or not. These four elements composing the variant
4277 definition are separated by the pipe character.
4278
4279 This environment variable is intended for :command:`module` command internal
4280 use to get knowledge of the variant value defined by the loaded *modulefiles*
4281 in order to keep environment consistent when requirements are set over a
4282 specific variant value or just to report these variant values when listing
4283 loaded modules.
4284
4285 .. only:: html
4286
4287 .. versionadded:: 4.8
4288
4289 .. versionchanged:: 5.0
4290 Variable renamed from ``MODULES_LMVARIANT`` to ``__MODULES_LMVARIANT``
4291
4292 .. envvar:: __MODULES_PUSHENV_<VAR>
4293
4294 Stack of saved values for :envvar:`<VAR>` environment variable. A colon-\
4295 separated list containing pairs of elements. A pair is formed by a loaded
4296 module name followed by the value set to :envvar:`<VAR>` in this module with
4297 :mfcmd:`pushenv` command. An ampersand character separates the two parts of
4298 the pair.
4299
4300 First element in list corresponds to the lastly set value of :envvar:`<VAR>`.
4301 If a value were set to :envvar:`<VAR>` prior the first evaluated
4302 :mfcmd:`pushenv` command, this value is associated to an empty module name to
4303 record it as a pair element in :envvar:`__MODULES_PUSHENV_\<VAR\>`.
4304
4305 .. only:: html
4306
4307 .. versionadded:: 5.1
4308
4309 .. envvar:: __MODULES_QUAR_<VAR>
4310
4311 Value of environment variable :envvar:`<VAR>` passed to :file:`modulecmd.tcl`
4312 in order to restore :envvar:`<VAR>` to this value once started.
4313
4314 .. only:: html
4315
4316 .. versionadded:: 4.1
4317
4318 .. versionchanged:: 5.0
4319 Variable renamed from ``<VAR>_modquar`` to ``__MODULES_QUAR_<VAR>``
4320
4321 .. envvar:: __MODULES_QUARANTINE_SET
4322
4323 If set to ``1``, restore the environment variables set on hold by the
4324 quarantine mechanism when starting :file:`modulecmd.tcl` script. This
4325 variable is automatically defined by Modules shell initialization scripts or
4326 :command:`module` shell function when they apply the quarantine mechanism.
4327 (see :envvar:`MODULES_QUARANTINE_SUPPORT`).
4328
4329 .. only:: html
4330
4331 .. versionadded:: 5.0
4332
4333 .. envvar:: __MODULES_SHARE_<VAR>
4334
4335 Reference counter variable for path-like variable :envvar:`<VAR>`. A colon
4336 separated list containing pairs of elements. A pair is formed by a path
4337 element followed its usage counter which represents the number of times
4338 this path has been enabled in variable :envvar:`<VAR>`. A colon separates the
4339 two parts of the pair.
4340
4341 An element of a path-like variable is added to the reference counter variable
4342 as soon as it is added more than one time. When an element of a path-like
4343 variable is not found in the reference counter variable, it means this
4344 element has only be added once to the path-like variable.
4345
4346 When an empty string is added as an element in the path-like variable, it is
4347 added to the reference counter variable even if added only once to
4348 distinguish between an empty path-like variable and a path-like variable
4349 containing an empty string as single element.
4350
4351 .. only:: html
4352
4353 .. versionadded:: 4.0
4354
4355 .. versionchanged:: 5.0
4356 Variable renamed from ``<VAR>_modshare`` to ``__MODULES_SHARE_<VAR>``
4357
4358 .. versionchanged:: 5.0
4359 Elements are added to the reference counter variable only if added more
4360 than one time in the relative path-like variable
4361
4362
4363 .. envvar:: _LMFILES_
4364
4365 A colon separated list of the full pathname for all loaded *modulefiles*.
4366
4367 This environment variable is generated by :command:`module` command and
4368 should not be modified externally.
4369
4370 .. envvar:: LOADEDMODULES
4371
4372 A colon separated list of all loaded *modulefiles*.
4373
4374 This environment variable is generated by :command:`module` command and
4375 should not be modified externally.
4376
4377 .. envvar:: MODULECONTACT
4378
4379 Email address to contact in case any issue occurs during the interpretation
4380 of modulefiles.
4381
4382 This environment variable value supersedes the default value set in the
4383 :mconfig:`contact` configuration option. It can be defined with the
4384 :subcmd:`config` sub-command.
4385
4386 .. only:: html
4387
4388 .. versionadded:: 4.0
4389
4390 .. envvar:: MODULEPATH
4391
4392 The path that the :command:`module` command searches when looking for
4393 *modulefiles*. Typically, it is set to the main *modulefiles* directory,
4394 |file modulefilesdir|, by the initialization script. :envvar:`MODULEPATH`
4395 can be set using :subcmd:`module use<use>` or by the module initialization
4396 script to search group or personal *modulefile* directories before or after
4397 the main *modulefile* directory.
4398
4399 Path elements registered in the :envvar:`MODULEPATH` environment variable may
4400 contain reference to environment variables which are converted to their
4401 corresponding value by :command:`module` command each time it looks at the
4402 :envvar:`MODULEPATH` value. If an environment variable referred in a path
4403 element is not defined, its reference is converted to an empty string.
4404
4405 .. envvar:: MODULERCFILE
4406
4407 The location of a global run-command file(s) containing *modulefile* specific
4408 setup. See `Modulecmd startup`_ section for detailed information.
4409
4410 Several global run-command files may be defined in this environment variable
4411 by separating each of them by colon character.
4412
4413 This environment variable value supersedes the default value set in the
4414 :mconfig:`rcfile` configuration option. It can be defined with the
4415 :subcmd:`config` sub-command.
4416
4417 .. envvar:: MODULES_ABORT_ON_ERROR
4418
4419 A colon separated list of the module sub-commands that abort their evaluation
4420 sequence when an error is raised by an evaluated module. When error occurs,
4421 evaluations already done are withdrawn and the remaining modules to evaluate
4422 are skipped.
4423
4424 Accepted sub-commands that can be set in value list are:
4425
4426 * :subcmd:`load`
4427 * :command:`ml`
4428 * :subcmd:`mod-to-sh`
4429 * :subcmd:`purge`
4430 * :subcmd:`reload`
4431 * :subcmd:`switch`
4432 * :subcmd:`switch_unload<switch>`
4433 * :subcmd:`try-load`
4434 * :subcmd:`unload`
4435
4436 Module sub-commands not configured to follow the *abort on error* behavior,
4437 apply the *continue on error* behavior. In this case if one modulefile
4438 evaluation fails, sequence continues with remaining modulefiles. When
4439 :option:`--force` option is used, *continue on error* behavior applies.
4440
4441 This environment variable value supersedes the default value set in the
4442 :mconfig:`abort_on_error` configuration option. It can be defined with the
4443 :subcmd:`config` sub-command.
4444
4445 .. only:: html
4446
4447 .. versionadded:: 5.4
4448
4449 .. envvar:: MODULES_ADVANCED_VERSION_SPEC
4450
4451 If set to ``1``, enable advanced module version specifiers (see `Advanced
4452 module version specifiers`_ section). If set to ``0``, disable advanced
4453 module version specifiers.
4454
4455 This environment variable value supersedes the default value set in the
4456 :mconfig:`advanced_version_spec` configuration option. It can be defined with
4457 the :subcmd:`config` sub-command.
4458
4459 .. only:: html
4460
4461 .. versionadded:: 4.4
4462
4463 .. _MODULES_AUTO_HANDLING:
4464
4465 .. envvar:: MODULES_AUTO_HANDLING
4466
4467 If set to ``1``, enable automated module handling mode. If set to ``0``
4468 disable automated module handling mode. Other values are ignored.
4469
4470 Automated module handling mode consists in additional actions triggered when
4471 loading or unloading a *modulefile* to satisfy the constraints it declares.
4472 When loading a *modulefile*, following actions are triggered:
4473
4474 * Conflict Unload: unload of the *modulefiles* declared as a
4475 :mfcmd:`conflict` of the loading *modulefile* or if it is the same
4476 *modulefile* than the one loading but with a different set of variant or
4477 coming from a different modulepath.
4478
4479 * Requirement Load: load of the *modulefiles* declared as a :mfcmd:`prereq`
4480 of the loading *modulefile*.
4481
4482 * Useless Requirement Unload: unload of the :mfcmd:`prereq` modulefiles that
4483 have been automatically loaded for either an unloaded conflicting
4484 modulefile or a modulefile part of this useless requirement unloading
4485 batch. Modulefiles are added to this unloading batch only if they are not
4486 required by any other loaded modulefiles and if they are not tagged
4487 ``keep-loaded``, ``sticky`` or ``super-sticky``.
4488
4489 * Dependent Reload: reload of the modulefiles declaring a :mfcmd:`prereq`
4490 onto loading *modulefile* or declaring a :mfcmd:`prereq` or a :ref:`via
4491 requirement<MODULES_REQUIRE_VIA>` onto a *modulefile* part of this
4492 reloading batch.
4493
4494 When unloading a *modulefile*, following actions are triggered:
4495
4496 * Dependent Unload: unload of the modulefiles declaring a non-optional
4497 :mfcmd:`prereq` or a :ref:`via requirement<MODULES_REQUIRE_VIA>` onto
4498 unloaded modulefile or a modulefile part of this unloading batch. A
4499 :mfcmd:`prereq` modulefile is considered optional if the :mfcmd:`prereq`
4500 definition order is made of multiple modulefiles and at least one
4501 alternative modulefile is loaded.
4502
4503 * Useless Requirement Unload: unload of the :mfcmd:`prereq` modulefiles that
4504 have been automatically loaded for either the unloaded modulefile, an
4505 unloaded dependent modulefile or a modulefile part of this useless
4506 requirement unloading batch. Modulefiles are added to this unloading batch
4507 only if they are not required by any other loaded modulefiles and if they
4508 are not tagged ``keep-loaded``, ``sticky`` or ``super-sticky``.
4509
4510 * Dependent Reload: reload of the modulefiles declaring a :mfcmd:`conflict`
4511 or an optional :mfcmd:`prereq` onto either the unloaded modulefile, an
4512 unloaded dependent or an unloaded useless requirement or declaring a
4513 :mfcmd:`prereq` or a :ref:`via requirement<MODULES_REQUIRE_VIA>` onto a
4514 modulefile part of this reloading batch.
4515
4516 In case a loaded *modulefile* has some of its declared constraints
4517 unsatisfied (pre-required modulefile not loaded or conflicting modulefile
4518 loaded for instance), this loaded *modulefile* is excluded from the automatic
4519 reload actions described above.
4520
4521 For the specific case of the :subcmd:`switch` sub-command, where a modulefile
4522 is unloaded to then load another modulefile. Dependent modulefiles to Unload
4523 are merged into the Dependent modulefiles to Reload that are reloaded after
4524 the load of the switched-to modulefile. Such process also applies to the
4525 Dependent Unload modulefiles of Conflict Unload modules.
4526
4527 The reload phase of all Dependent Reload modulefiles occurs after the
4528 evaluation of the main *modulefile* (either load, unload or switch
4529 evaluation).
4530
4531 The reload phase of a Dependent Reload modulefile is skipped if any of the
4532 following conditions are met:
4533
4534 * The required modules for this modulefile are not loaded.
4535 * A conflict is detected with the currently loaded environment.
4536 * The enabled modulepaths have changed, and the modulefile is no longer
4537 available.
4538
4539 However, reload is always attempted if the modulefile is tagged as
4540 ``super-sticky`` or ``sticky``, and force mode is not enabled. *Abort on
4541 error* behavior is applied if reload of such module kind fails whatever the
4542 value of the :mconfig:`abort_on_error` configuration option. Dependent
4543 Reload modulefiles whose reload has been skipped are treated as Dependent
4544 Unload modulefiles.
4545
4546 Conflict Unload mechanism is activated only if :mconfig:`conflict_unload`
4547 configuration option is also enabled.
4548
4549 This environment variable value supersedes the default value set on the
4550 :mconfig:`auto_handling` configuration option. It can be defined with the
4551 :subcmd:`config` sub-command. The :option:`--auto` and :option:`--no-auto`
4552 command line switches override this environment variable.
4553
4554 .. only:: html
4555
4556 .. versionadded:: 4.2
4557
4558 .. versionchanged:: 5.1
4559 Modules with keep-loaded tag set are excluded from Useless Requirement
4560 Unload mechanism
4561
4562 .. versionchanged:: 5.5
4563 Modules with sticky or super-sticky tag set are excluded from Useless
4564 Requirement Unload mechanism
4565
4566 .. versionchanged:: 5.5
4567 Conflict Unload and Useless Requirement Unload mechanisms added on
4568 module load context
4569
4570 .. versionchanged:: 5.5
4571 Reload of a Dependent Reload module is skipped if it is not loadable
4572
4573 .. versionchanged:: 5.5
4574 Reload of all Dependent Reload modules occurs after the main evaluation
4575
4576 .. versionchanged:: 5.6
4577 *Abort on error* behavior is always applied if reload of a Dependent
4578 Reload sticky or super-sticky module fails
4579
4580 .. envvar:: MODULES_AVAIL_INDEPTH
4581
4582 If set to ``1``, enable in depth search results for :subcmd:`avail`
4583 sub-command. If set to ``0`` disable :subcmd:`avail` sub-command in depth
4584 mode. Other values are ignored.
4585
4586 When in depth mode is enabled, modulefiles and directories contained in
4587 directories matching search query are also included in search results. When
4588 disabled these modulefiles and directories contained in matching directories
4589 are excluded.
4590
4591 This environment variable value supersedes the default value set in the
4592 :mconfig:`avail_indepth` configuration option. It can be defined with the
4593 :subcmd:`config` sub-command. The :option:`--indepth` and
4594 :option:`--no-indepth` command line switches override this environment
4595 variable.
4596
4597 .. only:: html
4598
4599 .. versionadded:: 4.3
4600
4601 .. envvar:: MODULES_AVAIL_OUTPUT
4602
4603 A colon separated list of the elements to report in addition to module names
4604 on :subcmd:`avail` sub-command regular output mode.
4605
4606 Accepted elements that can be set in value list are:
4607
4608 * ``alias``: module aliases.
4609 * ``provided-alias``: show module aliases and evaluate all modulefiles to get
4610 aliases provided by them.
4611 * ``dirwsym``: directories associated with symbolic versions.
4612 * ``hidden``: show all hidden modules.
4613 * ``indesym``: symbolic versions reported independently from the module or
4614 directory they are attached to.
4615 * ``key``: legend appended at the end of the output to explain it.
4616 * ``modulepath``: modulepath names set as header prior the list of available
4617 modules found in them.
4618 * ``sym``: symbolic versions associated with available modules.
4619 * ``tag``: tags associated with available modules.
4620 * ``variant``: variants and their possible values associated with available
4621 modules.
4622 * ``variantifspec``: like ``variant`` but only if a variant has been
4623 specified in search query.
4624 * ``via``: mention next to modulepath name which loaded module enables it if
4625 any.
4626
4627 The order of the elements in the list does not matter. Module names are the
4628 only content reported when *LIST* is set to an empty value.
4629
4630 In case the ``modulepath`` element is missing from value list, the available
4631 modules from global/user rc and all enabled modulepaths are reported as a
4632 single list.
4633
4634 When ``indesym`` element is set, ``dirwsym`` and ``sym`` elements are
4635 disabled.
4636
4637 This environment variable value supersedes the default value set in the
4638 :mconfig:`avail_output` configuration option. It can be defined with
4639 the :subcmd:`config` sub-command. The :option:`--output`/:option:`-o` command
4640 line switches override this environment variable.
4641
4642 .. only:: html
4643
4644 .. versionadded:: 4.7
4645
4646 .. versionchanged:: 5.3
4647 Elements ``variant`` and ``variantifspec`` added
4648
4649 .. versionchanged:: 5.3.1
4650 Element ``indesym`` added
4651
4652 .. versionchanged:: 5.6
4653 Elements ``hidden``, ``provided-alias`` and ``via`` added
4654
4655 .. envvar:: MODULES_AVAIL_TERSE_OUTPUT
4656
4657 A colon separated list of the elements to report in addition to module names
4658 on :subcmd:`avail` sub-command terse output mode.
4659
4660 See :envvar:`MODULES_AVAIL_OUTPUT` to get the accepted elements that can be
4661 set in value list. Exception for ``via`` element which is not accepted for
4662 terse output mode.
4663
4664 The order of the elements in the list does not matter. Module names are the
4665 only content reported when *LIST* is set to an empty value.
4666
4667 This environment variable value supersedes the default value set in the
4668 :mconfig:`avail_terse_output` configuration option. It can be defined with
4669 the :subcmd:`config` sub-command. The :option:`--output`/:option:`-o`
4670 command line switches override this environment variable.
4671
4672 .. only:: html
4673
4674 .. versionadded:: 4.7
4675
4676 .. versionchanged:: 5.3
4677 Elements ``variant`` and ``variantifspec`` added
4678
4679 .. versionchanged:: 5.6
4680 Elements ``hidden`` and ``provided-alias`` added
4681
4682 .. envvar:: MODULES_CACHE_BUFFER_BYTES
4683
4684 Size of the buffer used when reading or writing cache files. Accepted values
4685 are integers comprised between 4096 and 1000000.
4686
4687 .. only:: html
4688
4689 .. versionadded:: 5.3
4690
4691 .. envvar:: MODULES_CACHE_EXPIRY_SECS
4692
4693 Number of seconds a cache file is considered valid after being generated. For
4694 example, if set to ``3600`` it means a cache file expires one hour after
4695 being generated and is then ignored.
4696
4697 When set to ``0`` cache file never expires. Accepted values are integers
4698 comprised between 0 (cache files never expire) and 31536000 (equivalent to
4699 one year duration).
4700
4701 .. only:: html
4702
4703 .. versionadded:: 5.3
4704
4705 .. envvar:: MODULES_CMD
4706
4707 The location of the active module command script.
4708
4709 This environment variable is generated by :command:`module` command and
4710 should not be modified externally.
4711
4712 .. only:: html
4713
4714 .. versionadded:: 4.1
4715
4716 .. envvar:: MODULES_COLLECTION_PIN_VERSION
4717
4718 If set to ``1``, register exact version number of modulefiles when saving a
4719 collection. Otherwise modulefile version number is omitted if it corresponds
4720 to the explicitly set default version and also to the implicit default when
4721 the configuration option :mconfig:`implicit_default` is enabled.
4722
4723 This environment variable value supersedes the default value set in the
4724 :mconfig:`collection_pin_version` configuration option. It can be defined
4725 with the :subcmd:`config` sub-command.
4726
4727 .. only:: html
4728
4729 .. versionadded:: 4.1
4730
4731 .. envvar:: MODULES_COLLECTION_PIN_TAG
4732
4733 If set to ``1``, register all tags applying to modulefiles when saving a
4734 collection. Otherwise only the extra tags set through the :option:`--tag`
4735 option and tags resulting from specific module states (like ``auto-loaded``
4736 and ``keep-loaded`` tags) are recorded in collection. Note that the
4737 ``nearly-forbidden`` tag due to its temporal meaning is not saved in
4738 collection even when this configuration option is enabled.
4739
4740 This environment variable value supersedes the default value set in the
4741 :mconfig:`collection_pin_tag` configuration option. It can be defined with
4742 the :subcmd:`config` sub-command.
4743
4744 .. only:: html
4745
4746 .. versionadded:: 5.1
4747
4748 .. envvar:: MODULES_COLLECTION_TARGET
4749
4750 The collection target that determines what collections are valid thus
4751 reachable on the current system.
4752
4753 Collection directory may sometimes be shared on multiple machines which may
4754 use different modules setup. For instance modules users may access with the
4755 same :envvar:`HOME` directory multiple systems using different OS versions.
4756 When it happens a collection made on machine 1 may be erroneous on machine 2.
4757
4758 When a target is set, only the collections made for that target are
4759 available to the :subcmd:`restore`, :subcmd:`savelist`, :subcmd:`saveshow`,
4760 :subcmd:`saverm`, :subcmd:`stash`, :subcmd:`stashpop`, :subcmd:`stashlist`,
4761 :subcmd:`stashshow`, and :subcmd:`stashrm` sub-commands. Saving a collection
4762 registers the target footprint by suffixing the collection filename with
4763 ``.$MODULES_COLLECTION_TARGET``. The collection target is not involved when
4764 collection is specified as file path on the :subcmd:`saveshow`,
4765 :subcmd:`restore` and :subcmd:`save` sub-commands.
4766
4767 For example, the :envvar:`MODULES_COLLECTION_TARGET` variable may be set with
4768 results from commands like :command:`lsb_release`, :command:`hostname`,
4769 :command:`dnsdomainname`, etc.
4770
4771 This environment variable value supersedes the default value set in the
4772 :mconfig:`collection_target` configuration option. It can be defined with
4773 the :subcmd:`config` sub-command.
4774
4775 .. only:: html
4776
4777 .. versionadded:: 4.0
4778
4779 .. envvar:: MODULES_COLOR
4780
4781 Defines if output should be colored or not. Accepted values are ``never``,
4782 ``auto`` and ``always``.
4783
4784 When color mode is set to ``auto``, output is colored only if the standard
4785 error output channel is attached to a terminal.
4786
4787 This environment variable value supersedes the default value set in the
4788 :mconfig:`color` configuration option. It can be defined with the
4789 :subcmd:`config` sub-command. The :option:`--color` command line switch
4790 overrides this environment variable.
4791
4792 :envvar:`NO_COLOR`, :envvar:`CLICOLOR` and :envvar:`CLICOLOR_FORCE`
4793 environment variables are also honored to define color mode. The ``never``
4794 mode is set if :envvar:`NO_COLOR` is defined (regardless of its value) or if
4795 :envvar:`CLICOLOR` equals to ``0``. If :envvar:`CLICOLOR` is set to another
4796 value, it corresponds to the ``auto`` mode. The ``always`` mode is set if
4797 :envvar:`CLICOLOR_FORCE` is set to a value different than ``0``.
4798 :envvar:`NO_COLOR` variable prevails over :envvar:`CLICOLOR` and
4799 :envvar:`CLICOLOR_FORCE`. Color mode set with these three variables is
4800 superseded by mode set with :envvar:`MODULES_COLOR` environment variable or
4801 with :option:`--color` command line switch..
4802
4803 .. only:: html
4804
4805 .. versionadded:: 4.3
4806
4807 .. envvar:: MODULES_COLORS
4808
4809 Specifies the colors and other attributes used to highlight various parts of
4810 the output. Its value is a colon-separated list of output items associated to
4811 a Select Graphic Rendition (SGR) code. It follows the same syntax than
4812 :envvar:`LS_COLORS`.
4813
4814 Output items are designated by keys. Items able to be colorized are:
4815 highlighted element (``hi``), debug information (``db``), trace information
4816 (``tr``), tag separator (``se``); Error (``er``), warning (``wa``), module
4817 error (``me``) and info (``in``) message prefixes; Modulepath (``mp``),
4818 directory (``di``), module alias (``al``), module variant (``va``), module
4819 symbolic version (``sy``), module ``default`` version (``de``) and modulefile
4820 command (``cm``).
4821
4822 `Module tags`_ can also be colorized. The key to set in the color palette to
4823 get a graphical rendering of a tag is the tag name or the tag abbreviation if
4824 one is defined for tag. The SGR code applied to a tag name is ignored if an
4825 abbreviation is set for this tag thus the SGR code should be defined for this
4826 abbreviation to get a graphical rendering. Each basic tag has by default a
4827 key set in the color palette, based on its abbreviated string: auto-loaded
4828 (``aL``), forbidden (``F``), hidden and hidden-loaded (``H``), loaded
4829 (``L``), nearly-forbidden (``nF``), sticky (``S``), super-sticky (``sS``),
4830 keep-loaded (``kL``) and warning (``W``).
4831
4832 See the Select Graphic Rendition (SGR) section in the documentation of the
4833 text terminal that is used for permitted values and their meaning as
4834 character attributes. These substring values are integers in decimal
4835 representation and can be concatenated with semicolons. Modules takes care of
4836 assembling the result into a complete SGR sequence (``\33[...m``). Common
4837 values to concatenate include ``1`` for bold, ``4`` for underline, ``30`` to
4838 ``37`` for foreground colors and ``90`` to ``97`` for 16-color mode
4839 foreground colors. See also https://en.wikipedia.org/wiki/ANSI_escape_code#Select_Graphic_Rendition_parameters
4840 for a complete SGR code reference.
4841
4842 No graphical rendition will be applied to an output item that could normally
4843 be colored but which is not defined in the color set. Thus if
4844 :envvar:`MODULES_COLORS` is defined empty, no output will be colored at all.
4845
4846 This environment variable value supersedes the default value set in the
4847 :mconfig:`colors` configuration option. It can be defined with the
4848 :subcmd:`config` sub-command.
4849
4850 .. only:: html
4851
4852 .. versionadded:: 4.3
4853
4854 .. versionchanged:: 4.6
4855 Output item for trace information (``tr``) added
4856
4857 .. versionchanged:: 4.7
4858 Output items for module tags auto-loaded (``aL``), forbidden (``F``),
4859 hidden and hidden-loaded (``H``), loaded (``L``), nearly-forbidden
4860 (``nF``), sticky (``S``) and super-sticky (``sS``) added
4861
4862 .. versionchanged:: 4.8
4863 Output item for module variant (``va``) added
4864
4865 .. versionchanged:: 5.1
4866 Output item for keep-loaded module tag (``kL``) added
4867
4868 .. versionchanged:: 5.6
4869 Output item for warning module tag (``W``) added
4870
4871 .. envvar:: MODULES_CONFLICT_UNLOAD
4872
4873 If set to ``1``, enable automated unload of conflicting modules when loading
4874 a module. If set to ``0``, disable this automated conflict unload mechanism.
4875
4876 Conflict Unload is a mechanism part of the :ref:`automated module handling
4877 mode<MODULES_AUTO_HANDLING>`. To activate this mechanism,
4878 :mconfig:`auto_handling` configuration option should also be enabled.
4879
4880 This environment variable value supersedes the default value set in the
4881 :mconfig:`conflict_unload` configuration option. It can be defined with
4882 the :subcmd:`config` sub-command.
4883
4884 .. only:: html
4885
4886 .. versionadded:: 5.5
4887
4888 .. envvar:: MODULES_EDITOR
4889
4890 Text editor command name or path for use to open modulefile through the
4891 :subcmd:`edit` sub-command.
4892
4893 This environment variable value supersedes the default value set in the
4894 :mconfig:`editor` configuration option. It can be defined with the
4895 :subcmd:`config` sub-command.
4896
4897 Text editor could also be defined through the :envvar:`VISUAL` or
4898 :envvar:`EDITOR` environment variables. These environment variables are
4899 overridden by :envvar:`MODULES_EDITOR`.
4900
4901 .. only:: html
4902
4903 .. versionadded:: 4.8
4904
4905 .. envvar:: MODULES_EXTENDED_DEFAULT
4906
4907 If set to ``1``, a specified module version is matched against starting
4908 portion of existing module versions, where portion is a substring separated
4909 from the rest of the version string by a ``.`` character. For example
4910 specified modules ``mod/1`` and ``mod/1.2`` will match existing modulefile
4911 ``mod/1.2.3``.
4912
4913 In case multiple modulefiles match the specified module version and a single
4914 module has to be selected, the explicitly set default version is returned if
4915 it is part of matching modulefiles. Otherwise the implicit default among
4916 matching modulefiles is returned if defined (see
4917 :envvar:`MODULES_IMPLICIT_DEFAULT` section)
4918
4919 This environment variable value supersedes the default value set in the
4920 :mconfig:`extended_default` configuration option. It can be defined with the
4921 :subcmd:`config` sub-command.
4922
4923 .. only:: html
4924
4925 .. versionadded:: 4.4
4926
4927 .. envvar:: MODULES_FAMILY_<NAME>
4928
4929 Module name minus version that provides for the *name* family in currently
4930 loaded environment. This environment variable is defined through the use of
4931 the :mfcmd:`family` modulefile command.
4932
4933 For instance if loading modulefile ``foo/1.0`` defines being member of the
4934 ``bar`` family, the :envvar:`MODULES_FAMILY_BAR<MODULES_FAMILY_\<NAME\>>`
4935 will be set to the ``foo`` value.
4936
4937 This environment variable is generated by :command:`module` command and
4938 should not be modified externally.
4939
4940 .. only:: html
4941
4942 .. versionadded:: 5.1
4943
4944 .. envvar:: MODULES_HIDE_AUTO_LOADED
4945
4946 If set to ``1``, tag automatically loaded modules ``hidden-loaded``. These
4947 modules will not appear on :subcmd:`list` sub-command unless :option:`--all`
4948 option is set.
4949
4950 This environment variable value supersedes the default value set in the
4951 :mconfig:`hide_auto_loaded` configuration option. It can be defined with the
4952 :subcmd:`config` sub-command.
4953
4954 .. only:: html
4955
4956 .. versionadded:: 5.5
4957
4958 .. envvar:: MODULES_ICASE
4959
4960 When module specification are passed as argument to module sub-commands or
4961 modulefile Tcl commands, defines the case sensitiveness to apply to match
4962 them. When :envvar:`MODULES_ICASE` is set to ``never``, a case sensitive
4963 match is applied in any cases. When set to ``search``, a case insensitive
4964 match is applied to the :subcmd:`avail`, :subcmd:`list`, :subcmd:`whatis`,
4965 :subcmd:`paths`, :subcmd:`savelist` and :subcmd:`spider` sub-commands. When
4966 set to ``always``, a case insensitive match is also applied to the other
4967 module sub-commands and modulefile Tcl commands for the module specification
4968 they receive as argument.
4969
4970 This environment variable value supersedes the default value set in the
4971 :mconfig:`icase` configuration option. It can be defined with the
4972 :subcmd:`config` sub-command. The :option:`--icase`/:option:`-i` command line
4973 switches, which correspond to the ``always`` mode, override this environment
4974 variable.
4975
4976 .. only:: html
4977
4978 .. versionadded:: 4.4
4979
4980 .. versionchanged:: 5.1
4981 Search mode applied to :subcmd:`list` sub-command
4982
4983 .. versionchanged:: 5.2
4984 Search mode applied to :subcmd:`savelist` sub-command
4985
4986 .. versionchanged:: 5.6
4987 Search mode applied to :subcmd:`spider` sub-command
4988
4989 .. envvar:: MODULES_IGNORE_CACHE
4990
4991 Ignore (if set to ``1``) or not (if set to ``0``) module cache.
4992
4993 This environment variable value supersedes the default value set in the
4994 :mconfig:`ignore_cache` configuration option. It can be defined with the
4995 :subcmd:`config` sub-command. The :option:`--ignore-cache` command line
4996 switch overrides this environment variable.
4997
4998 .. only:: html
4999
5000 .. versionadded:: 5.3
5001
5002 .. envvar:: MODULES_IGNORE_USER_RC
5003
5004 Skip evaluation (if set to ``1``) or not (if set to ``0``) of user-specific
5005 module rc file (:file:`$HOME/.modulerc`).
5006
5007 This environment variable value supersedes the default value set in the
5008 :mconfig:`ignore_user_rc` configuration option. It can be defined with the
5009 :subcmd:`config` sub-command. The :option:`--ignore-user-rc` command line
5010 switch overrides this environment variable.
5011
5012 .. only:: html
5013
5014 .. versionadded:: 5.3
5015
5016 .. envvar:: MODULES_IMPLICIT_DEFAULT
5017
5018 Defines (if set to ``1``) or not (if set to ``0``) an implicit default
5019 version for modules without a default version explicitly defined (see
5020 :ref:`Locating Modulefiles` section in the :ref:`modulefile(5)` man page).
5021
5022 Without either an explicit or implicit default version defined a module must
5023 be fully qualified (version should be specified in addition to its name) to
5024 get:
5025
5026 * targeted by module :subcmd:`load`, :subcmd:`switch`, :subcmd:`display`,
5027 :subcmd:`help`, :subcmd:`test` and :subcmd:`path` sub-commands.
5028
5029 * restored from a collection, unless already loaded in collection-specified
5030 order.
5031
5032 * automatically loaded by :ref:`automated module handling
5033 mechanisms<MODULES_AUTO_HANDLING>` when declared as module requirement,
5034 with :mfcmd:`prereq` or :mfcmd:`module load<module>` modulefile commands.
5035
5036 An error is returned in the above situations if either no explicit or
5037 implicit default version is defined.
5038
5039 This environment variable value supersedes the default value set in the
5040 :mconfig:`implicit_default` configuration option. It can be defined with the
5041 :subcmd:`config` sub-command. This environment variable is ignored if
5042 :mconfig:`implicit_default` has been declared locked in
5043 :mconfig:`locked_configs` configuration option.
5044
5045 .. only:: html
5046
5047 .. versionadded:: 4.3
5048
5049 .. envvar:: MODULES_IMPLICIT_REQUIREMENT
5050
5051 Defines (if set to ``1``) or not (if set to ``0``) an implicit prereq or
5052 conflict requirement onto modules specified respectively on
5053 :mfcmd:`module load<module>` or :mfcmd:`module unload<module>` commands in
5054 modulefile. When enabled an implicit conflict requirement onto switched-off
5055 module and a prereq requirement onto switched-on module are also defined for
5056 :mfcmd:`module switch <module>` commands used in modulefile.
5057
5058 This environment variable value supersedes the default value set in the
5059 :mconfig:`implicit_requirement` configuration option. It can be defined with
5060 the :subcmd:`config` sub-command. The ``--not-req`` option, applied to a
5061 :mfcmd:`module` command in a modulefile, overrides this environment variable.
5062
5063 .. only:: html
5064
5065 .. versionadded:: 4.7
5066
5067 .. envvar:: MODULES_LIST_OUTPUT
5068
5069 A colon separated list of the elements to report in addition to module names
5070 on :subcmd:`list` sub-command regular output mode.
5071
5072 Accepted elements that can be set in value list are:
5073
5074 * ``alias``: module aliases targeting loaded modules.
5075 * ``header``: sentence to introduce the list of loaded modules or to state
5076 that no modules are loaded currently.
5077 * ``hidden``: show hidden loaded modules.
5078 * ``idx``: index position of each loaded module.
5079 * ``indesym``: symbolic versions reported independently from the loaded
5080 module they are attached to.
5081 * ``key``: legend appended at the end of the output to explain it.
5082 * ``variant``: variant values selected for loaded modules.
5083 * ``sym``: symbolic versions associated with loaded modules.
5084 * ``tag``: tags associated with loaded modules.
5085
5086 The order of the elements in the list does not matter. Module names are the
5087 only content reported when *LIST* is set to an empty value.
5088
5089 This environment variable value supersedes the default value set in the
5090 :mconfig:`list_output` configuration option. It can be defined with the
5091 :subcmd:`config` sub-command. The :option:`--output`/:option:`-o` command
5092 line switches override this environment variable.
5093
5094 .. only:: html
5095
5096 .. versionadded:: 4.7
5097
5098 .. versionchanged:: 4.8
5099 Element ``variant`` added
5100
5101 .. versionchanged:: 5.4
5102 Elements ``alias`` and ``indesym`` added
5103
5104 .. versionchanged:: 5.6
5105 Element ``hidden`` added
5106
5107 .. envvar:: MODULES_LIST_TERSE_OUTPUT
5108
5109 A colon separated list of the elements to report in addition to module names
5110 on :subcmd:`list` sub-command terse output mode.
5111
5112 See :envvar:`MODULES_LIST_OUTPUT` to get the accepted elements that can be
5113 set in value list.
5114
5115 The order of the elements in the list does not matter. Module names are the
5116 only content reported when *LIST* is set to an empty value.
5117
5118 This environment variable value supersedes the default value set in the
5119 :mconfig:`list_terse_output` configuration option. It can be defined with the
5120 :subcmd:`config` sub-command. The :option:`--output`/:option:`-o` command
5121 line switches override this environment variable.
5122
5123 .. only:: html
5124
5125 .. versionadded:: 4.7
5126
5127 .. versionchanged:: 4.8
5128 Element ``variant`` added
5129
5130 .. versionchanged:: 5.4
5131 Elements ``alias`` and ``indesym`` added
5132
5133 .. versionchanged:: 5.6
5134 Element ``hidden`` added
5135
5136 .. envvar:: MODULES_LOGGED_EVENTS
5137
5138 A colon separated list of the events to log. Accepted events that can be set
5139 in value list are:
5140
5141 * ``auto_eval``: log automatically triggered modulefile evaluations
5142 * ``requested_eval``: log modulefile evaluations directly requested by user
5143 * ``requested_cmd``: log module commands directly requested by user
5144
5145 This environment variable value supersedes the default value set in the
5146 :mconfig:`logged_events` configuration option. It can be defined with the
5147 :subcmd:`config` sub-command. This environment variable is ignored if
5148 :mconfig:`logged_events` has been declared locked in
5149 :mconfig:`locked_configs` configuration option.
5150
5151 .. only:: html
5152
5153 .. versionadded:: 5.5
5154
5155 .. envvar:: MODULES_LOGGER
5156
5157 Command to log informational messages. The value of this variable is composed
5158 of a logger command name or path eventually followed by command-line options.
5159
5160 This environment variable value supersedes the default value set in the
5161 :mconfig:`logger` configuration option. It can be defined with the
5162 :subcmd:`config` sub-command. This environment variable is ignored if
5163 :mconfig:`logger` has been declared locked in :mconfig:`locked_configs`
5164 configuration option.
5165
5166 If :envvar:`MODULES_LOGGER` variable is set to an empty string, logger
5167 will not be launched.
5168
5169 .. only:: html
5170
5171 .. versionadded:: 5.5
5172
5173 .. envvar:: MODULES_MCOOKIE_CHECK
5174
5175 If set to ``eval``, the Modules magic cookie (i.e., ``#%Module``
5176 file signature) is only checked to determine if a file is a modulefile when
5177 evaluating these files. If set to ``always``, the Modules magic cookie is
5178 also checked when searching for modules.
5179
5180 The ``eval`` mode is made to significantly reduce file checks when walking
5181 through modulepaths to search for *modulefiles*. Special care should be given
5182 to the content of modulepaths when this ``eval`` mode is set as the following
5183 kind of files are included in search results:
5184
5185 * *modulefiles* with a magic cookie requiring a higher version of
5186 :file:`modulecmd.tcl`
5187 * files not beginning with the magic cookie ``#%Module``
5188 * read-protected files
5189
5190 When a :ref:`module cache<Module cache>` file is available for a given
5191 modulepath, ``eval`` mode is not applied as cache content is generated in
5192 ``always`` mode.
5193
5194 This environment variable value supersedes the default value set in the
5195 :mconfig:`mcookie_check` configuration option. It can be defined with the
5196 :subcmd:`config` sub-command.
5197
5198 .. only:: html
5199
5200 .. versionadded:: 5.1
5201
5202 .. envvar:: MODULES_MCOOKIE_VERSION_CHECK
5203
5204 If set to ``1``, the version set in the Modules magic cookie in modulefile
5205 is checked against the current version of :file:`modulecmd.tcl` to determine
5206 if the modulefile can be evaluated.
5207
5208 When a :ref:`module cache<Module cache>` file is available for a given
5209 modulepath, version check is considered enabled as cache content is generated
5210 in this mode.
5211
5212 This environment variable value supersedes the default value set in the
5213 :mconfig:`mcookie_version_check` configuration option. It can be defined with
5214 the :subcmd:`config` sub-command.
5215
5216 .. only:: html
5217
5218 .. versionadded:: 4.7
5219
5220 .. envvar:: MODULES_ML
5221
5222 If set to ``1``, define :command:`ml` command when initializing Modules (see
5223 `Package Initialization`_ section). If set to ``0``, :command:`ml` command is
5224 not defined.
5225
5226 This environment variable value supersedes the default value set in the
5227 :mconfig:`ml` configuration option. It can be defined with the
5228 :subcmd:`config` sub-command.
5229
5230 To enable or disable :command:`ml` command, :envvar:`MODULES_ML` should be set
5231 prior Modules initialization or the :mconfig:`ml` configuration option should
5232 be set in the :file:`initrc` configuration file.
5233
5234 .. only:: html
5235
5236 .. versionadded:: 4.5
5237
5238 .. envvar:: MODULES_NEARLY_FORBIDDEN_DAYS
5239
5240 Number of days a module is considered *nearly forbidden* prior reaching its
5241 expiry date set by :mfcmd:`module-forbid` modulefile command. When a *nearly
5242 forbidden* module is evaluated a warning message is issued to inform module
5243 will soon be forbidden. If set to ``0``, modules will never be considered
5244 *nearly forbidden*. Accepted values are integers comprised between 0 and 365.
5245
5246 This environment variable value supersedes the default value set in the
5247 :mconfig:`nearly_forbidden_days` configuration option. It can be defined with
5248 the :subcmd:`config` sub-command.
5249
5250 .. only:: html
5251
5252 .. versionadded:: 4.6
5253
5254 .. envvar:: MODULES_PAGER
5255
5256 Text viewer for use to paginate message output if error output stream is
5257 attached to a terminal. The value of this variable is composed of a pager
5258 command name or path eventually followed by command-line options.
5259
5260 This environment variable value supersedes the default value set in the
5261 :mconfig:`pager` configuration option. It can be defined with the
5262 :subcmd:`config` sub-command.
5263
5264 If :envvar:`MODULES_PAGER` variable is set to an empty string or to the value
5265 ``cat``, pager will not be launched.
5266
5267 Pager is never launched if :file:`modulecmd.tcl` program is run for scripting
5268 language rather shells.
5269
5270 .. only:: html
5271
5272 .. versionadded:: 4.1
5273
5274 .. versionchanged:: 5.5
5275 No pager when :file:`modulecmd.tcl` is run for scripting languages
5276
5277 .. envvar:: MODULES_PROTECTED_ENVVARS
5278
5279 A colon separated list of environment variable names that should not be
5280 modified by any modulefile command.
5281
5282 Prevents modifications by :mfcmd:`append-path`, :mfcmd:`prepend-path`,
5283 :mfcmd:`remove-path`, :mfcmd:`setenv` and :mfcmd:`unsetenv`. When these
5284 modulefile commands attempt to modify a protected environment variable,
5285 a warning message is emitted and modification is ignored.
5286
5287 This environment variable value supersedes the default value set in the
5288 :mconfig:`protected_envvars` configuration option. It can be defined with the
5289 :subcmd:`config` sub-command.
5290
5291 .. only:: html
5292
5293 .. versionadded:: 5.2
5294
5295 .. envvar:: MODULES_QUARANTINE_SUPPORT
5296
5297 If set to ``1``, produces the shell code for quarantine mechanism when the
5298 :subcmd:`autoinit` sub-command generates the :command:`module` shell
5299 function.
5300
5301 The generated shell code for quarantine mechanism indirectly passes the
5302 environment variable defined in :envvar:`MODULES_RUN_QUARANTINE` to the
5303 :file:`modulecmd.tcl` script to protect its run-time environment from
5304 side-effect coming from the current definition of these variables.
5305
5306 To enable quarantine support, :envvar:`MODULES_QUARANTINE_SUPPORT` should be
5307 set to ``1`` prior Modules initialization or the
5308 :mconfig:`quarantine_support` configuration should be set to ``1`` in the
5309 :file:`initrc` configuration file.
5310
5311 Generated code for quarantine mechanism sets the
5312 :envvar:`__MODULES_QUARANTINE_SET` environment variable when calling the
5313 :file:`modulecmd.tcl` script to make it restore the environment variable put
5314 in quarantine.
5315
5316 This environment variable value supersedes the default value set in the
5317 :mconfig:`quarantine_support` configuration option. It can be defined with
5318 the :subcmd:`config` sub-command.
5319
5320 .. only:: html
5321
5322 .. versionadded:: 5.0
5323
5324 .. envvar:: MODULES_REDIRECT_OUTPUT
5325
5326 If set to ``0``, the output generated by module command is kept on stderr and
5327 not redirected to stdout channel.
5328
5329 This environment variable value supersedes the default value set in the
5330 :mconfig:`redirect_output` configuration option. It can be defined with
5331 the :subcmd:`config` sub-command. The :option:`--redirect` and
5332 :option:`--no-redirect` command line switches override this environment
5333 variable.
5334
5335 .. only:: html
5336
5337 .. versionadded:: 5.1
5338
5339 .. _MODULES_REQUIRE_VIA:
5340
5341 .. envvar:: MODULES_REQUIRE_VIA
5342
5343 If set to ``1``, consider loaded module that enables a modulepath (through
5344 the use of the modulefile commands :mfcmd:`module use<module>`,
5345 :mfcmd:`append-path MODULEPATH<append-path>`, or :mfcmd:`prepend-path
5346 MODULEPATH<prepend-path>`) a requirement for loaded modules stored in this
5347 modulepath. If set to ``0``, no dependency is made between these modules.
5348
5349 This environment variable value supersedes the default value set in the
5350 :mconfig:`require_via` configuration option. It can be defined with the
5351 :subcmd:`config` sub-command.
5352
5353 .. only:: html
5354
5355 .. versionadded:: 5.6
5356
5357 .. envvar:: MODULES_RESET_TARGET_STATE
5358
5359 Defines behavior of :subcmd:`reset` sub-command. When set to ``__init__``,
5360 initial environment is restored. When set to ``__purge__``, :subcmd:`reset`
5361 performs a :subcmd:`purge` sub-command. Any other value designates a name
5362 collection to :subcmd:`restore`.
5363
5364 This environment variable value supersedes the default value set in the
5365 :mconfig:`reset_target_state` configuration option. It can be defined with
5366 the :subcmd:`config` sub-command.
5367
5368 .. only:: html
5369
5370 .. versionadded:: 5.2
5371
5372 .. envvar:: MODULES_RUN_QUARANTINE
5373
5374 A space separated list of environment variable names that should be passed
5375 indirectly to :file:`modulecmd.tcl` to protect its run-time environment from
5376 side-effect coming from their current definition.
5377
5378 If the quarantine mechanism has been included in :command:`module` shell
5379 function (see :envvar:`MODULES_QUARANTINE_SUPPORT`), each variable found in
5380 :envvar:`MODULES_RUN_QUARANTINE` will have its value emptied or set to the
5381 value of the corresponding :envvar:`MODULES_RUNENV_\<VAR\>` variable when
5382 defining :file:`modulecmd.tcl` run-time environment.
5383
5384 Original values of these environment variables set in quarantine are passed
5385 to :file:`modulecmd.tcl` via :envvar:`__MODULES_QUAR_\<VAR\>` variables.
5386
5387 This environment variable value supersedes the default value set in the
5388 :mconfig:`run_quarantine` configuration option. It can be defined with the
5389 :subcmd:`config` sub-command.
5390
5391 .. only:: html
5392
5393 .. versionadded:: 4.1
5394
5395 .. envvar:: MODULES_RUNENV_<VAR>
5396
5397 Value to set to environment variable :envvar:`<VAR>` for
5398 :file:`modulecmd.tcl` run-time execution if :envvar:`<VAR>` is referred in
5399 :envvar:`MODULES_RUN_QUARANTINE`.
5400
5401 .. only:: html
5402
5403 .. versionadded:: 4.1
5404
5405 .. envvar:: MODULES_SEARCH_MATCH
5406
5407 When searching for modules with :subcmd:`avail`, :subcmd:`list`,
5408 :subcmd:`spider` or collections with :subcmd:`savelist` sub-commands, defines
5409 the way query string should match against available module/collection names.
5410 With ``starts_with`` value, returned modules/collections are those whose
5411 name begins by search query string. When set to ``contains``, any
5412 modules/collections whose fully qualified name contains search query string
5413 are returned.
5414
5415 This environment variable value supersedes the default value set in the
5416 :mconfig:`search_match` configuration option. It can be defined with the
5417 :subcmd:`config` sub-command. The :option:`--starts-with` and
5418 :option:`--contains` command line switches override this environment
5419 variable.
5420
5421 .. only:: html
5422
5423 .. versionadded:: 4.3
5424
5425 .. versionchanged:: 5.1
5426 Support for :subcmd:`list` sub-command added
5427
5428 .. versionchanged:: 5.2
5429 Support for :subcmd:`savelist` sub-command added
5430
5431 .. versionchanged:: 5.6
5432 Support for :subcmd:`spider` sub-command added
5433
5434 .. envvar:: MODULES_SET_SHELL_STARTUP
5435
5436 If set to ``1``, defines when :command:`module` command initializes the shell
5437 startup file to ensure that the :command:`module` command is still defined in
5438 sub-shells. Setting shell startup file means defining the :envvar:`ENV` and
5439 :envvar:`BASH_ENV` environment variable to the Modules bourne shell
5440 initialization script. If set to ``0``, shell startup file is not defined.
5441
5442 This environment variable value supersedes the default value set in the
5443 :mconfig:`set_shell_startup` configuration option. It can be defined with the
5444 :subcmd:`config` sub-command.
5445
5446 To enable shell startup file, :envvar:`MODULES_SET_SHELL_STARTUP` should be
5447 set to ``1`` prior Modules initialization or the :mconfig:`set_shell_startup`
5448 configuration option should be set to ``1`` in the :file:`initrc`
5449 configuration file.
5450
5451 .. only:: html
5452
5453 .. versionadded:: 4.3
5454
5455 .. envvar:: MODULES_SHELLS_WITH_KSH_FPATH
5456
5457 A list of shell on which the :envvar:`FPATH` environment variable should be
5458 defined at initialization time to point to the :file:`ksh-functions`
5459 directory where the ksh initialization script for module command is located.
5460 It enables for the listed shells to get module function defined when starting
5461 ksh as sub-shell from there.
5462
5463 Accepted values are a list of shell among *sh*, *bash*, *csh*, *tcsh* and
5464 *fish* separated by colon character (``:``).
5465
5466 This environment variable value supersedes the default value set in the
5467 :mconfig:`shells_with_ksh_fpath` configuration option. It can be defined with
5468 the :subcmd:`config` sub-command.
5469
5470 To enable the setup of :envvar:`FPATH` for some shells,
5471 :envvar:`MODULES_SHELLS_WITH_KSH_FPATH` should be set to the list of these
5472 shells prior Modules initialization or the :mconfig:`shells_with_ksh_fpath`
5473 configuration option should be set to the list of these shells in the
5474 :file:`initrc` configuration file.
5475
5476 .. only:: html
5477
5478 .. versionadded:: 4.7
5479
5480 .. envvar:: MODULES_SILENT_SHELL_DEBUG
5481
5482 If set to ``1``, disable any ``xtrace`` or ``verbose`` debugging property set
5483 on current shell session for the duration of either the :command:`module`
5484 command or the module shell initialization script. Only applies to Bourne
5485 Shell (sh) and its derivatives.
5486
5487 This environment variable value supersedes the default value set in the
5488 :mconfig:`silent_shell_debug` configuration option. It can be defined with the
5489 :subcmd:`config` sub-command.
5490
5491 To generate the code to silence shell debugging property in the
5492 :command:`module` shell function, :envvar:`MODULES_SILENT_SHELL_DEBUG` should
5493 be set to ``1`` prior Modules initialization or the
5494 :mconfig:`silent_shell_debug` configuration option should be set to ``1`` in
5495 the :file:`initrc` configuration file.
5496
5497 .. only:: html
5498
5499 .. versionadded:: 4.1
5500
5501 .. envvar:: MODULES_SITECONFIG
5502
5503 Location of a site-specific configuration script to source into
5504 :file:`modulecmd.tcl`. See :ref:`Site-specific configuration` section for
5505 details.
5506
5507 This environment variable value supersedes the default value set in the
5508 :mconfig:`extra_siteconfig` configuration option. It can be defined with the
5509 :subcmd:`config` sub-command. This environment variable is ignored if
5510 :mconfig:`extra_siteconfig` has been declared locked in
5511 :mconfig:`locked_configs` configuration option.
5512
5513 .. only:: html
5514
5515 .. versionadded:: 4.3
5516
5517 .. envvar:: MODULES_SOURCE_CACHE
5518
5519 If set to ``1``, cache content of files evaluated in modulefile through
5520 :manpage:`source(n)` Tcl command. When same file is sourced multiple times,
5521 cached content is reused rather reading file again.
5522
5523 This environment variable value supersedes the default value set in the
5524 :mconfig:`source_cache` configuration option. It can be defined with the
5525 :subcmd:`config` sub-command.
5526
5527 .. only:: html
5528
5529 .. versionadded:: 5.4
5530
5531 .. envvar:: MODULES_SPIDER_INDEPTH
5532
5533 If set to ``1``, enable in depth search results for :subcmd:`spider`
5534 sub-command. If set to ``0`` disable :subcmd:`spider` sub-command in depth
5535 mode. Other values are ignored.
5536
5537 When in depth mode is enabled, modulefiles and directories contained in
5538 directories matching search query are also included in search results. When
5539 disabled these modulefiles and directories contained in matching directories
5540 are excluded.
5541
5542 This environment variable value supersedes the default value set in the
5543 :mconfig:`spider_indepth` configuration option. It can be defined with the
5544 :subcmd:`config` sub-command. The :option:`--indepth` and
5545 :option:`--no-indepth` command line switches override this environment
5546 variable.
5547
5548 .. only:: html
5549
5550 .. versionadded:: 5.6
5551
5552 .. envvar:: MODULES_SPIDER_OUTPUT
5553
5554 A colon separated list of the elements to report in addition to module names
5555 on :subcmd:`spider` sub-command regular output mode.
5556
5557 Accepted elements that can be set in value list are:
5558
5559 * ``alias``: module aliases.
5560 * ``provided-alias``: show module aliases and evaluate all modulefiles to get
5561 aliases provided by them.
5562 * ``dirwsym``: directories associated with symbolic versions.
5563 * ``hidden``: show all hidden modules.
5564 * ``indesym``: symbolic versions reported independently from the module or
5565 directory they are attached to.
5566 * ``key``: legend appended at the end of the output to explain it.
5567 * ``modulepath``: modulepath names set as header prior the list of available
5568 modules found in them.
5569 * ``sym``: symbolic versions associated with available modules.
5570 * ``tag``: tags associated with available modules.
5571 * ``variant``: variants and their possible values associated with available
5572 modules.
5573 * ``variantifspec``: like ``variant`` but only if a variant has been
5574 specified in search query.
5575 * ``via``: mention next to modulepath name which module enables it if any.
5576
5577 The order of the elements in the list does not matter. Module names are the
5578 only content reported when *LIST* is set to an empty value.
5579
5580 In case the ``modulepath`` element is missing from value list, the available
5581 modules from global/user rc and all enabled modulepaths are reported as a
5582 single list.
5583
5584 When ``indesym`` element is set, ``dirwsym`` and ``sym`` elements are
5585 disabled.
5586
5587 This environment variable value supersedes the default value set in the
5588 :mconfig:`spider_output` configuration option. It can be defined with
5589 the :subcmd:`config` sub-command. The :option:`--output`/:option:`-o` command
5590 line switches override this environment variable.
5591
5592 .. only:: html
5593
5594 .. versionadded:: 5.6
5595
5596 .. envvar:: MODULES_SPIDER_TERSE_OUTPUT
5597
5598 A colon separated list of the elements to report in addition to module names
5599 on :subcmd:`spider` sub-command terse output mode.
5600
5601 See :envvar:`MODULES_SPIDER_OUTPUT` to get the accepted elements that can be
5602 set in value list. Exception for ``via`` element which is not accepted for
5603 terse output mode.
5604
5605 The order of the elements in the list does not matter. Module names are the
5606 only content reported when *LIST* is set to an empty value.
5607
5608 This environment variable value supersedes the default value set in the
5609 :mconfig:`spider_terse_output` configuration option. It can be defined with
5610 the :subcmd:`config` sub-command. The :option:`--output`/:option:`-o`
5611 command line switches override this environment variable.
5612
5613 .. only:: html
5614
5615 .. versionadded:: 5.6
5616
5617 .. envvar:: MODULES_STICKY_PURGE
5618
5619 When unloading a sticky or super-sticky module during a module
5620 :subcmd:`purge`, raise an ``error`` or emit a ``warning`` message or be
5621 ``silent``.
5622
5623 This environment variable value supersedes the default value set in the
5624 :mconfig:`sticky_purge` configuration option. It can be defined with the
5625 :subcmd:`config` sub-command.
5626
5627 .. only:: html
5628
5629 .. versionadded:: 5.4
5630
5631 .. envvar:: MODULES_TAG_ABBREV
5632
5633 Specifies the abbreviation strings used to report module tags (see `Module
5634 tags`_ section). Its value is a colon-separated list of module tag names
5635 associated to an abbreviation string (e.g. *tagname=abbrev*).
5636
5637 If a tag is associated to an empty string abbreviation, this tag will not be
5638 reported. In case the whole :envvar:`MODULES_TAG_ABBREV` environment variable
5639 is set to an empty string, tags are reported but not abbreviated.
5640
5641 This environment variable value supersedes the default value set in the
5642 :mconfig:`tag_abbrev` configuration option. It can be defined with the
5643 :subcmd:`config` sub-command.
5644
5645 .. only:: html
5646
5647 .. versionadded:: 4.7
5648
5649 .. envvar:: MODULES_TAG_COLOR_NAME
5650
5651 Specifies the tag names or abbreviations whose graphical rendering should be
5652 applied over themselves instead of being applied over the name of the module
5653 they are attached to. Value of :envvar:`MODULES_TAG_COLOR_NAME` is a
5654 colon-separated list of module tag names or abbreviation strings (see `Module
5655 tags`_ section).
5656
5657 When a select graphic rendition is defined for a tag name or a tag
5658 abbreviation string, it is applied over the module name associated with the
5659 tag and tag name or abbreviation is not displayed. When listed in
5660 :envvar:`MODULES_TAG_COLOR_NAME` environment variable, a tag name or
5661 abbreviation is displayed and select graphic rendition is applied over it.
5662
5663 This environment variable value supersedes the default value set in the
5664 :mconfig:`tag_color_name` configuration option. It can be defined with the
5665 :subcmd:`config` sub-command.
5666
5667 .. only:: html
5668
5669 .. versionadded:: 4.7
5670
5671 .. envvar:: MODULES_TCL_LINTER
5672
5673 Command name or path for use to check syntax of modulefile through the
5674 :subcmd:`lint` sub-command.
5675
5676 This environment variable value supersedes the default value set in the
5677 :mconfig:`tcl_linter` configuration option. It can be defined with the
5678 :subcmd:`config` sub-command.
5679
5680 .. only:: html
5681
5682 .. versionadded:: 5.2
5683
5684 .. envvar:: MODULES_TERM_BACKGROUND
5685
5686 Inform Modules of the terminal background color to determine if the color set
5687 for dark background or the color set for light background should be used to
5688 color output in case no specific color set is defined with the
5689 :envvar:`MODULES_COLORS` variable. Accepted values are ``dark`` and
5690 ``light``.
5691
5692 This environment variable value supersedes the default value set in the
5693 :mconfig:`term_background` configuration option. It can be defined with the
5694 :subcmd:`config` sub-command.
5695
5696 .. only:: html
5697
5698 .. versionadded:: 4.3
5699
5700 .. envvar:: MODULES_TERM_WIDTH
5701
5702 Specifies the number of columns of the output. If set to ``0``, the output
5703 width will be the full terminal width, which is automatically detected by
5704 the module command. Accepted values are integers comprised between 0 and
5705 1000.
5706
5707 This environment variable value supersedes the default value set in the
5708 :mconfig:`term_width` configuration option. It can be defined with the
5709 :subcmd:`config` sub-command. The :option:`--width`/:option:`-w` command line
5710 switches override this environment variable.
5711
5712 .. only:: html
5713
5714 .. versionadded:: 4.7
5715
5716 .. envvar:: MODULES_UNIQUE_NAME_LOADED
5717
5718 If set to ``1``, allows only one module loaded per module name. A conflict is
5719 raised when loading a module whose name or alternative names are shared by an
5720 already loaded module.
5721
5722 This environment variable value supersedes the default value set in the
5723 :mconfig:`unique_name_loaded` configuration option. It can be defined with
5724 the :subcmd:`config` sub-command.
5725
5726 .. only:: html
5727
5728 .. versionadded:: 5.4
5729
5730 .. envvar:: MODULES_UNLOAD_MATCH_ORDER
5731
5732 When a module unload request matches multiple loaded modules, unload firstly
5733 loaded module or lastly loaded module. Accepted values are ``returnfirst``
5734 and ``returnlast``.
5735
5736 This environment variable value supersedes the default value set in the
5737 :mconfig:`unload_match_order` configuration option. It can be defined with
5738 the :subcmd:`config` sub-command.
5739
5740 .. only:: html
5741
5742 .. versionadded:: 4.3
5743
5744 .. envvar:: MODULES_VARIANT_SHORTCUT
5745
5746 Specifies the shortcut characters that could be used to specify and report
5747 module variants (see :ref:`Module variants` section). Its value is a
5748 colon-separated list of variant names associated to a shortcut character
5749 (e.g., *variantname=shortcutchar*).
5750
5751 A variant shortcut must be of one character length and must avoid characters
5752 used for other concerns or in module names or version specifications (i.e.,
5753 *[-+~/@=:,a-zA-Z0-9]*).
5754
5755 If a shortcut is associated to an empty string or an invalid character, this
5756 shortcut definition will be ignored.
5757
5758 This environment variable value supersedes the default value set in the
5759 :mconfig:`variant_shortcut` configuration option. It can be defined with the
5760 :subcmd:`config` sub-command.
5761
5762 .. only:: html
5763
5764 .. versionadded:: 4.8
5765
5766 .. envvar:: MODULES_VERBOSITY
5767
5768 Defines the verbosity level of the module command. Available verbosity levels
5769 from the least to the most verbose are:
5770
5771 * ``silent``: turn off error, warning and informational messages but does not
5772 affect module command output result.
5773 * ``concise``: enable error and warning messages but disable informational
5774 messages.
5775 * ``normal``: turn on informational messages, like a report of the additional
5776 module evaluations triggered by loading or unloading modules, aborted
5777 evaluation issues or a report of each module evaluation occurring during a
5778 :subcmd:`restore` or :subcmd:`source` sub-commands.
5779 * ``verbose``: add additional informational messages, like a systematic
5780 report of the loading or unloading module evaluations.
5781 * ``verbose2``: report loading or unloading module evaluations of
5782 hidden-loaded modules, report if loading module is already loaded or if
5783 unloading module is not loaded.
5784 * ``trace``: provide details on module searches, resolutions, selections and
5785 evaluations.
5786 * ``debug``: print debugging messages about module command execution.
5787 * ``debug2``: report :file:`modulecmd.tcl` procedure calls in addition to
5788 printing debug messages.
5789
5790 This environment variable value supersedes the default value set in the
5791 :mconfig:`verbosity` configuration option. It can be defined with the
5792 :subcmd:`config` sub-command. The :option:`--silent`, :option:`--verbose`,
5793 :option:`--debug` and :option:`--trace` command line switches override this
5794 environment variable.
5795
5796 .. only:: html
5797
5798 .. versionadded:: 4.3
5799
5800 .. versionchanged:: 4.6
5801 Verbosity levels ``trace`` and ``debug2`` added
5802
5803 .. versionchanged:: 4.7
5804 Verbosity level ``verbose2`` added
5805
5806 .. envvar:: MODULES_WA_277
5807
5808 If set to ``1`` prior to Modules package initialization, enables workaround
5809 for Tcsh history issue (see https://github.com/envmodules/modules/issues/277).
5810 This issue leads to erroneous history entries under Tcsh shell. When
5811 workaround is enabled, an alternative *module* alias is defined which fixes
5812 the history mechanism issue. However the alternative definition of the
5813 *module* alias weakens shell evaluation of the code produced by modulefiles.
5814 Characters with a special meaning for Tcsh shell (like ``{`` and ``}``) may
5815 not be used anymore in shell alias definition otherwise the evaluation of the
5816 code produced by modulefiles will return a syntax error.
5817
5818 This environment variable value supersedes the default value set in the
5819 :mconfig:`wa_277` configuration option. It can be defined with the
5820 :subcmd:`config` sub-command.
5821
5822 To enable this workaround, :envvar:`MODULES_WA_277` should be set to ``1``
5823 prior Modules initialization or the :mconfig:`wa_277` configuration option
5824 should be set to ``1`` in the :file:`initrc` configuration file.
5825
5826 .. only:: html
5827
5828 .. versionadded:: 4.3
5829
5830 .. envvar:: MODULESHOME
5831
5832 The location of the main Modules package file directory containing module
5833 command initialization scripts, the executable program :file:`modulecmd.tcl`,
5834 and a directory containing a collection of main *modulefiles*.
5835
5836 This environment variable value supersedes the default value set in the
5837 :mconfig:`home` configuration option. It can be defined with the
5838 :subcmd:`config` sub-command.
5839
5840
5841 FILES
5842 -----
5843
5844 |file prefix|
5845
5846 The :envvar:`MODULESHOME` directory.
5847
5848 |file etcdir_initrc|
5849
5850 The configuration file evaluated by :file:`modulecmd.tcl` when it initializes
5851 to enable the default modulepaths, load the default modules and set
5852 :command:`module` command configuration.
5853
5854 :file:`initrc` is a :ref:`modulefile(5)` so it is written as a Tcl script and
5855 defines modulepaths to enable with :mfcmd:`module use<module>`, modules to
5856 load with :mfcmd:`module load<module>` and configuration to apply with
5857 :subcmd:`module config<config>`. As any modulefile :file:`initrc` must begin
5858 with the Modules magic cookie (i.e., ``#%Module`` file signature).
5859
5860 :file:`initrc` is optional. When this configuration file is present it is
5861 evaluated after the :file:`modulespath` configuration file. See the
5862 :ref:`Package Initialization` section for details.
5863
5864 |file etcdir_modulespath|
5865
5866 The configuration file evaluated by :file:`modulecmd.tcl` when it initializes
5867 to enable the default modulepaths. This file contains the list of modulepaths
5868 separated by either newline or colon characters.
5869
5870 :file:`modulespath` is optional. When this configuration file is present it
5871 is evaluated before the :file:`initrc` configuration file. See the
5872 :ref:`Package Initialization` section for details.
5873
5874 |file etcdir_siteconfig|
5875
5876 The site-specific configuration script of :file:`modulecmd.tcl`. An
5877 additional configuration script could be defined using the
5878 :envvar:`MODULES_SITECONFIG` environment variable. See :ref:`Site-specific
5879 configuration` for detailed information.
5880
5881 |file etcdir_rc|
5882
5883 The system-wide modules rc file. The location of this file can be changed
5884 using the :envvar:`MODULERCFILE` environment variable as described above.
5885
5886 :file:`$HOME/.modulerc`
5887
5888 The user specific modules rc file.
5889
5890 :file:`$HOME/.module`
5891
5892 The user specific collection directory.
5893
5894 |file modulefilesdir|
5895
5896 The directory for system-wide *modulefiles*. The location of the directory
5897 can be changed using the :envvar:`MODULEPATH` environment variable as
5898 described above.
5899
5900 :file:`<modulepath>/.modulerc`
5901
5902 Modulepath-specific module rc file.
5903
5904 :file:`<modulepath>/.modulecache`
5905
5906 Modulepath-specific :ref:`module cache<Module cache>` file.
5907
5908 |file libexecdir_modulecmd|
5909
5910 The *modulefile* interpreter that gets executed upon each invocation
5911 of :command:`module`.
5912
5913 |file initdir_shell|
5914
5915 The Modules package initialization file sourced into the user's environment.
5916
5917
5918 SEE ALSO
5919 --------
5920
5921 :ref:`ml(1)`, :ref:`modulefile(5)`, :ref:`envml(1)`
5922