Debian Codegraph @

doc/source/modulefile.rst

raw
1 .. _modulefile(5):
2
3 modulefile
4 ==========
5
6
7 DESCRIPTION
8 -----------
9
10 *modulefiles* are written in the Tool Command Language, :manpage:`Tcl(n)` and
11 are interpreted by the :file:`modulecmd.tcl` program via the :ref:`module(1)`
12 user interface. *modulefiles* can be loaded, unloaded, or switched on-the-fly
13 while the user is working; and can be used to implement site policies
14 regarding the access and use of applications.
15
16 A *modulefile* begins with the ``#%Module`` file signature, also called the
17 Modules magic cookie. A version number may be placed after this string. The
18 version number is useful as the *modulefile* format may change thus it
19 reflects the minimum version of :file:`modulecmd.tcl` required to interpret
20 the modulefile. If a version number doesn't exist, then :file:`modulecmd.tcl`
21 will assume the *modulefile* is compatible. Files without the magic cookie or
22 with a version number greater than the current version of
23 :file:`modulecmd.tcl` will not be interpreted. If the
24 :mconfig:`mcookie_version_check` configuration is disabled the version number
25 set is not checked.
26
27 Each *modulefile* contains the changes to a user's environment needed to
28 access an application. Tcl is a simple programming language which permits
29 *modulefiles* to be arbitrarily complex, depending upon the application's
30 and the *modulefile* writer's needs. If support for extended tcl (tclX)
31 has been configured for your installation of the Modules package, you may
32 use all the extended commands provided by tclX, too.
33
34 A typical *modulefile* is a simple bit of code that set or add entries
35 to the :envvar:`PATH`, :envvar:`MANPATH`, or other environment variables. A
36 Modulefile is evaluated against current :file:`modulecmd.tcl`'s mode which
37 leads to specific evaluation results. For instance if the *modulefile* sets a
38 value to an environment variable, this variable is set when modulefile is
39 loaded and unset when modulefile is unloaded.
40
41 Tcl has conditional statements that are evaluated when the *modulefile* is
42 interpreted. This is very effective for managing path or environment changes
43 due to different OS releases or architectures. The user environment
44 information is encapsulated into a single *modulefile* kept in a central
45 location. The same *modulefile* is used by every user on any machine. So,
46 from the user's perspective, starting an application is exactly the same
47 irrespective of the machine or platform they are on.
48
49 *modulefiles* also hide the notion of different types of shells. From the
50 user's perspective, changing the environment for one shell looks exactly
51 the same as changing the environment for another shell. This is useful
52 for new or novice users and eliminates the need for statements such as "if
53 you're using the C Shell do this ..., otherwise if you're using the Bourne
54 shell do this ...". Announcing and accessing new software is uniform and
55 independent of the user's shell. From the *modulefile* writer's perspective,
56 this means one set of information will take care of every type of shell.
57
58 .. _Modules specific Tcl commands:
59
60 Modules Specific Tcl Commands
61 -----------------------------
62
63 The Modules Package uses commands which are extensions to the "standard"
64 Tool Command Language :manpage:`Tcl(n)` package. Unless otherwise specified,
65 the Module commands return the empty string. Some commands behave differently
66 when a *modulefile* is loaded or unloaded. The command descriptions assume
67 the *modulefile* is being loaded.
68
69 .. mfcmd:: add-property name value
70
71 Associate module tag *value* to currently loading *modulefile*. Argument
72 *name* is ignored. See :mfcmd:`module-tag` command for more information on
73 tags.
74
75 .. only:: html or latex
76
77 .. versionadded:: 5.6
78
79 .. mfcmd:: always-load [options] modulefile...
80
81 Load *modulefile* and apply the ``keep-loaded`` tag to it in order to avoid
82 the automatic unload of this *modulefile* when modules dependent of it are
83 unloaded.
84
85 :mfcmd:`always-load` command accepts the following options:
86
87 * ``--modulepath modulepathlist``
88 * ``--optional``
89 * ``--tag taglist``
90
91 *modulefile* is declared as a requirement of currently loading module. This
92 command acts as an alias of :mfcmd:`module load<module>` command. If more
93 than one *modulefile* are specified, then this list acts as a Boolean AND
94 operation, which means all specified *modulefiles* are required.
95
96 When the ``--optional`` option is set, each specified *modulefile* is
97 declared as an optional requirement. A *modulefile* that cannot be loaded,
98 will not stop the evaluation.
99
100 The ``--tag`` option accepts a list of module tags to apply to *modulefile*
101 once loaded in addition to the ``keep-loaded`` tag. *taglist* corresponds to
102 the concatenation of multiple tags separated by colon character. *taglist*
103 should not contain tags inherited from *modulefile* state or from other
104 modulefile commands. If module is already loaded, tags from *taglist* are
105 added to the list of tags already applied to this module.
106
107 The ``--modulepath`` option accepts a list of modulepath. *modulepathlist*
108 corresponds to the concatenation of multiple modulepaths separated by colon
109 character. When this option is set, required *modulefile* should be located
110 within one of the listed modulepaths. A path in this list may correspond to
111 the first path elements of an actual modulepath (e.g., ``/path/to`` will
112 match modulefiles located into the ``/path/to/modulefiles`` modulepath
113 directory).
114
115 If an attempt to load *modulefile* is performed and ``--modulepath`` option
116 is set, *modulefile* will be searched in the enabled modulepaths whose start
117 match one of the specified paths and in the specified paths not matching any
118 enabled modulepaths. For instance if this option is set to
119 ``/path/to:/another/path`` and ``/path/to/modulefiles`` is currently the sole
120 enabled modulepath, *modulefile* will be searched into
121 ``/path/to/modulefiles`` and ``/another/path`` directories.
122
123 .. only:: html or latex
124
125 .. versionadded:: 5.1
126
127 .. versionchanged:: 5.2
128 Option ``--optional`` added
129
130 .. versionchanged:: 5.5
131 Option ``--modulepath`` added
132
133 .. mfcmd:: append-path [-d C|--delim C|--delim=C] [--duplicates] variable value...
134
135 See :mfcmd:`prepend-path`.
136
137 .. mfcmd:: break
138
139 This is not a Modules-specific command, it's actually part of Tcl, which
140 has been overloaded similar to the :mfcmd:`continue` and :mfcmd:`exit`
141 commands to have the effect of causing the module not to be listed as loaded
142 and not affect other modules being loaded concurrently. All non-environment
143 commands within the module will be performed up to this point. Processing
144 will continue on to the next module on the command line unless if
145 :mconfig:`abort_on_error` configuration option is enabled for running module
146 sub-command. The :mfcmd:`break` command will only have this effect if not
147 used within a Tcl loop though.
148
149 An example: Suppose that a full selection of *modulefiles* are needed for
150 various different architectures, but some of the *modulefiles* are not
151 needed and the user should be alerted. Having the unnecessary *modulefile*
152 be a link to the following ``notavail`` *modulefile* will perform the task
153 as required.
154
155 .. code-block:: tcl
156
157 #%Module
158
159 module-help {This module does nothing but alert the user}
160 module-help "that the [module-info name] module is not available"
161
162 module-whatis {Notifies user that module is not available.}
163
164 set curMod [module-info name]
165 if {[module-info mode load]} {
166 puts stderr "Note: '$curMod' is not available for [uname sysname]."
167 }
168 break
169
170 Modulefile using :mfcmd:`break` command when unloading may be unloaded anyway
171 if :option:`--force` option is set. To forbid the unload of a modulefile, it
172 is recommended to tag it ``super-sticky`` with :mfcmd:`module-tag` command.
173
174 .. only:: html or latex
175
176 .. versionchanged:: 5.4
177 Breaking modulefile is unloaded anyway when :option:`--force` option is
178 set
179
180 .. mfcmd:: chdir directory
181
182 Set the current working directory to *directory*.
183
184 .. mfcmd:: complete shell name body
185
186 Define shell completion for command *name* with specified *body* if *shell*
187 is the current shell under which :file:`modulecmd.tcl` was invoked. *Body*
188 corresponds to argument options accepted by the shell command which
189 defines completion. When a *modulefile* is unloaded, :mfcmd:`complete`
190 becomes :mfcmd:`uncomplete`.
191
192 The following *shells* are supported: bash, tcsh, bash and fish. Please refer
193 to the documentation of these shells to learn how to define completion. The
194 command is ignored if an unsupported shell is specified.
195
196 .. only:: html or latex
197
198 .. versionadded:: 5.1
199
200 .. mfcmd:: conflict modulefile...
201
202 :mfcmd:`conflict` controls whether or not the *modulefile* will be loaded.
203 The :mfcmd:`conflict` command lists *modulefiles* which conflict with the
204 current *modulefile*. If a list contains more than one *modulefile*, then
205 each member of the list acts as a Boolean OR operation. Multiple
206 :mfcmd:`conflict` commands may be used to create a Boolean AND operation. If
207 one of the requirements have not been satisfied, an error is reported and the
208 current *modulefile* makes no changes to the user's environment.
209
210 If an argument for :mfcmd:`conflict` is a directory and any other
211 *modulefile* from that directory has been loaded, then a conflict will occur.
212 For example, specifying X11 as a :mfcmd:`conflict` will stop X11/R4 and
213 X11/R5 from being loaded at the same time.
214
215 The parameter *modulefile* may also be a symbolic modulefile name or a
216 modulefile alias. It may also leverage a specific syntax to finely select
217 module version (see `Advanced module version specifiers`_ section below).
218
219 If the :mconfig:`conflict_unload` and :mconfig:`auto_handling` configuration
220 options are enabled, :mfcmd:`conflict` will attempt to unload all loaded
221 modules that match specification. (see :ref:`Automated module handling
222 mechanisms<MODULES_AUTO_HANDLING>` in :ref:`module(1)`).
223
224 .. only:: html or latex
225
226 .. versionchanged:: 5.5
227 An attempt to unload module is made if :mconfig:`conflict_unload` and
228 :mconfig:`auto_handling` configuration options are enabled
229
230 .. mfcmd:: continue
231
232 This is not a modules specific command but another overloaded Tcl command
233 and is similar to the :mfcmd:`break` or :mfcmd:`exit` commands except the
234 module will be listed as loaded as well as performing any environment or Tcl
235 commands up to this point and then continuing on to the next module on
236 the command line. The :mfcmd:`continue` command will only have this effect if
237 not used within a Tcl loop though.
238
239 .. mfcmd:: depends-on [options] modulefile...
240
241 Alias of :mfcmd:`prereq-all` command.
242
243 .. only:: html or latex
244
245 .. versionadded:: 5.1
246
247 .. versionchanged:: 5.2
248 Option ``--optional`` added
249
250 .. versionchanged:: 5.5
251 Option ``--modulepath`` added
252
253 .. mfcmd:: depends-on-any [options] modulefile...
254
255 Alias of :mfcmd:`prereq` command.
256
257 .. only:: html or latex
258
259 .. versionadded:: 5.6
260
261 .. mfcmd:: exit [N]
262
263 This is not a modules specific command but another overloaded Tcl command
264 and is similar to the :mfcmd:`break` or :mfcmd:`continue` commands. However,
265 this command will cause the immediate cessation of this module. Any
266 additional modules on the command line will not be evaluated even if the
267 :mconfig:`abort_on_error` configuration option is disabled for running
268 module sub-command. This module and the subsequent modules will not be listed
269 as loaded. No environment commands will be performed in the current module.
270
271 .. mfcmd:: extensions modulefile...
272
273 Alias of :mfcmd:`provide` command.
274
275 .. only:: html or latex
276
277 .. versionadded:: 5.1
278
279 .. versionchanged:: 5.6
280 Changed from *no-operation* command to alias of :mfcmd:`provide`
281
282 .. mfcmd:: family name
283
284 Defines loading modulefile as a member of family *name*. Only one member of a
285 family could be loaded. Error is raised when attempting to load another
286 member of the same family *name*.
287
288 :mfcmd:`family` corresponds to the definition of a :mfcmd:`conflict` on
289 *name* and the definition of a :mfcmd:`module-alias` *name* targeting
290 currently loading module.
291
292 In addition, the :envvar:`MODULES_FAMILY_\<NAME\>` environment variable is
293 defined and set to the currently loading module name minus version. This
294 variable helps to know what module provides for the family *name* in the
295 currently loaded environment. For instance if loading modulefile ``foo/1.0``
296 defines being member of the ``bar`` family, the
297 :envvar:`MODULES_FAMILY_BAR<MODULES_FAMILY_\<NAME\>>` will be set to the
298 ``foo`` value. For compatibility, the :envvar:`LMOD_FAMILY_\<NAME\>`
299 environment variable is also defined and set to the same value than
300 :envvar:`MODULES_FAMILY_\<NAME\>`.
301
302 *name* should be a non-empty string only containing characters that could be
303 part of an environment variable name (i.e., *[a-zA-Z0-9_]*).
304
305 If the :mconfig:`conflict_unload` and :mconfig:`auto_handling` configuration
306 options are enabled, an attempt to unload loaded module that defines the same
307 family is made. (see :ref:`Automated module handling
308 mechanisms<MODULES_AUTO_HANDLING>` in :ref:`module(1)`).
309
310 .. only:: html or latex
311
312 .. versionadded:: 5.1
313
314 .. versionchanged:: 5.5
315 An attempt to unload module defining same family is made if
316 :mconfig:`conflict_unload` and :mconfig:`auto_handling` configuration
317 options are enabled
318
319 .. mfcmd:: getenv [--return-value] variable [value]
320
321 Returns value of environment *variable*. If *variable* is not defined,
322 *value* is returned if set, an empty string is returned otherwise. The
323 :mfcmd:`getenv` command should be preferred over the Tcl global variable
324 ``env`` to query environment variables.
325
326 When modulefile is evaluated in *display* mode, :mfcmd:`getenv` returns
327 *variable* name prefixed with dollar sign (e.g., ``$variable``) unless if the
328 ``--return-value`` option is set. When this option is set the value of
329 environment *variable* or defined fallback value is returned in *display*
330 mode.
331
332 .. only:: html or latex
333
334 .. versionadded:: 4.0
335
336 .. versionchanged:: 4.2
337 Optional argument *value* added
338
339 .. versionchanged:: 5.0
340 An empty string is returned instead of ``_UNDEFINED_`` when *variable*
341 is not defined and no *value* is set
342
343 .. versionchanged:: 5.1
344 Option ``--return-value`` added
345
346 .. versionchanged:: 5.7
347 Command available from module rc file context
348
349 .. mfcmd:: getvariant [--return-value] variant [value]
350
351 Returns value of designated *variant*. If *variant* is not defined, *value*
352 is returned if set, an empty string is returned otherwise. The
353 :mfcmd:`getvariant` command should be preferred over the
354 :mfvar:`ModuleVariant` Tcl array to query a variant value.
355
356 When modulefile is evaluated in *display* mode, :mfcmd:`getvariant` returns
357 *variant* name enclosed in curly braces (e.g., ``{variant}``) unless if the
358 ``--return-value`` option is set. When this option is set the value of
359 *variant* or defined fallback value is returned in *display* mode.
360
361 .. only:: html or latex
362
363 .. versionadded:: 4.8
364
365 .. versionchanged:: 5.1
366 Option ``--return-value`` added.
367
368
369 .. mfcmd:: haveDynamicMPATH
370
371 :mfcmd:`haveDynamicMPATH` command signals that a modulefile modifies the
372 :envvar:`MODULEPATH` environment variable. It is useful when the modulefile
373 conditionally updates :envvar:`MODULEPATH` and is processed by Lmod tool.
374
375 Here in the Modules tool, this command is implemented as a *no-operation*,
376 since the :subcmd:`spider` sub-command evaluates the modulefile in the
377 context of the current user to determine whether :envvar:`MODULEPATH` is
378 updated.
379
380 .. only:: html or latex
381
382 .. versionadded:: 5.6
383
384 .. mfcmd:: hide-modulefile modulefile
385
386 Alias of :mfcmd:`module-hide` command.
387
388 .. only:: html or latex
389
390 .. versionadded:: 5.5
391
392 .. mfcmd:: hide-version modulefile
393
394 Alias of :mfcmd:`module-hide` command.
395
396 .. only:: html or latex
397
398 .. versionadded:: 5.5
399
400 .. mfcmd:: is-avail modulefile...
401
402 The :mfcmd:`is-avail` command returns a true value if any of the listed
403 *modulefiles* exists in enabled :envvar:`MODULEPATH`. If a list contains more
404 than one *modulefile*, then each member acts as a boolean OR operation. If an
405 argument for :mfcmd:`is-avail` is a directory and a *modulefile* exists in
406 the directory :mfcmd:`is-avail` would return a true value.
407
408 The parameter *modulefile* may also be a symbolic modulefile name or a
409 modulefile alias. It may also leverage a specific syntax to finely select
410 module version (see `Advanced module version specifiers`_ section below).
411
412 .. only:: html or latex
413
414 .. versionadded:: 4.1
415
416 .. mfcmd:: is-loaded [modulefile...]
417
418 The :mfcmd:`is-loaded` command returns a true value if any of the listed
419 *modulefiles* has been loaded or if any *modulefile* is loaded in case no
420 argument is provided. If a list contains more than one *modulefile*, then
421 each member acts as a boolean OR operation. If an argument for
422 :mfcmd:`is-loaded` is a directory and any *modulefile* from the directory has
423 been loaded :mfcmd:`is-loaded` would return a true value.
424
425 The parameter *modulefile* may also be a symbolic modulefile name or a
426 modulefile alias. It may also leverage a specific syntax to finely select
427 module version (see `Advanced module version specifiers`_ section below).
428
429 .. mfcmd:: is-saved [collection...]
430
431 The :mfcmd:`is-saved` command returns a true value if any of the listed
432 *collections* exists or if any *collection* exists in case no argument is
433 provided. If a list contains more than one *collection*, then each member
434 acts as a boolean OR operation.
435
436 If :envvar:`MODULES_COLLECTION_TARGET` is set, a suffix equivalent to the
437 value of this variable is appended to the passed *collection* name. In case
438 no *collection* argument is provided, a true value will only be returned if
439 a collection matching currently set target exists.
440
441 .. only:: html or latex
442
443 .. versionadded:: 4.1
444
445 .. mfcmd:: is-used [directory...]
446
447 The :mfcmd:`is-used` command returns a true value if any of the listed
448 *directories* has been enabled in :envvar:`MODULEPATH` or if any *directory*
449 is enabled in case no argument is provided. If a list contains more than one
450 *directory*, then each member acts as a boolean OR operation.
451
452 A relative *directory* is resolved against the directory of the modulefile
453 being evaluated and also against the current working directory, as a
454 relative path entry in :envvar:`MODULEPATH` refers to the latter.
455
456 .. only:: html or latex
457
458 .. versionadded:: 4.1
459
460 .. versionchanged:: 5.7
461 A relative *directory* is also resolved against the current working
462 directory
463
464 .. mfcmd:: lsb-release field
465
466 Provide certain Linux Standard Base (LSB) information. :mfcmd:`lsb-release`
467 will invoke the :manpage:`lsb_release(1)` command to get each *field*
468 information.
469
470 *field* values are:
471
472 * ``id``: string id of distributor
473 * ``release``: release number of distribution
474 * ``codename``: codename according to distribution release
475
476 .. only:: html or latex
477
478 .. versionadded:: 5.5
479
480 .. mfcmd:: module [sub-command] [sub-command-options] [sub-command-args]
481
482 This command permits a *modulefile* to :subcmd:`load` or :subcmd:`unload`
483 other *modulefiles* or to :subcmd:`use` or :subcmd:`unuse` *modulepaths*. No
484 checks are made to ensure that the *modulefile* does not try to load itself.
485 Often it is useful to have a single *modulefile* that performs a number of
486 ``module load`` commands. For example, if every user on the system requires a
487 basic set of applications loaded, then a core *modulefile* would contain the
488 necessary ``module load`` commands.
489
490 The ``--not-req`` option may be set for the ``load``, ``try-load``,
491 ``load-any``, ``unload`` and ``switch`` sub-commands to inhibit the
492 definition of an implicit prereq or conflict requirement onto specified
493 modules.
494
495 On ``try-load`` sub-command, *modulefiles* are considered optional prereq
496 requirement. However an error is raised if they cannot be loaded unless if
497 they are not found or forbidden.
498
499 The ``load-any`` sub-command loads one *modulefile* from the specified list.
500 An error is obtained if no *modulefile* from the list can be loaded. No
501 operation is performed if a *modulefile* from the list is found already
502 loaded.
503
504 The ``unload`` sub-command unloads one matching *modulefile* for each module
505 specification provided as argument if :mconfig:`auto_handling` or
506 :mconfig:`conflict_unload` configuration options are disabled. When both
507 options are enabled, ``unload`` removes all loaded modules matching each
508 module specification. When both options are enabled, modules dependent of the
509 unloaded modules are also unloaded. Otherwise an error is raised if module to
510 unload has a dependent module loaded.
511
512 If the :mconfig:`require_via` configuration option is enabled, the ``use``
513 sub-command defines a requirement of modulefiles stored in the added
514 modulepath onto current *modulefile*.
515
516 The ``unuse`` sub-command accepts the ``--remove-on-unload``,
517 ``--noop-on-unload``, ``--append-on-unload`` and ``--prepend-on-unload``
518 options to control the behavior to apply when *modulefile* is unloaded. See
519 :mfcmd:`remove-path` for further explanation.
520
521 The ``load``, ``try-load``, ``load-any`` and ``switch`` sub-commands accept
522 the ``--tag`` option to apply specified tags to *modulefile* once loaded.
523 Option accepts a concatenation of multiple module tags separated by colon
524 character. *taglist* should not contain tags inherited from *modulefile*
525 state or from other modulefile commands. If module is already loaded, tags
526 from *taglist* are added to the list of tags already applied to this module.
527
528 Command line switches :option:`--auto`, :option:`--no-auto` and
529 :option:`--force` are ignored when passed to a :mfcmd:`module` command set in
530 a *modulefile*.
531
532 Not all the *sub-commands* described in the :ref:`Module Sub-Commands`
533 section of the :ref:`module(1)` man page are available when :mfcmd:`module`
534 is used as a Modules specific Tcl command. The following table summarizes the
535 different sub-commands available for each interpretation context.
536
537 +--------------------------------+---------------------+---------------------+
538 | Sub-commands available from | Sub-commands avail\ | Sub-commands avail\ |
539 | modulefile interpretation | able from :file:`i\ | able from run-comm\ |
540 | | nitrc` configuration| and (rc) file |
541 | | file and sourced | interpretation |
542 | | script file | |
543 +================================+=====================+=====================+
544 | :subcmd:`load`, | Same sub-commands | *None* |
545 | :subcmd:`load-any`, | available than for | |
546 | :subcmd:`switch`, | modulefile and | |
547 | :subcmd:`try-load`, | :subcmd:`config` | |
548 | :subcmd:`unload`, | sub-command. | |
549 | :subcmd:`unuse`, :subcmd:`use`.| | |
550 | Also available but not recomm\ | | |
551 | ended for use from regular | | |
552 | modulefile: :subcmd:`aliases`, | | |
553 | :subcmd:`avail`, | | |
554 | :subcmd:`display`, | | |
555 | :subcmd:`initadd`, | | |
556 | :subcmd:`initclear`, | | |
557 | :subcmd:`initlist`, | | |
558 | :subcmd:`initprepend`, | | |
559 | :subcmd:`initrm`, | | |
560 | :subcmd:`initswitch`, | | |
561 | :subcmd:`list`, | | |
562 | :subcmd:`purge`, | | |
563 | :subcmd:`reload`, | | |
564 | :subcmd:`restore`, | | |
565 | :subcmd:`save`, | | |
566 | :subcmd:`savelist`, | | |
567 | :subcmd:`saverm`, | | |
568 | :subcmd:`saveshow`, | | |
569 | :subcmd:`search`, | | |
570 | :subcmd:`test`, | | |
571 | :subcmd:`whatis` | | |
572 +--------------------------------+---------------------+---------------------+
573
574 .. only:: html or latex
575
576 .. versionchanged:: 4.7
577 Option ``--not-req`` added for ``load``, ``unload`` and ``switch``
578 sub-commands
579
580 .. versionchanged:: 5.0
581 :subcmd:`source` sub-command is not allowed anymore and ``source`` Tcl
582 command should be used instead
583
584 .. versionchanged:: 5.1
585 Options ``--remove-on-unload``, ``--noop-on-unload``,
586 ``--append-on-unload`` and ``--prepend-on-unload`` added for ``unuse``
587 sub-command
588
589 .. versionchanged:: 5.1
590 Option ``--tag`` added for ``load``, ``try-load``, ``load-any`` and
591 ``switch`` sub-commands
592
593 .. versionchanged:: 5.1
594 Option ``--not-req`` added for ``try-load`` and ``load-any``
595 sub-commands
596
597 .. versionchanged:: 5.5
598 When :mconfig:`auto_handling` and :mconfig:`conflict_unload`
599 configuration options are enabled, ``unload`` sub-command removes all
600 matching modules loaded and modules that depend on them
601
602 .. versionchanged:: 5.6
603 When :mconfig:`require_via` configuration option is enabled, a
604 modulefile using new modulepath is considered a requirement of
605 modulefiles stored in this modulepath.
606
607 .. mfcmd:: module-alias name modulefile
608
609 Assigns the *modulefile* to the alias *name*. This command should be
610 placed in one of the :file:`modulecmd.tcl` rc files in order to provide
611 shorthand invocations of frequently used *modulefile* names.
612
613 The parameter *modulefile* may be either
614
615 * a fully qualified *modulefile* with name and version
616
617 * a symbolic *modulefile* name
618
619 * another *modulefile* alias
620
621 .. mfcmd:: module-forbid [options] modulefile...
622
623 Forbid use of *modulefile*. An error is obtained when trying to evaluate a
624 forbidden module. This command should be placed in one of the
625 :file:`modulecmd.tcl` rc files.
626
627 :mfcmd:`module-forbid` command accepts the following options:
628
629 * ``--after datetime``
630 * ``--before datetime``
631 * ``--not-user {user...}``
632 * ``--not-group {group...}``
633 * ``--user {user...}``
634 * ``--group {group...}``
635 * ``--message {text message}``
636 * ``--nearly-message {text message}``
637
638 If ``--after`` option is set, forbidding is only effective after specified
639 date time. Following the same principle, if ``--before`` option is set,
640 forbidding is only effective before specified date time. Accepted date time
641 format is ``YYYY-MM-DD[THH:MM]``. If no time (``HH:MM``) is specified,
642 ``00:00`` is assumed. ``--after`` and ``--before`` options are not supported
643 on Tcl versions prior to 8.5.
644
645 If ``--not-user`` option is set, forbidding is not applied if the username of
646 the user currently running :file:`modulecmd.tcl` is part of the list of
647 username specified. Following the same approach, if ``--not-group`` option is
648 set, forbidding is not applied if current user is member of one of the groups
649 specified. When both options are set, forbidding is not applied if a match is
650 found for ``--not-user`` or ``--not-group``.
651
652 If ``--user`` option is set, forbidding is applied only if the username of
653 the user currently running :file:`modulecmd.tcl` is part of the list of
654 username specified. Following the same approach, if ``--group`` option is
655 set, forbidding is applied only if current user is member of one of the
656 groups specified. When both options are set, forbidding is applied if a match
657 is found for ``--user`` or ``--group``. If the same user name is set on both
658 ``--user`` and ``--not-user`` options, ``--user`` prevails over
659 ``--not-user``. If the same group name is set on both ``--group`` and
660 ``--not-group``, ``--group`` prevails over ``--not-group``.
661
662 Error message returned when trying to evaluate a forbidden module can be
663 supplemented with the *text message* set through ``--message`` option.
664
665 If ``--after`` option is set, modules are considered *nearly forbidden*
666 during a number of days defined by the :mconfig:`nearly_forbidden_days`
667 :file:`modulecmd.tcl` configuration option
668 (see :envvar:`MODULES_NEARLY_FORBIDDEN_DAYS`), prior reaching the expiry
669 date fixed by ``--after`` option. When a *nearly forbidden* module is
670 evaluated a warning message is issued to inform module will soon be
671 forbidden. This warning message can be supplemented with the *text message*
672 set through ``--nearly-message`` option.
673
674 If a :mfcmd:`module-forbid` command applies to a *modulefile* also targeted
675 by a :mfcmd:`module-hide --hard<module-hide>` command, this module is
676 unveiled when precisely named to return an access error.
677
678 Forbidden modules included in the result of :subcmd:`avail` or
679 :subcmd:`spider` sub-commands are reported with a ``forbidden`` tag applied
680 to them. Nearly forbidden modules included in the result of :subcmd:`avail`,
681 :subcmd:`list` or :subcmd:`spider` sub-commands are reported with a
682 ``nearly-forbidden`` tag applied to them. See :ref:`Module tags` section in
683 :ref:`module(1)`.
684
685 The parameter *modulefile* may leverage a specific syntax to finely select
686 module version (see `Advanced module version specifiers`_ section below). It
687 may also be a full path file name to precisely designate one module in a
688 specific modulepath.
689
690 .. only:: html or latex
691
692 .. versionadded:: 4.6
693
694 .. versionchanged:: 5.4
695 Full path file name may be used to designate *modulefile*
696
697 .. versionchanged:: 5.4
698 Options ``--user`` and ``--group`` added
699
700 .. mfcmd:: module-help string
701
702 Defines a string which is displayed in case of the invocation of the
703 :subcmd:`module help<help>` command. This command takes no action on non-help
704 *modulefile* evaluation.
705
706 Multi-word *string* should be enclosed in curly-braces or double-quotes.
707 There may be more than one :mfcmd:`module-help` command call in a
708 *modulefile*. In which case each command call is reported as a separate line.
709
710 If a *modulefile* also defines a ``ModulesHelp`` procedure, the text defined
711 with :mfcmd:`module-help` is printed before running this procedure on
712 ``help`` evaluation mode.
713
714 .. only:: html or latex
715
716 .. versionadded:: 5.6
717
718 .. mfcmd:: module-hide [options] modulefile...
719
720 Hide *modulefile* to exclude it from available module search or module
721 selection unless query refers to *modulefile* by its exact name. This command
722 should be placed in one of the :file:`modulecmd.tcl` rc files.
723
724 :mfcmd:`module-hide` command accepts the following options:
725
726 * ``--soft|--hard``
727 * ``--hidden-loaded``
728 * ``--after datetime``
729 * ``--before datetime``
730 * ``--not-user {user...}``
731 * ``--not-group {group...}``
732 * ``--user {user...}``
733 * ``--group {group...}``
734
735 When ``--soft`` option is set, *modulefile* is also set hidden, but hiding is
736 disabled when search or selection query's root name matches module's root
737 name. This soft hiding mode enables to hide modulefiles from bare module
738 availability listing yet keeping the ability to select such module for load
739 with the regular resolution mechanism (i.e., no need to use module exact name
740 to select it)
741
742 When ``--hard`` option is set, *modulefile* is also set hidden and stays
743 hidden even if search or selection query refers to *modulefile* by its exact
744 name.
745
746 When ``--hidden-loaded`` option is set, hidden state also applies to the
747 *modulefile* when it is loaded. Hidden loaded modules do not appear on
748 :subcmd:`list` sub-command output, unless :option:`--all` option is set.
749 Their loading or unloading informational messages are not reported unless the
750 :envvar:`verbosity of Modules<MODULES_VERBOSITY>` is set to a level higher
751 than ``verbose``. Hidden loaded modules are detected in any cases by state
752 query commands like :mfcmd:`is-loaded`.
753
754 If ``--after`` option is set, hiding is only effective after specified date
755 time. Following the same principle, if ``--before`` option is set, hiding is
756 only effective before specified date time. Accepted date time format is
757 ``YYYY-MM-DD[THH:MM]``. If no time (``HH:MM``) is specified, ``00:00`` is
758 assumed. ``--after`` and ``--before`` options are not supported on Tcl
759 versions prior to 8.5.
760
761 If ``--not-user`` option is set, hiding is not applied if the username of the
762 user currently running :file:`modulecmd.tcl` is part of the list of username
763 specified. Following the same approach, if ``--not-group`` option is set,
764 hiding is not applied if current user is member of one of the groups
765 specified. When both options are set, hiding is not applied if a match is
766 found for ``--not-user`` or ``--not-group``.
767
768 If ``--user`` option is set, hiding is applied only if the username of the
769 user currently running :file:`modulecmd.tcl` is part of the list of username
770 specified. Following the same approach, if ``--group`` option is set, hiding
771 is applied only if current user is member of one of the groups specified.
772 When both options are set, hiding is applied if a match is found for
773 ``--user`` or ``--group``. If the same user name is set on both ``--user``
774 and ``--not-user`` options, ``--user`` prevails over ``--not-user``. If the
775 same group name is set on both ``--group`` and ``--not-group``, ``--group``
776 prevails over ``--not-group``.
777
778 If the :option:`--all` option is set on :subcmd:`avail`, :subcmd:`aliases`,
779 :subcmd:`whatis`, :subcmd:`search` or :subcmd:`spider` sub-commands, hiding
780 is disabled thus hidden modulefiles are included in module search.
781 Hard-hidden modules (i.e., declared hidden with ``--hard`` option) are not
782 affected by :option:`--all` and stay hidden even if option is set.
783 :option:`--all` option does not apply to *module selection* sub-commands like
784 :subcmd:`load`. Thus in such context a hidden module should always be
785 referred by its exact full name (e.g., ``foo/1.2.3`` not ``foo``) unless if
786 it has been hidden in ``--soft`` mode. A hard-hidden module cannot be
787 unveiled or selected in any case.
788
789 If several :mfcmd:`module-hide` commands target the same *modulefile*, the
790 strongest hiding level is retained which means if both a regular, a
791 ``--soft`` hiding command match a given module, regular hiding mode is
792 considered. If both a regular and a ``--hard`` hiding command match a given
793 module, hard hiding mode is retained. A set ``--hidden-loaded`` option is
794 retained even if the :mfcmd:`module-hide` statement on which it is declared
795 is superseded by a stronger :mfcmd:`module-hide` statement with no
796 ``--hidden-loaded`` option set.
797
798 Hidden modules included in the result of :subcmd:`avail` or :subcmd:`spider`
799 sub-commands are reported with a ``hidden`` tag applied to them. Hidden
800 loaded modules included in the result of :subcmd:`list` sub-command are
801 reported with a ``hidden-loaded`` tag applied to them. This tag is not
802 reported on :subcmd:`avail` or :subcmd:`spider` sub-commands context. See
803 :ref:`Module tags` section in :ref:`module(1)`.
804
805 The parameter *modulefile* may also be a symbolic modulefile name or a
806 modulefile alias. It may also leverage a specific syntax to finely select
807 module version (see `Advanced module version specifiers`_ section below).
808 Moreover it may also be a full path file name to precisely designate one
809 module in a specific modulepath.
810
811 .. only:: html or latex
812
813 .. versionadded:: 4.6
814
815 .. versionchanged:: 4.7
816 Option ``--hidden-loaded`` added.
817
818 .. versionchanged:: 5.4
819 Full path file name may be used to designate *modulefile*
820
821 .. versionchanged:: 5.4
822 Options ``--user`` and ``--group`` added
823
824 .. mfcmd:: module-info option [info-args]
825
826 Provide information about the :file:`modulecmd.tcl` program's state. Some of
827 the information is specific to the internals of :file:`modulecmd.tcl`.
828 *option* is the type of information to be provided, and *info-args* are any
829 arguments needed.
830
831 **module-info alias** name
832
833 Returns the full *modulefile* name to which the *modulefile* alias *name*
834 is assigned
835
836 **module-info command** [commandname]
837
838 Returns the currently running :file:`modulecmd.tcl`'s command as a string
839 if no *commandname* is given.
840
841 Returns ``1`` if :file:`modulecmd.tcl`'s command is *commandname*.
842 *commandname* can be: ``load``, ``unload``, ``refresh``, ``reload``,
843 ``source``, ``switch``, ``display``, ``avail``, ``aliases``, ``list``,
844 ``whatis``, ``search``, ``purge``, ``restore``, ``help``, ``test``,
845 ``try-load``, ``load-any``, ``mod-to-sh``, ``reset``, ``stash``,
846 ``stashpop`` or ``spider``.
847
848 .. only:: html or latex
849
850 .. versionadded:: 4.0
851
852 **module-info loaded** modulefile
853
854 Returns the names of currently loaded modules matching passed *modulefile*.
855 The parameter *modulefile* might either be a fully qualified *modulefile*
856 with name and version or just a directory which in case all loaded
857 *modulefiles* from the directory will be returned. The parameter
858 *modulefile* may also be a symbolic modulefile name or a modulefile alias.
859
860 This command only returns the name and version of designated loaded module.
861 The defined variants of the loaded module are not included in the returned
862 string.
863
864 .. only:: html or latex
865
866 .. versionadded:: 4.1
867
868 **module-info mode** [modetype]
869
870 Returns the current :file:`modulecmd.tcl`'s mode as a string if no
871 *modetype* is given.
872
873 Returns ``1`` if :file:`modulecmd.tcl`'s mode is *modetype*. *modetype* can
874 be: ``load``, ``unload``, ``remove`` (alias of ``unload``), ``switch``,
875 ``refresh``, ``nonpersist`` (alias of ``refresh``), ``display``, ``help``,
876 ``test``, ``whatis`` or ``scan``.
877
878 **module-info name**
879
880 Return the name of the *modulefile*. This is not the full pathname for
881 *modulefile*. See the `Modules Variables`_ section for information on the
882 full pathname.
883
884 This command only returns the name and version of currently evaluating
885 *modulefile*. The defined variants are not included in the returned string.
886 See :mfcmd:`getvariant` command or :mfvar:`ModuleVariant` array variable to
887 get defined variant values for currently evaluating *modulefile*.
888
889 **module-info shell** [shellname]
890
891 Return the current shell under which :file:`modulecmd.tcl` was invoked if
892 no *shellname* is given. The current shell is the first parameter of
893 :file:`modulecmd.tcl`, which is normally hidden by the :command:`module`
894 alias.
895
896 If a *shellname* is given, returns ``1`` if :file:`modulecmd.tcl`'s current
897 shell is *shellname*, returns ``0`` otherwise. *shellname* can be: ``sh``,
898 ``bash``, ``ksh``, ``zsh``, ``csh``, ``tcsh``, ``fish``, ``cmd``, ``pwsh``,
899 ``tcl``, ``perl``, ``python``, ``ruby``, ``lisp``, ``cmake``, ``r``.
900
901 **module-info shelltype** [shelltypename]
902
903 Return the family of the shell under which *modulefile* was invoked if no
904 *shelltypename* is given. As of :mfcmd:`module-info shell<module-info>` this
905 depends on the first parameter of :file:`modulecmd.tcl`. The output reflects
906 a shell type determining the shell syntax of the commands produced by
907 :file:`modulecmd.tcl`.
908
909 If a *shelltypename* is given, returns ``1`` if :file:`modulecmd.tcl`'s
910 current shell type is *shelltypename*, returns ``0`` otherwise.
911 *shelltypename* can be: ``sh``, ``csh``, ``fish``, ``cmd``, ``pwsh``,
912 ``tcl``, ``perl``, ``python``, ``ruby``, ``lisp``, ``cmake``, ``r``.
913
914 **module-info specified**
915
916 Return the module designation (name, version and variants) specified that
917 led to current *modulefile* evaluation.
918
919 **module-info symbols** modulefile
920
921 Returns a list of all symbolic versions assigned to the passed
922 *modulefile*. The parameter *modulefile* might either be a full qualified
923 *modulefile* with name and version, another symbolic *modulefile* name
924 or a *modulefile* alias.
925
926 **module-info tags** [tag]
927
928 Returns all tags assigned to currently evaluated *modulefile* as a list of
929 strings if no *tag* name is given (see :ref:`Module tags` section in
930 :ref:`module(1)`)
931
932 When tags are assigned to specific module variants, they are returned only
933 if this variant is the one currently evaluated.
934
935 Returns ``1`` if one of the tags applying to currently evaluated
936 *modulefile* is *tag*. Returns ``0`` otherwise.
937
938 .. only:: html or latex
939
940 .. versionadded:: 4.7
941
942 **module-info type**
943
944 Returns either ``C`` or ``Tcl`` to indicate which :command:`module` command
945 is being executed, either the C version or the Tcl-only version, to allow
946 the *modulefile* writer to handle any differences between the two.
947
948 **module-info usergroups** [name]
949
950 Returns all the groups the user currently running :file:`modulecmd.tcl` is
951 member of as a list of strings if no *name* is given.
952
953 Returns ``1`` if one of the group current user running :file:`modulecmd.tcl`
954 is member of is *name*. Returns ``0`` otherwise.
955
956 If the Modules Tcl extension library is disabled, the :manpage:`id(1)`
957 command is invoked to fetch groups of current user.
958
959 .. only:: html or latex
960
961 .. versionadded:: 4.6
962
963 **module-info username** [name]
964
965 Returns the username of the user currently running :file:`modulecmd.tcl` as
966 a string if no *name* is given.
967
968 Returns ``1`` if username of current user running :file:`modulecmd.tcl` is
969 *name*. Returns ``0`` otherwise.
970
971 If the Modules Tcl extension library is disabled, the :manpage:`id(1)`
972 command is invoked to fetch username of current user.
973
974 .. only:: html or latex
975
976 .. versionadded:: 4.6
977
978 **module-info version** modulefile
979
980 Returns the physical module name and version of the passed symbolic
981 version *modulefile*. The parameter *modulefile* might either be a full
982 qualified *modulefile* with name and version, another symbolic *modulefile*
983 name or a *modulefile* alias.
984
985 .. mfcmd:: module-tag [options] tag modulefile...
986
987 Associate *tag* to designated *modulefile*. This tag information will be
988 reported along *modulefile* on :subcmd:`avail`, :subcmd:`list` and
989 :subcmd:`spider` sub-commands (see :ref:`Module tags` section in
990 :ref:`module(1)`). Tag information can be queried during *modulefile*
991 evaluation with the :mfcmd:`module-info tags<module-info>` modulefile
992 command. :mfcmd:`module-tag` commands should be placed in one of the
993 :file:`modulecmd.tcl` rc files.
994
995 :mfcmd:`module-tag` command accepts the following options:
996
997 * ``--not-user {user...}``
998 * ``--not-group {group...}``
999 * ``--user {user...}``
1000 * ``--group {group...}``
1001
1002 If ``--not-user`` option is set, the tag is not applied if the username of
1003 the user currently running :file:`modulecmd.tcl` is part of the list of
1004 username specified. Following the same approach, if ``--not-group`` option is
1005 set, the tag is not applied if current user is member of one of the groups
1006 specified. When both options are set, the tag is not applied if a match is
1007 found for ``--not-user`` or ``--not-group``.
1008
1009 If ``--user`` option is set, the tag is applied only if the username of the
1010 user currently running :file:`modulecmd.tcl` is part of the list of username
1011 specified. Following the same approach, if ``--group`` option is set, the tag
1012 is applied only if current user is member of one of the groups specified.
1013 When both options are set, the tag is applied if a match is found for
1014 ``--user`` or ``--group``. If the same user name is set on both ``--user``
1015 and ``--not-user`` options, ``--user`` prevails over ``--not-user``. If the
1016 same group name is set on both ``--group`` and ``--not-group``, ``--group``
1017 prevails over ``--not-group``.
1018
1019 The parameter *modulefile* may also be a symbolic modulefile name or a
1020 modulefile alias. It may also leverage a specific syntax to finely select
1021 module version (see `Advanced module version specifiers`_ section below).
1022 Moreover it may also be a full path file name to precisely designate one
1023 module in a specific modulepath.
1024
1025 Tags inherited from other modulefile commands or module states cannot be set
1026 with :mfcmd:`module-tag`. Otherwise an error is returned. Those special tags
1027 are: ``auto-loaded``, ``forbidden``, ``hidden``, ``hidden-loaded``,
1028 ``loaded``, ``nearly-forbidden`` and ``warning``.
1029
1030 When *tag* equals ``sticky`` or ``super-sticky``, designated *modulefile* is
1031 defined :ref:`Sticky modules`.
1032
1033 When *tag* equals ``keep-loaded``, designated *modulefile* is not
1034 automatically unloaded when it has been auto-loaded and its dependent modules
1035 are getting unloaded.
1036
1037 .. only:: html or latex
1038
1039 .. versionadded:: 4.7
1040
1041 .. versionchanged:: 5.1
1042 Tag ``keep-loaded`` added
1043
1044 .. versionchanged:: 5.4
1045 Full path file name may be used to designate *modulefile*
1046
1047 .. versionchanged:: 5.4
1048 Options ``--user`` and ``--group`` added
1049
1050 .. mfcmd:: module-version modulefile version-name...
1051
1052 Assigns the symbolic *version-name* to the *modulefile*. This command
1053 should be placed in one of the :file:`modulecmd.tcl` rc files in order to
1054 provide shorthand invocations of frequently used *modulefile* names.
1055
1056 The special *version-name* default specifies the default version to be
1057 used for module commands, if no specific version is given. This replaces
1058 the definitions made in the :file:`.version` file in former
1059 :file:`modulecmd.tcl` releases.
1060
1061 The parameter *modulefile* may be either
1062
1063 * a fully or partially qualified *modulefile* with name / version. If
1064 name is ``.`` (dot) then the current directory name is assumed to be the
1065 module name. (Use this for deep *modulefile* directories.)
1066
1067 * a symbolic *modulefile* name
1068
1069 * another *modulefile* alias
1070
1071 .. mfcmd:: module-virtual name modulefile
1072
1073 Assigns the *modulefile* to the virtual module *name*. This command should be
1074 placed in rc files in order to define virtual modules.
1075
1076 A virtual module stands for a module *name* associated to a *modulefile*. The
1077 modulefile is the script interpreted when loading or unloading the virtual
1078 module which appears or can be found with its virtual name.
1079
1080 The parameter *modulefile* corresponds to the relative or absolute file
1081 location of a *modulefile*.
1082
1083 .. only:: html or latex
1084
1085 .. versionadded:: 4.1
1086
1087 .. mfcmd:: module-warn [options] --message {text message} modulefile...
1088
1089 Print warning message when evaluating *modulefile*. This command could be
1090 placed in one of the :file:`modulecmd.tcl` rc files or within *modulefiles*.
1091 Warning is emitted when *modulefile* is evaluated in ``load``, ``display``,
1092 ``test``, ``help``.
1093
1094 :mfcmd:`module-warn` command accepts the following options:
1095
1096 * ``--after datetime``
1097 * ``--before datetime``
1098 * ``--not-user {user...}``
1099 * ``--not-group {group...}``
1100 * ``--user {user...}``
1101 * ``--group {group...}``
1102
1103 If ``--after`` option is set, warning is only effective after specified date
1104 time. Following the same principle, if ``--before`` option is set, warning is
1105 only effective before specified date time. Accepted date time format is
1106 ``YYYY-MM-DD[THH:MM]``. If no time (``HH:MM``) is specified, ``00:00`` is
1107 assumed. ``--after`` and ``--before`` options are not supported on Tcl
1108 versions prior to 8.5.
1109
1110 If ``--not-user`` option is set, warning is not applied if the username of
1111 the user currently running :file:`modulecmd.tcl` is part of the list of
1112 username specified. Following the same approach, if ``--not-group`` option is
1113 set, warning is not applied if current user is member of one of the groups
1114 specified. When both options are set, warning is not applied if a match is
1115 found for ``--not-user`` or ``--not-group``.
1116
1117 If ``--user`` option is set, warning is applied only if the username of the
1118 user currently running :file:`modulecmd.tcl` is part of the list of username
1119 specified. Following the same approach, if ``--group`` option is set, warning
1120 is applied only if current user is member of one of the groups specified.
1121 When both options are set, warning is applied if a match is found for
1122 ``--user`` or ``--group``. If the same user name is set on both ``--user``
1123 and ``--not-user`` options, ``--user`` prevails over ``--not-user``. If the
1124 same group name is set on both ``--group`` and ``--not-group``, ``--group``
1125 prevails over ``--not-group``.
1126
1127 Modules in warning included in the result of :subcmd:`avail`, :subcmd:`list`
1128 or :subcmd:`spider` sub-commands are reported with a ``warning`` tag applied
1129 to them. See :ref:`Module tags` section in :ref:`module(1)`.
1130
1131 The parameter *modulefile* may leverage a specific syntax to finely select
1132 module version (see `Advanced module version specifiers`_ section below). It
1133 may also be a full path file name to precisely designate one module in a
1134 specific modulepath.
1135
1136 .. only:: html or latex
1137
1138 .. versionadded:: 5.6
1139
1140 .. mfcmd:: module-whatis string
1141
1142 Defines a string which is displayed in case of the invocation of the
1143 :subcmd:`module whatis<whatis>` command. There may be more than one
1144 :mfcmd:`module-whatis` line in a *modulefile*. This command takes no actions
1145 in case of :subcmd:`load`, :subcmd:`display`, etc. invocations of
1146 :file:`modulecmd.tcl`.
1147
1148 The *string* parameter has to be enclosed in double-quotes if there's more
1149 than one word specified. Words are defined to be separated by whitespace
1150 characters (space, tab, cr).
1151
1152 .. mfcmd:: modulepath-ignore pattern...
1153
1154 Ignore files and directories matching *pattern* when walking down modulepath
1155 content to search for modulefiles. Ignored elements are handled as if they
1156 do not exist: they are not checked, not walked down, not reported and not
1157 recorded in modulepath cache file.
1158
1159 *pattern* follows the same syntax and behavior than git with
1160 :file:`.gitignore` files:
1161
1162 * A pattern without slash (except an optional trailing one) matches files or
1163 directories at any depth below the directory of the rc file defining it.
1164 * A pattern with a slash at its start or in its middle is relative to the
1165 directory of the rc file defining it.
1166 * A pattern ending with a slash only matches directories.
1167 * ``*`` matches anything except a slash. ``?`` matches any single character
1168 except a slash. ``[...]`` matches one character from a range or class.
1169 * A leading ``**/`` means match in any directory. A trailing ``/**`` matches
1170 everything inside the designated directory. ``a/**/b`` matches with zero
1171 or more intermediate directories.
1172 * A pattern starting with ``!`` negates a previous match: the element is
1173 re-included. It is not possible to re-include an element if one of its
1174 parent directories is ignored.
1175 * When several patterns match an element, the last matching pattern decides.
1176
1177 When defined in a ``.modulerc`` file located within a modulepath directory,
1178 patterns are relative to the directory of this rc file. When defined in a
1179 global or user rc file, patterns apply to every modulepath, relatively to
1180 their root directory.
1181
1182 The ``.modulerc`` and ``.version`` files of walked-through directories are
1183 exempt from ignore matching.
1184
1185 ``modulepath-ignore`` definitions should not be conditional: ignored
1186 elements are excluded from modulepath cache file when it is built, so
1187 patterns have to be static to get consistent results whether cache is used
1188 or not.
1189
1190 The :mconfig:`modulepath_ignore` configuration option, enabled by default,
1191 controls whether ``modulepath-ignore`` definitions are applied.
1192
1193 .. only:: html or latex
1194
1195 .. versionadded:: 5.7
1196
1197 .. mfcmd:: modulepath-label directory label
1198
1199 Assigns *label* string to modulepath *directory*. This *label* is used on
1200 :subcmd:`avail`, :subcmd:`whatis`, :subcmd:`search` and :subcmd:`spider`
1201 output to refer to the modulepath.
1202
1203 The parameter *directory* corresponds to a fully or partially qualified
1204 modulepath. If *directory* is ``.`` (dot) then the current directory of the
1205 modulerc file defining this command is assumed.
1206
1207 .. only:: html or latex
1208
1209 .. versionadded:: 5.4
1210
1211 .. versionchanged:: 5.6
1212 Label also applied on :subcmd:`whatis` and :subcmd:`search` output
1213
1214 .. mfcmd:: prepend-path [-d C|--delim C|--delim=C] [--duplicates] variable value...
1215
1216 Append or prepend *value* to environment *variable*. The
1217 *variable* is a colon, or *delimiter*, separated list such as
1218 ``PATH=directory:directory:directory``. The default delimiter is a colon
1219 ``:``, but an arbitrary one can be given by the ``--delim`` option. For
1220 example a space can be used instead (which will need to be handled in
1221 the Tcl specially by enclosing it in ``" "`` or ``{ }``). A space, however,
1222 can not be specified by the ``--delim=C`` form.
1223
1224 A reference counter environment variable is also set to know the number of
1225 times *value* has been added to environment *variable* when it is added more
1226 than one time. This reference counter environment variable is named by
1227 prefixing *variable* by :envvar:`__MODULES_SHARE_<__MODULES_SHARE_\<VAR\>>`.
1228
1229 When *value* is already defined in environment *variable*, it is not added
1230 again or moved at the end or at the beginning of *variable*. Exception is
1231 made when the ``--duplicates`` option is set in which case *value* is added
1232 again to *variable*.
1233
1234 If the *variable* is not set, it is created. When a *modulefile* is
1235 unloaded, :mfcmd:`append-path` and :mfcmd:`prepend-path` become
1236 :mfcmd:`remove-path`.
1237
1238 If *value* corresponds to the concatenation of multiple elements separated by
1239 colon, or *delimiter*, character, each element is treated separately.
1240
1241 The provided *value* is used as-is. If any path resolution is required, it
1242 must be performed within the *modulefile* itself. Use caution when including
1243 characters with special meanings in the shell context (such as ``~``), as the
1244 shell may expand these paths automatically. This can prevent the
1245 corresponding entries from being properly removed when the *modulefile* is
1246 unloaded.
1247
1248 If the *variable* is :envvar:`MODULEPATH` and :mconfig:`require_via`
1249 configuration option is activated, the *modulefile* is considered a
1250 dependency by the loaded modulefiles stored in the added modulepaths.
1251
1252 If a link is defined for *variable* through the :mconfig:`linked_envvars`
1253 configuration option, the same :mfcmd:`prepend-path` command is applied to
1254 all associated environment variables.
1255
1256 If an initial value is defined for the *variable* through the
1257 :mconfig:`init_envvars` configuration option, that value is assigned before
1258 the modification is applied when the *variable* is not already set.
1259
1260 .. only:: html or latex
1261
1262 .. versionchanged:: 4.1
1263 Option ``--duplicates`` added
1264
1265 .. versionchanged:: 5.4
1266 *value* equal to *delimiter* character allowed
1267
1268 .. versionchanged:: 5.6
1269 When :mconfig:`require_via` configuration option is enabled, a
1270 modulefile adding path to :envvar:`MODULEPATH` environment variable is
1271 considered a requirement of modulefiles stored in this path.
1272
1273 .. mfcmd:: prereq [options] modulefile...
1274
1275 :mfcmd:`prereq` controls whether or not the *modulefile* will be loaded. The
1276 :mfcmd:`prereq` command lists *modulefiles* which must have been previously
1277 loaded before the current *modulefile* will be loaded. If a list contains
1278 more than one *modulefile*, then each member of the list acts as a Boolean OR
1279 operation. Multiple :mfcmd:`prereq` commands may be used to create a Boolean
1280 AND operation. If one of the requirements have not been satisfied, an error
1281 is reported and the current *modulefile* makes no changes to the user's
1282 environment.
1283
1284 If an argument for :mfcmd:`prereq` is a directory and any *modulefile* from
1285 the directory has been loaded, then the prerequisite is met. For example,
1286 specifying X11 as a :mfcmd:`prereq` means that any version of X11, X11/R4 or
1287 X11/R5, must be loaded before proceeding.
1288
1289 The parameter *modulefile* may also be a symbolic modulefile name or a
1290 modulefile alias. It may also leverage a specific syntax to finely select
1291 module version (see `Advanced module version specifiers`_ section below).
1292
1293 :mfcmd:`prereq` command accepts the following options:
1294
1295 * ``--modulepath modulepathlist``
1296 * ``--optional``
1297 * ``--tag taglist``
1298
1299 When the ``--optional`` option is set, the whole list of specified
1300 *modulefiles* is declared as an optional requirement list. Evaluation is not
1301 stopped if no *modulefile* from the list is loaded.
1302
1303 If the :mconfig:`auto_handling` configuration option is enabled
1304 :mfcmd:`prereq` will attempt to load specified modulefile if not found loaded
1305 yet (see :ref:`Automated module handling mechanisms<MODULES_AUTO_HANDLING>`
1306 in :ref:`module(1)`).
1307
1308 The ``--tag`` option accepts a list of module tags to apply to *modulefile*
1309 once loaded. *taglist* corresponds to the concatenation of multiple tags
1310 separated by colon character. *taglist* should not contain tags inherited
1311 from *modulefile* state or from other modulefile commands. If module is
1312 already loaded, tags from *taglist* are added to the list of tags already
1313 applied to this module.
1314
1315 The ``--modulepath`` option accepts a list of modulepath. *modulepathlist*
1316 corresponds to the concatenation of multiple modulepaths separated by colon
1317 character. When this option is set, required *modulefile* should be located
1318 within one of the listed modulepaths. A path in this list may correspond to
1319 the first path elements of an actual modulepath (e.g., ``/path/to`` will
1320 match modulefiles located into the ``/path/to/modulefiles`` modulepath
1321 directory).
1322
1323 If an attempt to load *modulefile* is performed and ``--modulepath`` option
1324 is set, *modulefile* will be searched in the enabled modulepaths whose start
1325 match one of the specified paths and in the specified paths not matching any
1326 enabled modulepaths. For instance if this option is set to
1327 ``/path/to:/another/path`` and ``/path/to/modulefiles`` is currently the sole
1328 enabled modulepath, *modulefile* will be searched into
1329 ``/path/to/modulefiles`` and ``/another/path`` directories.
1330
1331 .. only:: html or latex
1332
1333 .. versionchanged:: 4.2
1334 An attempt to load modulefile is made if :mconfig:`auto_handling`
1335 configuration option is enabled
1336
1337 .. versionchanged:: 5.1
1338 Option ``--tag`` added
1339
1340 .. versionchanged:: 5.2
1341 Option ``--optional`` added
1342
1343 .. versionchanged:: 5.5
1344 Option ``--modulepath`` added
1345
1346 .. mfcmd:: prereq-all [options] modulefile...
1347
1348 Declare *modulefile* as a requirement of currently loading module. This
1349 command acts as an alias of :mfcmd:`prereq` command. If more than one
1350 *modulefile* are specified, then this list acts as a Boolean AND operation,
1351 which means all specified *modulefiles* are required.
1352
1353 :mfcmd:`prereq-all` command accepts the following options:
1354
1355 * ``--modulepath modulepathlist``
1356 * ``--optional``
1357 * ``--tag taglist``
1358
1359 When the ``--optional`` option is set, each specified *modulefile* is
1360 declared as an optional requirement. A *modulefile* that cannot be loaded,
1361 will not stop the evaluation.
1362
1363 .. only:: html or latex
1364
1365 .. versionadded:: 5.1
1366
1367 .. versionchanged:: 5.2
1368 Option ``--optional`` added
1369
1370 .. versionchanged:: 5.5
1371 Option ``--modulepath`` added
1372
1373 .. mfcmd:: prereq-any [options] modulefile...
1374
1375 Alias of :mfcmd:`prereq` command.
1376
1377 .. only:: html or latex
1378
1379 .. versionadded:: 5.1
1380
1381 .. versionchanged:: 5.2
1382 Option ``--optional`` added
1383
1384 .. versionchanged:: 5.5
1385 Option ``--modulepath`` added
1386
1387 .. mfcmd:: provide modulefile...
1388
1389 Define each specified *modulefile* as a module alias of currently evaluating
1390 module. :mfcmd:`provide` command helps to declare the additional elements
1391 included in a modulefile.
1392
1393 The :mfcmd:`provide` command should be paired with a :mfcmd:`conflict`
1394 command if the specified alias should be uniquely provided in the currently
1395 loaded environment.
1396
1397 Note: A module alias defined using :mfcmd:`provide` command will not be
1398 recognized during module resolution. It is recommended to use the
1399 :mfcmd:`module-alias` command to define an alias that points to the default
1400 resolution target.
1401
1402 .. only:: html or latex
1403
1404 .. versionadded:: 5.6
1405
1406 .. mfcmd:: pushenv variable value
1407
1408 Set environment *variable* to *value* and save previous value of *variable*
1409 to restore it when *modulefile* is unloaded. Like for :mfcmd:`setenv`
1410 modulefile command, changes made to *variable* with :mfcmd:`pushenv` are
1411 applied to *variable* in Tcl's ``env`` array to update environment *variable*
1412 value in current evaluation context.
1413
1414 When *modulefile* is unloaded, the *value* saved from the :mfcmd:`pushenv`
1415 command of this modulefile is removed from saved value stack list. *variable*
1416 is then set to the remaining *value* on top of the stack or it is unset if
1417 stack becomes empty.
1418
1419 Saved value stack list for *variable* is stored in an environment variable
1420 which is named by prefixing *variable* by :envvar:`__MODULES_PUSHENV_\
1421 <__MODULES_PUSHENV_\<VAR\>>`.
1422
1423 If a link is defined for *variable* through the :mconfig:`linked_envvars`
1424 configuration option, the same :mfcmd:`pushenv` command is applied to all
1425 associated environment variables.
1426
1427 .. only:: html or latex
1428
1429 .. versionadded:: 5.1
1430
1431 .. mfcmd:: puts [-nonewline] [channelId] string
1432
1433 Writes the characters given by *string* to the channel given by *channelId*.
1434 This command is part of the regular set of Tcl commands but it is enhanced
1435 with specific features in the modulefile evaluation context. See the
1436 :manpage:`puts(n)` Tcl man page for the basic description of this command.
1437 Specific features for modulefile evaluation context are described in the
1438 remainder of this section.
1439
1440 Content written to the ``stderr`` channel is rendered as output message
1441 produced by modulefile. Content written to the ``stdout`` channel is rendered
1442 as shell command evaluated in the user current shell environment. Content
1443 sent to ``stdout`` is spooled to be rendered after the environment changes
1444 made by modulefile.
1445
1446 When *channelId* equals ``prestdout``, content is rendered as shell command
1447 evaluated in current shell environment. This content is spooled and rendered
1448 prior any other environment changes.
1449
1450 When *channelId* equals ``log``, content is sent to the log system through
1451 the defined :mconfig:`logger` command.
1452
1453 .. only:: html or latex
1454
1455 .. versionchanged:: 4.1
1456 Content sent to ``stdout`` is spooled to apply it after the rendering
1457 of the environment changes made by modulefile
1458
1459 .. versionchanged:: 5.1
1460 Channel ``prestdout`` added to render content prior any other
1461 environment changes
1462
1463 .. versionchanged:: 5.5
1464 Channel ``log`` added to send information to log system
1465
1466 .. mfcmd:: remove-path [options] variable value... [--append-on-unload|--prepend-on-unload value...]
1467
1468 Remove *value* from the colon, or *delimiter*, separated list in
1469 *variable*.
1470
1471 :mfcmd:`remove-path` command accepts the following options:
1472
1473 * ``-d C|--delim C|--delim=C``
1474 * ``--index``
1475 * ``--glob``
1476 * ``--remove-on-unload|--noop-on-unload|--append-on-unload|--prepend-on-unload``
1477
1478 See :mfcmd:`prepend-path` or :mfcmd:`append-path` for further
1479 explanation of using an arbitrary delimiter. Every string between colons, or
1480 delimiters, in *variable* is compared to *value*. If the two match, *value*
1481 is removed from *variable* if its reference counter is equal to 1 or unknown.
1482
1483 When ``--index`` option is set, *value* refers to an index in *variable*
1484 list. The string element pointed by this index is set for removal.
1485
1486 When ``--glob`` option is set, *value* refers to a glob-style pattern which
1487 is matched against values in *variable* to find those to remove. ``*``
1488 character in *value* matches any sequence of characters, including a null
1489 string. ``?`` character in *value* matches any single character. See
1490 :manpage:`string(n)` Tcl command for the full list of special characters.
1491
1492 When *modulefile* is unloaded, no operation is performed by default or if the
1493 ``--noop-on-unload`` option is set. If the ``--remove-on-unload`` option is
1494 set, *value* is removed. If the ``--append-on-unload`` option is set, append
1495 back *value* removed at load time or specific *value* if any set. If the
1496 ``--prepend-on-unload`` option is set, prepend back *value* removed at load
1497 time or specific *value* if any set. These options cannot be set if
1498 ``--index`` option is also set. The ``--append-on-unload`` and
1499 ``--prepend-on-unload`` options cannot be set if ``--glob`` option is also
1500 set.
1501
1502 Reference counter of *value* in *variable* denotes the number of times
1503 *value* has been added to *variable*. This information is stored in
1504 environment :envvar:`__MODULES_SHARE_variable<__MODULES_SHARE_\<VAR\>>`. When
1505 attempting to remove *value* from *variable*, relative reference counter is
1506 checked and *value* is removed only if counter is equal to 1 or not defined.
1507 Otherwise *value* is kept in *variable* and reference counter is decreased by
1508 1. If counter equals 1 after being decreased, *value* and its counter are
1509 removed from reference counter variable.
1510
1511 If *value* corresponds to the concatenation of multiple elements separated by
1512 colon, or *delimiter*, character, each element is treated separately.
1513
1514 An error is raised if *value* equals *delimiter* character.
1515
1516 If a link is defined for *variable* through the :mconfig:`linked_envvars`
1517 configuration option, the same :mfcmd:`remove-path` command is applied to
1518 all associated environment variables.
1519
1520 If an initial value is defined for *variable* through the
1521 :mconfig:`init_envvars` configuration option, variable is unset when, after
1522 the modification, its value matches the configured initial value and no
1523 explicit reference counter is defined.
1524
1525 .. only:: html or latex
1526
1527 .. versionchanged:: 4.1
1528 Option ``--index`` added
1529
1530 .. versionchanged:: 5.1
1531 Options ``--remove-on-unload``, ``--noop-on-unload``,
1532 ``--append-on-unload`` and ``--prepend-on-unload`` added
1533
1534 .. versionchanged:: 5.4
1535 Option ``--glob`` added
1536
1537 .. mfcmd:: report string
1538
1539 Output *string* as a message during *modulefile* evaluation.
1540
1541 .. only:: html or latex
1542
1543 .. versionadded:: 4.0
1544
1545 .. mfcmd:: reportError string
1546
1547 Output *string* as an error message during *modulefile* evaluation and raise
1548 error count. :mfcmd:`reportError` does not abort modulefile evaluation. Use
1549 the :manpage:`error(n)` Tcl command to abort evaluation in addition to emit
1550 an error message.
1551
1552 .. only:: html or latex
1553
1554 .. versionadded:: 4.0
1555
1556 .. mfcmd:: reportWarning string
1557
1558 Output *string* as a warning message during *modulefile* evaluation.
1559
1560 .. only:: html or latex
1561
1562 .. versionadded:: 4.0
1563
1564 .. mfcmd:: require-fullname
1565
1566 Abort *load* evaluation of *modulefile* if name specified to designate it is
1567 not the fully qualified one. Module alias or a symbolic version names are
1568 considered fully qualified names, exception made for the *default* symbol.
1569
1570 .. only:: html or latex
1571
1572 .. versionadded:: 5.1
1573
1574 .. mfcmd:: set-alias alias-name alias-string
1575
1576 Sets an alias with the name *alias-name* in the user's environment to the
1577 string *alias-string*. For some shells, aliases are not possible and the
1578 command has no effect (see `Shell support`_ section). When a *modulefile* is
1579 unloaded, :mfcmd:`set-alias` becomes :mfcmd:`unset-alias`.
1580
1581 .. mfcmd:: set-function function-name function-string
1582
1583 Creates a function with the name *function-name* in the user's environment
1584 with the function body *function-string*. For some shells, functions are not
1585 possible and the command has no effect (see `Shell support`_ section). When a
1586 *modulefile* is unloaded, :mfcmd:`set-function` becomes
1587 :mfcmd:`unset-function`.
1588
1589 .. only:: html or latex
1590
1591 .. versionadded:: 4.2
1592
1593 .. mfcmd:: setenv [--set-if-undef] variable value
1594
1595 Set environment *variable* to *value*. The :mfcmd:`setenv` command will also
1596 change the process' environment. A reference using Tcl's env associative
1597 array will reference changes made with the :mfcmd:`setenv` command. Changes
1598 made using Tcl's ``env`` associative array will **NOT** change the user's
1599 environment *variable* like the :mfcmd:`setenv` command. An environment
1600 change made this way will only affect the module parsing process. The
1601 :mfcmd:`setenv` command is also useful for changing the environment prior to
1602 the ``exec`` or :mfcmd:`system` command. When a *modulefile* is unloaded,
1603 :mfcmd:`setenv` becomes :mfcmd:`unsetenv`. If the environment *variable* had
1604 been defined it will be overwritten while loading the *modulefile*. A
1605 subsequent :subcmd:`unload` will unset the environment *variable* - the
1606 previous value cannot be restored! (Unless you handle it explicitly or if you
1607 use the :mfcmd:`pushenv` modulefile command instead of :mfcmd:`setenv`)
1608
1609 When the ``--set-if-undef`` option is set, environment variable is defined
1610 when *modulefile* is loaded only if not yet defined.
1611
1612 Any newline character in *value* is chopped if using *csh* or *tcsh* shells.
1613
1614 If a link is defined for *variable* through the :mconfig:`linked_envvars`
1615 configuration option, the same :mfcmd:`setenv` command is applied to all
1616 associated environment variables.
1617
1618 .. only:: html or latex
1619
1620 .. versionchanged:: 5.1
1621 Option ``--set-if-undef`` added
1622
1623 .. versionchanged:: 5.6
1624 Newline character in value supported except for *csh* and *tcsh* shells
1625
1626 .. mfcmd:: source-sh [--ignore eltlist] shell script [arg...]
1627
1628 Evaluate with *shell* the designated *script* with defined *arguments* to
1629 find out the environment changes it does. Those changes obtained by comparing
1630 environment prior and after *script* evaluation are then translated into
1631 corresponding *modulefile* commands, which are then applied during modulefile
1632 evaluation as if they were directly written in it.
1633
1634 When modulefile is unloaded, environment changes done are reserved by
1635 evaluating in the ``unload`` context the resulting modulefile commands, which
1636 were recorded in the :envvar:`__MODULES_LMSOURCESH` environment variable at
1637 ``load`` time.
1638
1639 Changes on environment variables, shell aliases, shell functions, shell
1640 completions and current working directory are tracked.
1641
1642 Changes made on environment variable intended for Modules private use (e.g.,
1643 :envvar:`LOADEDMODULES`, :envvar:`_LMFILES_`, ``__MODULES_*``) are ignored.
1644
1645 *Shell* could be specified as a command name or a fully qualified pathname.
1646 The following shells are supported: sh, dash, csh, tcsh, bash, ksh, ksh93,
1647 zsh and fish.
1648
1649 *Shell* could also be set to ``bash-eval``. In this mode, bash shell *script*
1650 is not sourced but the output resulting from its execution is evaluated to
1651 determine the environment changes it does.
1652
1653 The ``--ignore`` option accepts a list of shell elements whose changes made
1654 by *script* should be ignored. *eltlist* corresponds to the concatenation of
1655 multiple shell element separated by colon character. Accepted shell elements
1656 are: ``envvar``, ``alias``, ``function``, ``chdir`` and ``complete``.
1657
1658 .. note:: *shell* is run in non-interactive mode without loading any shell
1659 configuration or profile. As a result, script does not have access to
1660 transient definitions that are only available in interactive sessions or
1661 profile files, such as shell aliases, functions, or completion settings.
1662
1663 .. only:: html or latex
1664
1665 .. versionadded:: 4.6
1666
1667 .. versionchanged:: 5.1
1668 Changes on Modules private environment variable are ignored
1669
1670 .. versionchanged:: 5.1
1671 Support for tracking shell completion changes on bash, tcsh and fish
1672 shells added
1673
1674 .. versionchanged:: 5.4
1675 Support for ``bash-eval`` shell mode added
1676
1677 .. versionchanged:: 5.4
1678 Option ``--ignore`` added
1679
1680 .. mfcmd:: system string
1681
1682 Run *string* command through shell. On Unix, command is passed to the
1683 ``/bin/sh`` shell whereas on Windows it is passed to ``cmd.exe``.
1684 :file:`modulecmd.tcl` redirects stdout to stderr since stdout would be parsed
1685 by the evaluating shell. The exit status of the executed command is returned.
1686
1687 .. mfcmd:: uname field
1688
1689 Provide lookup of system information. Most *field* information are retrieved
1690 from the ``tcl_platform`` array (see the :manpage:`tclvars(n)` man page).
1691 Uname will return the string ``unknown`` if information is unavailable for
1692 the *field*.
1693
1694 :mfcmd:`uname` will invoke the :manpage:`uname(1)` command in order to get
1695 the operating system version and :manpage:`domainname(1)` to figure out the
1696 name of the domain.
1697
1698 *field* values are:
1699
1700 * ``sysname``: the operating system name
1701
1702 * ``nodename``: the hostname
1703
1704 * ``domain``: the name of the domain
1705
1706 * ``release``: the operating system release
1707
1708 * ``version``: the operating system version
1709
1710 * ``machine``: a standard name that identifies the system's hardware
1711
1712 .. mfcmd:: uncomplete name
1713
1714 Unsets completion for command *name* in the user's environment. When a
1715 *modulefile* is unloaded, no operation is performed.
1716
1717 The following shells are supported: bash, tcsh and fish.
1718
1719 .. only:: html or latex
1720
1721 .. versionadded:: 5.1
1722
1723 .. mfcmd:: unset-alias alias-name
1724
1725 Unsets an alias with the name *alias-name* in the user's environment.
1726
1727 .. mfcmd:: unset-function function-name
1728
1729 Removes a function with the name *function-name* from the user's environment.
1730
1731 .. only:: html or latex
1732
1733 .. versionadded:: 4.2
1734
1735 .. mfcmd:: unsetenv [options] variable [value]
1736
1737 Unsets environment *variable*. When a *modulefile* is unloaded, no operation
1738 is performed unless if an optional *value* is defined, in which case
1739 *variable* is set to *value*. The :mfcmd:`unsetenv` command changes the
1740 process' environment like :mfcmd:`setenv`.
1741
1742 If the ``--noop-on-unload`` option is set, no operation is performed when
1743 *modulefile* is unloaded. If the ``--unset-on-unload`` option is set,
1744 environment *variable* is also unset when *modulefile* is unloaded. These
1745 behaviors are applied even if an optional *value* is defined.
1746
1747 If a link is defined for *variable* through the :mconfig:`linked_envvars`
1748 configuration option, the same :mfcmd:`unsetenv` command is applied to all
1749 associated environment variables.
1750
1751 .. only:: html or latex
1752
1753 .. versionchanged:: 5.0
1754 *variable* is not unset when unloading *modulefile* and no optional
1755 value is provided
1756
1757 .. versionchanged:: 5.1
1758 Options ``--noop-on-unload`` and ``--unset-on-unload`` added
1759
1760 .. mfcmd:: variant [--boolean] [--default value] name [value...]
1761
1762 Declare :ref:`module variant<Module variants>` *name* with list of accepted
1763 *value* and instantiate it in the :mfvar:`ModuleVariant` array variable.
1764
1765 Variant's value is selected through the module designation that leads to the
1766 modulefile evaluation. See `Advanced module version specifiers`_ section to
1767 learn how variants could be specified.
1768
1769 Selected variant value is transmitted to the evaluating modulefile. A value
1770 must be specified for variant *name* and it must corresponds to a value in
1771 the accepted value list if such list is defined. Otherwise an error is
1772 raised. An exception is made if modulefile is evaluated in ``display`` mode:
1773 no error is raised if no value is specified for a given variant and variant
1774 is not instantiated in the :mfvar:`ModuleVariant` array variable. When no
1775 list of accepted value is defined, variant could be set to any value.
1776
1777 When the ``--default`` option is set, variant *name* is set to the *value*
1778 associated with this option in case no value is specified for variant in
1779 module designation.
1780
1781 If the ``--boolean`` option is set, variant *name* is defined as a Boolean
1782 variant. No list of accepted value should be defined in this case. All values
1783 recognized as Boolean value in Tcl are accepted (i.e., ``1``, ``true``,
1784 ``t``, ``yes``, ``y``, ``on``, ``0``, ``false``, ``f``, ``no``, ``n`` or
1785 ``off``). Boolean variants are instantiated in :mfvar:`ModuleVariant` using
1786 Tcl canonical form of Boolean value (i.e., ``0`` or ``1``).
1787
1788 A variant which is not defined as a Boolean variant cannot define Boolean
1789 values in its accepted value list, exception made for the ``0`` and ``1``
1790 integers. An error is raised otherwise.
1791
1792 Variant *name* should only be composed of characters part of the
1793 ``A-Za-z0-9_-`` range. Also, a variant name cannot start with ``-`` (minus)
1794 character and the overall name cannot just be a number. An error is raised
1795 if specified *name* does not match these rules.
1796
1797 A variant cannot be named ``version``. An error is raised otherwise.
1798
1799 .. only:: html or latex
1800
1801 .. versionadded:: 4.8
1802
1803 .. versionchanged:: 5.0
1804 No error raised if a defined variant is not specified when modulefile
1805 is evaluated in ``display`` mode
1806
1807 .. versionchanged:: 5.1
1808 Accepted value list is made optional
1809
1810 .. versionchanged:: 5.5
1811 Stricter variant name naming rule adopted
1812
1813 .. mfcmd:: versioncmp version1 version2
1814
1815 Compare version string *version1* against version string *version2*. Returns
1816 ``-1``, ``0`` or ``1`` respectively if *version1* is less than, equal to or
1817 greater than *version2*.
1818
1819 .. only:: html or latex
1820
1821 .. versionadded:: 4.7
1822
1823 .. mfcmd:: x-resource [resource-string|filename]
1824
1825 Merge resources into the X11 resource database. The resources are used to
1826 control look and behavior of X11 applications. The command will attempt
1827 to read resources from *filename*. If the argument isn't a valid file
1828 name, then string will be interpreted as a resource. Either *filename*
1829 or *resource-string* is then passed down to be :manpage:`xrdb(1)` command.
1830
1831 *modulefiles* that use this command, should in most cases contain one or
1832 more :mfcmd:`x-resource` lines, each defining one X11 resource. The
1833 :envvar:`DISPLAY` environment variable should be properly set and the X11
1834 server should be accessible. If :mfcmd:`x-resource` can't manipulate the X11
1835 resource database, the *modulefile* will exit with an error message.
1836
1837 Examples:
1838
1839 ``x-resource /u2/staff/leif/.xres/Ileaf``
1840
1841 The content of the *Ileaf* file is merged into the X11 resource database.
1842
1843 ``x-resource [glob ~/.xres/ileaf]``
1844
1845 The Tcl glob function is used to have the *modulefile* read different
1846 resource files for different users.
1847
1848 ``x-resource {Ileaf.popup.saveUnder: True}``
1849
1850 Merge the Ileaf resource into the X11 resource database.
1851
1852 .. _Modulefile and run-command interp diff:
1853
1854 Modulefiles and run-command (rc) files are differently interpreted. A limited
1855 number of the Modules specific Tcl commands are available for rc files
1856 interpretation since such files are intended to set parameters for modulefiles
1857 (like defining alias, hiding, tagging, etc) and not to change user
1858 environment. The following table summarizes the different commands available
1859 for each interpretation context.
1860
1861 +---------------------------+-----------------------------------------------------+
1862 | Commands available from | Commands available from run-command (rc) file |
1863 | modulefile interpretation | interpretation |
1864 +===========================+=====================================================+
1865 | All the Modules specific | :mfcmd:`getenv`, :mfcmd:`hide-modulefile`, |
1866 | and standard Tcl commands | :mfcmd:`hide-version`, :mfcmd:`is-loaded`, |
1867 | | :mfcmd:`is-used`, :mfcmd:`lsb-release`, |
1868 | | :mfcmd:`module-alias`, :mfcmd:`module-forbid`, |
1869 | | :mfcmd:`module-hide`, :mfcmd:`module-info`, |
1870 | | :mfcmd:`module-tag`, :mfcmd:`module-version`, |
1871 | | :mfcmd:`module-virtual`, :mfcmd:`module-warn`, |
1872 | | :mfcmd:`modulepath-ignore`, |
1873 | | :mfcmd:`modulepath-label`, :mfcmd:`system`, |
1874 | | :mfcmd:`uname`, :mfcmd:`versioncmp` and standard |
1875 | | Tcl commands |
1876 +---------------------------+-----------------------------------------------------+
1877
1878 .. note:: Global and user run-command files are interpreted like modulefiles
1879 and benefit from all Modules specific Tcl commands. However it not advised
1880 to perform environment changes from such files.
1881
1882
1883 Modules Variables
1884 -----------------
1885
1886 .. mfvar:: ModulesCurrentModulefile
1887
1888 The :mfvar:`ModulesCurrentModulefile` variable contains the full pathname of
1889 the *modulefile* being interpreted.
1890
1891 .. mfvar:: ModulesVersion
1892
1893 The :mfvar:`ModulesVersion` variable can be set in :file:`.version` file to
1894 designate the name of the *modulefile* version which should be considered
1895 as default in current directory (see `Locating Modulefiles`_ section below).
1896
1897 .. mfvar:: ModuleTool
1898
1899 The :mfvar:`ModuleTool` variable contains the name of the *module*
1900 implementation currently in use. The value of this variable is set to
1901 ``Modules`` for this implementation.
1902
1903 .. only:: html or latex
1904
1905 .. versionadded:: 4.7
1906
1907 .. mfvar:: ModuleToolVersion
1908
1909 The :mfvar:`ModuleToolVersion` variable contains the version of the *module*
1910 implementation currently in use. The value of this variable is set to
1911 |code version| for this version of Modules.
1912
1913 .. only:: html or latex
1914
1915 .. versionadded:: 4.7
1916
1917 .. mfvar:: ModuleVariant
1918
1919 The :mfvar:`ModuleVariant` array variable contains an element entry for each
1920 defined variant associated to the value of this variant (e.g., the
1921 ``$ModuleVariant(foo)`` syntax corresponds to the value of variant ``foo`` if
1922 defined). A Tcl evaluation error is obtained when accessing an undefined
1923 variant in :mfvar:`ModuleVariant` array. Use preferably the
1924 :mfcmd:`getvariant` command to retrieve a variant value when this variant
1925 state is not known.
1926
1927 The list of the currently defined variants can be retrieved with
1928 ``[array names ModuleVariant]`` Tcl code.
1929
1930 .. only:: html or latex
1931
1932 .. versionadded:: 4.8
1933
1934 .. _Locating Modulefiles:
1935
1936 Locating Modulefiles
1937 --------------------
1938
1939 Every directory in :envvar:`MODULEPATH` is searched to find the
1940 *modulefile*. A directory in :envvar:`MODULEPATH` can have an arbitrary number
1941 of sub-directories. If the user names a *modulefile* to be loaded which
1942 is actually a directory, the directory is opened and a search begins for
1943 an actual *modulefile*. First, :file:`modulecmd.tcl` looks for a file with
1944 the name :file:`.modulerc` in the directory. If this file exists, its contents
1945 will be evaluated as if it was a *modulefile* to be loaded. You may place
1946 :mfcmd:`module-version`, :mfcmd:`module-alias` and :mfcmd:`module-virtual`
1947 commands inside this file.
1948
1949 Additionally, before seeking for :file:`.modulerc` files in the module
1950 directory, the global modulerc file and the :file:`.modulerc` file found at
1951 the root of the modulepath directory are sourced, too. If a named version
1952 default now exists for the *modulefile* to be loaded, the assigned
1953 *modulefile* now will be sourced. Otherwise the file :file:`.version` is
1954 looked up in the module directory.
1955
1956 If the :file:`.version` file exists, it is opened and interpreted as Tcl code
1957 and takes precedence over a :file:`.modulerc` file in the same directory. If
1958 the Tcl variable :mfvar:`ModulesVersion` is set by the :file:`.version` file,
1959 :file:`modulecmd.tcl` will use the name as if it specifies a *modulefile* in
1960 this directory. This will become the default *modulefile* in this case.
1961 :mfvar:`ModulesVersion` cannot refer to a *modulefile* located in a different
1962 directory.
1963
1964 If :mfvar:`ModulesVersion` is a directory, the search begins anew down that
1965 directory. If the name does not match any files located in the current
1966 directory, the search continues through the remaining directories in
1967 :envvar:`MODULEPATH`.
1968
1969 Every :file:`.version` and :file:`.modulerc` file found is interpreted as Tcl
1970 code. The difference is that :file:`.version` only applies to the current
1971 directory, and the :file:`.modulerc` applies to the current directory and all
1972 subdirectories. Changes made in these files will affect the subsequently
1973 interpreted *modulefile*.
1974
1975 If a :file:`.modulecache` file is found at the root of a modulepath directory,
1976 this file is interpreted as Tcl code to learn all :file:`.modulerc`,
1977 :file:`.version` and modulefiles available. Modulepath content is read from
1978 :ref:`module cache<Module cache>` file. Modulepath directory is only walked
1979 through to check if limited access modulefiles or directories are available to
1980 current user.
1981
1982 If no default version may be figured out, an implicit default is selected when
1983 this behavior is enabled (see :envvar:`MODULES_IMPLICIT_DEFAULT` in
1984 :ref:`module(1)`). If disabled, module names should be fully qualified when no
1985 explicit default is defined for them, otherwise no default version is found
1986 and an error is returned. If enabled, then the highest numerically sorted
1987 *modulefile*, virtual module or module alias under the directory will be used.
1988 The dictionary comparison method of the :manpage:`lsort(n)` Tcl command is
1989 used to achieve this sort. If highest numerically sorted element is an alias,
1990 search continues on its *modulefile* target.
1991
1992 For example, it is possible for a user to have a directory named X11 which
1993 simply contains a :file:`.version` file specifying which version of X11 is to
1994 be loaded. Such a file would look like:
1995
1996 .. code-block:: tcl
1997
1998 #%Module
1999 set ModulesVersion R4
2000
2001 The equivalent :file:`.modulerc` would look like:
2002
2003 .. code-block:: tcl
2004
2005 #%Module
2006 module-version ./R4 default
2007
2008 If the extended default mechanism is enabled (see
2009 :envvar:`MODULES_EXTENDED_DEFAULT` in :ref:`module(1)`) the module version
2010 specified is matched against starting portion of existing module versions,
2011 where portion is a substring separated from the rest of version string by
2012 ``.`` or ``-`` characters.
2013
2014 When the implicit default mechanism and the `Advanced module version
2015 specifiers`_ are both enabled, a ``default`` and ``latest`` symbolic versions
2016 are automatically defined for each module name (also at each directory level
2017 in case of deep *modulefile*). Unless a symbolic version, alias, or regular
2018 module version already exists for these version names.
2019
2020 Every file in searched directories is checked to see if it begins with the
2021 Modules magic cookie (i.e., ``#%Module`` file signature) to determine if it is
2022 a *modulefile* (see `DESCRIPTION`_ section). When the :mconfig:`mcookie_check`
2023 configuration is set to ``eval``, this check is skipped and all files in
2024 search directories are considered *modulefiles*.
2025
2026 If user names a *modulefile* that cannot be found in the first *modulepath*
2027 directory, *modulefile* will be searched in next *modulepath* directory
2028 and so on until a matching *modulefile* is found. If search goes through
2029 a module alias or a symbolic version, this alias or symbol is resolved by
2030 first looking at the *modulefiles* in the *modulepath* where this alias or
2031 symbol is defined. If not found, resolution looks at the other *modulepaths*
2032 in their definition order.
2033
2034 When locating *modulefiles*, if a :file:`.modulerc`, a :file:`.version`, a
2035 directory or a *modulefile* cannot be read during the search it is simply
2036 ignored with no error message produced. Visibility of *modulefiles* can thus
2037 be adapted to the rights the user has been granted. Exception is made when
2038 trying to directly access a directory or a *modulefile*. In this case,
2039 the access issue is returned as an error message.
2040
2041 Depending on their name, their file permissions or the use of specific
2042 modulefile commands, *modulefile*, virtual module, module alias or symbolic
2043 version may be set hidden which impacts available modules search or module
2044 selection processes (see `Hiding modulefiles`_ section below).
2045
2046 .. _Hiding modulefiles:
2047
2048 Hiding modulefiles
2049 ------------------
2050
2051 A *modulefile*, virtual module, module alias or symbolic version whose name or
2052 element in their name starts with a dot character (``.``) or who are targeted
2053 by a :mfcmd:`module-hide` command are considered hidden. Hidden modules are
2054 not displayed or taken into account except if they are explicitly named (e.g.,
2055 ``foo/1.2.3`` or ``foo/.2.0`` not ``foo``). If module has been hidden with the
2056 ``--soft`` option of the :mfcmd:`module-hide` command set, it is not
2057 considered hidden if the root name of the query to search it matches module
2058 root name (e.g., searching ``foo`` will return a ``foo/1.2.3`` modulefile
2059 targeted by a ``module-hide --soft`` command). If module has been hidden with
2060 the ``--hard`` option of the :mfcmd:`module-hide` command set, it is always
2061 considered hidden thus it is never displayed nor taken into account even if
2062 it is explicitly named.
2063
2064 A *modulefile*, virtual module, module alias or symbolic version who are
2065 targeted by a :mfcmd:`module-hide --hard<module-hide>` command and a
2066 :mfcmd:`module-forbid` command or whose file access permissions are restricted
2067 are considered hard-hidden and forbidden. Such modules are not displayed or
2068 taken into account. When explicitly named for evaluation selection, such
2069 modules are unveiled to return an access error.
2070
2071 .. note:: When the :mconfig:`mcookie_check` configuration is set to ``eval``,
2072 file access permissions are not checked thus files with restricted
2073 permissions are included in search results but still lead to error if
2074 evaluated.
2075
2076 A symbolic version-name assigned to a hidden module is displayed or taken into
2077 account only if explicitly named and if module is not hard-hidden. Non-hidden
2078 module alias targeting a hidden *modulefile* appears like any other non-hidden
2079 module alias. Finally, a hidden symbolic version targeting a non-hidden module
2080 is displayed or taken into account only if not hard-hidden and explicitly
2081 named to refer to its non-hidden target.
2082
2083 The automatic version symbols (e.g., ``default`` and ``latest``) are
2084 unaffected by hiding. Moreover when a regular ``default`` or ``latest``
2085 version is set hidden, the corresponding automatic version symbol takes the
2086 left spot. For instance, if ``foo/default`` which targets ``foo/1.2.3`` is set
2087 hard-hidden, the ``default`` automatic version symbol will be set onto
2088 ``foo/2.1.3``, the highest available version of ``foo``.
2089
2090 When loading a *modulefile* or a virtual module targeted by a
2091 :mfcmd:`module-hide --hidden-loaded<module-hide>` command, this module
2092 inherits the ``hidden-loaded`` tag. Hidden loaded modules are not reported
2093 among :subcmd:`list` sub-command results.
2094
2095 If the :option:`--all` option is set on :subcmd:`avail`, :subcmd:`aliases`,
2096 :subcmd:`whatis`, :subcmd:`search` or :subcmd:`spider` sub-commands, hidden
2097 modules are taken into account in search. Hard-hidden modules are unaffected
2098 by this option.
2099
2100 If the :option:`--all` option is set on :subcmd:`list` sub-command, hidden
2101 loaded modules are included in result output.
2102
2103 A behavior equivalent to the use of the :option:`--all` option is obtained on
2104 :subcmd:`avail`, :subcmd:`list` and :subcmd:`spider` sub-commands by adding
2105 the ``hidden`` element to the output configuration option controlling regular
2106 or terse reporting of these sub-commands: :mconfig:`avail_output`,
2107 :mconfig:`avail_terse_output`, :mconfig:`list_output`,
2108 :mconfig:`list_terse_output`, :mconfig:`spider_output`,
2109 :mconfig:`spider_terse_output`.
2110
2111 .. _advanced_module_version_specifiers:
2112
2113 Advanced module version specifiers
2114 ----------------------------------
2115
2116 When the advanced module version specifiers mechanism is enabled (see
2117 :envvar:`MODULES_ADVANCED_VERSION_SPEC` in :ref:`module(1)`), the
2118 specification of modulefile passed on Modules specific Tcl commands changes.
2119 After the module name a version constraint and variants may be added.
2120
2121 Version specifiers
2122 ^^^^^^^^^^^^^^^^^^
2123
2124 After the module name a version constraint prefixed by the ``@`` character may
2125 be added. It could be directly appended to the module name or separated from
2126 it with a space character.
2127
2128 Constraints can be expressed to refine the selection of module version to:
2129
2130 * a single version with the ``@version`` syntax, for instance ``[email protected]``
2131 syntax will select module ``foo/1.2.3``
2132 * a list of versions with the ``@version1,version2,...`` syntax, for instance
2133 ``[email protected],1.10`` will match modules ``foo/1.2.3`` and ``foo/1.10``
2134 * a range of versions with the ``@version1:``, ``@:version2`` and
2135 ``@version1:version2`` syntaxes, for instance ``[email protected]:`` will select all
2136 versions of module ``foo`` greater than or equal to ``1.2``, ``foo@:1.3``
2137 will select all versions less than or equal to ``1.3`` and ``[email protected]:1.3``
2138 matches all versions between ``1.2`` and ``1.3`` including ``1.2`` and
2139 ``1.3`` versions
2140
2141 Advanced specification of single version or list of versions may benefit from
2142 the activation of the extended default mechanism (see
2143 :envvar:`MODULES_EXTENDED_DEFAULT` in :ref:`module(1)`) to use an abbreviated
2144 notation like ``@1`` to refer to more precise version numbers like ``1.2.3``.
2145 Characters ``.`` and ``-`` are considered version number separator to
2146 determine abbreviated versions. Range of versions on its side natively handles
2147 abbreviated versions.
2148 The upper bound may be less precise than the lower bound. An abbreviated
2149 upper bound includes all versions that extend it, provided they also satisfy
2150 the lower bound.
2151
2152 In order to be specified in a range of versions or compared to a range of
2153 versions, the version major element should corresponds to a number. For
2154 instance ``10a``, ``1.2.3``, ``1.foo`` are versions valid for range
2155 comparison whereas ``default`` or ``foo.2`` versions are invalid for range
2156 comparison.
2157
2158 Range of versions can be specified in version list, for instance
2159 ``foo@:1.2,1.4:1.6,1.8:``. Such specification helps to exclude specific
2160 versions, like versions ``1.3`` and ``1.7`` in previous example.
2161
2162 If the implicit default mechanism is also enabled (see
2163 :envvar:`MODULES_IMPLICIT_DEFAULT` in :ref:`module(1)`), a ``default`` and
2164 ``latest`` symbolic versions are automatically defined for each module name
2165 (also at each directory level for deep *modulefiles*). These automatic version
2166 symbols are defined unless a symbolic version, alias, or regular module
2167 version already exists for these ``default`` or ``latest`` version names.
2168 Using the ``mod@latest`` (or ``mod/latest``) syntax ensures highest available
2169 version will be selected.
2170
2171 .. only:: html or latex
2172
2173 .. versionadded:: 4.4
2174
2175 .. versionchanged:: 4.8
2176 Use of version range is allowed in version list
2177
2178 .. versionchanged:: 5.7
2179 Character ``-`` is also considered a version number separator
2180
2181 Variants
2182 ^^^^^^^^
2183
2184 After the module name, variants can be specified. :ref:`Module variants` are
2185 alternative evaluation of the same *modulefile*. A variant is specified by
2186 associating a value to its name. This specification is then transmitted to the
2187 evaluating *modulefile* which instantiates the variant in the
2188 :mfvar:`ModuleVariant` array variable when reaching the :mfcmd:`variant`
2189 modulefile command declaring this variant.
2190
2191 Variant can be specified with the ``name=value`` syntax where *name* is the
2192 declared variant name and *value*, the value this variant is set to when
2193 evaluating the *modulefile*.
2194
2195 Boolean variants can be specified with the ``+name`` syntax to set this
2196 variant on and with the ``-name`` or ``~name`` syntaxes to set this variant
2197 off. The ``-name`` syntax is not supported on :ref:`ml(1)` command as the
2198 minus sign already means to unload designated module. The ``~name`` and
2199 ``+name`` syntaxes could also be defined appended to another specification
2200 word (e.g., the module name, version or another variant specification),
2201 whereas ``-name`` syntax must be the start of a new specification word.
2202
2203 Boolean variants may also be specified with the ``name=value`` syntax. *value*
2204 should be set to ``1``, ``true``, ``t``, ``yes``, ``y`` or ``on`` to enable
2205 the variant or it should be set to ``0``, ``false``, ``f``, ``no``, ``n`` or
2206 ``off`` to disable the variant.
2207
2208 Shortcuts may be used to abbreviate variant specification. The
2209 :mconfig:`variant_shortcut` configuration option associates shortcut character
2210 to variant name. With a shortcut defined, variant could be specified with the
2211 ``<shortcut>value`` syntax. For instance if character ``%`` is set as a
2212 shortcut for variant ``foo``, the ``%value`` syntax is equivalent to the
2213 ``foo=value`` syntax.
2214
2215 Variant *name* should only be composed of characters part of the
2216 ``A-Za-z0-9_-`` range. Also, a variant name cannot start with ``-`` (minus)
2217 character and the overall name cannot just be a number.
2218
2219 Specific characters used in variant specification syntax cannot be used as
2220 part of the name or version of a module. These specific characters are ``+``,
2221 ``~``, ``=`` and all characters set as variant shortcut. Exception is made for
2222 ``+`` and ``~`` characters if string that follows after does not correspond to
2223 a valid variant name (e.g., *name+*, *name++*, *name/version+1*).
2224
2225 .. only:: html or latex
2226
2227 .. versionadded:: 4.8
2228
2229 .. versionchanged:: 5.5
2230 Stricter variant name naming rule adopted
2231
2232 .. versionchanged:: 5.5
2233 ``+`` and ``~`` characters are allowed in module name or version if not
2234 followed by a valid variant name
2235
2236 .. _Dependencies between modulefiles:
2237
2238 Dependencies between modulefiles
2239 --------------------------------
2240
2241 A modulefile may express dependencies on other modulefiles. Two kind of
2242 dependency exist: pre-requirement and conflict. The former means specified
2243 modulefiles should be loaded prior the modulefile that express the
2244 requirement. The latter means specified modulefiles should not be loaded for
2245 the modulefile that express the conflict to be loaded too.
2246
2247 Pre-requirement could be expressed with :mfcmd:`prereq`, :mfcmd:`prereq-any`,
2248 :mfcmd:`prereq-all`, :mfcmd:`depends-on`, :mfcmd:`depends-on-any`,
2249 :mfcmd:`always-load`, :mfcmd:`module load<module>`,
2250 :mfcmd:`module switch<module>`, :mfcmd:`module try-load<module>` or
2251 :mfcmd:`module load-any<module>` modulefile commands. When the
2252 :mconfig:`auto_handling` configuration option is disabled, required modulefile
2253 should be manually loaded prior their dependent modulefile when expressed with
2254 the :mfcmd:`prereq`, :mfcmd:`prereq-any`, :mfcmd:`prereq-all`,
2255 :mfcmd:`depends-on` or :mfcmd:`depends-on-any` modulefile commands. For other
2256 commands or when :mconfig:`auto_handling` is enabled, pre-required modulefiles
2257 are automatically loaded.
2258
2259 Another form of pre-requirement is expressed through the use of the modulefile
2260 commands :mfcmd:`module use<module>`, :mfcmd:`append-path
2261 MODULEPATH<append-path>`, or :mfcmd:`prepend-path MODULEPATH<prepend-path>`,
2262 when the :mconfig:`require_via` configuration option is enabled. In this
2263 context, a modulefile that adds a modulepath is treated as a requirement for
2264 the modulefiles loaded from that path. This pre-requirement is considered when
2265 such modules are already loaded, helping to maintain consistency when
2266 attempting to unload a modulefile that enables a modulepath.
2267
2268 Conflict is expressed with :mfcmd:`conflict`, :mfcmd:`family` or
2269 :mfcmd:`module unload<module>` modulefile commands. When the
2270 :mconfig:`auto_handling` or :mconfig:`conflict_unload` configuration options
2271 are disabled, a conflicting loaded modulefile should be manually unloaded
2272 prior loading the modulefile that express such conflict when defined with
2273 :mfcmd:`conflict` or :mfcmd:`family`. It is automatically unloaded when
2274 expressed with :mfcmd:`module unload<module>` (unless dependent modulefiles
2275 are loaded) or if :mconfig:`auto_handling` and :mconfig:`conflict_unload`
2276 options are enabled. An error is raised when trying to load a module that is
2277 already loaded but with a different variant set or coming from a different
2278 modulepath. If both options are enabled the loaded module is automatically
2279 unloaded to satisfy the new set of variant or modulepath asked.
2280
2281 It is strongly advised to define dependencies prior environment changes in a
2282 modulefile. Dependency resolution should be done before any environment change
2283 to ensure the environment is getting set in the same order whether
2284 pre-requirements are already loaded, or if they are automatically loaded when
2285 loading the modulefile which depends on them, or if all loaded modules are
2286 reloaded or refreshed. This is especially important when the modulefile
2287 updates an environment variable also altered by other modulefiles like
2288 :envvar:`PATH`. As the order of the path elements in such variable defines
2289 priority, it is important that this order does not change depending on the way
2290 the modulefiles are loaded. Moreover when :mconfig:`conflict_unload` is
2291 enabled, a conflicting loaded modulefile is unloaded at the time the
2292 :mfcmd:`conflict`, :mfcmd:`family` or :mfcmd:`module unload<module>` command
2293 is evaluated. Environment changes made prior to this command by the loading
2294 modulefile are overridden by this unload when they affect variables also
2295 altered by the unloaded modulefile. For instance a variable set by the loading
2296 modulefile ends up unset if it is also set by the unloaded modulefile.
2297
2298 :command:`module` keeps environment consistent which means a modulefile cannot
2299 be loaded if its requirements are not loaded or if a conflicting module is
2300 loaded. In addition a loaded module cannot be unloaded if other loaded modules
2301 depends on it. The :ref:`automated module handling
2302 mechanisms<MODULES_AUTO_HANDLING>` attempt to solve the dependencies expressed
2303 by loading or unloading additional modulefiles. When the :option:`--no-auto`
2304 option is set on :command:`module` command when loading or unload modulefile,
2305 automated module handling mechanisms are disabled and dependencies have to be
2306 solved manually. When dependencies are not satisfied, modulefile fails to load
2307 or unload.
2308
2309 Adding the ``--not-req`` option when expressing dependencies in modulefile
2310 with the :mfcmd:`module` command will attempt to load or unload the designated
2311 modulefile but it will not mark them as pre-requirement or conflict.
2312
2313 Adding the ``--optional`` option on :mfcmd:`prereq`, :mfcmd:`prereq-any`,
2314 :mfcmd:`prereq-all`, :mfcmd:`depends-on`, :mfcmd:`depends-on-any` or
2315 :mfcmd:`always-load` modulefile commands declares the pre-requirement as
2316 optional. If an optional pre-requirement is not found loaded or cannot be
2317 automatically loaded, the dependency expressed is yet considered satisfied.
2318 When an optional requirement is loaded afterward, the dependent module will
2319 get automatically reloaded if the :mconfig:`auto_handling` configuration
2320 option is enabled.
2321
2322 By adding the :option:`--force` option to the :command:`module` command when
2323 loading or unloading modulefile, the consistency checks are by-passed. This
2324 option cannot be used when expressing dependencies in modulefiles. If a module
2325 has been force loaded whereas its requirements are not loaded or whereas a
2326 conflicting module is also loaded, the user environment is said inconsistent.
2327
2328 Note that a pre-requirement should be found in the loaded module list prior
2329 its dependent module. User environment is considered inconsistent if
2330 pre-requirement module is found loaded after dependent module, as the
2331 environment changes may have been done in the wrong priority order.
2332
2333 When user environment is considered inconsistent global operations achieved by
2334 :subcmd:`refresh`, :subcmd:`reload` and :subcmd:`save` sub-commands cannot
2335 perform. This mechanism is there to avoid the situation to worsen by
2336 re-evaluating all loaded modules or recording this environment.
2337
2338 When the :mconfig:`auto_handling` configuration option is enabled, if missing
2339 pre-requirement modulefile gets loaded or conflicting modulefile gets unloaded
2340 the inconsistent loaded module will be automatically reloaded to make user
2341 environment consistent again.
2342
2343 .. only:: html or latex
2344
2345 .. versionchanged:: 4.2
2346 Options :option:`--force`, :option:`--auto` and :option:`--no-auto`
2347 added
2348
2349 .. versionchanged:: 4.2
2350 :ref:`Automated module handling mechanisms<MODULES_AUTO_HANDLING>` added
2351
2352 .. versionchanged:: 4.7
2353 Option ``--not-req`` added
2354
2355 .. versionchanged:: 5.6
2356 A modulefile enabling a modulepath is considered a requirement of
2357 modulefiles stored in this path if :mconfig:`require_via` configuration
2358 option is enabled
2359
2360 Modulefile Specific Help
2361 ------------------------
2362
2363 Users can request help about a specific *modulefile* through the
2364 :ref:`module(1)` command. The *modulefile* can print helpful information or
2365 start help oriented programs by defining a ``ModulesHelp`` subroutine. The
2366 subroutine will be called when the :subcmd:`module help modulefile<help>`
2367 command is used.
2368
2369 Help text may also be defined within *modulefile* with :mfcmd:`module-help`
2370 command. Text defined such way is printed before evaluation of ``ModulesHelp``
2371 subroutine if any.
2372
2373
2374 Modulefile Specific Test
2375 ------------------------
2376
2377 Users can request test of a specific *modulefile* through the :ref:`module(1)`
2378 command. The *modulefile* can perform some sanity checks on its
2379 definition or on its underlying programs by defining a ``ModulesTest``
2380 subroutine. The subroutine will be called when the
2381 :subcmd:`module test modulefile<test>` command is used. The subroutine should
2382 return 1 in case of success. If no or any other value is returned, test is
2383 considered failed.
2384
2385
2386 Modulefile Display
2387 ------------------
2388
2389 The :subcmd:`module display modulefile<display>` command will detail all
2390 changes that will be made to the environment. After displaying all of the
2391 environment changes :file:`modulecmd.tcl` will call the ``ModulesDisplay``
2392 subroutine. The ``ModulesDisplay`` subroutine is a good place to put
2393 additional descriptive information about the *modulefile*.
2394
2395
2396 .. _Compatibility with Lmod Tcl modulefile:
2397
2398 Compatibility with Lmod Tcl modulefile
2399 --------------------------------------
2400
2401 The :file:`modulecmd.tcl` program supports Tcl modulefile or modulerc written
2402 for Lmod, the alternative :command:`module` implementation developed in Lua.
2403 Except for the specific cases listed below, such modulefiles can be evaluated
2404 by Modules without producing errors. Key differences between the two
2405 implementations are outlined below.
2406
2407 The ``remove-property`` modulefile command is evaluated as a *no-operation*
2408 command. No error is obtained if this command is used in modulefiles but no
2409 change occurs.
2410
2411 The :mfcmd:`haveDynamicMPATH` is evaluated as a *no-operation* modulefile
2412 command. If modulefile conditionally updates :envvar:`MODULEPATH` environment
2413 variable, this command is needed to help Lmod know that modulefile changes
2414 :envvar:`MODULEPATH`. :subcmd:`spider` sub-command on Modules does not need
2415 this information as modulefile is evaluated in the context of the current
2416 user to determine whether :envvar:`MODULEPATH` is updated.
2417
2418 The :mfcmd:`break` command does not accept any argument. A ``msg`` argument
2419 can be set on Lmod to provide a customized break error message.
2420
2421 The :mfcmd:`setenv`, :mfcmd:`unsetenv`, :mfcmd:`prepend-path`,
2422 :mfcmd:`append-path`, :mfcmd:`remove-path`, :mfcmd:`pushenv` and ``module``
2423 :mfcmd:`load<module>`, :mfcmd:`load-any<module>`, :mfcmd:`try-load<module>`
2424 and :mfcmd:`unload<module>` modulefile commands do not support the ``--mode``
2425 option. An error is raised if this option is used.
2426
2427 The :mfcmd:`setenv` and :mfcmd:`unsetenv` modulefile commands do not support
2428 the ``--respect`` option. An error is raised if this option is used.
2429
2430 Use of :mfcmd:`reportError` command aborts modulefile evaluation on Lmod. This
2431 command only reports an error message on Modules.
2432
2433 The :mfcmd:`require-fullname` command only aborts *load* modulefile evaluation
2434 whereas the Lmod implementation also aborts *unload* and *display*
2435 evaluations.
2436
2437 When processing a :mfcmd:`family` command, the :envvar:`LMOD_FAMILY_\<NAME\>`
2438 environment variable is also defined to be compatible with modulefiles or
2439 scripts relying on such variable.
2440
2441 When unloading a modulefile, the :mfcmd:`pushenv` command does not update the
2442 value of the environment variable if this modulefile was not defining the
2443 value currently in use.
2444
2445 The third optional argument of :mfcmd:`append-path` and :mfcmd:`prepend-path`
2446 commands corresponds to a priority specification on Lmod whereas these two
2447 commands accept multiple path element arguments on Modules.
2448
2449 The :mfcmd:`prereq` command is equivalent to the :mfcmd:`prereq-any` command
2450 on Modules whereas on Lmod it is equivalent to the :mfcmd:`prereq-all`
2451 command.
2452
2453 If the :mconfig:`auto_handling` configuration option is disabled, the
2454 requirements defined with the :mfcmd:`depends-on` or :mfcmd:`depends-on-any`
2455 commands are not automatically loaded and an error is raised if none of these
2456 requirements are found loaded.
2457
2458 If the :mconfig:`auto_handling` or :mconfig:`conflict_unload` configuration
2459 options are disabled, the conflicts defined with the :mfcmd:`family` command
2460 are not automatically unloaded and an error is raised when trying to load a
2461 module defining a family already defined by a loaded module.
2462
2463 On :subcmd:`module load-any<load-any>` sub-command and modulefile command, a
2464 modulefile evaluation error is not reported and :subcmd:`module
2465 load-any<load-any>` continues to the next modulefile instead of aborting the
2466 whole process. No attempt to load listed modulefiles is made if one of these
2467 modulefiles is found already loaded.
2468
2469 On :mfcmd:`module try-load<module>` modulefile command, each modulefile
2470 specified is considered an optional pre-requirement. If it is loaded
2471 afterward and if the :mconfig:`auto_handling` configuration option is enabled,
2472 the dependent module will get automatically reloaded.
2473
2474 .. only:: html or latex
2475
2476 .. versionadded:: 5.1
2477
2478 .. versionchanged:: 5.5
2479 Modulefile commands :mfcmd:`hide-modulefile` and :mfcmd:`hide-version`
2480 implemented
2481
2482 .. versionchanged:: 5.6
2483 Modulefile commands :mfcmd:`add-property`, :mfcmd:`depends-on-any` and
2484 :mfcmd:`haveDynamicMPATH` implemented
2485
2486 .. _Shell support:
2487
2488 Shell support
2489 -------------
2490
2491 The :file:`modulecmd.tcl` program that evaluates *modulefiles* supports a
2492 variety of shells or languages: *sh* family shells (*sh*, *bash*, *ksh* and
2493 *zsh*), *csh* family shells (*csh* and *tcsh*), *fish*, *cmd*, *pwsh*,
2494 *python*, *perl*, *ruby*, *tcl*, *cmake*, *r*, and *lisp*.
2495
2496 Modulefiles produce environment changes when evaluated, like defining an
2497 environment variable. The :file:`modulecmd.tcl` program outputs the
2498 corresponding code for the selected "shell". Thereafter this code is evaluated
2499 by the :command:`module` alias or function to update the current environment.
2500
2501 Depending on the "shell" kind, not all the environment changes that can be
2502 defined in modulefiles are supported. The following table summarizes the
2503 changes that are supported by the shells supported by :file:`modulecmd.tcl`.
2504
2505 +--------+-----------------------+----------------------+-------------------------+---------------------+----------------+---------------------+
2506 | | Environment variables | Shell alias | Shell functions | Command completion | :mfcmd:`chdir` | :mfcmd:`x-resource` |
2507 | | (:mfcmd:`setenv`, | (:mfcmd:`set-alias`, | (:mfcmd:`set-function`, | (:mfcmd:`complete`, | | |
2508 | | :mfcmd:`unsetenv`, | :mfcmd:`unset-alias`)| :mfcmd:`unset-function`)| :mfcmd:`uncomplete`)| | |
2509 | | :mfcmd:`pushenv`, | | | | | |
2510 | | :mfcmd:`append-path`, | | | | | |
2511 | | :mfcmd:`prepend-path`,| | | | | |
2512 | | :mfcmd:`remove-path`) | | | | | |
2513 +========+=======================+======================+=========================+=====================+================+=====================+
2514 | sh | x | x | x | | x | x |
2515 +--------+-----------------------+----------------------+-------------------------+---------------------+----------------+---------------------+
2516 | bash | x | x | x | x | x | x |
2517 +--------+-----------------------+----------------------+-------------------------+---------------------+----------------+---------------------+
2518 | ksh | x | x | x | | x | x |
2519 +--------+-----------------------+----------------------+-------------------------+---------------------+----------------+---------------------+
2520 | zsh | x | x | x | | x | x |
2521 +--------+-----------------------+----------------------+-------------------------+---------------------+----------------+---------------------+
2522 | csh | x | x | | | x | x |
2523 +--------+-----------------------+----------------------+-------------------------+---------------------+----------------+---------------------+
2524 | tcsh | x | x | | x | x | x |
2525 +--------+-----------------------+----------------------+-------------------------+---------------------+----------------+---------------------+
2526 | fish | x | x | x | x | x | x |
2527 +--------+-----------------------+----------------------+-------------------------+---------------------+----------------+---------------------+
2528 | cmd | x | x | | | x | |
2529 +--------+-----------------------+----------------------+-------------------------+---------------------+----------------+---------------------+
2530 | pwsh | x | x | x | x | x | |
2531 +--------+-----------------------+----------------------+-------------------------+---------------------+----------------+---------------------+
2532 | python | x | | | | x | x |
2533 +--------+-----------------------+----------------------+-------------------------+---------------------+----------------+---------------------+
2534 | perl | x | | | | x | x |
2535 +--------+-----------------------+----------------------+-------------------------+---------------------+----------------+---------------------+
2536 | ruby | x | | | | x | x |
2537 +--------+-----------------------+----------------------+-------------------------+---------------------+----------------+---------------------+
2538 | tcl | x | | | | x | x |
2539 +--------+-----------------------+----------------------+-------------------------+---------------------+----------------+---------------------+
2540 | cmake | x | | | | | x |
2541 +--------+-----------------------+----------------------+-------------------------+---------------------+----------------+---------------------+
2542 | r | x | | | | x | x |
2543 +--------+-----------------------+----------------------+-------------------------+---------------------+----------------+---------------------+
2544 | lisp | x | | | | x | x |
2545 +--------+-----------------------+----------------------+-------------------------+---------------------+----------------+---------------------+
2546
2547 The :mfcmd:`source-sh` command evaluates a shell script and produces the
2548 modulefile commands corresponding to the environment changes made by this
2549 script. :mfcmd:`source-sh` is able to evaluate *sh*, *bash*, *ksh*, *zsh*,
2550 *csh*, *tcsh* and *fish* shell scripts. :mfcmd:`source-sh` produces
2551 environment changes corresponding to the kinds listed in the above table.
2552 Based on the evaluated script, refer to the above table to know the
2553 environment changes that will be rendered for the shell specified to
2554 :file:`modulecmd.tcl` program.
2555
2556
2557 ENVIRONMENT
2558 -----------
2559
2560 See the :ref:`ENVIRONMENT<module ENVIRONMENT>` section in the
2561 :ref:`module(1)` man page.
2562
2563 SEE ALSO
2564 --------
2565
2566 :ref:`envml(1)`, :ref:`ml(1)`, :ref:`module(1)`, ref:`modulecmd(1)`,
2567 :manpage:`Tcl(n)`, :manpage:`TclX(n)`, :manpage:`id(1)`, :manpage:`xrdb(1)`,
2568 :manpage:`exec(n)`, :manpage:`uname(1)`, :manpage:`domainname(1)`,
2569 :manpage:`tclvars(n)`, :manpage:`lsort(n)`, :manpage:`string(n)`
2570
2571
2572 NOTES
2573 -----
2574
2575 Tcl was developed by John Ousterhout at the University of California
2576 at Berkeley.
2577
2578 TclX was developed by Karl Lehenbauer and Mark Diekhans.