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