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