1MODULEFILE(4) Modules MODULEFILE(4)
2
6 modulefile - files containing Tcl code for the Modules package
7
9 modulefiles are written in the Tool Command Language, Tcl(n) and are
10 interpreted by the modulecmd.tcl program via the module user interface.
11 modulefiles can be loaded, unloaded, or switched on-the-fly while the
12 user is working; and can be used to implement site policies regarding
13 the access and use of applications.
14 A modulefile begins with the #%Module file signature, also called the
16 Modules magic cookie. A version number may be placed after this string.
17 The version number is useful as the modulefile format may change thus
18 it reflects the minimum version of modulecmd.tcl required to interpret
19 the modulefile. If a version number doesn't exist, then modulecmd.tcl
20 will assume the modulefile is compatible. Files without the magic
21 cookie or with a version number greater than the current version of
22 modulecmd.tcl will not be interpreted. If the mcookie_version_check
23 configuration is disabled the version number set is not checked.
24 Each modulefile contains the changes to a user's environment needed to
26 access an application. Tcl is a simple programming language which per‐
27 mits modulefiles to be arbitrarily complex, depending upon the applica‐
28 tion's and the modulefile writer's needs. If support for extended tcl
29 (tclX) has been configured for your installation of the Modules pack‐
30 age, you may use all the extended commands provided by tclX, too.
31 A typical modulefile is a simple bit of code that set or add entries to
33 the PATH, MANPATH, or other environment variables. A Modulefile is
34 evaluated against current modulecmd.tcl's mode which leads to specific
35 evaluation results. For instance if the modulefile sets a value to an
36 environment variable, this variable is set when modulefile is loaded
37 and unset when modulefile is unloaded.
38 Tcl has conditional statements that are evaluated when the modulefile
40 is interpreted. This is very effective for managing path or environment
41 changes due to different OS releases or architectures. The user envi‐
42 ronment information is encapsulated into a single modulefile kept in a
43 central location. The same modulefile is used by every user on any ma‐
44 chine. So, from the user's perspective, starting an application is ex‐
45 actly the same irrespective of the machine or platform they are on.
46 modulefiles also hide the notion of different types of shells. From the
48 user's perspective, changing the environment for one shell looks ex‐
49 actly the same as changing the environment for another shell. This is
50 useful for new or novice users and eliminates the need for statements
51 such as "if you're using the C Shell do this ..., otherwise if you're
52 using the Bourne shell do this ...". Announcing and accessing new soft‐
53 ware is uniform and independent of the user's shell. From the module‐
54 file writer's perspective, this means one set of information will take
55 care of every type of shell.
56
58 The Modules Package uses commands which are extensions to the "stan‐
59 dard" Tool Command Language Tcl(n) package. Unless otherwise specified,
60 the Module commands return the empty string. Some commands behave dif‐
61 ferently when a modulefile is loaded or unloaded. The command descrip‐
62 tions assume the modulefile is being loaded.
63 always-load [--optional] [--tag taglist] modulefile...
65 Load modulefile and apply the keep-loaded tag to it in order to
66 avoid the automatic unload of this modulefile when modules de‐
67 pendent of it are unloaded.
68 modulefile is declared as a requirement of currently loading
70 module. This command acts as an alias of module load command. If
71 more than one modulefile are specified, then this list acts as a
72 Boolean AND operation, which means all specified modulefiles are
73 required.
74 When the --optional option is set, each specified modulefile is
76 declared as an optional requirement. A modulefile that cannot be
77 loaded, will not stop the evaluation.
78 The --tag option accepts a list of module tags to apply to mod‐
80 ulefile once loaded in addition to the keep-loaded tag. taglist
81 corresponds to the concatenation of multiple tags separated by
82 colon character. taglist should not contain tags inherited from
83 modulefile state or from other modulefile commands. If module is
84 already loaded, tags from taglist are added to the list of tags
85 already applied to this module.
86 append-path [-d C|--delim C|--delim=C] [--duplicates] variable value...
88 See prepend-path.
89 break This is not a Modules-specific command, it's actually part of
91 Tcl, which has been overloaded similar to the continue and exit
92 commands to have the effect of causing the module not to be
93 listed as loaded and not affect other modules being loaded con‐
94 currently. All non-environment commands within the module will
95 be performed up to this point and processing will continue on to
96 the next module on the command line. The break command will only
97 have this effect if not used within a Tcl loop though.
98 An example: Suppose that a full selection of modulefiles are
100 needed for various different architectures, but some of the mod‐
101 ulefiles are not needed and the user should be alerted. Having
102 the unnecessary modulefile be a link to the following notavail
103 modulefile will perform the task as required.
104 #%Module1.0
106 ## notavail modulefile
107 ##
108 proc ModulesHelp { } {
109 puts stderr "This module does nothing but alert the user"
110 puts stderr "that the [module-info name] module is not available"
111 }
112 module-whatis "Notifies user that module is not available."
114 set curMod [module-info name]
115 if { [ module-info mode load ] } {
116 puts stderr "Note: '$curMod' is not available for [uname sysname]."
117 }
118 break
119 chdir directory
121 Set the current working directory to directory.
122 complete shell name body
124 Define shell completion for command name with specified body if
125 shell is the current shell under which modulecmd.tcl was in‐
126 voked. Body corresponds to argument options accepted by the
127 shell command which defines completion. When a modulefile is un‐
128 loaded, complete becomes uncomplete.
129 The following shells are supported: bash, tcsh, bash and fish.
131 Please refer to the documentation of these shells to learn how
132 to define completion. The command is ignored if an unsupported
133 shell is specified.
134 conflict modulefile...
136 conflict controls whether or not the modulefile will be loaded.
137 The conflict command lists modulefiles which conflict with the
138 current modulefile. If a list contains more than one modulefile,
139 then each member of the list acts as a Boolean OR operation.
140 Multiple conflict commands may be used to create a Boolean AND
141 operation. If one of the requirements have not been satisfied,
142 an error is reported and the current modulefile makes no changes
143 to the user's environment.
144 If an argument for conflict is a directory and any other module‐
146 file from that directory has been loaded, then a conflict will
147 occur. For example, specifying X11 as a conflict will stop
148 X11/R4 and X11/R5 from being loaded at the same time.
149 The parameter modulefile may also be a symbolic modulefile name
151 or a modulefile alias. It may also leverage a specific syntax to
152 finely select module version (see Advanced module version speci‐
153 fiers section below).
154 continue
156 This is not a modules specific command but another overloaded
157 Tcl command and is similar to the break or exit commands except
158 the module will be listed as loaded as well as performing any
159 environment or Tcl commands up to this point and then continuing
160 on to the next module on the command line. The continue command
161 will only have this effect if not used within a Tcl loop though.
162 depends-on [--optional] [--tag taglist] modulefile...
164 Alias of prereq-all command.
165 exit [N]
167 This is not a modules specific command but another overloaded
168 Tcl command and is similar to the break or continue commands.
169 However, this command will cause the immediate cessation of this
170 module and any additional ones on the command line. This module
171 and the subsequent modules will not be listed as loaded. No en‐
172 vironment commands will be performed in the current module.
173 family name
175 Defines loading modulefile as a member of family name. Only one
176 member of a family could be loaded. Error is raised when at‐
177 tempting to load another member of the same family name.
178 family corresponds to the definition of a conflict on name and
180 the definition of a module-alias name targeting currently load‐
181 ing module.
182 In addition, the MODULES_FAMILY_<NAME> environment variable is
184 defined and set to the currently loading module name minus ver‐
185 sion. This variable helps to know what module provides for the
186 family name in the currently loaded environment. For instance if
187 loading modulefile foo/1.0 defines being member of the bar fam‐
188 ily, the MODULES_FAMILY_BAR will be set to the foo value. For
189 compatibility, the LMOD_FAMILY_<NAME> environment variable is
190 also defined and set to the same value than
191 MODULES_FAMILY_<NAME>.
192 name should be a non-empty string only containing characters
194 that could be part of an environment variable name (i.e.,
195 [a-zA-Z0-9_]).
196 getenv [--return-value] variable [value]
198 Returns value of environment variable. If variable is not de‐
199 fined, value is returned if set, an empty string is returned
200 otherwise. The getenv command should be preferred over the Tcl
201 global variable env to query environment variables.
202 When modulefile is evaluated in display mode, getenv returns
204 variable name prefixed with dollar sign (e.g., $variable) unless
205 if the --return-value option is set. When this option is set the
206 value of environment variable or defined fallback value is re‐
207 turned in display mode.
208 getvariant [--return-value] variant [value]
210 Returns value of designated variant. If variant is not defined,
211 value is returned if set, an empty string is returned otherwise.
212 The getvariant command should be preferred over the
213 ModuleVariant Tcl array to query a variant value.
214 When modulefile is evaluated in display mode, getvariant returns
216 variant name enclosed in curly braces (e.g., {variant}) unless
217 if the --return-value option is set. When this option is set the
218 value of variant or defined fallback value is returned in dis‐
219 play mode.
220 is-avail modulefile...
222 The is-avail command returns a true value if any of the listed
223 modulefiles exists in enabled MODULEPATH. If a list contains
224 more than one modulefile, then each member acts as a boolean OR
225 operation. If an argument for is-avail is a directory and a mod‐
226 ulefile exists in the directory is-avail would return a true
227 value.
228 The parameter modulefile may also be a symbolic modulefile name
230 or a modulefile alias. It may also leverage a specific syntax to
231 finely select module version (see Advanced module version speci‐
232 fiers section below).
233 is-loaded [modulefile...]
235 The is-loaded command returns a true value if any of the listed
236 modulefiles has been loaded or if any modulefile is loaded in
237 case no argument is provided. If a list contains more than one
238 modulefile, then each member acts as a boolean OR operation. If
239 an argument for is-loaded is a directory and any modulefile from
240 the directory has been loaded is-loaded would return a true
241 value.
242 The parameter modulefile may also be a symbolic modulefile name
244 or a modulefile alias. It may also leverage a specific syntax to
245 finely select module version (see Advanced module version speci‐
246 fiers section below).
247 is-saved [collection...]
249 The is-saved command returns a true value if any of the listed
250 collections exists or if any collection exists in case no argu‐
251 ment is provided. If a list contains more than one collection,
252 then each member acts as a boolean OR operation.
253 If MODULES_COLLECTION_TARGET is set, a suffix equivalent to the
255 value of this variable is appended to the passed collection
256 name. In case no collection argument is provided, a true value
257 will only be returned if a collection matching currently set
258 target exists.
259 is-used [directory...]
261 The is-used command returns a true value if any of the listed
262 directories has been enabled in MODULEPATH or if any directory
263 is enabled in case no argument is provided. If a list contains
264 more than one directory, then each member acts as a boolean OR
265 operation.
266 module [sub-command] [sub-command-options] [sub-command-args]
268 This command permits a modulefile to load or unload other mod‐
269 ulefiles or to use or unuse modulepaths. No checks are made to
270 ensure that the modulefile does not try to load itself. Often
271 it is useful to have a single modulefile that performs a number
272 of module load commands. For example, if every user on the sys‐
273 tem requires a basic set of applications loaded, then a core
274 modulefile would contain the necessary module load commands.
275 The --not-req option may be set for the load, try-load,
277 load-any, unload and switch sub-commands to inhibit the defini‐
278 tion of an implicit prereq or conflict requirement onto speci‐
279 fied modules.
280 On try-load sub-command, if specified modulefile is not found
282 thus loaded, no implicit prereq requirement is defined over this
283 module.
284 The load-any sub-command loads one modulefile from the specified
286 list. An error is obtained if no modulefile from the list can
287 be loaded. No operation is performed if a modulefile from the
288 list is found already loaded.
289 The unuse sub-command accepts the --remove-on-unload,
291 --noop-on-unload, --append-on-unload and --prepend-on-unload op‐
292 tions to control the behavior to apply when modulefile is un‐
293 loaded. See remove-path for further explanation.
294 The load, try-load, load-any and switch sub-commands accept the
296 --tag option to apply specified tags to modulefile once loaded.
297 Option accepts a concatenation of multiple module tags separated
298 by colon character. taglist should not contain tags inherited
299 from modulefile state or from other modulefile commands. If mod‐
300 ule is already loaded, tags from taglist are added to the list
301 of tags already applied to this module.
302 Command line switches --auto, --no-auto and --force are ignored
304 when passed to a module command set in a modulefile.
305 Not all the sub-commands described in the Module Sub-Commands
307 section of the module man page are available when module is used
308 as a Modules specific Tcl command. The following table summa‐
309 rizes the different sub-commands available for each interpreta‐
310 tion context.
311 ┌────────────────────┬─────────────────────┬─────────────────────┐
313 │Sub-commands avail‐ │ Sub-commands avail‐ │ Sub-commands avail‐ │
314 │able from module‐ │ able from initrc │ able from run-com‐ │
315 │file interpretation │ configuration file │ mand (rc) file in‐ │
316 │ │ and sourced script │ terpretation │
317 │ │ file │ │
318 └────────────────────┴─────────────────────┴─────────────────────┘
319 │load, load-any, │ Same sub-commands │ None │
335 │switch, try-load, │ available than for │ │
336 │unload, unuse, use. │ modulefile and │ │
337 │Also available but │ config sub-command. │ │
338 │not recommended for │ │ │
339 │use from regular │ │ │
340 │modulefile: │ │ │
341 │aliases, avail, │ │ │
342 │display, initadd, │ │ │
343 │initclear, │ │ │
344 │initlist, │ │ │
345 │initprepend, │ │ │
346 │initrm, initswitch, │ │ │
347 │list, purge, │ │ │
348 │reload, restore, │ │ │
349 │save, savelist, │ │ │
350 │saverm, saveshow, │ │ │
351 │search, test, │ │ │
352 │whatis │ │ │
353 └────────────────────┴─────────────────────┴─────────────────────┘
354 module-alias name modulefile
356 Assigns the modulefile to the alias name. This command should be
357 placed in one of the modulecmd.tcl rc files in order to provide
358 shorthand invocations of frequently used modulefile names.
359 The parameter modulefile may be either
361 • a fully qualified modulefile with name and version
363 • a symbolic modulefile name
365 • another modulefile alias
367 module-forbid [options] modulefile...
369 Forbid use of modulefile. An error is obtained when trying to
370 evaluate a forbidden module. This command should be placed in
371 one of the modulecmd.tcl rc files.
372 module-forbid command accepts the following options:
374 • --after datetime
376 • --before datetime
378 • --not-user {user...}
380 • --not-group {group...}
382 • --message {text message}
384 • --nearly-message {text message}
386 If --after option is set, forbidding is only effective after
388 specified date time. Following the same principle, if --before
389 option is set, forbidding is only effective before specified
390 date time. Accepted date time format is YYYY-MM-DD[THH:MM]. If
391 no time (HH:MM) is specified, 00:00 is assumed. --after and
392 --before options are not supported on Tcl versions prior to 8.5.
393 If --not-user option is set, forbidding is not applied if the
395 username of the user currently running modulecmd.tcl is part of
396 the list of username specified. Following the same approach, if
397 --not-group option is set, forbidding is not applied if current
398 user is member of one the group specified. When both options are
399 set, forbidding is not applied if a match is found for
400 --not-user or --not-group.
401 Error message returned when trying to evaluate a forbidden mod‐
403 ule can be supplemented with the text message set through --mes‐
404 sage option.
405 If --after option is set, modules are considered nearly forbid‐
407 den during a number of days defined by the nearly_forbidden_days
408 modulecmd.tcl configuration option (see
409 MODULES_NEARLY_FORBIDDEN_DAYS), prior reaching the expiry date
410 fixed by --after option. When a nearly forbidden module is eval‐
411 uated a warning message is issued to inform module will soon be
412 forbidden. This warning message can be supplemented with the
413 text message set through --nearly-message option.
414 If a module-forbid command applies to a modulefile also targeted
416 by a module-hide --hard command, this module is unveiled when
417 precisely named to return an access error.
418 Forbidden modules included in the result of an avail sub-command
420 are reported with a forbidden tag applied to them. Nearly for‐
421 bidden modules included in the result of an avail or a list
422 sub-command are reported with a nearly-forbidden tag applied to
423 them. See Module tags section in module.
424 The parameter modulefile may leverage a specific syntax to
426 finely select module version (see Advanced module version speci‐
427 fiers section below).
428 module-hide [options] modulefile...
430 Hide modulefile to exclude it from available module search or
431 module selection unless query refers to modulefile by its exact
432 name. This command should be placed in one of the modulecmd.tcl
433 rc files.
434 module-hide command accepts the following options:
436 • --soft|--hard
438 • --hidden-loaded
440 • --after datetime
442 • --before datetime
444 • --not-user {user...}
446 • --not-group {group...}
448 When --soft option is set, modulefile is also set hidden, but
450 hiding is disabled when search or selection query's root name
451 matches module's root name. This soft hiding mode enables to
452 hide modulefiles from bare module availability listing yet keep‐
453 ing the ability to select such module for load with the regular
454 resolution mechanism (i.e., no need to use module exact name to
455 select it)
456 When --hard option is set, modulefile is also set hidden and
458 stays hidden even if search or selection query refers to module‐
459 file by its exact name.
460 When --hidden-loaded option is set, hidden state also applies to
462 the modulefile when it is loaded. Hidden loaded modules do not
463 appear on list sub-command output, unless --all option is set.
464 Their loading or unloading informational messages are not re‐
465 ported unless the verbosity of Modules is set to a level higher
466 than verbose. Hidden loaded modules are detected in any cases by
467 state query commands like is-loaded.
468 If --after option is set, hiding is only effective after speci‐
470 fied date time. Following the same principle, if --before option
471 is set, hiding is only effective before specified date time. Ac‐
472 cepted date time format is YYYY-MM-DD[THH:MM]. If no time
473 (HH:MM) is specified, 00:00 is assumed. --after and --before op‐
474 tions are not supported on Tcl versions prior to 8.5.
475 If --not-user option is set, hiding is not applied if the user‐
477 name of the user currently running modulecmd.tcl is part of the
478 list of username specified. Following the same approach, if
479 --not-group option is set, hiding is not applied if current user
480 is member of one the group specified. When both options are
481 set, hiding is not applied if a match is found for --not-user or
482 --not-group.
483 If the --all option is set on avail, aliases, whatis or search
485 sub-commands, hiding is disabled thus hidden modulefiles are in‐
486 cluded in module search. Hard-hidden modules (i.e., declared
487 hidden with --hard option) are not affected by --all and stay
488 hidden even if option is set. --all option does not apply to
489 module selection sub-commands like load. Thus in such context a
490 hidden module should always be referred by its exact full name
491 (e.g., foo/1.2.3 not foo) unless if it has been hidden in --soft
492 mode. A hard-hidden module cannot be unveiled or selected in any
493 case.
494 If several module-hide commands target the same modulefile, the
496 strongest hiding level is retained which means if both a regu‐
497 lar, a --soft hiding command match a given module, regular hid‐
498 ing mode is considered. If both a regular and a --hard hiding
499 command match a given module, hard hiding mode is retained. A
500 set --hidden-loaded option is retained even if the module-hide
501 statement on which it is declared is superseded by a stronger
502 module-hide statement with no --hidden-loaded option set.
503 Hidden modules included in the result of an avail sub-command
505 are reported with a hidden tag applied to them. Hidden loaded
506 modules included in the result of a list sub-command are re‐
507 ported with a hidden-loaded tag applied to them. This tag is not
508 reported on avail sub-command context. See Module tags section
509 in module.
510 The parameter modulefile may also be a symbolic modulefile name
512 or a modulefile alias. It may also leverage a specific syntax to
513 finely select module version (see Advanced module version speci‐
514 fiers section below).
515 module-info option [info-args]
517 Provide information about the modulecmd.tcl program's state.
518 Some of the information is specific to the internals of mod‐
519 ulecmd.tcl. option is the type of information to be provided,
520 and info-args are any arguments needed.
521 module-info alias name
523 Returns the full modulefile name to which the modulefile
524 alias name is assigned
525 module-info command [commandname]
527 Returns the currently running modulecmd.tcl's command as a
528 string if no commandname is given.
529 Returns 1 if modulecmd.tcl's command is commandname. com‐
531 mandname can be: load, unload, refresh, reload, source,
532 switch, display, avail, aliases, list, whatis, search, purge,
533 restore, help, test, try-load, load-any, mod-to-sh, reset,
534 stash or stashpop.
535 module-info loaded modulefile
537 Returns the names of currently loaded modules matching passed
538 modulefile. The parameter modulefile might either be a fully
539 qualified modulefile with name and version or just a direc‐
540 tory which in case all loaded modulefiles from the directory
541 will be returned. The parameter modulefile may also be a sym‐
542 bolic modulefile name or a modulefile alias.
543 This command only returns the name and version of designated
545 loaded module. The defined variants of the loaded module are
546 not included in the returned string.
547 module-info mode [modetype]
549 Returns the current modulecmd.tcl's mode as a string if no
550 modetype is given.
551 Returns 1 if modulecmd.tcl's mode is modetype. modetype can
553 be: load, unload, remove (alias of unload), switch, refresh,
554 nonpersist (alias of refresh), display, help, test, whatis or
555 scan.
556 module-info name
558 Return the name of the modulefile. This is not the full path‐
559 name for modulefile. See the Modules Variables section for
560 information on the full pathname.
561 This command only returns the name and version of currently
563 evaluating modulefile. The defined variants are not included
564 in the returned string. See getvariant command or
565 ModuleVariant array variable to get defined variant values
566 for currently evaluating modulefile.
567 module-info shell [shellname]
569 Return the current shell under which modulecmd.tcl was in‐
570 voked if no shellname is given. The current shell is the
571 first parameter of modulecmd.tcl, which is normally hidden by
572 the module alias.
573 If a shellname is given, returns 1 if modulecmd.tcl's current
575 shell is shellname, returns 0 otherwise. shellname can be:
576 sh, bash, ksh, zsh, csh, tcsh, fish, cmd, tcl, perl, python,
577 ruby, lisp, cmake, r.
578 module-info shelltype [shelltypename]
580 Return the family of the shell under which modulefile was in‐
581 voked if no shelltypename is given. As of module-info shell
582 this depends on the first parameter of modulecmd.tcl. The
583 output reflects a shell type determining the shell syntax of
584 the commands produced by modulecmd.tcl.
585 If a shelltypename is given, returns 1 if modulecmd.tcl's
587 current shell type is shelltypename, returns 0 otherwise.
588 shelltypename can be: sh, csh, fish, cmd, tcl, perl, python,
589 ruby, lisp, cmake, r.
590 module-info specified
592 Return the module designation (name, version and variants)
593 specified that led to current modulefile evaluation.
594 module-info symbols modulefile
596 Returns a list of all symbolic versions assigned to the
597 passed modulefile. The parameter modulefile might either be a
598 full qualified modulefile with name and version, another sym‐
599 bolic modulefile name or a modulefile alias.
600 module-info tags [tag]
602 Returns all tags assigned to currently evaluated modulefile
603 as a list of strings if no tag name is given (see Module tags
604 section in module)
605 When tags are assigned to specific module variants, they are
607 returned only if this variant is the one currently evaluated.
608 Returns 1 if one of the tags applying to currently evaluated
610 modulefile is tag. Returns 0 otherwise.
611 module-info type
613 Returns either C or Tcl to indicate which module command is
614 being executed, either the C version or the Tcl-only version,
615 to allow the modulefile writer to handle any differences be‐
616 tween the two.
617 module-info usergroups [name]
619 Returns all the groups the user currently running mod‐
620 ulecmd.tcl is member of as a list of strings if no name is
621 given.
622 Returns 1 if one of the group current user running mod‐
624 ulecmd.tcl is member of is name. Returns 0 otherwise.
625 If the Modules Tcl extension library is disabled, the id(1)
627 command is invoked to fetch groups of current user.
628 module-info username [name]
630 Returns the username of the user currently running mod‐
631 ulecmd.tcl as a string if no name is given.
632 Returns 1 if username of current user running modulecmd.tcl
634 is name. Returns 0 otherwise.
635 If the Modules Tcl extension library is disabled, the id(1)
637 command is invoked to fetch username of current user.
638 module-info version modulefile
640 Returns the physical module name and version of the passed
641 symbolic version modulefile. The parameter modulefile might
642 either be a full qualified modulefile with name and version,
643 another symbolic modulefile name or a modulefile alias.
644 module-tag [options] tag modulefile...
646 Associate tag to designated modulefile. This tag information
647 will be reported along modulefile on avail and list sub-commands
648 (see Module tags section in module). Tag information can be
649 queried during modulefile evaluation with the module-info tags
650 modulefile command. module-tag commands should be placed in one
651 of the modulecmd.tcl rc files.
652 module-tag command accepts the following options:
654 • --not-user {user...}
656 • --not-group {group...}
658 If --not-user option is set, the tag is not applied if the user‐
660 name of the user currently running modulecmd.tcl is part of the
661 list of username specified. Following the same approach, if
662 --not-group option is set, the tag is not applied if current
663 user is member of one the group specified. When both options are
664 set, the tag is not applied if a match is found for --not-user
665 or --not-group.
666 The parameter modulefile may also be a symbolic modulefile name
668 or a modulefile alias. It may also leverage a specific syntax to
669 finely select module version (see Advanced module version speci‐
670 fiers section below).
671 Tags inherited from other modulefile commands or module states
673 cannot be set with module-tag. Otherwise an error is returned.
674 Those special tags are: auto-loaded, forbidden, hidden, hid‐
675 den-loaded, loaded and nearly-forbidden.
676 When tag equals sticky or super-sticky, designated modulefile is
678 defined Sticky modules.
679 When tag equals keep-loaded, designated modulefile is not auto‐
681 matically unloaded when it has been auto-loaded and its depen‐
682 dent modules are getting unloaded.
683 module-version modulefile version-name...
685 Assigns the symbolic version-name to the modulefile. This com‐
686 mand should be placed in one of the modulecmd.tcl rc files in
687 order to provide shorthand invocations of frequently used mod‐
688 ulefile names.
689 The special version-name default specifies the default version
691 to be used for module commands, if no specific version is given.
692 This replaces the definitions made in the .version file in for‐
693 mer modulecmd.tcl releases.
694 The parameter modulefile may be either
696 • a fully or partially qualified modulefile with name / version.
698 If name is . (dot) then the current directory name is assumed
699 to be the module name. (Use this for deep modulefile directo‐
700 ries.)
701 • a symbolic modulefile name
703 • another modulefile alias
705 module-virtual name modulefile
707 Assigns the modulefile to the virtual module name. This command
708 should be placed in rc files in order to define virtual modules.
709 A virtual module stands for a module name associated to a mod‐
711 ulefile. The modulefile is the script interpreted when loading
712 or unloading the virtual module which appears or can be found
713 with its virtual name.
714 The parameter modulefile corresponds to the relative or absolute
716 file location of a modulefile.
717 module-whatis string
719 Defines a string which is displayed in case of the invocation of
720 the module whatis command. There may be more than one
721 module-whatis line in a modulefile. This command takes no ac‐
722 tions in case of load, display, etc. invocations of mod‐
723 ulecmd.tcl.
724 The string parameter has to be enclosed in double-quotes if
726 there's more than one word specified. Words are defined to be
727 separated by whitespace characters (space, tab, cr).
728 prepend-path [-d C|--delim C|--delim=C] [--duplicates] variable
730 value...
731 Append or prepend value to environment variable. The variable is
732 a colon, or delimiter, separated list such as PATH=directory:di‐
733 rectory:directory. The default delimiter is a colon :, but an
734 arbitrary one can be given by the --delim option. For example a
735 space can be used instead (which will need to be handled in the
736 Tcl specially by enclosing it in " " or { }). A space, however,
737 can not be specified by the --delim=C form.
738 A reference counter environment variable is also set to know the
740 number of times value has been added to environment variable
741 when it is added more than one time. This reference counter en‐
742 vironment variable is named by prefixing variable by
743 __MODULES_SHARE_.
744 When value is already defined in environment variable, it is not
746 added again or moved at the end or at the beginning of variable.
747 Exception is made when the --duplicates option is set in which
748 case value is added again to variable.
749 If the variable is not set, it is created. When a modulefile is
751 unloaded, append-path and prepend-path become remove-path.
752 If value corresponds to the concatenation of multiple elements
754 separated by colon, or delimiter, character, each element is
755 treated separately.
756 prereq [--optional] [--tag taglist] modulefile...
758 prereq controls whether or not the modulefile will be loaded.
759 The prereq command lists modulefiles which must have been previ‐
760 ously loaded before the current modulefile will be loaded. If a
761 list contains more than one modulefile, then each member of the
762 list acts as a Boolean OR operation. Multiple prereq commands
763 may be used to create a Boolean AND operation. If one of the re‐
764 quirements have not been satisfied, an error is reported and the
765 current modulefile makes no changes to the user's environment.
766 If an argument for prereq is a directory and any modulefile from
768 the directory has been loaded, then the prerequisite is met. For
769 example, specifying X11 as a prereq means that any version of
770 X11, X11/R4 or X11/R5, must be loaded before proceeding.
771 The parameter modulefile may also be a symbolic modulefile name
773 or a modulefile alias. It may also leverage a specific syntax to
774 finely select module version (see Advanced module version speci‐
775 fiers section below).
776 When the --optional option is set, the whole list of specified
778 modulefiles is declared as an optional requirement list. Evalua‐
779 tion is not stopped if no modulefile from the list is loaded.
780 If the auto_handling configuration option is enabled prereq will
782 attempt to load specified modulefile if not found loaded yet
783 (see MODULES_AUTO_HANDLING in module).
784 The --tag option accepts a list of module tags to apply to mod‐
786 ulefile once loaded. taglist corresponds to the concatenation of
787 multiple tags separated by colon character. taglist should not
788 contain tags inherited from modulefile state or from other mod‐
789 ulefile commands. If module is already loaded, tags from taglist
790 are added to the list of tags already applied to this module.
791 prereq-all [--optional] [--tag taglist] modulefile...
793 Declare modulefile as a requirement of currently loading module.
794 This command acts as an alias of prereq command. If more than
795 one modulefile are specified, then this list acts as a Boolean
796 AND operation, which means all specified modulefiles are re‐
797 quired.
798 When the --optional option is set, each specified modulefile is
800 declared as an optional requirement. A modulefile that cannot be
801 loaded, will not stop the evaluation.
802 prereq-any [--optional] [--tag taglist] modulefile...
804 Alias of prereq command.
805 pushenv variable value
807 Set environment variable to value and save previous value of
808 variable to restore it when modulefile is unloaded. Like for
809 setenv modulefile command, changes made to variable with pushenv
810 are applied to variable in Tcl's env array to update environment
811 variable value in current evaluation context.
812 When modulefile is unloaded, the value saved from the pushenv
814 command of this modulefile is removed from saved value stack
815 list. variable is then set to the remaining value on top of the
816 stack or it is unset if stack becomes empty.
817 Saved value stack list for variable is stored in an environment
819 variable which is named by prefixing variable by
820 __MODULES_PUSHENV_.
821 puts [-nonewline] [channelId] string
823 Writes the characters given by string to the channel given by
824 channelId. This command is not a Modules-specific command, it
825 is actually part of Tcl. See the puts(n) Tcl man page for a
826 complete description of this command.
827 Content written to the stderr channel is rendered as output mes‐
829 sage produced by modulefile. Content written to the stdout chan‐
830 nel is rendered as shell command evaluated in the user current
831 shell environment. Content sent to stdout is spooled to be ren‐
832 dered after the environment changes made by modulefile.
833 When channelId equals prestdout, content is rendered as shell
835 command evaluated in current shell environment. This content is
836 spooled and rendered prior any other environment changes.
837 remove-path [options] variable value... [--append-on-un‐
839 load|--prepend-on-unload value...]
840 Remove value from the colon, or delimiter, separated list in
841 variable.
842 remove-path command accepts the following options:
844 • -d C|--delim C|--delim=C
846 • --index
848 • --remove-on-unload|--noop-on-unload|--append-on-un‐
850 load|--prepend-on-unload
851 See prepend-path or append-path for further explanation of using
853 an arbitrary delimiter. Every string between colons, or delim‐
854 iters, in variable is compared to value. If the two match, value
855 is removed from variable if its reference counter is equal to 1
856 or unknown.
857 When --index option is set, value refers to an index in variable
859 list. The string element pointed by this index is set for re‐
860 moval.
861 When modulefile is unloaded, no operation is performed by de‐
863 fault or if the --noop-on-unload option is set. If the --re‐
864 move-on-unload option is set, value is removed. If the --ap‐
865 pend-on-unload option is set, append back value removed at load
866 time or specific value if any set. If the --prepend-on-unload
867 option is set, prepend back value removed at load time or spe‐
868 cific value if any set. These options cannot be set if --index
869 option is also set.
870 Reference counter of value in variable denotes the number of
872 times value has been added to variable. This information is
873 stored in environment __MODULES_SHARE_variable. When attempting
874 to remove value from variable, relative reference counter is
875 checked and value is removed only if counter is equal to 1 or
876 not defined. Otherwise value is kept in variable and reference
877 counter is decreased by 1. If counter equals 1 after being de‐
878 creased, value and its counter are removed from reference
879 counter variable.
880 If value corresponds to the concatenation of multiple elements
882 separated by colon, or delimiter, character, each element is
883 treated separately.
884 reportError string
886 Output string as an error message during modulefile evaluation
887 and raise error count. reportError does not abort modulefile
888 evaluation. Use the error(n) Tcl command to abort evaluation in
889 addition to emit an error message.
890 reportWarning string
892 Output string as a warning message during modulefile evaluation.
893 require-fullname
895 Abort load evaluation of modulefile if name specified to desig‐
896 nate it is not the fully qualified one. Module alias or a sym‐
897 bolic version names are considered fully qualified names, excep‐
898 tion made for the default symbol.
899 set-alias alias-name alias-string
901 Sets an alias with the name alias-name in the user's environment
902 to the string alias-string. For some shells, aliases are not
903 possible and the command has no effect (see Shell support sec‐
904 tion). When a modulefile is unloaded, set-alias becomes
905 unset-alias.
906 set-function function-name function-string
908 Creates a function with the name function-name in the user's en‐
909 vironment with the function body function-string. For some
910 shells, functions are not possible and the command has no effect
911 (see Shell support section). When a modulefile is unloaded,
912 set-function becomes unset-function.
913 setenv [--set-if-undef] variable value
915 Set environment variable to value. The setenv command will also
916 change the process' environment. A reference using Tcl's env as‐
917 sociative array will reference changes made with the setenv com‐
918 mand. Changes made using Tcl's env associative array will NOT
919 change the user's environment variable like the setenv command.
920 An environment change made this way will only affect the module
921 parsing process. The setenv command is also useful for changing
922 the environment prior to the exec or system command. When a mod‐
923 ulefile is unloaded, setenv becomes unsetenv. If the environment
924 variable had been defined it will be overwritten while loading
925 the modulefile. A subsequent unload will unset the environment
926 variable - the previous value cannot be restored! (Unless you
927 handle it explicitly or if you use the pushenv modulefile com‐
928 mand instead of setenv)
929 When the --set-if-undef option is set, environment variable is
931 defined when modulefile is loaded only if not yet defined.
932 source-sh shell script [arg...]
934 Evaluate with shell the designated script with defined arguments
935 to find out the environment changes it does. Those changes ob‐
936 tained by comparing environment prior and after script evalua‐
937 tion are then translated into corresponding modulefile commands,
938 which are then applied during modulefile evaluation as if they
939 were directly written in it.
940 When modulefile is unloaded, environment changes done are re‐
942 served by evaluating in the unload context the resulting module‐
943 file commands, which were recorded in the __MODULES_LMSOURCESH
944 environment variable at load time.
945 Changes on environment variables, shell aliases, shell func‐
947 tions, shell completions and current working directory are
948 tracked.
949 Changes made on environment variable intended for Modules pri‐
951 vate use (e.g., LOADEDMODULES, _LMFILES_, __MODULES_*) are ig‐
952 nored.
953 Shell could be specified as a command name or a fully qualified
955 pathname. The following shells are supported: sh, dash, csh,
956 tcsh, bash, ksh, ksh93, zsh and fish.
957 system string
959 Run string command through shell. On Unix, command is passed to
960 the /bin/sh shell whereas on Windows it is passed to cmd.exe.
961 modulecmd.tcl redirects stdout to stderr since stdout would be
962 parsed by the evaluating shell. The exit status of the executed
963 command is returned.
964 uname field
966 Provide lookup of system information. Most field information are
967 retrieved from the tcl_platform array (see the tclvars(n) man
968 page). Uname will return the string unknown if information is
969 unavailable for the field.
970 uname will invoke the uname(1) command in order to get the oper‐
972 ating system version and domainname(1) to figure out the name of
973 the domain.
974 field values are:
976 • sysname: the operating system name
978 • nodename: the hostname
980 • domain: the name of the domain
982 • release: the operating system release
984 • version: the operating system version
986 • machine: a standard name that identifies the system's hardware
988 uncomplete name
990 Unsets completion for command name in the user's environment.
991 When a modulefile is unloaded, no operation is performed.
992 The following shells are supported: bash, tcsh and fish.
994 unset-alias alias-name
996 Unsets an alias with the name alias-name in the user's environ‐
997 ment.
998 unset-function function-name
1000 Removes a function with the name function-name from the user's
1001 environment.
1002 unsetenv [options] variable [value]
1004 Unsets environment variable. When a modulefile is unloaded, no
1005 operation is performed unless if an optional value is defined,
1006 in which case variable is to value. The unsetenv command changes
1007 the process' environment like setenv.
1008 If the --noop-on-unload option is set, no operation is performed
1010 when modulefile is unloaded. If the --unset-on-unload option is
1011 set, environment variable is also unset when modulefile is un‐
1012 loaded. These behaviors are applied even if an optional value is
1013 defined.
1014 variant [--boolean] [--default value] name [value...]
1016 Declare module variant name with list of accepted value and in‐
1017 stantiate it in the ModuleVariant array variable.
1018 Variant's value is selected through the module designation that
1020 leads to the modulefile evaluation. See Advanced module version
1021 specifiers section to learn how variants could be specified.
1022 Selected variant value is transmitted to the evaluating module‐
1024 file. A value must be specified for variant name and it must
1025 corresponds to a value in the accepted value list if such list
1026 is defined. Otherwise an error is raised. An exception is made
1027 if modulefile is evaluated in display mode: no error is raised
1028 if no value is specified for a given variant and variant is not
1029 instantiated in the ModuleVariant array variable. When no list
1030 of accepted value is defined, variant could be set to any value.
1031 When the --default option is set, variant name is set to the
1033 value associated with this option in case no value is specified
1034 for variant in module designation.
1035 If the --boolean option is set, variant name is defined as a
1037 Boolean variant. No list of accepted value should be defined in
1038 this case. All values recognized as Boolean value in Tcl are ac‐
1039 cepted (i.e., 1, true, t, yes, y, on, 0, false, f, no, n or
1040 off). Boolean variants are instantiated in ModuleVariant using
1041 Tcl canonical form of Boolean value (i.e., 0 or 1).
1042 A variant which is not defined as a Boolean variant cannot de‐
1044 fine Boolean values in its accepted value list, exception made
1045 for the 0 and 1 integers. An error is raised otherwise.
1046 A variant cannot be named version. An error is raised otherwise.
1048 versioncmp version1 version2
1050 Compare version string version1 against version string version2.
1051 Returns -1, 0 or 1 respectively if version1 is less than, equal
1052 to or greater than version2.
1053 x-resource [resource-string|filename]
1055 Merge resources into the X11 resource database. The resources
1056 are used to control look and behavior of X11 applications. The
1057 command will attempt to read resources from filename. If the ar‐
1058 gument isn't a valid file name, then string will be interpreted
1059 as a resource. Either filename or resource-string is then passed
1060 down to be xrdb(1) command.
1061 modulefiles that use this command, should in most cases contain
1063 one or more x-resource lines, each defining one X11 resource.
1064 The DISPLAY environment variable should be properly set and the
1065 X11 server should be accessible. If x-resource can't manipulate
1066 the X11 resource database, the modulefile will exit with an er‐
1067 ror message.
1068 Examples:
1070 x-resource /u2/staff/leif/.xres/Ileaf
1072 The content of the Ileaf file is merged into the X11 resource
1073 database.
1074 x-resource [glob ~/.xres/ileaf]
1076 The Tcl glob function is used to have the modulefile read
1077 different resource files for different users.
1078 x-resource {Ileaf.popup.saveUnder: True}
1080 Merge the Ileaf resource into the X11 resource database.
1081 Modulefiles and run-command (rc) files are differently interpreted. A
1083 limited number of the Modules specific Tcl commands are available for
1084 rc files interpretation since such files are intended to set parameters
1085 for modulefiles (like defining alias, hiding, tagging, etc) and not to
1086 change user environment. The following table summarizes the different
1087 commands available for each interpretation context.
1088 ┌───────────────────────────┬────────────────────────────┐
1090 │Commands available from │ Commands available from │
1091 │modulefile interpretation │ run-command (rc) file in‐ │
1092 │ │ terpretation │
1093 ├───────────────────────────┼────────────────────────────┤
1094 │All the Modules specific │ is-loaded, is-used, │
1095 │and standard Tcl commands │ module-alias, │
1096 │ │ module-forbid, │
1097 │ │ module-hide, module-info, │
1098 │ │ module-tag, │
1099 │ │ module-version, │
1100 │ │ module-virtual, system, │
1101 │ │ uname, versioncmp and │
1102 │ │ standard Tcl commands │
1103 └───────────────────────────┴────────────────────────────┘
1104 NOTE:
1106 Global and user run-command files are interpreted like modulefiles
1107 and benefit from all Modules specific Tcl commands. However it not
1108 advised to perform environment changes from such files.
1109
1111 ModulesCurrentModulefile
1112 The ModulesCurrentModulefile variable contains the full pathname
1113 of the modulefile being interpreted.
1114 ModulesVersion
1116 The ModulesVersion variable can be set in .version file to des‐
1117 ignate the name of the modulefile version which should be con‐
1118 sidered as default in current directory (see Locating Module‐
1119 files section below).
1120 ModuleTool
1122 The ModuleTool variable contains the name of the module imple‐
1123 mentation currently in use. The value of this variable is set to
1124 Modules for this implementation.
1125 ModuleToolVersion
1127 The ModuleToolVersion variable contains the version of the mod‐
1128 ule implementation currently in use. The value of this variable
1129 is set to 5.3.1 for this version of Modules.
1130 ModuleVariant
1132 The ModuleVariant array variable contains an element entry for
1133 each defined variant associated to the value of this variant
1134 (e.g., the $ModuleVariant(foo) syntax corresponds to the value
1135 of variant foo if defined). A Tcl evaluation error is obtained
1136 when accessing an undefined variant in ModuleVariant array. Use
1137 preferably the getvariant command to retrieve a variant value
1138 when this variant state is not known.
1139 The list of the currently defined variants can be retrieved with
1141 [array names ModuleVariant] Tcl code.
1142
1144 Every directory in MODULEPATH is searched to find the modulefile. A di‐
1145 rectory in MODULEPATH can have an arbitrary number of sub-directories.
1146 If the user names a modulefile to be loaded which is actually a direc‐
1147 tory, the directory is opened and a search begins for an actual module‐
1148 file. First, modulecmd.tcl looks for a file with the name .modulerc in
1149 the directory. If this file exists, its contents will be evaluated as
1150 if it was a modulefile to be loaded. You may place module-version,
1151 module-alias and module-virtual commands inside this file.
1152 Additionally, before seeking for .modulerc files in the module direc‐
1154 tory, the global modulerc file and the .modulerc file found at the root
1155 of the modulepath directory are sourced, too. If a named version de‐
1156 fault now exists for the modulefile to be loaded, the assigned module‐
1157 file now will be sourced. Otherwise the file .version is looked up in
1158 the module directory.
1159 If the .version file exists, it is opened and interpreted as Tcl code
1161 and takes precedence over a .modulerc file in the same directory. If
1162 the Tcl variable ModulesVersion is set by the .version file, mod‐
1163 ulecmd.tcl will use the name as if it specifies a modulefile in this
1164 directory. This will become the default modulefile in this case.
1165 ModulesVersion cannot refer to a modulefile located in a different di‐
1166 rectory.
1167 If ModulesVersion is a directory, the search begins anew down that di‐
1169 rectory. If the name does not match any files located in the current
1170 directory, the search continues through the remaining directories in
1171 MODULEPATH.
1172 Every .version and .modulerc file found is interpreted as Tcl code. The
1174 difference is that .version only applies to the current directory, and
1175 the .modulerc applies to the current directory and all subdirectories.
1176 Changes made in these files will affect the subsequently interpreted
1177 modulefile.
1178 If a .modulecache file is found at the root of a modulepath directory,
1180 this file is interpreted as Tcl code to learn all .modulerc, .version
1181 and modulefiles available. Modulepath content is read from module cache
1182 file. Modulepath directory is only walked through to check if limited
1183 access modulefiles or directories are available to current user.
1184 If no default version may be figured out, an implicit default is se‐
1186 lected when this behavior is enabled (see MODULES_IMPLICIT_DEFAULT in
1187 module). If disabled, module names should be fully qualified when no
1188 explicit default is defined for them, otherwise no default version is
1189 found and an error is returned. If enabled, then the highest numeri‐
1190 cally sorted modulefile, virtual module or module alias under the di‐
1191 rectory will be used. The dictionary comparison method of the lsort(n)
1192 Tcl command is used to achieve this sort. If highest numerically sorted
1193 element is an alias, search continues on its modulefile target.
1194 For example, it is possible for a user to have a directory named X11
1196 which simply contains a .version file specifying which version of X11
1197 is to be loaded. Such a file would look like:
1198 #%Module1.0
1200 ##
1201 ## The desired version of X11
1202 ##
1203 set ModulesVersion "R4"
1204 The equivalent .modulerc would look like:
1206 #%Module1.0
1208 ##
1209 ## The desired version of X11
1210 ##
1211 module-version "./R4" default
1212 If the extended default mechanism is enabled (see
1214 MODULES_EXTENDED_DEFAULT in module) the module version specified is
1215 matched against starting portion of existing module versions, where
1216 portion is a substring separated from the rest of version string by a .
1217 character.
1218 When the implicit default mechanism and the Advanced module version
1220 specifiers are both enabled, a default and latest symbolic versions are
1221 automatically defined for each module name (also at each directory
1222 level in case of deep modulefile). Unless a symbolic version, alias, or
1223 regular module version already exists for these version names.
1224 Every file in searched directories is checked to see if it begins with
1226 the Modules magic cookie (i.e., #%Module file signature) to determine
1227 if it is a modulefile (see DESCRIPTION section). When the mcookie_check
1228 configuration is set to eval, this check is skipped and all files in
1229 search directories are considered modulefiles.
1230 If user names a modulefile that cannot be found in the first modulepath
1232 directory, modulefile will be searched in next modulepath directory and
1233 so on until a matching modulefile is found. If search goes through a
1234 module alias or a symbolic version, this alias or symbol is resolved by
1235 first looking at the modulefiles in the modulepath where this alias or
1236 symbol is defined. If not found, resolution looks at the other mod‐
1237 ulepaths in their definition order.
1238 When locating modulefiles, if a .modulerc, a .version, a directory or a
1240 modulefile cannot be read during the search it is simply ignored with
1241 no error message produced. Visibility of modulefiles can thus be
1242 adapted to the rights the user has been granted. Exception is made when
1243 trying to directly access a directory or a modulefile. In this case,
1244 the access issue is returned as an error message.
1245 Depending on their name, their file permissions or the use of specific
1247 modulefile commands, modulefile, virtual module, module alias or sym‐
1248 bolic version may be set hidden which impacts available modules search
1249 or module selection processes (see Hiding modulefiles section below).
1250
1252 A modulefile, virtual module, module alias or symbolic version whose
1253 name or element in their name starts with a dot character (.) or who
1254 are targeted by a module-hide command are considered hidden. Hidden
1255 modules are not displayed or taken into account except if they are ex‐
1256 plicitly named (e.g., foo/1.2.3 or foo/.2.0 not foo). If module has
1257 been hidden with the --soft option of the module-hide command set, it
1258 is not considered hidden if the root name of the query to search it
1259 matches module root name (e.g., searching foo will return a foo/1.2.3
1260 modulefile targeted by a module-hide --soft command). If module has
1261 been hidden with the --hard option of the module-hide command set, it
1262 is always considered hidden thus it is never displayed nor taken into
1263 account even if it is explicitly named.
1264 A modulefile, virtual module, module alias or symbolic version who are
1266 targeted by a module-hide --hard command and a module-forbid command or
1267 whose file access permissions are restricted are considered hard-hidden
1268 and forbidden. Such modules are not displayed or taken into account.
1269 When explicitly named for evaluation selection, such modules are un‐
1270 veiled to return an access error.
1271 NOTE:
1273 When the mcookie_check configuration is set to eval, file access
1274 permissions are not checked thus files with restricted permissions
1275 are included in search results but still lead to error if evaluated.
1276 A symbolic version-name assigned to a hidden module is displayed or
1278 taken into account only if explicitly named and if module is not
1279 hard-hidden. Non-hidden module alias targeting a hidden modulefile ap‐
1280 pears like any other non-hidden module alias. Finally, a hidden sym‐
1281 bolic version targeting a non-hidden module is displayed or taken into
1282 account only if not hard-hidden and explicitly named to refer to its
1283 non-hidden target.
1284 The automatic version symbols (e.g., default and latest) are unaffected
1286 by hiding. Moreover when a regular default or latest version is set
1287 hidden, the corresponding automatic version symbol takes the left spot.
1288 For instance, if foo/default which targets foo/1.2.3 is set hard-hid‐
1289 den, the default automatic version symbol will be set onto foo/2.1.3,
1290 the highest available version of foo.
1291 When loading a modulefile or a virtual module targeted by a module-hide
1293 --hidden-loaded command, this module inherits the hidden-loaded tag.
1294 Hidden loaded modules are not reported among list sub-command results.
1295 If the --all is set on avail, aliases, whatis or search sub-commands,
1297 hidden modules are taken into account in search. Hard-hidden modules
1298 are unaffected by this option.
1299 If the --all is set on list sub-command, hidden loaded modules are in‐
1301 cluded in result output.
1302
1304 When the advanced module version specifiers mechanism is enabled (see
1305 MODULES_ADVANCED_VERSION_SPEC in module), the specification of module‐
1306 file passed on Modules specific Tcl commands changes. After the module
1307 name a version constraint and variants may be added.
1308 Version specifiers
1310 After the module name a version constraint prefixed by the @ character
1311 may be added. It could be directly appended to the module name or sepa‐
1312 rated from it with a space character.
1313 Constraints can be expressed to refine the selection of module version
1315 to:
1316 • a single version with the @version syntax, for instance foo@1.2.3
1318 syntax will select module foo/1.2.3
1319 • a list of versions with the @version1,version2,... syntax, for in‐
1321 stance foo@1.2.3,1.10 will match modules foo/1.2.3 and foo/1.10
1322 • a range of versions with the @version1:, @:version2 and @ver‐
1324 sion1:version2 syntaxes, for instance foo@1.2: will select all ver‐
1325 sions of module foo greater than or equal to 1.2, foo@:1.3 will se‐
1326 lect all versions less than or equal to 1.3 and foo@1.2:1.3 matches
1327 all versions between 1.2 and 1.3 including 1.2 and 1.3 versions
1328 Advanced specification of single version or list of versions may bene‐
1330 fit from the activation of the extended default mechanism (see
1331 MODULES_EXTENDED_DEFAULT in module) to use an abbreviated notation like
1332 @1 to refer to more precise version numbers like 1.2.3. Range of ver‐
1333 sions on its side natively handles abbreviated versions.
1334 In order to be specified in a range of versions or compared to a range
1336 of versions, the version major element should corresponds to a number.
1337 For instance 10a, 1.2.3, 1.foo are versions valid for range comparison
1338 whereas default or foo.2 versions are invalid for range comparison.
1339 Range of versions can be specified in version list, for instance
1341 foo@:1.2,1.4:1.6,1.8:. Such specification helps to exclude specific
1342 versions, like versions 1.3 and 1.7 in previous example.
1343 If the implicit default mechanism is also enabled (see
1345 MODULES_IMPLICIT_DEFAULT in module), a default and latest symbolic ver‐
1346 sions are automatically defined for each module name (also at each di‐
1347 rectory level for deep modulefiles). These automatic version symbols
1348 are defined unless a symbolic version, alias, or regular module version
1349 already exists for these default or latest version names. Using the
1350 mod@latest (or mod/latest) syntax ensures highest available version
1351 will be selected.
1352 Variants
1354 After the module name, variants can be specified. Module variants are
1355 alternative evaluation of the same modulefile. A variant is specified
1356 by associating a value to its name. This specification is then trans‐
1357 mitted to the evaluating modulefile which instantiates the variant in
1358 the ModuleVariant array variable when reaching the variant modulefile
1359 command declaring this variant.
1360 Variant can be specified with the name=value syntax where name is the
1362 declared variant name and value, the value this variant is set to when
1363 evaluating the modulefile.
1364 Boolean variants can be specified with the +name syntax to set this
1366 variant on and with the -name or ~name syntaxes to set this variant
1367 off. The -name syntax is not supported on ml command as the minus sign
1368 already means to unload designated module. The ~name and +name syntaxes
1369 could also be defined appended to another specification word (e.g., the
1370 module name, version or another variant specification), whereas -name
1371 syntax must be the start of a new specification word.
1372 Boolean variants may also be specified with the name=value syntax.
1374 value should be set to 1, true, t, yes, y or on to enable the variant
1375 or it should be set to 0, false, f, no, n or off to disable the vari‐
1376 ant.
1377 Shortcuts may be used to abbreviate variant specification. The
1379 variant_shortcut configuration option associates shortcut character to
1380 variant name. With a shortcut defined, variant could be specified with
1381 the <shortcut>value syntax. For instance if character % is set as a
1382 shortcut for variant foo, the %value syntax is equivalent to the
1383 foo=value syntax.
1384 Specific characters used in variant specification syntax cannot be used
1386 as part of the name of a module. These specific characters are +, ~, =
1387 and all characters set as variant shortcut. Exception is made for +
1388 character which could be set one or several consecutive times at the
1389 end of module name (e.g., name+ or name++).
1390
1392 A modulefile may express dependencies on other modulefiles. Two kind of
1393 dependency exist: pre-requirement and conflict. The former means speci‐
1394 fied modulefiles should be loaded prior the modulefile that express the
1395 requirement. The latter means specified modulefiles should not be
1396 loaded for the modulefile that express the conflict to be loaded too.
1397 Pre-requirement could be expressed with prereq, prereq-any, prereq-all,
1399 depends-on, always-load, module load, module switch, module try-load or
1400 module load-any modulefile commands. When the auto_handling configura‐
1401 tion option is disabled, required modulefile should be manually loaded
1402 prior their dependent modulefile when expressed with the prereq,
1403 prereq-any, prereq-all or depends-on modulefile commands. For other
1404 commands or when auto_handling is enabled, pre-required modulefiles are
1405 automatically loaded.
1406 Conflict is expressed with conflict or module unload modulefile com‐
1408 mands. A conflicting loaded modulefile should be manually unloaded
1409 prior loading the modulefile that express such conflict when defined
1410 with conflict. It is automatically unloaded when expressed with module
1411 unload.
1412 It is strongly advised to define dependencies prior environment changes
1414 in a modulefile. Dependency resolution should be done before any envi‐
1415 ronment change to ensure the environment is getting set in the same or‐
1416 der whether pre-requirements are already loaded, or if they are auto‐
1417 matically loaded when loading the modulefile which depends on them, or
1418 if all loaded modules are reloaded or refreshed. This is especially im‐
1419 portant when the modulefile updates an environment variable also al‐
1420 tered by other modulefiles like PATH. As the order of the path elements
1421 in such variable defines priority, it is important that this order does
1422 not change depending on the way the modulefiles are loaded.
1423 module keeps environment consistent which means a modulefile cannot be
1425 loaded if its requirements are not loaded or if a conflicting module is
1426 loaded. In addition a loaded module cannot be unloaded if other loaded
1427 modules depends on it. The automated module handling mechanisms attempt
1428 to solve the dependencies expressed by loading or unloading additional
1429 modulefiles. When the --no-auto option is set on module command when
1430 loading or unload modulefile, automated module handling mechanisms are
1431 disabled and dependencies have to be solved manually. When dependencies
1432 are not satisfied, modulefile fails to load or unload.
1433 Adding the --not-req option when expressing dependencies in modulefile
1435 with the module command will attempt to load or unload the designated
1436 modulefile but it will not mark them as pre-requirement or conflict.
1437 Adding the --optional option on prereq, prereq-any, prereq-all,
1439 depends-on or always-load modulefile commands declares the pre-require‐
1440 ment as optional. If an optional pre-requirement is not found loaded or
1441 cannot be automatically loaded, the dependency expressed is yet consid‐
1442 ered satisfied. When an optional requirement is loaded afterward, the
1443 dependent module will get automatically reloaded if the auto_handling
1444 configuration option is enabled.
1445 By adding the --force option to the module command when loading or un‐
1447 loading modulefile, the consistency checks are by-passed. This option
1448 cannot be used when expressing dependencies in modulefiles. If a module
1449 has been force loaded whereas its requirements are not loaded or
1450 whereas a conflicting module is also loaded, the user environment is
1451 said inconsistent.
1452 Note that a pre-requirement should be found in the loaded module list
1454 prior its dependent module. User environment is considered inconsistent
1455 if pre-requirement module is found loaded after dependent module, as
1456 the environment changes may have been done in the wrong priority order.
1457 When user environment is considered inconsistent global operations
1459 achieved by refresh, reload and save sub-commands cannot perform. This
1460 mechanism is there to avoid the situation to worsen by re-evaluating
1461 all loaded modules or recording this environment.
1462 When the auto_handling configuration option is enabled, if missing
1464 pre-requirement modulefile gets loaded or conflicting modulefile gets
1465 unloaded the inconsistent loaded module will be automatically reloaded
1466 to make user environment consistent again.
1467
1469 Users can request help about a specific modulefile through the module
1470 command. The modulefile can print helpful information or start help
1471 oriented programs by defining a ModulesHelp subroutine. The subroutine
1472 will be called when the module help modulefile command is used.
1473
1475 Users can request test of a specific modulefile through the module com‐
1476 mand. The modulefile can perform some sanity checks on its definition
1477 or on its underlying programs by defining a ModulesTest subroutine. The
1478 subroutine will be called when the module test modulefile command is
1479 used. The subroutine should return 1 in case of success. If no or any
1480 other value is returned, test is considered failed.
1481
1483 The module display modulefile command will detail all changes that will
1484 be made to the environment. After displaying all of the environment
1485 changes modulecmd.tcl will call the ModulesDisplay subroutine. The Mod‐
1486 ulesDisplay subroutine is a good place to put additional descriptive
1487 information about the modulefile.
1488
1490 The modulecmd.tcl program supports Tcl modulefile written for Lmod, the
1491 alternative module implementation developed in Lua. Such modulefiles
1492 can be evaluated by Modules without raising error. Differences between
1493 the two implementations are listed below.
1494 The add-property, remove-property and extensions modulefile commands
1496 are evaluated as a no-operation command. No error is obtained if these
1497 commands are used in modulefiles but no change occurs.
1498 The break command does not accept any argument. A msg argument can be
1500 set on Lmod to provide a customized break error message.
1501 Use of reportError command aborts modulefile evaluation on Lmod. This
1503 command only reports an error message on Modules.
1504 The require-fullname command only aborts load modulefile evaluation
1506 whereas the Lmod implementation also aborts unload and display evalua‐
1507 tions.
1508 When processing a family command, the LMOD_FAMILY_<NAME> environment
1510 variable is also defined to be compatible with modulefiles or scripts
1511 relying on such variable.
1512 When unloading a modulefile, the pushenv command does not update the
1514 value of the environment variable if this modulefile was not defining
1515 the value currently in use.
1516 The third optional argument of append-path and prepend-path commands
1518 corresponds to a priority specification on Lmod whereas these two com‐
1519 mands accept multiple path element arguments on Modules.
1520 The prereq command is equivalent to the prereq-any command on Modules
1522 whereas on Lmod it is equivalent to the prereq-all command.
1523 If the auto_handling configuration option is disabled, the requirements
1525 defined with the depends-on command are not automatically loaded and an
1526 error is raised if none of these requirements are found loaded.
1527 On module load-any sub-command and modulefile command, a modulefile
1529 evaluation error is not reported and module load-any continues to the
1530 next modulefile instead of aborting the whole process. No attempt to
1531 load listed modulefiles is made if one of these modulefiles is found
1532 already loaded.
1533 On module try-load modulefile command, each modulefile specified is
1535 considered an optional pre-requirement. If it is loaded afterward and
1536 if the auto_handling configuration option is enabled, the dependent
1537 module will get automatically reloaded.
1538
1540 The modulecmd.tcl program that evaluates modulefiles supports a variety
1541 of shells or languages: sh family shells (sh, bash, ksh and zsh), csh
1542 family shells (csh and tcsh), fish, cmd, python, perl, ruby, tcl,
1543 cmake, r, and lisp.
1544 Modulefiles produce environment changes when evaluated, like defining
1546 an environment variable. The modulecmd.tcl program outputs the corre‐
1547 sponding code for the selected "shell". Thereafter this code is evalu‐
1548 ated by the module alias or function to update the current environment.
1549 Depending on the "shell" kind, not all the environment changes that can
1551 be defined in modulefiles are supported. The following table summarizes
1552 the changes that are supported by the shells supported by mod‐
1553 ulecmd.tcl.
1554┌───────┬───────────────┬──────────────┬─────────────────┬─────────────┬───────┬────────────┐
1556│ │ Environ‐ │ Shell │ Shell │ Command │ chdir │ x-resource │
1557│ │ ment vari‐ │ alias (‐ │ functions │ completion │ │ │
1558│ │ ables (‐ │ set-alias, │ (‐ │ (complete, │ │ │
1559│ │ setenv, │ unset-alias) │ set-func‐ │ uncomplete) │ │ │
1560│ │ unsetenv, │ │ tion, │ │ │ │
1561│ │ pushenv, │ │ unset-function) │ │ │ │
1562│ │ append-path, │ │ │ │ │ │
1563│ │ prepend-path, │ │ │ │ │ │
1564│ │ remove-path) │ │ │ │ │ │
1565├───────┼───────────────┼──────────────┼─────────────────┼─────────────┼───────┼────────────┤
1566│sh │ ⦁ │ ⦁ │ ⦁ │ │ ⦁ │ ⦁ │
1567├───────┼───────────────┼──────────────┼─────────────────┼─────────────┼───────┼────────────┤
1568│bash │ ⦁ │ ⦁ │ ⦁ │ ⦁ │ ⦁ │ ⦁ │
1569└───────┴───────────────┴──────────────┴─────────────────┴─────────────┴───────┴────────────┘
1570│ksh │ ⦁ │ ⦁ │ ⦁ │ │ ⦁ │ ⦁ │
1573├───────┼───────────────┼──────────────┼─────────────────┼─────────────┼───────┼────────────┤
1574│zsh │ ⦁ │ ⦁ │ ⦁ │ │ ⦁ │ ⦁ │
1575├───────┼───────────────┼──────────────┼─────────────────┼─────────────┼───────┼────────────┤
1576│csh │ ⦁ │ ⦁ │ │ │ ⦁ │ ⦁ │
1577├───────┼───────────────┼──────────────┼─────────────────┼─────────────┼───────┼────────────┤
1578│tcsh │ ⦁ │ ⦁ │ │ ⦁ │ ⦁ │ ⦁ │
1579├───────┼───────────────┼──────────────┼─────────────────┼─────────────┼───────┼────────────┤
1580│fish │ ⦁ │ ⦁ │ ⦁ │ ⦁ │ ⦁ │ ⦁ │
1581├───────┼───────────────┼──────────────┼─────────────────┼─────────────┼───────┼────────────┤
1582│cmd │ ⦁ │ ⦁ │ │ │ ⦁ │ │
1583├───────┼───────────────┼──────────────┼─────────────────┼─────────────┼───────┼────────────┤
1584│python │ ⦁ │ │ │ │ ⦁ │ ⦁ │
1585├───────┼───────────────┼──────────────┼─────────────────┼─────────────┼───────┼────────────┤
1586│perl │ ⦁ │ │ │ │ ⦁ │ ⦁ │
1587├───────┼───────────────┼──────────────┼─────────────────┼─────────────┼───────┼────────────┤
1588│ruby │ ⦁ │ │ │ │ ⦁ │ ⦁ │
1589├───────┼───────────────┼──────────────┼─────────────────┼─────────────┼───────┼────────────┤
1590│tcl │ ⦁ │ │ │ │ ⦁ │ ⦁ │
1591├───────┼───────────────┼──────────────┼─────────────────┼─────────────┼───────┼────────────┤
1592│cmake │ ⦁ │ │ │ │ │ ⦁ │
1593├───────┼───────────────┼──────────────┼─────────────────┼─────────────┼───────┼────────────┤
1594│r │ ⦁ │ │ │ │ ⦁ │ ⦁ │
1595├───────┼───────────────┼──────────────┼─────────────────┼─────────────┼───────┼────────────┤
1596│lisp │ ⦁ │ │ │ │ ⦁ │ ⦁ │
1597└───────┴───────────────┴──────────────┴─────────────────┴─────────────┴───────┴────────────┘
1598 The source-sh command evaluates a shell script and produces the module‐
1600 file commands corresponding to the environment changes made by this
1601 script. source-sh is able to evaluate sh, bash, ksh, zsh, csh, tcsh and
1602 fish shell scripts. source-sh produces environment changes correspond‐
1603 ing to the kinds listed in the above table. Based on the evaluated
1604 script, refer to the above table to know the environment changes that
1605 will be rendered for the shell specified to modulecmd.tcl program.
1606
1608 See the ENVIRONMENT section in the module man page.
1609
1611 module, ml, Tcl(n), TclX(n), id(1), xrdb(1), exec(n), uname(1), domain‐
1612 name(1), tclvars(n), lsort(n)
1613
1615 Tcl was developed by John Ousterhout at the University of California at
1616 Berkeley.
1617 TclX was developed by Karl Lehenbauer and Mark Diekhans.
1619
1621 1996-1999 John L. Furlani & Peter W. Osel, 1998-2017 R.K.Owen,
1622 2002-2004 Mark Lakata, 2004-2017 Kent Mein, 2016-2022 Xavier Delaruelle
16235.3.1 2023-06-27 MODULEFILE(4)