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(1) user inter‐
11 face. modulefiles can be loaded, unloaded, or switched on-the-fly while
12 the user is working; and can be used to implement site policies regard‐
13 ing 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 MODULES_FAM‐
191 ILY_<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(1) man page are available when module is
308 used as a Modules specific Tcl command. The following table sum‐
309 marizes the different sub-commands available for each interpre‐
310 tation 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 con‐ │ │
337 │Also available but │ fig sub-command. │ │
338 │not recommended for │ │ │
339 │use from regular │ │ │
340 │modulefile: │ │ │
341 │aliases, avail, │ │ │
342 │display, initadd, │ │ │
343 │initclear, │ │ │
344 │initlist, init‐ │ │ │
345 │prepend, initrm, │ │ │
346 │initswitch, list, │ │ │
347 │purge, reload, re‐ │ │ │
348 │store, save, │ │ │
349 │savelist, saverm, │ │ │
350 │saveshow, search, │ │ │
351 │test, whatis │ │ │
352 └────────────────────┴─────────────────────┴─────────────────────┘
353 module-alias name modulefile
355 Assigns the modulefile to the alias name. This command should be
356 placed in one of the modulecmd.tcl rc files in order to provide
357 shorthand invocations of frequently used modulefile names.
358 The parameter modulefile may be either
360 • a fully qualified modulefile with name and version
362 • a symbolic modulefile name
364 • another modulefile alias
366 module-forbid [options] modulefile...
368 Forbid use of modulefile. An error is obtained when trying to
369 evaluate a forbidden module. This command should be placed in
370 one of the modulecmd.tcl rc files.
371 module-forbid command accepts the following options:
373 • --after datetime
375 • --before datetime
377 • --not-user {user...}
379 • --not-group {group...}
381 • --message {text message}
383 • --nearly-message {text message}
385 If --after option is set, forbidding is only effective after
387 specified date time. Following the same principle, if --before
388 option is set, forbidding is only effective before specified
389 date time. Accepted date time format is YYYY-MM-DD[THH:MM]. If
390 no time (HH:MM) is specified, 00:00 is assumed. --after and
391 --before options are not supported on Tcl versions prior to 8.5.
392 If --not-user option is set, forbidding is not applied if the
394 username of the user currently running modulecmd.tcl is part of
395 the list of username specified. Following the same approach, if
396 --not-group option is set, forbidding is not applied if current
397 user is member of one the group specified. When both options are
398 set, forbidding is not applied if a match is found for
399 --not-user or --not-group.
400 Error message returned when trying to evaluate a forbidden mod‐
402 ule can be supplemented with the text message set through --mes‐
403 sage option.
404 If --after option is set, modules are considered nearly forbid‐
406 den during a number of days defined by the nearly_forbidden_days
407 modulecmd.tcl configuration option (see MODULES_NEARLY_FORBID‐
408 DEN_DAYS), prior reaching the expiry date fixed by --after op‐
409 tion. When a nearly forbidden module is evaluated a warning mes‐
410 sage is issued to inform module will soon be forbidden. This
411 warning message can be supplemented with the text message set
412 through --nearly-message option.
413 If a module-forbid command applies to a modulefile also targeted
415 by a module-hide --hard command, this module is unveiled when
416 precisely named to return an access error.
417 Forbidden modules included in the result of an avail sub-command
419 are reported with a forbidden tag applied to them. Nearly for‐
420 bidden modules included in the result of an avail or a list
421 sub-command are reported with a nearly-forbidden tag applied to
422 them. See Module tags section in module(1).
423 The parameter modulefile may leverage a specific syntax to
425 finely select module version (see Advanced module version speci‐
426 fiers section below).
427 module-hide [options] modulefile...
429 Hide modulefile to exclude it from available module search or
430 module selection unless query refers to modulefile by its exact
431 name. This command should be placed in one of the modulecmd.tcl
432 rc files.
433 module-hide command accepts the following options:
435 • --soft|--hard
437 • --hidden-loaded
439 • --after datetime
441 • --before datetime
443 • --not-user {user...}
445 • --not-group {group...}
447 When --soft option is set, modulefile is also set hidden, but
449 hiding is disabled when search or selection query's root name
450 matches module's root name. This soft hiding mode enables to
451 hide modulefiles from bare module availability listing yet keep‐
452 ing the ability to select such module for load with the regular
453 resolution mechanism (i.e., no need to use module exact name to
454 select it)
455 When --hard option is set, modulefile is also set hidden and
457 stays hidden even if search or selection query refers to module‐
458 file by its exact name.
459 When --hidden-loaded option is set, hidden state also applies to
461 the modulefile when it is loaded. Hidden loaded modules do not
462 appear on list sub-command output, unless --all option is set.
463 Their loading or unloading informational messages are not re‐
464 ported unless the verbosity of Modules is set to a level higher
465 than verbose. Hidden loaded modules are detected in any cases by
466 state query commands like is-loaded.
467 If --after option is set, hiding is only effective after speci‐
469 fied date time. Following the same principle, if --before option
470 is set, hiding is only effective before specified date time. Ac‐
471 cepted date time format is YYYY-MM-DD[THH:MM]. If no time
472 (HH:MM) is specified, 00:00 is assumed. --after and --before op‐
473 tions are not supported on Tcl versions prior to 8.5.
474 If --not-user option is set, hiding is not applied if the user‐
476 name of the user currently running modulecmd.tcl is part of the
477 list of username specified. Following the same approach, if
478 --not-group option is set, hiding is not applied if current user
479 is member of one the group specified. When both options are
480 set, hiding is not applied if a match is found for --not-user or
481 --not-group.
482 If the --all option is set on avail, aliases, whatis or search
484 sub-commands, hiding is disabled thus hidden modulefiles are in‐
485 cluded in module search. Hard-hidden modules (i.e., declared
486 hidden with --hard option) are not affected by --all and stay
487 hidden even if option is set. --all option does not apply to
488 module selection sub-commands like load. Thus in such context a
489 hidden module should always be referred by its exact full name
490 (e.g., foo/1.2.3 not foo) unless if it has been hidden in --soft
491 mode. A hard-hidden module cannot be unveiled or selected in any
492 case.
493 If several module-hide commands target the same modulefile, the
495 strongest hiding level is retained which means if both a regu‐
496 lar, a --soft hiding command match a given module, regular hid‐
497 ing mode is considered. If both a regular and a --hard hiding
498 command match a given module, hard hiding mode is retained. A
499 set --hidden-loaded option is retained even if the module-hide
500 statement on which it is declared is superseded by a stronger
501 module-hide statement with no --hidden-loaded option set.
502 Hidden modules included in the result of an avail sub-command
504 are reported with a hidden tag applied to them. Hidden loaded
505 modules included in the result of a list sub-command are re‐
506 ported with a hidden-loaded tag applied to them. This tag is not
507 reported on avail sub-command context. See Module tags section
508 in module(1).
509 The parameter modulefile may also be a symbolic modulefile name
511 or a modulefile alias. It may also leverage a specific syntax to
512 finely select module version (see Advanced module version speci‐
513 fiers section below).
514 module-info option [info-args]
516 Provide information about the modulecmd.tcl program's state.
517 Some of the information is specific to the internals of mod‐
518 ulecmd.tcl. option is the type of information to be provided,
519 and info-args are any arguments needed.
520 module-info alias name
522 Returns the full modulefile name to which the modulefile
523 alias name is assigned
524 module-info command [commandname]
526 Returns the currently running modulecmd.tcl's command as a
527 string if no commandname is given.
528 Returns 1 if modulecmd.tcl's command is commandname. com‐
530 mandname can be: load, unload, refresh, reload, source,
531 switch, display, avail, aliases, list, whatis, search, purge,
532 restore, help, test, try-load, load-any, mod-to-sh, reset,
533 stash or stashpop.
534 module-info loaded modulefile
536 Returns the names of currently loaded modules matching passed
537 modulefile. The parameter modulefile might either be a fully
538 qualified modulefile with name and version or just a direc‐
539 tory which in case all loaded modulefiles from the directory
540 will be returned. The parameter modulefile may also be a sym‐
541 bolic modulefile name or a modulefile alias.
542 This command only returns the name and version of designated
544 loaded module. The defined variants of the loaded module are
545 not included in the returned string.
546 module-info mode [modetype]
548 Returns the current modulecmd.tcl's mode as a string if no
549 modetype is given.
550 Returns 1 if modulecmd.tcl's mode is modetype. modetype can
552 be: load, unload, remove (alias of unload), switch, refresh,
553 nonpersist (alias of refresh), display, help, test or whatis.
554 module-info name
556 Return the name of the modulefile. This is not the full path‐
557 name for modulefile. See the Modules Variables section for
558 information on the full pathname.
559 This command only returns the name and version of currently
561 evaluating modulefile. The defined variants are not included
562 in the returned string. See getvariant command or
563 ModuleVariant array variable to get defined variant values
564 for currently evaluating modulefile.
565 module-info shell [shellname]
567 Return the current shell under which modulecmd.tcl was in‐
568 voked if no shellname is given. The current shell is the
569 first parameter of modulecmd.tcl, which is normally hidden by
570 the module alias.
571 If a shellname is given, returns 1 if modulecmd.tcl's current
573 shell is shellname, returns 0 otherwise. shellname can be:
574 sh, bash, ksh, zsh, csh, tcsh, fish, cmd, tcl, perl, python,
575 ruby, lisp, cmake, r.
576 module-info shelltype [shelltypename]
578 Return the family of the shell under which modulefile was in‐
579 voked if no shelltypename is given. As of module-info shell
580 this depends on the first parameter of modulecmd.tcl. The
581 output reflects a shell type determining the shell syntax of
582 the commands produced by modulecmd.tcl.
583 If a shelltypename is given, returns 1 if modulecmd.tcl's
585 current shell type is shelltypename, returns 0 otherwise.
586 shelltypename can be: sh, csh, fish, cmd, tcl, perl, python,
587 ruby, lisp, cmake, r.
588 module-info specified
590 Return the module designation (name, version and variants)
591 specified that led to current modulefile evaluation.
592 module-info symbols modulefile
594 Returns a list of all symbolic versions assigned to the
595 passed modulefile. The parameter modulefile might either be
596 a full qualified modulefile with name and version, another
597 symbolic modulefile name or a modulefile alias.
598 module-info tags [tag]
600 Returns all tags assigned to currently evaluated modulefile
601 as a list of strings if no tag name is given (see Module tags
602 section in module(1))
603 When tags are assigned to specific module variants, they are
605 returned only if this variant is the one currently evaluated.
606 Returns 1 if one of the tags applying to currently evaluated
608 modulefile is tag. Returns 0 otherwise.
609 module-info type
611 Returns either C or Tcl to indicate which module command is
612 being executed, either the C version or the Tcl-only ver‐
613 sion, to allow the modulefile writer to handle any differ‐
614 ences between the two.
615 module-info usergroups [name]
617 Returns all the groups the user currently running mod‐
618 ulecmd.tcl is member of as a list of strings if no name is
619 given.
620 Returns 1 if one of the group current user running mod‐
622 ulecmd.tcl is member of is name. Returns 0 otherwise.
623 If the Modules Tcl extension library is disabled, the id(1)
625 command is invoked to fetch groups of current user.
626 module-info username [name]
628 Returns the username of the user currently running mod‐
629 ulecmd.tcl as a string if no name is given.
630 Returns 1 if username of current user running modulecmd.tcl
632 is name. Returns 0 otherwise.
633 If the Modules Tcl extension library is disabled, the id(1)
635 command is invoked to fetch username of current user.
636 module-info version modulefile
638 Returns the physical module name and version of the passed
639 symbolic version modulefile. The parameter modulefile might
640 either be a full qualified modulefile with name and version,
641 another symbolic modulefile name or a modulefile alias.
642 module-tag [options] tag modulefile...
644 Associate tag to designated modulefile. This tag information
645 will be reported along modulefile on avail and list sub-commands
646 (see Module tags section in module(1)). Tag information can be
647 queried during modulefile evaluation with the module-info tags
648 modulefile command. module-tag commands should be placed in one
649 of the modulecmd.tcl rc files.
650 module-tag command accepts the following options:
652 • --not-user {user...}
654 • --not-group {group...}
656 If --not-user option is set, the tag is not applied if the user‐
658 name of the user currently running modulecmd.tcl is part of the
659 list of username specified. Following the same approach, if
660 --not-group option is set, the tag is not applied if current
661 user is member of one the group specified. When both options are
662 set, the tag is not applied if a match is found for --not-user
663 or --not-group.
664 The parameter modulefile may also be a symbolic modulefile name
666 or a modulefile alias. It may also leverage a specific syntax to
667 finely select module version (see Advanced module version speci‐
668 fiers section below).
669 Tags inherited from other modulefile commands or module states
671 cannot be set with module-tag. Otherwise an error is returned.
672 Those special tags are: auto-loaded, forbidden, hidden, hid‐
673 den-loaded, loaded and nearly-forbidden.
674 When tag equals sticky or super-sticky, designated modulefile is
676 defined Sticky modules.
677 When tag equals keep-loaded, designated modulefile is not auto‐
679 matically unloaded when it has been auto-loaded and its depen‐
680 dent modules are getting unloaded.
681 module-version modulefile version-name...
683 Assigns the symbolic version-name to the modulefile. This com‐
684 mand should be placed in one of the modulecmd.tcl rc files in
685 order to provide shorthand invocations of frequently used mod‐
686 ulefile names.
687 The special version-name default specifies the default version
689 to be used for module commands, if no specific version is given.
690 This replaces the definitions made in the .version file in for‐
691 mer modulecmd.tcl releases.
692 The parameter modulefile may be either
694 • a fully or partially qualified modulefile with name / version.
696 If name is . (dot) then the current directory name is assumed
697 to be the module name. (Use this for deep modulefile directo‐
698 ries.)
699 • a symbolic modulefile name
701 • another modulefile alias
703 module-virtual name modulefile
705 Assigns the modulefile to the virtual module name. This command
706 should be placed in rc files in order to define virtual modules.
707 A virtual module stands for a module name associated to a mod‐
709 ulefile. The modulefile is the script interpreted when loading
710 or unloading the virtual module which appears or can be found
711 with its virtual name.
712 The parameter modulefile corresponds to the relative or absolute
714 file location of a modulefile.
715 module-whatis string
717 Defines a string which is displayed in case of the invocation of
718 the module whatis command. There may be more than one
719 module-whatis line in a modulefile. This command takes no ac‐
720 tions in case of load, display, etc. invocations of mod‐
721 ulecmd.tcl.
722 The string parameter has to be enclosed in double-quotes if
724 there's more than one word specified. Words are defined to be
725 separated by whitespace characters (space, tab, cr).
726 prepend-path [-d C|--delim C|--delim=C] [--duplicates] variable
728 value...
729 Append or prepend value to environment variable. The variable is
730 a colon, or delimiter, separated list such as PATH=directory:di‐
731 rectory:directory. The default delimiter is a colon :, but an
732 arbitrary one can be given by the --delim option. For example a
733 space can be used instead (which will need to be handled in the
734 Tcl specially by enclosing it in " " or { }). A space, however,
735 can not be specified by the --delim=C form.
736 A reference counter environment variable is also set to know the
738 number of times value has been added to environment variable
739 when it is added more than one time. This reference counter en‐
740 vironment variable is named by prefixing variable by __MOD‐
741 ULES_SHARE_.
742 When value is already defined in environment variable, it is not
744 added again or moved at the end or at the beginning of variable.
745 Exception is made when the --duplicates option is set in which
746 case value is added again to variable.
747 If the variable is not set, it is created. When a modulefile is
749 unloaded, append-path and prepend-path become remove-path.
750 If value corresponds to the concatenation of multiple elements
752 separated by colon, or delimiter, character, each element is
753 treated separately.
754 prereq [--optional] [--tag taglist] modulefile...
756 prereq controls whether or not the modulefile will be loaded.
757 The prereq command lists modulefiles which must have been previ‐
758 ously loaded before the current modulefile will be loaded. If a
759 list contains more than one modulefile, then each member of the
760 list acts as a Boolean OR operation. Multiple prereq commands
761 may be used to create a Boolean AND operation. If one of the re‐
762 quirements have not been satisfied, an error is reported and the
763 current modulefile makes no changes to the user's environment.
764 If an argument for prereq is a directory and any modulefile from
766 the directory has been loaded, then the prerequisite is met. For
767 example, specifying X11 as a prereq means that any version of
768 X11, X11/R4 or X11/R5, must be loaded before proceeding.
769 The parameter modulefile may also be a symbolic modulefile name
771 or a modulefile alias. It may also leverage a specific syntax to
772 finely select module version (see Advanced module version speci‐
773 fiers section below).
774 When the --optional option is set, the whole list of specified
776 modulefiles is declared as an optional requirement list. Evalua‐
777 tion is not stopped if no modulefile from the list is loaded.
778 If the auto_handling configuration option is enabled prereq will
780 attempt to load specified modulefile if not found loaded yet
781 (see MODULES_AUTO_HANDLING in module(1)).
782 The --tag option accepts a list of module tags to apply to mod‐
784 ulefile once loaded. taglist corresponds to the concatenation of
785 multiple tags separated by colon character. taglist should not
786 contain tags inherited from modulefile state or from other mod‐
787 ulefile commands. If module is already loaded, tags from taglist
788 are added to the list of tags already applied to this module.
789 prereq-all [--optional] [--tag taglist] modulefile...
791 Declare modulefile as a requirement of currently loading module.
792 This command acts as an alias of prereq command. If more than
793 one modulefile are specified, then this list acts as a Boolean
794 AND operation, which means all specified modulefiles are re‐
795 quired.
796 When the --optional option is set, each specified modulefile is
798 declared as an optional requirement. A modulefile that cannot be
799 loaded, will not stop the evaluation.
800 prereq-any [--optional] [--tag taglist] modulefile...
802 Alias of prereq command.
803 pushenv variable value
805 Set environment variable to value and save previous value of
806 variable to restore it when modulefile is unloaded. Like for
807 setenv modulefile command, changes made to variable with pushenv
808 are applied to variable in Tcl's env array to update environment
809 variable value in current evaluation context.
810 When modulefile is unloaded, the value saved from the pushenv
812 command of this modulefile is removed from saved value stack
813 list. variable is then set to the remaining value on top of the
814 stack or it is unset if stack becomes empty.
815 Saved value stack list for variable is stored in an environment
817 variable which is named by prefixing variable by __MOD‐
818 ULES_PUSHENV_.
819 puts [-nonewline] [channelId] string
821 Writes the characters given by string to the channel given by
822 channelId. This command is not a Modules-specific command, it
823 is actually part of Tcl. See the puts(n) Tcl man page for a
824 complete description of this command.
825 Content written to the stderr channel is rendered as output mes‐
827 sage produced by modulefile. Content written to the stdout chan‐
828 nel is rendered as shell command evaluated in the user current
829 shell environment. Content sent to stdout is spooled to be ren‐
830 dered after the environment changes made by modulefile.
831 When channelId equals prestdout, content is rendered as shell
833 command evaluated in current shell environment. This content is
834 spooled and rendered prior any other environment changes.
835 remove-path [options] variable value... [--append-on-un‐
837 load|--prepend-on-unload value...]
838 Remove value from the colon, or delimiter, separated list in
839 variable.
840 remove-path command accepts the following options:
842 • -d C|--delim C|--delim=C
844 • --index
846 • --remove-on-unload|--noop-on-unload|--append-on-un‐
848 load|--prepend-on-unload
849 See prepend-path or append-path for further explanation of using
851 an arbitrary delimiter. Every string between colons, or delim‐
852 iters, in variable is compared to value. If the two match, value
853 is removed from variable if its reference counter is equal to 1
854 or unknown.
855 When --index option is set, value refers to an index in variable
857 list. The string element pointed by this index is set for re‐
858 moval.
859 When modulefile is unloaded, no operation is performed by de‐
861 fault or if the --noop-on-unload option is set. If the --re‐
862 move-on-unload option is set, value is removed. If the --ap‐
863 pend-on-unload option is set, append back value removed at load
864 time or specific value if any set. If the --prepend-on-unload
865 option is set, prepend back value removed at load time or spe‐
866 cific value if any set. These options cannot be set if --index
867 option is also set.
868 Reference counter of value in variable denotes the number of
870 times value has been added to variable. This information is
871 stored in environment __MODULES_SHARE_variable. When attempting
872 to remove value from variable, relative reference counter is
873 checked and value is removed only if counter is equal to 1 or
874 not defined. Otherwise value is kept in variable and reference
875 counter is decreased by 1. If counter equals 1 after being de‐
876 creased, value and its counter are removed from reference
877 counter variable.
878 If value corresponds to the concatenation of multiple elements
880 separated by colon, or delimiter, character, each element is
881 treated separately.
882 reportError string
884 Output string as an error message during modulefile evaluation
885 and raise error count. reportError does not abort modulefile
886 evaluation. Use the error(n) Tcl command to abort evaluation in
887 addition to emit an error message.
888 reportWarning string
890 Output string as a warning message during modulefile evaluation.
891 require-fullname
893 Abort load evaluation of modulefile if name specified to desig‐
894 nate it is not the fully qualified one. Module alias or a sym‐
895 bolic version names are considered fully qualified names, excep‐
896 tion made for the default symbol.
897 set-alias alias-name alias-string
899 Sets an alias with the name alias-name in the user's environment
900 to the string alias-string. For some shells, aliases are not
901 possible and the command has no effect (see Shell support sec‐
902 tion). When a modulefile is unloaded, set-alias becomes
903 unset-alias.
904 set-function function-name function-string
906 Creates a function with the name function-name in the user's en‐
907 vironment with the function body function-string. For some
908 shells, functions are not possible and the command has no effect
909 (see Shell support section). When a modulefile is unloaded,
910 set-function becomes unset-function.
911 setenv [--set-if-undef] variable value
913 Set environment variable to value. The setenv command will also
914 change the process' environment. A reference using Tcl's env as‐
915 sociative array will reference changes made with the setenv com‐
916 mand. Changes made using Tcl's env associative array will NOT
917 change the user's environment variable like the setenv command.
918 An environment change made this way will only affect the module
919 parsing process. The setenv command is also useful for changing
920 the environment prior to the exec or system command. When a mod‐
921 ulefile is unloaded, setenv becomes unsetenv. If the environment
922 variable had been defined it will be overwritten while loading
923 the modulefile. A subsequent unload will unset the environment
924 variable - the previous value cannot be restored! (Unless you
925 handle it explicitly or if you use the pushenv modulefile com‐
926 mand instead of setenv)
927 When the --set-if-undef option is set, environment variable is
929 defined when modulefile is loaded only if not yet defined.
930 source-sh shell script [arg...]
932 Evaluate with shell the designated script with defined arguments
933 to find out the environment changes it does. Those changes ob‐
934 tained by comparing environment prior and after script evalua‐
935 tion are then translated into corresponding modulefile commands,
936 which are then applied during modulefile evaluation as if they
937 were directly written in it.
938 When modulefile is unloaded, environment changes done are re‐
940 served by evaluating in the unload context the resulting module‐
941 file commands, which were recorded in the __MODULES_LMSOURCESH
942 environment variable at load time.
943 Changes on environment variables, shell aliases, shell func‐
945 tions, shell completions and current working directory are
946 tracked.
947 Changes made on environment variable intended for Modules pri‐
949 vate use (e.g., LOADEDMODULES, _LMFILES_, __MODULES_*) are ig‐
950 nored.
951 Shell could be specified as a command name or a fully qualified
953 pathname. The following shells are supported: sh, dash, csh,
954 tcsh, bash, ksh, ksh93, zsh and fish.
955 system string
957 Run string command through shell. On Unix, command is passed to
958 the /bin/sh shell whereas on Windows it is passed to cmd.exe.
959 modulecmd.tcl redirects stdout to stderr since stdout would be
960 parsed by the evaluating shell. The exit status of the executed
961 command is returned.
962 uname field
964 Provide lookup of system information. Most field information are
965 retrieved from the tcl_platform array (see the tclvars(n) man
966 page). Uname will return the string unknown if information is
967 unavailable for the field.
968 uname will invoke the uname(1) command in order to get the oper‐
970 ating system version and domainname(1) to figure out the name of
971 the domain.
972 field values are:
974 • sysname: the operating system name
976 • nodename: the hostname
978 • domain: the name of the domain
980 • release: the operating system release
982 • version: the operating system version
984 • machine: a standard name that identifies the system's hardware
986 uncomplete name
988 Unsets completion for command name in the user's environment.
989 When a modulefile is unloaded, no operation is performed.
990 The following shells are supported: bash, tcsh and fish.
992 unset-alias alias-name
994 Unsets an alias with the name alias-name in the user's environ‐
995 ment.
996 unset-function function-name
998 Removes a function with the name function-name from the user's
999 environment.
1000 unsetenv [options] variable [value]
1002 Unsets environment variable. When a modulefile is unloaded, no
1003 operation is performed unless if an optional value is defined,
1004 in which case variable is to value. The unsetenv command changes
1005 the process' environment like setenv.
1006 If the --noop-on-unload option is set, no operation is performed
1008 when modulefile is unloaded. If the --unset-on-unload option is
1009 set, environment variable is also unset when modulefile is un‐
1010 loaded. These behaviors are applied even if an optional value is
1011 defined.
1012 variant [--boolean] [--default value] name [value...]
1014 Declare module variant name with list of accepted value and in‐
1015 stantiate it in the ModuleVariant array variable.
1016 Variant's value is selected through the module designation that
1018 leads to the modulefile evaluation. See Advanced module version
1019 specifiers section to learn how variants could be specified.
1020 Selected variant value is transmitted to the evaluating module‐
1022 file. A value must be specified for variant name and it must
1023 corresponds to a value in the accepted value list if such list
1024 is defined. Otherwise an error is raised. An exception is made
1025 if modulefile is evaluated in display mode: no error is raised
1026 if no value is specified for a given variant and variant is not
1027 instantiated in the ModuleVariant array variable. When no list
1028 of accepted value is defined, variant could be set to any value.
1029 When the --default option is set, variant name is set to the
1031 value associated with this option in case no value is specified
1032 for variant in module designation.
1033 If the --boolean option is set, variant name is defined as a
1035 Boolean variant. No list of accepted value should be defined in
1036 this case. All values recognized as Boolean value in Tcl are ac‐
1037 cepted (i.e., 1, true, t, yes, y, on, 0, false, f, no, n or
1038 off). Boolean variants are instantiated in ModuleVariant using
1039 Tcl canonical form of Boolean value (i.e., 0 or 1).
1040 A variant which is not defined as a Boolean variant cannot de‐
1042 fine Boolean values in its accepted value list, exception made
1043 for the 0 and 1 integers. An error is raised otherwise.
1044 A variant cannot be named version. An error is raised otherwise.
1046 versioncmp version1 version2
1048 Compare version string version1 against version string version2.
1049 Returns -1, 0 or 1 respectively if version1 is less than, equal
1050 to or greater than version2.
1051 x-resource [resource-string|filename]
1053 Merge resources into the X11 resource database. The resources
1054 are used to control look and behavior of X11 applications. The
1055 command will attempt to read resources from filename. If the ar‐
1056 gument isn't a valid file name, then string will be interpreted
1057 as a resource. Either filename or resource-string is then passed
1058 down to be xrdb(1) command.
1059 modulefiles that use this command, should in most cases contain
1061 one or more x-resource lines, each defining one X11 resource.
1062 The DISPLAY environment variable should be properly set and the
1063 X11 server should be accessible. If x-resource can't manipulate
1064 the X11 resource database, the modulefile will exit with an er‐
1065 ror message.
1066 Examples:
1068 x-resource /u2/staff/leif/.xres/Ileaf
1070 The content of the Ileaf file is merged into the X11 resource
1071 database.
1072 x-resource [glob ~/.xres/ileaf]
1074 The Tcl glob function is used to have the modulefile read
1075 different resource files for different users.
1076 x-resource {Ileaf.popup.saveUnder: True}
1078 Merge the Ileaf resource into the X11 resource database.
1079 Modulefiles and run-command (rc) files are differently interpreted. A
1081 limited number of the Modules specific Tcl commands are available for
1082 rc files interpretation since such files are intended to set parameters
1083 for modulefiles (like defining alias, hiding, tagging, etc) and not to
1084 change user environment. The following table summarizes the different
1085 commands available for each interpretation context.
1086 ┌───────────────────────────┬────────────────────────────┐
1088 │Commands available from │ Commands available from │
1089 │modulefile interpretation │ run-command (rc) file in‐ │
1090 │ │ terpretation │
1091 ├───────────────────────────┼────────────────────────────┤
1092 │All the Modules specific │ is-loaded, is-used, │
1093 │and standard Tcl commands │ module-alias, │
1094 │ │ module-forbid, │
1095 │ │ module-hide, module-info, │
1096 │ │ module-tag, │
1097 │ │ module-version, │
1098 │ │ module-virtual, system, │
1099 │ │ uname, versioncmp and │
1100 │ │ standard Tcl commands │
1101 └───────────────────────────┴────────────────────────────┘
1102 NOTE:
1104 Global and user run-command files are interpreted like modulefiles
1105 and benefit from all Modules specific Tcl commands. However it not
1106 advised to perform environment changes from such files.
1107
1109 ModulesCurrentModulefile
1110 The ModulesCurrentModulefile variable contains the full pathname
1111 of the modulefile being interpreted.
1112 ModulesVersion
1114 The ModulesVersion variable can be set in .version file to des‐
1115 ignate the name of the modulefile version which should be con‐
1116 sidered as default in current directory (see Locating Module‐
1117 files section below).
1118 ModuleTool
1120 The ModuleTool variable contains the name of the module imple‐
1121 mentation currently in use. The value of this variable is set to
1122 Modules for this implementation.
1123 ModuleToolVersion
1125 The ModuleToolVersion variable contains the version of the mod‐
1126 ule implementation currently in use. The value of this variable
1127 is set to 5.2.0 for this version of Modules.
1128 ModuleVariant
1130 The ModuleVariant array variable contains an element entry for
1131 each defined variant associated to the value of this variant
1132 (e.g., the $ModuleVariant(foo) syntax corresponds to the value
1133 of variant foo if defined). A Tcl evaluation error is obtained
1134 when accessing an undefined variant in ModuleVariant array. Use
1135 preferably the getvariant command to retrieve a variant value
1136 when this variant state is not known.
1137 The list of the currently defined variants can be retrieved with
1139 [array names ModuleVariant] Tcl code.
1140
1142 Every directory in MODULEPATH is searched to find the modulefile. A di‐
1143 rectory in MODULEPATH can have an arbitrary number of sub-directories.
1144 If the user names a modulefile to be loaded which is actually a direc‐
1145 tory, the directory is opened and a search begins for an actual module‐
1146 file. First, modulecmd.tcl looks for a file with the name .modulerc in
1147 the directory. If this file exists, its contents will be evaluated as
1148 if it was a modulefile to be loaded. You may place module-version,
1149 module-alias and module-virtual commands inside this file.
1150 Additionally, before seeking for .modulerc files in the module direc‐
1152 tory, the global modulerc file and the .modulerc file found at the root
1153 of the modulepath directory are sourced, too. If a named version de‐
1154 fault now exists for the modulefile to be loaded, the assigned module‐
1155 file now will be sourced. Otherwise the file .version is looked up in
1156 the module directory.
1157 If the .version file exists, it is opened and interpreted as Tcl code
1159 and takes precedence over a .modulerc file in the same directory. If
1160 the Tcl variable ModulesVersion is set by the .version file, mod‐
1161 ulecmd.tcl will use the name as if it specifies a modulefile in this
1162 directory. This will become the default modulefile in this case.
1163 ModulesVersion cannot refer to a modulefile located in a different di‐
1164 rectory.
1165 If ModulesVersion is a directory, the search begins anew down that di‐
1167 rectory. If the name does not match any files located in the current
1168 directory, the search continues through the remaining directories in
1169 MODULEPATH.
1170 Every .version and .modulerc file found is interpreted as Tcl code. The
1172 difference is that .version only applies to the current directory, and
1173 the .modulerc applies to the current directory and all subdirectories.
1174 Changes made in these files will affect the subsequently interpreted
1175 modulefile.
1176 If no default version may be figured out, an implicit default is se‐
1178 lected when this behavior is enabled (see MODULES_IMPLICIT_DEFAULT in
1179 module(1)). If disabled, module names should be fully qualified when no
1180 explicit default is defined for them, otherwise no default version is
1181 found and an error is returned. If enabled, then the highest numeri‐
1182 cally sorted modulefile, virtual module or module alias under the di‐
1183 rectory will be used. The dictionary comparison method of the lsort(n)
1184 Tcl command is used to achieve this sort. If highest numerically sorted
1185 element is an alias, search continues on its modulefile target.
1186 For example, it is possible for a user to have a directory named X11
1188 which simply contains a .version file specifying which version of X11
1189 is to be loaded. Such a file would look like:
1190 #%Module1.0
1192 ##
1193 ## The desired version of X11
1194 ##
1195 set ModulesVersion "R4"
1196 The equivalent .modulerc would look like:
1198 #%Module1.0
1200 ##
1201 ## The desired version of X11
1202 ##
1203 module-version "./R4" default
1204 If the extended default mechanism is enabled (see MODULES_EXTENDED_DE‐
1206 FAULT in module(1)) the module version specified is matched against
1207 starting portion of existing module versions, where portion is a sub‐
1208 string separated from the rest of version string by a . character.
1209 When the implicit default mechanism and the Advanced module version
1211 specifiers are both enabled, a default and latest symbolic versions are
1212 automatically defined for each module name (also at each directory
1213 level in case of deep modulefile). Unless a symbolic version, alias, or
1214 regular module version already exists for these version names.
1215 Every file in searched directories is checked to see if it begins with
1217 the Modules magic cookie (i.e., #%Module file signature) to determine
1218 if it is a modulefile (see DESCRIPTION section). When the mcookie_check
1219 configuration is set to eval, this check is skipped and all files in
1220 search directories are considered modulefiles.
1221 If user names a modulefile that cannot be found in the first modulepath
1223 directory, modulefile will be searched in next modulepath directory and
1224 so on until a matching modulefile is found. If search goes through a
1225 module alias or a symbolic version, this alias or symbol is resolved by
1226 first looking at the modulefiles in the modulepath where this alias or
1227 symbol is defined. If not found, resolution looks at the other mod‐
1228 ulepaths in their definition order.
1229 When locating modulefiles, if a .modulerc, a .version, a directory or a
1231 modulefile cannot be read during the search it is simply ignored with
1232 no error message produced. Visibility of modulefiles can thus be
1233 adapted to the rights the user has been granted. Exception is made when
1234 trying to directly access a directory or a modulefile. In this case,
1235 the access issue is returned as an error message.
1236 Depending on their name, their file permissions or the use of specific
1238 modulefile commands, modulefile, virtual module, module alias or sym‐
1239 bolic version may be set hidden which impacts available modules search
1240 or module selection processes (see Hiding modulefiles section below).
1241
1243 A modulefile, virtual module, module alias or symbolic version whose
1244 name or element in their name starts with a dot character (.) or who
1245 are targeted by a module-hide command are considered hidden. Hidden
1246 modules are not displayed or taken into account except if they are ex‐
1247 plicitly named (e.g., foo/1.2.3 or foo/.2.0 not foo). If module has
1248 been hidden with the --soft option of the module-hide command set, it
1249 is not considered hidden if the root name of the query to search it
1250 matches module root name (e.g., searching foo will return a foo/1.2.3
1251 modulefile targeted by a module-hide --soft command). If module has
1252 been hidden with the --hard option of the module-hide command set, it
1253 is always considered hidden thus it is never displayed nor taken into
1254 account even if it is explicitly named.
1255 A modulefile, virtual module, module alias or symbolic version who are
1257 targeted by a module-hide --hard command and a module-forbid command or
1258 whose file access permissions are restricted are considered hard-hidden
1259 and forbidden. Such modules are not displayed or taken into account.
1260 When explicitly named for evaluation selection, such modules are un‐
1261 veiled to return an access error.
1262 NOTE:
1264 When the mcookie_check configuration is set to eval, file access
1265 permissions are not checked thus files with restricted permissions
1266 are included in search results but still lead to error if evaluated.
1267 A symbolic version-name assigned to a hidden module is displayed or
1269 taken into account only if explicitly named and if module is not
1270 hard-hidden. Non-hidden module alias targeting a hidden modulefile ap‐
1271 pears like any other non-hidden module alias. Finally, a hidden sym‐
1272 bolic version targeting a non-hidden module is displayed or taken into
1273 account only if not hard-hidden and explicitly named to refer to its
1274 non-hidden target.
1275 The automatic version symbols (e.g., default and latest) are unaffected
1277 by hiding. Moreover when a regular default or latest version is set
1278 hidden, the corresponding automatic version symbol takes the left spot.
1279 For instance, if foo/default which targets foo/1.2.3 is set hard-hid‐
1280 den, the default automatic version symbol will be set onto foo/2.1.3,
1281 the highest available version of foo.
1282 When loading a modulefile or a virtual module targeted by a module-hide
1284 --hidden-loaded command, this module inherits the hidden-loaded tag.
1285 Hidden loaded modules are not reported among list sub-command results.
1286 If the --all is set on avail, aliases, whatis or search sub-commands,
1288 hidden modules are taken into account in search. Hard-hidden modules
1289 are unaffected by this option.
1290 If the --all is set on list sub-command, hidden loaded modules are in‐
1292 cluded in result output.
1293
1295 When the advanced module version specifiers mechanism is enabled (see
1296 MODULES_ADVANCED_VERSION_SPEC in module(1)), the specification of mod‐
1297 ulefile passed on Modules specific Tcl commands changes. After the
1298 module name a version constraint and variants may be added.
1299 Version specifiers
1301 After the module name a version constraint prefixed by the @ character
1302 may be added. It could be directly appended to the module name or sepa‐
1303 rated from it with a space character.
1304 Constraints can be expressed to refine the selection of module version
1306 to:
1307 • a single version with the @version syntax, for instance foo@1.2.3
1309 syntax will select module foo/1.2.3
1310 • a list of versions with the @version1,version2,... syntax, for in‐
1312 stance foo@1.2.3,1.10 will match modules foo/1.2.3 and foo/1.10
1313 • a range of versions with the @version1:, @:version2 and @ver‐
1315 sion1:version2 syntaxes, for instance foo@1.2: will select all ver‐
1316 sions of module foo greater than or equal to 1.2, foo@:1.3 will se‐
1317 lect all versions less than or equal to 1.3 and foo@1.2:1.3 matches
1318 all versions between 1.2 and 1.3 including 1.2 and 1.3 versions
1319 Advanced specification of single version or list of versions may bene‐
1321 fit from the activation of the extended default mechanism (see MOD‐
1322 ULES_EXTENDED_DEFAULT in module(1)) to use an abbreviated notation like
1323 @1 to refer to more precise version numbers like 1.2.3. Range of ver‐
1324 sions on its side natively handles abbreviated versions.
1325 In order to be specified in a range of versions or compared to a range
1327 of versions, the version major element should corresponds to a number.
1328 For instance 10a, 1.2.3, 1.foo are versions valid for range comparison
1329 whereas default or foo.2 versions are invalid for range comparison.
1330 Range of versions can be specified in version list, for instance
1332 foo@:1.2,1.4:1.6,1.8:. Such specification helps to exclude specific
1333 versions, like versions 1.3 and 1.7 in previous example.
1334 If the implicit default mechanism is also enabled (see MODULES_IM‐
1336 PLICIT_DEFAULT in module(1)), a default and latest symbolic versions
1337 are automatically defined for each module name (also at each directory
1338 level for deep modulefiles). These automatic version symbols are de‐
1339 fined unless a symbolic version, alias, or regular module version al‐
1340 ready exists for these default or latest version names. Using the
1341 mod@latest (or mod/latest) syntax ensures highest available version
1342 will be selected.
1343 Variants
1345 After the module name, variants can be specified. Module variants are
1346 alternative evaluation of the same modulefile. A variant is specified
1347 by associating a value to its name. This specification is then trans‐
1348 mitted to the evaluating modulefile which instantiates the variant in
1349 the ModuleVariant array variable when reaching the variant modulefile
1350 command declaring this variant.
1351 Variant can be specified with the name=value syntax where name is the
1353 declared variant name and value, the value this variant is set to when
1354 evaluating the modulefile.
1355 Boolean variants can be specified with the +name syntax to set this
1357 variant on and with the -name or ~name syntaxes to set this variant
1358 off. The -name syntax is not supported on ml(1) command as the minus
1359 sign already means to unload designated module. The ~name and +name
1360 syntaxes could also be defined appended to another specification word
1361 (e.g., the module name, version or another variant specification),
1362 whereas -name syntax must be the start of a new specification word.
1363 Boolean variants may also be specified with the name=value syntax.
1365 value should be set to 1, true, t, yes, y or on to enable the variant
1366 or it should be set to 0, false, f, no, n or off to disable the vari‐
1367 ant.
1368 Shortcuts may be used to abbreviate variant specification. The vari‐
1370 ant_shortcut configuration option associates shortcut character to
1371 variant name. With a shortcut defined, variant could be specified with
1372 the <shortcut>value syntax. For instance if character % is set as a
1373 shortcut for variant foo, the %value syntax is equivalent to the
1374 foo=value syntax.
1375 Specific characters used in variant specification syntax cannot be used
1377 as part of the name of a module. These specific characters are +, ~, =
1378 and all characters set as variant shortcut. Exception is made for +
1379 character which could be set one or several consecutive times at the
1380 end of module name (e.g., name+ or name++).
1381
1383 A modulefile may express dependencies on other modulefiles. Two kind of
1384 dependency exist: pre-requirement and conflict. The former means speci‐
1385 fied modulefiles should be loaded prior the modulefile that express the
1386 requirement. The latter means specified modulefiles should not be
1387 loaded for the modulefile that express the conflict to be loaded too.
1388 Pre-requirement could be expressed with prereq, prereq-any, prereq-all,
1390 depends-on, always-load, module load, module switch, module try-load or
1391 module load-any modulefile commands. When the auto_handling configura‐
1392 tion option is disabled, required modulefile should be manually loaded
1393 prior their dependent modulefile when expressed with the prereq,
1394 prereq-any, prereq-all or depends-on modulefile commands. For other
1395 commands or when auto_handling is enabled, pre-required modulefiles are
1396 automatically loaded.
1397 Conflict is expressed with conflict or module unload modulefile com‐
1399 mands. A conflicting loaded modulefile should be manually unloaded
1400 prior loading the modulefile that express such conflict when defined
1401 with conflict. It is automatically unloaded when expressed with module
1402 unload.
1403 It is strongly advised to define dependencies prior environment changes
1405 in a modulefile. Dependency resolution should be done before any envi‐
1406 ronment change to ensure the environment is getting set in the same or‐
1407 der whether pre-requirements are already loaded, or if they are auto‐
1408 matically loaded when loading the modulefile which depends on them, or
1409 if all loaded modules are reloaded or refreshed. This is especially im‐
1410 portant when the modulefile updates an environment variable also al‐
1411 tered by other modulefiles like PATH. As the order of the path elements
1412 in such variable defines priority, it is important that this order does
1413 not change depending on the way the modulefiles are loaded.
1414 module keeps environment consistent which means a modulefile cannot be
1416 loaded if its requirements are not loaded or if a conflicting module is
1417 loaded. In addition a loaded module cannot be unloaded if other loaded
1418 modules depends on it. The automated module handling mechanisms attempt
1419 to solve the dependencies expressed by loading or unloading additional
1420 modulefiles. When the --no-auto option is set on module command when
1421 loading or unload modulefile, automated module handling mechanisms are
1422 disabled and dependencies have to be solved manually. When dependencies
1423 are not satisfied, modulefile fails to load or unload.
1424 Adding the --not-req option when expressing dependencies in modulefile
1426 with the module command will attempt to load or unload the designated
1427 modulefile but it will not mark them as pre-requirement or conflict.
1428 Adding the --optional option on prereq, prereq-any, prereq-all,
1430 depends-on or always-load modulefile commands declares the pre-require‐
1431 ment as optional. If an optional pre-requirement is not found loaded or
1432 cannot be automatically loaded, the dependency expressed is yet consid‐
1433 ered satisfied. When an optional requirement is loaded afterward, the
1434 dependent module will get automatically reloaded if the auto_handling
1435 configuration option is enabled.
1436 By adding the --force option to the module command when loading or un‐
1438 loading modulefile, the consistency checks are by-passed. This option
1439 cannot be used when expressing dependencies in modulefiles. If a module
1440 has been force loaded whereas its requirements are not loaded or
1441 whereas a conflicting module is also loaded, the user environment is
1442 said inconsistent.
1443 Note that a pre-requirement should be found in the loaded module list
1445 prior its dependent module. User environment is considered inconsistent
1446 if pre-requirement module is found loaded after dependent module, as
1447 the environment changes may have been done in the wrong priority order.
1448 When user environment is considered inconsistent global operations
1450 achieved by refresh, reload and save sub-commands cannot perform. This
1451 mechanism is there to avoid the situation to worsen by re-evaluating
1452 all loaded modules or recording this environment.
1453 When the auto_handling configuration option is enabled, if missing
1455 pre-requirement modulefile gets loaded or conflicting modulefile gets
1456 unloaded the inconsistent loaded module will be automatically reloaded
1457 to make user environment consistent again.
1458
1460 Users can request help about a specific modulefile through the mod‐
1461 ule(1) command. The modulefile can print helpful information or start
1462 help oriented programs by defining a ModulesHelp subroutine. The sub‐
1463 routine will be called when the module help modulefile command is used.
1464
1466 Users can request test of a specific modulefile through the module(1)
1467 command. The modulefile can perform some sanity checks on its defini‐
1468 tion or on its underlying programs by defining a ModulesTest subrou‐
1469 tine. The subroutine will be called when the module test modulefile
1470 command is used. The subroutine should return 1 in case of success. If
1471 no or any other value is returned, test is considered failed.
1472
1474 The module display modulefile command will detail all changes that will
1475 be made to the environment. After displaying all of the environment
1476 changes modulecmd.tcl will call the ModulesDisplay subroutine. The Mod‐
1477 ulesDisplay subroutine is a good place to put additional descriptive
1478 information about the modulefile.
1479
1481 The modulecmd.tcl program supports Tcl modulefile written for Lmod, the
1482 alternative module implementation developed in Lua. Such modulefiles
1483 can be evaluated by Modules without raising error. Differences between
1484 the two implementations are listed below.
1485 The add-property, remove-property and extensions modulefile commands
1487 are evaluated as a no-operation command. No error is obtained if these
1488 commands are used in modulefiles but no change occurs.
1489 The break command does not accept any argument. A msg argument can be
1491 set on Lmod to provide a customized break error message.
1492 Use of reportError command aborts modulefile evaluation on Lmod. This
1494 command only reports an error message on Modules.
1495 The require-fullname command only aborts load modulefile evaluation
1497 whereas the Lmod implementation also aborts unload and display evalua‐
1498 tions.
1499 When processing a family command, the LMOD_FAMILY_<NAME> environment
1501 variable is also defined to be compatible with modulefiles or scripts
1502 relying on such variable.
1503 When unloading a modulefile, the pushenv command does not update the
1505 value of the environment variable if this modulefile was not defining
1506 the value currently in use.
1507 The third optional argument of append-path and prepend-path commands
1509 corresponds to a priority specification on Lmod whereas these two com‐
1510 mands accept multiple path element arguments on Modules.
1511 The prereq command is equivalent to the prereq-any command on Modules
1513 whereas on Lmod it is equivalent to the prereq-all command.
1514 If the auto_handling configuration option is disabled, the requirements
1516 defined with the depends-on command are not automatically loaded and an
1517 error is raised if none of these requirements are found loaded.
1518 On module load-any sub-command and modulefile command, a modulefile
1520 evaluation error is not reported and module load-any continues to the
1521 next modulefile instead of aborting the whole process. No attempt to
1522 load listed modulefiles is made if one of these modulefiles is found
1523 already loaded.
1524 On module try-load modulefile command, each modulefile specified is
1526 considered an optional pre-requirement. If it is loaded afterward and
1527 if the auto_handling configuration option is enabled, the dependent
1528 module will get automatically reloaded.
1529
1531 The modulecmd.tcl program that evaluates modulefiles supports a variety
1532 of shells or languages: sh family shells (sh, bash, ksh and zsh), csh
1533 family shells (csh and tcsh), fish, cmd, python, perl, ruby, tcl,
1534 cmake, r, and lisp.
1535 Modulefiles produce environment changes when evaluated, like defining
1537 an environment variable. The modulecmd.tcl program outputs the corre‐
1538 sponding code for the selected "shell". Thereafter this code is evalu‐
1539 ated by the module alias or function to update the current environment.
1540 Depending on the "shell" kind, not all the environment changes that can
1542 be defined in modulefiles are supported. The following table summarizes
1543 the changes that are supported by the shells supported by mod‐
1544 ulecmd.tcl.
1545┌───────┬───────────────┬──────────────┬─────────────────┬─────────────┬───────┬────────────┐
1553│ │ Environ‐ │ Shell │ Shell │ Command │ chdir │ x-resource │
1554│ │ ment vari‐ │ alias (‐ │ functions │ completion │ │ │
1555│ │ ables (‐ │ set-alias, │ (‐ │ (complete, │ │ │
1556│ │ setenv, │ unset-alias) │ set-func‐ │ uncomplete) │ │ │
1557│ │ unsetenv, │ │ tion, │ │ │ │
1558│ │ pushenv, │ │ unset-function) │ │ │ │
1559│ │ append-path, │ │ │ │ │ │
1560│ │ prepend-path, │ │ │ │ │ │
1561│ │ remove-path) │ │ │ │ │ │
1562├───────┼───────────────┼──────────────┼─────────────────┼─────────────┼───────┼────────────┤
1563│sh │ ⦁ │ ⦁ │ ⦁ │ │ ⦁ │ ⦁ │
1564├───────┼───────────────┼──────────────┼─────────────────┼─────────────┼───────┼────────────┤
1565│bash │ ⦁ │ ⦁ │ ⦁ │ ⦁ │ ⦁ │ ⦁ │
1566├───────┼───────────────┼──────────────┼─────────────────┼─────────────┼───────┼────────────┤
1567│ksh │ ⦁ │ ⦁ │ ⦁ │ │ ⦁ │ ⦁ │
1568├───────┼───────────────┼──────────────┼─────────────────┼─────────────┼───────┼────────────┤
1569│zsh │ ⦁ │ ⦁ │ ⦁ │ │ ⦁ │ ⦁ │
1570├───────┼───────────────┼──────────────┼─────────────────┼─────────────┼───────┼────────────┤
1571│csh │ ⦁ │ ⦁ │ │ │ ⦁ │ ⦁ │
1572├───────┼───────────────┼──────────────┼─────────────────┼─────────────┼───────┼────────────┤
1573│tcsh │ ⦁ │ ⦁ │ │ ⦁ │ ⦁ │ ⦁ │
1574├───────┼───────────────┼──────────────┼─────────────────┼─────────────┼───────┼────────────┤
1575│fish │ ⦁ │ ⦁ │ ⦁ │ ⦁ │ ⦁ │ ⦁ │
1576├───────┼───────────────┼──────────────┼─────────────────┼─────────────┼───────┼────────────┤
1577│cmd │ ⦁ │ ⦁ │ │ │ ⦁ │ │
1578├───────┼───────────────┼──────────────┼─────────────────┼─────────────┼───────┼────────────┤
1579│python │ ⦁ │ │ │ │ ⦁ │ ⦁ │
1580├───────┼───────────────┼──────────────┼─────────────────┼─────────────┼───────┼────────────┤
1581│perl │ ⦁ │ │ │ │ ⦁ │ ⦁ │
1582├───────┼───────────────┼──────────────┼─────────────────┼─────────────┼───────┼────────────┤
1583│ruby │ ⦁ │ │ │ │ ⦁ │ ⦁ │
1584├───────┼───────────────┼──────────────┼─────────────────┼─────────────┼───────┼────────────┤
1585│tcl │ ⦁ │ │ │ │ ⦁ │ ⦁ │
1586├───────┼───────────────┼──────────────┼─────────────────┼─────────────┼───────┼────────────┤
1587│cmake │ ⦁ │ │ │ │ │ ⦁ │
1588├───────┼───────────────┼──────────────┼─────────────────┼─────────────┼───────┼────────────┤
1589│r │ ⦁ │ │ │ │ ⦁ │ ⦁ │
1590├───────┼───────────────┼──────────────┼─────────────────┼─────────────┼───────┼────────────┤
1591│lisp │ ⦁ │ │ │ │ ⦁ │ ⦁ │
1592└───────┴───────────────┴──────────────┴─────────────────┴─────────────┴───────┴────────────┘
1593 The source-sh command evaluates a shell script and produces the module‐
1595 file commands corresponding to the environment changes made by this
1596 script. source-sh is able to evaluate sh, bash, ksh, zsh, csh, tcsh and
1597 fish shell scripts. source-sh produces environment changes correspond‐
1598 ing to the kinds listed in the above table. Based on the evaluated
1599 script, refer to the above table to know the environment changes that
1600 will be rendered for the shell specified to modulecmd.tcl program.
1601
1603 See the ENVIRONMENT section in the module(1) man page.
1604
1606 module(1), ml(1), Tcl(n), TclX(n), id(1), xrdb(1), exec(n), uname(1),
1607 domainname(1), tclvars(n), lsort(n)
1608
1610 Tcl was developed by John Ousterhout at the University of California at
1611 Berkeley.
1612 TclX was developed by Karl Lehenbauer and Mark Diekhans.
1614
1616 1996-1999 John L. Furlani & Peter W. Osel, 1998-2017 R.K.Owen,
1617 2002-2004 Mark Lakata, 2004-2017 Kent Mein, 2016-2022 Xavier Delaruelle
16185.2.0 2022-11-08 MODULEFILE(4)