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 [--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 The --tag option accepts a list of module tags to apply to mod‐
76 ulefile once loaded in addition to the keep-loaded tag. taglist
77 corresponds to the concatenation of multiple tags separated by
78 colon character. taglist should not contain tags inherited from
79 modulefile state or from other modulefile commands. If module is
80 already loaded, tags from taglist are added to the list of tags
81 already applied to this module.
82 append-path [-d C|--delim C|--delim=C] [--duplicates] variable value...
84 See prepend-path.
85 break This is not a Modules-specific command, it's actually part of
87 Tcl, which has been overloaded similar to the continue and exit
88 commands to have the effect of causing the module not to be
89 listed as loaded and not affect other modules being loaded con‐
90 currently. All non-environment commands within the module will
91 be performed up to this point and processing will continue on to
92 the next module on the command line. The break command will only
93 have this effect if not used within a Tcl loop though.
94 An example: Suppose that a full selection of modulefiles are
96 needed for various different architectures, but some of the mod‐
97 ulefiles are not needed and the user should be alerted. Having
98 the unnecessary modulefile be a link to the following notavail
99 modulefile will perform the task as required.
100 #%Module1.0
102 ## notavail modulefile
103 ##
104 proc ModulesHelp { } {
105 puts stderr "This module does nothing but alert the user"
106 puts stderr "that the [module-info name] module is not available"
107 }
108 module-whatis "Notifies user that module is not available."
110 set curMod [module-info name]
111 if { [ module-info mode load ] } {
112 puts stderr "Note: '$curMod' is not available for [uname sysname]."
113 }
114 break
115 chdir directory
117 Set the current working directory to directory.
118 complete shell name body
120 Define shell completion for command name with specified body if
121 shell is the current shell under which modulecmd.tcl was in‐
122 voked. Body corresponds to argument options accepted by the
123 shell command which defines completion. When a modulefile is un‐
124 loaded, complete becomes uncomplete.
125 The following shells are supported: bash, tcsh, bash and fish.
127 Please refer to the documentation of these shells to learn how
128 to define completion. The command is ignored if an unsupported
129 shell is specified.
130 conflict modulefile...
132 conflict controls whether or not the modulefile will be loaded.
133 The conflict command lists modulefiles which conflict with the
134 current modulefile. If a list contains more than one modulefile,
135 then each member of the list acts as a Boolean OR operation.
136 Multiple conflict commands may be used to create a Boolean AND
137 operation. If one of the requirements have not been satisfied,
138 an error is reported and the current modulefile makes no changes
139 to the user's environment.
140 If an argument for conflict is a directory and any other module‐
142 file from that directory has been loaded, then a conflict will
143 occur. For example, specifying X11 as a conflict will stop
144 X11/R4 and X11/R5 from being loaded at the same time.
145 The parameter modulefile may also be a symbolic modulefile name
147 or a modulefile alias. It may also leverage a specific syntax to
148 finely select module version (see Advanced module version speci‐
149 fiers section below).
150 continue
152 This is not a modules specific command but another overloaded
153 Tcl command and is similar to the break or exit commands except
154 the module will be listed as loaded as well as performing any
155 environment or Tcl commands up to this point and then continuing
156 on to the next module on the command line. The continue command
157 will only have this effect if not used within a Tcl loop though.
158 depends-on [--tag taglist] modulefile...
160 Alias of prereq-all command.
161 exit [N]
163 This is not a modules specific command but another overloaded
164 Tcl command and is similar to the break or continue commands.
165 However, this command will cause the immediate cessation of this
166 module and any additional ones on the command line. This module
167 and the subsequent modules will not be listed as loaded. No en‐
168 vironment commands will be performed in the current module.
169 family name
171 Defines loading modulefile as a member of family name. Only one
172 member of a family could be loaded. Error is raised when at‐
173 tempting to load another member of the same family name.
174 family corresponds to the definition of a conflict on name and
176 the definition of a module-alias name targeting currently load‐
177 ing module.
178 In addition, the MODULES_FAMILY_<NAME> environment variable is
180 defined and set to the currently loading module name minus ver‐
181 sion. This variable helps to know what module provides for the
182 family name in the currently loaded environment. For instance if
183 loading modulefile foo/1.0 defines being member of the bar fam‐
184 ily, the MODULES_FAMILY_BAR will be set to the foo value. For
185 compatibility, the LMOD_FAMILY_<NAME> environment variable is
186 also defined and set to the same value than MODULES_FAM‐
187 ILY_<NAME>.
188 name should be a non-empty string only containing characters
190 that could be part of an environment variable name (i.e.,
191 [a-zA-Z0-9_]).
192 getenv [--return-value] variable [value]
194 Returns value of environment variable. If variable is not de‐
195 fined, value is returned if set, an empty string is returned
196 otherwise. The getenv command should be preferred over the Tcl
197 global variable env to query environment variables.
198 When modulefile is evaluated in display mode, getenv returns
200 variable name prefixed with dollar sign (e.g., $variable) unless
201 if the --return-value option is set. When this option is set the
202 value of environment variable or defined fallback value is re‐
203 turned in display mode.
204 getvariant [--return-value] variant [value]
206 Returns value of designated variant. If variant is not defined,
207 value is returned if set, an empty string is returned otherwise.
208 The getvariant command should be preferred over the
209 ModuleVariant Tcl array to query a variant value.
210 When modulefile is evaluated in display mode, getvariant returns
212 variant name enclosed in curly braces (e.g., {variant}) unless
213 if the --return-value option is set. When this option is set the
214 value of variant or defined fallback value is returned in dis‐
215 play mode.
216 is-avail modulefile...
218 The is-avail command returns a true value if any of the listed
219 modulefiles exists in enabled MODULEPATH. If a list contains
220 more than one modulefile, then each member acts as a boolean OR
221 operation. If an argument for is-avail is a directory and a mod‐
222 ulefile exists in the directory is-avail would return a true
223 value.
224 The parameter modulefile may also be a symbolic modulefile name
226 or a modulefile alias. It may also leverage a specific syntax to
227 finely select module version (see Advanced module version speci‐
228 fiers section below).
229 is-loaded [modulefile...]
231 The is-loaded command returns a true value if any of the listed
232 modulefiles has been loaded or if any modulefile is loaded in
233 case no argument is provided. If a list contains more than one
234 modulefile, then each member acts as a boolean OR operation. If
235 an argument for is-loaded is a directory and any modulefile from
236 the directory has been loaded is-loaded would return a true
237 value.
238 The parameter modulefile may also be a symbolic modulefile name
240 or a modulefile alias. It may also leverage a specific syntax to
241 finely select module version (see Advanced module version speci‐
242 fiers section below).
243 is-saved [collection...]
245 The is-saved command returns a true value if any of the listed
246 collections exists or if any collection exists in case no argu‐
247 ment is provided. If a list contains more than one collection,
248 then each member acts as a boolean OR operation.
249 If MODULES_COLLECTION_TARGET is set, a suffix equivalent to the
251 value of this variable is appended to the passed collection
252 name. In case no collection argument is provided, a true value
253 will only be returned if a collection matching currently set
254 target exists.
255 is-used [directory...]
257 The is-used command returns a true value if any of the listed
258 directories has been enabled in MODULEPATH or if any directory
259 is enabled in case no argument is provided. If a list contains
260 more than one directory, then each member acts as a boolean OR
261 operation.
262 module [sub-command] [sub-command-options] [sub-command-args]
264 This command permits a modulefile to load or unload other mod‐
265 ulefiles or to use or unuse modulepaths. No checks are made to
266 ensure that the modulefile does not try to load itself. Often
267 it is useful to have a single modulefile that performs a number
268 of module load commands. For example, if every user on the sys‐
269 tem requires a basic set of applications loaded, then a core
270 modulefile would contain the necessary module load commands.
271 The --not-req option may be set for the load, try-load,
273 load-any, unload and switch sub-commands to inhibit the defini‐
274 tion of an implicit prereq or conflict requirement onto speci‐
275 fied modules.
276 On try-load sub-command, if specified modulefile is not found
278 thus loaded, no implicit prereq requirement is defined over this
279 module.
280 The load-any sub-command loads one modulefile from the specified
282 list. An error is obtained if no modulefile from the list can
283 be loaded. No operation is performed if a modulefile from the
284 list is found already loaded.
285 The unuse sub-command accepts the --remove-on-unload,
287 --noop-on-unload, --append-on-unload and --prepend-on-unload op‐
288 tions to control the behavior to apply when modulefile is un‐
289 loaded. See remove-path for further explanation.
290 The load, try-load, load-any and switch sub-commands accept the
292 --tag option to apply specified tags to modulefile once loaded.
293 Option accepts a concatenation of multiple module tags separated
294 by colon character. taglist should not contain tags inherited
295 from modulefile state or from other modulefile commands. If mod‐
296 ule is already loaded, tags from taglist are added to the list
297 of tags already applied to this module.
298 Command line switches --auto, --no-auto and --force are ignored
300 when passed to a module command set in a modulefile.
301 Not all the sub-commands described in the Module Sub-Commands
303 section of the module(1) man page are available when module is
304 used as a Modules specific Tcl command. The following table sum‐
305 marizes the different sub-commands available for each interpre‐
306 tation context.
307 ┌────────────────────┬─────────────────────┬─────────────────────┐
309 │Sub-commands avail‐ │ Sub-commands avail‐ │ Sub-commands avail‐ │
310 │able from module‐ │ able from initrc │ able from run-com‐ │
311 │file interpretation │ configuration file │ mand (rc) file in‐ │
312 │ │ and sourced script │ terpretation │
313 │ │ file │ │
314 ├────────────────────┼─────────────────────┼─────────────────────┤
315 │load, load-any, │ Same sub-commands │ None │
316 │switch, try-load, │ available than for │ │
317 │unload, unuse, use. │ modulefile and con‐ │ │
318 │Also available but │ fig sub-command. │ │
319 │not recommanded for │ │ │
320 │use from regular │ │ │
321 │modulefile: │ │ │
322 │aliases, avail, │ │ │
323 │display, initadd, │ │ │
324 │initclear, │ │ │
325 │initlist, init‐ │ │ │
326 │prepend, initrm, │ │ │
327 │initswitch, list, │ │ │
328 │purge, reload, re‐ │ │ │
329 │store, save, │ │ │
330 │savelist, saverm, │ │ │
331 │saveshow, search, │ │ │
332 │test, whatis │ │ │
333 └────────────────────┴─────────────────────┴─────────────────────┘
334 module-alias name modulefile
336 Assigns the modulefile to the alias name. This command should be
337 placed in one of the modulecmd.tcl rc files in order to provide
338 shorthand invocations of frequently used modulefile names.
339 The parameter modulefile may be either
341 • a fully qualified modulefile with name and version
343 • a symbolic modulefile name
345 • another modulefile alias
347 module-forbid [options] modulefile...
349 Forbid use of modulefile. An error is obtained when trying to
350 evaluate a forbidden module. This command should be placed in
351 one of the modulecmd.tcl rc files.
352 module-forbid command accepts the following options:
354 • --after datetime
356 • --before datetime
358 • --not-user {user...}
360 • --not-group {group...}
362 • --message {text message}
364 • --nearly-message {text message}
366 If --after option is set, forbidding is only effective after
368 specified date time. Following the same principle, if --before
369 option is set, forbidding is only effective before specified
370 date time. Accepted date time format is YYYY-MM-DD[THH:MM]. If
371 no time (HH:MM) is specified, 00:00 is assumed. --after and
372 --before options are not supported on Tcl versions prior to 8.5.
373 If --not-user option is set, forbidding is not applied if the
375 username of the user currently running modulecmd.tcl is part of
376 the list of username specified. Following the same approach, if
377 --not-group option is set, forbidding is not applied if current
378 user is member of one the group specified. When both options are
379 set, forbidding is not applied if a match is found for
380 --not-user or --not-group.
381 Error message returned when trying to evaluate a forbidden mod‐
383 ule can be supplemented with the text message set through --mes‐
384 sage option.
385 If --after option is set, modules are considered nearly forbid‐
387 den during a number of days defined by the nearly_forbidden_days
388 modulecmd.tcl configuration option (see MODULES_NEARLY_FORBID‐
389 DEN_DAYS), prior reaching the expiry date fixed by --after op‐
390 tion. When a nearly forbidden module is evaluated a warning mes‐
391 sage is issued to inform module will soon be forbidden. This
392 warning message can be supplemented with the text message set
393 through --nearly-message option.
394 If a module-forbid command applies to a modulefile also targeted
396 by a module-hide --hard command, this module is unveiled when
397 precisely named to return an access error.
398 Forbidden modules included in the result of an avail sub-command
400 are reported with a forbidden tag applied to them. Nearly for‐
401 bidden modules included in the result of an avail or a list
402 sub-command are reported with a nearly-forbidden tag applied to
403 them. See Module tags section in module(1).
404 The parameter modulefile may leverage a specific syntax to
406 finely select module version (see Advanced module version speci‐
407 fiers section below).
408 module-hide [options] modulefile...
410 Hide modulefile to exclude it from available module search or
411 module selection unless query refers to modulefile by its exact
412 name. This command should be placed in one of the modulecmd.tcl
413 rc files.
414 module-hide command accepts the following options:
416 • --soft|--hard
418 • --hidden-loaded
420 • --after datetime
422 • --before datetime
424 • --not-user {user...}
426 • --not-group {group...}
428 When --soft option is set, modulefile is also set hidden, but
430 hiding is disabled when search or selection query's root name
431 matches module's root name. This soft hiding mode enables to
432 hide modulefiles from bare module availability listing yet keep‐
433 ing the ability to select such module for load with the regular
434 resolution mechanism (i.e., no need to use module exact name to
435 select it)
436 When --hard option is set, modulefile is also set hidden and
438 stays hidden even if search or selection query refers to module‐
439 file by its exact name.
440 When --hidden-loaded option is set, hidden state also applies to
442 the modulefile when it is loaded. Hidden loaded modules do not
443 appear on list sub-command output, unless --all option is set.
444 Their loading or unloading informational messages are not re‐
445 ported unless the verbosity of Modules is set to a level higher
446 than verbose. Hidden loaded modules are detected in any cases by
447 state query commands like is-loaded.
448 If --after option is set, hiding is only effective after speci‐
450 fied date time. Following the same principle, if --before option
451 is set, hiding is only effective before specified date time. Ac‐
452 cepted date time format is YYYY-MM-DD[THH:MM]. If no time
453 (HH:MM) is specified, 00:00 is assumed. --after and --before op‐
454 tions are not supported on Tcl versions prior to 8.5.
455 If --not-user option is set, hiding is not applied if the user‐
457 name of the user currently running modulecmd.tcl is part of the
458 list of username specified. Following the same approach, if
459 --not-group option is set, hiding is not applied if current user
460 is member of one the group specified. When both options are
461 set, hiding is not applied if a match is found for --not-user or
462 --not-group.
463 If the --all option is set on avail, aliases, whatis or search
465 sub-commands, hiding is disabled thus hidden modulefiles are in‐
466 cluded in module search. Hard-hidden modules (i.e., declared
467 hidden with --hard option) are not affected by --all and stay
468 hidden even if option is set. --all option does not apply to
469 module selection sub-commands like load. Thus in such context a
470 hidden module should always be referred by its exact full name
471 (e.g., foo/1.2.3 not foo) unless if it has been hidden in --soft
472 mode. A hard-hidden module cannot be unveiled or selected in any
473 case.
474 If several module-hide commands target the same modulefile, the
476 strongest hiding level is retained which means if both a regu‐
477 lar, a --soft hiding command match a given module, regular hid‐
478 ing mode is considered. If both a regular and a --hard hiding
479 command match a given module, hard hiding mode is retained. A
480 set --hidden-loaded option is retained even if the module-hide
481 statement on which it is declared is superseded by a stronger
482 module-hide statement with no --hidden-loaded option set.
483 Hidden modules included in the result of an avail sub-command
485 are reported with a hidden tag applied to them. Hidden loaded
486 modules included in the result of a list sub-command are re‐
487 ported with a hidden-loaded tag applied to them. This tag is not
488 reported on avail sub-command context. See Module tags section
489 in module(1).
490 The parameter modulefile may also be a symbolic modulefile name
492 or a modulefile alias. It may also leverage a specific syntax to
493 finely select module version (see Advanced module version speci‐
494 fiers section below).
495 module-info option [info-args]
497 Provide information about the modulecmd.tcl program's state.
498 Some of the information is specific to the internals of mod‐
499 ulecmd.tcl. option is the type of information to be provided,
500 and info-args are any arguments needed.
501 module-info alias name
503 Returns the full modulefile name to which the modulefile
504 alias name is assigned
505 module-info command [commandname]
507 Returns the currently running modulecmd.tcl's command as a
508 string if no commandname is given.
509 Returns 1 if modulecmd.tcl's command is commandname. com‐
511 mandname can be: load, unload, refresh, reload, source,
512 switch, display, avail, aliases, list, whatis, search, purge,
513 restore, help, test, try-load or load-any.
514 module-info loaded modulefile
516 Returns the names of currently loaded modules matching passed
517 modulefile. The parameter modulefile might either be a fully
518 qualified modulefile with name and version or just a direc‐
519 tory which in case all loaded modulefiles from the directory
520 will be returned. The parameter modulefile may also be a sym‐
521 bolic modulefile name or a modulefile alias.
522 This command only returns the name and version of designated
524 loaded module. The defined variants of the loaded module are
525 not included in the returned string.
526 module-info mode [modetype]
528 Returns the current modulecmd.tcl's mode as a string if no
529 modetype is given.
530 Returns 1 if modulecmd.tcl's mode is modetype. modetype can
532 be: load, unload, remove (alias of unload), switch, refresh,
533 nonpersist (alias of refresh), display, help, test or whatis.
534 module-info name
536 Return the name of the modulefile. This is not the full path‐
537 name for modulefile. See the Modules Variables section for
538 information on the full pathname.
539 This command only returns the name and version of currently
541 evaluating modulefile. The defined variants are not included
542 in the returned string. See getvariant command or
543 ModuleVariant array variable to get defined variant values
544 for currently evaluating modulefile.
545 module-info shell [shellname]
547 Return the current shell under which modulecmd.tcl was in‐
548 voked if no shellname is given. The current shell is the
549 first parameter of modulecmd.tcl, which is normally hidden by
550 the module alias.
551 If a shellname is given, returns 1 if modulecmd.tcl's current
553 shell is shellname, returns 0 otherwise. shellname can be:
554 sh, bash, ksh, zsh, csh, tcsh, fish, tcl, perl, python, ruby,
555 lisp, cmake, r.
556 module-info shelltype [shelltypename]
558 Return the family of the shell under which modulefile was in‐
559 voked if no shelltypename is given. As of module-info shell
560 this depends on the first parameter of modulecmd.tcl. The
561 output reflects a shell type determining the shell syntax of
562 the commands produced by modulecmd.tcl.
563 If a shelltypename is given, returns 1 if modulecmd.tcl's
565 current shell type is shelltypename, returns 0 otherwise.
566 shelltypename can be: sh, csh, fish, tcl, perl, python, ruby,
567 lisp, cmake, r.
568 module-info specified
570 Return the module designation (name, version and variants)
571 specified that led to current modulefile evaluation.
572 module-info symbols modulefile
574 Returns a list of all symbolic versions assigned to the
575 passed modulefile. The parameter modulefile might either be
576 a full qualified modulefile with name and version, another
577 symbolic modulefile name or a modulefile alias.
578 module-info tags [tag]
580 Returns all tags assigned to currently evaluated modulefile
581 as a list of strings if no tag name is given (see Module tags
582 section in module(1))
583 When tags are assigned to specific module variants, they are
585 returned only if this variant is the one currently evaluated.
586 Returns 1 if one of the tags applying to currently evaluated
588 modulefile is tag. Returns 0 otherwise.
589 module-info type
591 Returns either C or Tcl to indicate which module command is
592 being executed, either the C version or the Tcl-only ver‐
593 sion, to allow the modulefile writer to handle any differ‐
594 ences between the two.
595 module-info usergroups [name]
597 Returns all the groups the user currently running mod‐
598 ulecmd.tcl is member of as a list of strings if no name is
599 given.
600 Returns 1 if one of the group current user running mod‐
602 ulecmd.tcl is member of is name. Returns 0 otherwise.
603 If the Modules Tcl extension library is disabled, the id(1)
605 command is invoked to fetch groups of current user.
606 module-info username [name]
608 Returns the username of the user currently running mod‐
609 ulecmd.tcl as a string if no name is given.
610 Returns 1 if username of current user running modulecmd.tcl
612 is name. Returns 0 otherwise.
613 If the Modules Tcl extension library is disabled, the id(1)
615 command is invoked to fetch username of current user.
616 module-info version modulefile
618 Returns the physical module name and version of the passed
619 symbolic version modulefile. The parameter modulefile might
620 either be a full qualified modulefile with name and version,
621 another symbolic modulefile name or a modulefile alias.
622 module-tag [options] tag modulefile...
624 Associate tag to designated modulefile. This tag information
625 will be reported along modulefile on avail and list sub-commands
626 (see Module tags section in module(1)). Tag information can be
627 queried during modulefile evaluation with the module-info tags
628 modulefile command. module-tag commands should be placed in one
629 of the modulecmd.tcl rc files.
630 module-tag command accepts the following options:
632 • --not-user {user...}
634 • --not-group {group...}
636 If --not-user option is set, the tag is not applied if the user‐
638 name of the user currently running modulecmd.tcl is part of the
639 list of username specified. Following the same approach, if
640 --not-group option is set, the tag is not applied if current
641 user is member of one the group specified. When both options are
642 set, the tag is not applied if a match is found for --not-user
643 or --not-group.
644 The parameter modulefile may also be a symbolic modulefile name
646 or a modulefile alias. It may also leverage a specific syntax to
647 finely select module version (see Advanced module version speci‐
648 fiers section below).
649 Tags inherited from other modulefile commands or module states
651 cannot be set with module-tag. Otherwise an error is returned.
652 Those special tags are: auto-loaded, forbidden, hidden, hid‐
653 den-loaded, loaded and nearly-forbidden.
654 When tag equals sticky or super-sticky, designated modulefile is
656 defined Sticky modules.
657 When tag equals keep-loaded, designated modulefile is not auto‐
659 matically unloaded when it has been auto-loaded and its depen‐
660 dent modules are getting unloaded.
661 module-version modulefile version-name...
663 Assigns the symbolic version-name to the modulefile. This com‐
664 mand should be placed in one of the modulecmd.tcl rc files in
665 order to provide shorthand invocations of frequently used mod‐
666 ulefile names.
667 The special version-name default specifies the default version
669 to be used for module commands, if no specific version is given.
670 This replaces the definitions made in the .version file in for‐
671 mer modulecmd.tcl releases.
672 The parameter modulefile may be either
674 • a fully or partially qualified modulefile with name / version.
676 If name is . (dot) then the current directory name is assumed
677 to be the module name. (Use this for deep modulefile directo‐
678 ries.)
679 • a symbolic modulefile name
681 • another modulefile alias
683 module-virtual name modulefile
685 Assigns the modulefile to the virtual module name. This command
686 should be placed in rc files in order to define virtual modules.
687 A virtual module stands for a module name associated to a mod‐
689 ulefile. The modulefile is the script interpreted when loading
690 or unloading the virtual module which appears or can be found
691 with its virtual name.
692 The parameter modulefile corresponds to the relative or absolute
694 file location of a modulefile.
695 module-whatis string
697 Defines a string which is displayed in case of the invocation of
698 the module whatis command. There may be more than one
699 module-whatis line in a modulefile. This command takes no ac‐
700 tions in case of load, display, etc. invocations of mod‐
701 ulecmd.tcl.
702 The string parameter has to be enclosed in double-quotes if
704 there's more than one word specified. Words are defined to be
705 separated by whitespace characters (space, tab, cr).
706 prepend-path [-d C|--delim C|--delim=C] [--duplicates] variable
708 value...
709 Append or prepend value to environment variable. The variable is
710 a colon, or delimiter, separated list such as PATH=directory:di‐
711 rectory:directory. The default delimiter is a colon :, but an
712 arbitrary one can be given by the --delim option. For example a
713 space can be used instead (which will need to be handled in the
714 Tcl specially by enclosing it in " " or { }). A space, however,
715 can not be specified by the --delim=C form.
716 A reference counter environment variable is also set to know the
718 number of times value has been added to environment variable
719 when it is added more than one time. This reference counter en‐
720 vironment variable is named by prefixing variable by __MOD‐
721 ULES_SHARE_.
722 When value is already defined in environment variable, it is not
724 added again or moved at the end or at the beginning of variable.
725 Exception is made when the --duplicates option is set in which
726 case value is added again to variable.
727 If the variable is not set, it is created. When a modulefile is
729 unloaded, append-path and prepend-path become remove-path.
730 If value corresponds to the concatenation of multiple elements
732 separated by colon, or delimiter, character, each element is
733 treated separately.
734 prereq [--tag taglist] modulefile...
736 prereq controls whether or not the modulefile will be loaded.
737 The prereq command lists modulefiles which must have been previ‐
738 ously loaded before the current modulefile will be loaded. If a
739 list contains more than one modulefile, then each member of the
740 list acts as a Boolean OR operation. Multiple prereq commands
741 may be used to create a Boolean AND operation. If one of the re‐
742 quirements have not been satisfied, an error is reported and the
743 current modulefile makes no changes to the user's environment.
744 If an argument for prereq is a directory and any modulefile from
746 the directory has been loaded, then the prerequisite is met. For
747 example, specifying X11 as a prereq means that any version of
748 X11, X11/R4 or X11/R5, must be loaded before proceeding.
749 The parameter modulefile may also be a symbolic modulefile name
751 or a modulefile alias. It may also leverage a specific syntax to
752 finely select module version (see Advanced module version speci‐
753 fiers section below).
754 If the auto_handling configuration option is enabled prereq will
756 attempt to load specified modulefile if not found loaded yet
757 (see MODULES_AUTO_HANDLING in module(1)).
758 The --tag option accepts a list of module tags to apply to mod‐
760 ulefile once loaded. taglist corresponds to the concatenation of
761 multiple tags separated by colon character. taglist should not
762 contain tags inherited from modulefile state or from other mod‐
763 ulefile commands. If module is already loaded, tags from taglist
764 are added to the list of tags already applied to this module.
765 prereq-all [--tag taglist] modulefile...
767 Declare modulefile as a requirement of currently loading module.
768 This command acts as an alias of prereq command. If more than
769 one modulefile are specified, then this list acts as a Boolean
770 AND operation, which means all specified modulefiles are re‐
771 quired.
772 prereq-any [--tag taglist] modulefile...
774 Alias of prereq command.
775 pushenv variable value
777 Set environment variable to value and save previous value of
778 variable to restore it when modulefile is unloaded. Like for
779 setenv modulefile command, changes made to variable with pushenv
780 are applied to variable in Tcl's env array to update environment
781 variable value in current evaluation context.
782 When modulefile is unloaded, the value saved from the pushenv
784 command of this modulefile is removed from saved value stack
785 list. variable is then set to the remaining value on top of the
786 stack or it is unset if stack becomes empty.
787 Saved value stack list for variable is stored in an environment
789 variable which is named by prefixing variable by __MOD‐
790 ULES_PUSHENV_.
791 puts [-nonewline] [channelId] string
793 Writes the characters given by string to the channel given by
794 channelId. This command is not a Modules-specific command, it
795 is actually part of Tcl. See the puts(n) Tcl man page for a
796 complete description of this command.
797 Content written to the stderr channel is rendered as output mes‐
799 sage produced by modulefile. Content written to the stdout chan‐
800 nel is rendered as shell command evaluated in the user current
801 shell environment. Content sent to stdout is spooled to be ren‐
802 dered after the environment changes made by modulefile.
803 When channelId equals prestdout, content is rendered as shell
805 command evaluated in current shell environment. This content is
806 spooled and rendered prior any other environment changes.
807 remove-path [options] variable value... [--append-on-un‐
809 load|--prepend-on-unload value...]
810 Remove value from the colon, or delimiter, separated list in
811 variable.
812 remove-path command accepts the following options:
814 • -d C|--delim C|--delim=C
816 • --index
818 • --remove-on-unload|--noop-on-unload|--append-on-un‐
820 load|--prepend-on-unload
821 See prepend-path or append-path for further explanation of using
823 an arbitrary delimiter. Every string between colons, or delim‐
824 iters, in variable is compared to value. If the two match, value
825 is removed from variable if its reference counter is equal to 1
826 or unknown.
827 When --index option is set, value refers to an index in variable
829 list. The string element pointed by this index is set for re‐
830 moval.
831 When modulefile is unloaded, no operation is performed by de‐
833 fault or if the --noop-on-unload option is set. If the --re‐
834 move-on-unload option is set, value is removed. If the --ap‐
835 pend-on-unload option is set, append back value removed at load
836 time or specific value if any set. If the --prepend-on-unload
837 option is set, prepend back value removed at load time or spe‐
838 cific value if any set. These options cannot be set if --index
839 option is also set.
840 Reference counter of value in variable denotes the number of
842 times value has been added to variable. This information is
843 stored in environment __MODULES_SHARE_variable. When attempting
844 to remove value from variable, relative reference counter is
845 checked and value is removed only if counter is equal to 1 or
846 not defined. Otherwise value is kept in variable and reference
847 counter is decreased by 1. If counter equals 1 after being de‐
848 creased, value and its counter are removed from reference
849 counter variable.
850 If value corresponds to the concatenation of multiple elements
852 separated by colon, or delimiter, character, each element is
853 treated separately.
854 reportError string
856 Output string as an error message during modulefile evaluation
857 and raise error count. reportError does not abort modulefile
858 evaluation. Use the error(n) Tcl command to abort evaluation in
859 addition to emit an error message.
860 reportWarning string
862 Output string as a warning message during modulefile evaluation.
863 require-fullname
865 Abort load evaluation of modulefile if name specified to desig‐
866 nate it is not the fully qualified one. Module alias or a sym‐
867 bolic version names are considered fully qualified names, excep‐
868 tion made for the default symbol.
869 set-alias alias-name alias-string
871 Sets an alias or function with the name alias-name in the user's
872 environment to the string alias-string. For some shells, aliases
873 are not possible and the command has no effect. When a module‐
874 file is unloaded, set-alias becomes unset-alias.
875 set-function function-name function-string
877 Creates a function with the name function-name in the user's en‐
878 vironment with the function body function-string. For some
879 shells, functions are not possible and the command has no ef‐
880 fect. When a modulefile is unloaded, set-function becomes
881 unset-function.
882 setenv [--set-if-undef] variable value
884 Set environment variable to value. The setenv command will also
885 change the process' environment. A reference using Tcl's env as‐
886 sociative array will reference changes made with the setenv com‐
887 mand. Changes made using Tcl's env associative array will NOT
888 change the user's environment variable like the setenv command.
889 An environment change made this way will only affect the module
890 parsing process. The setenv command is also useful for changing
891 the environment prior to the exec or system command. When a mod‐
892 ulefile is unloaded, setenv becomes unsetenv. If the environment
893 variable had been defined it will be overwritten while loading
894 the modulefile. A subsequent unload will unset the environment
895 variable - the previous value cannot be restored! (Unless you
896 handle it explicitly or if you use the pushenv modulefile com‐
897 mand instead of setenv)
898 When the --set-if-undef option is set, environment variable is
900 defined when modulefile is loaded only if not yet defined.
901 source-sh shell script [arg...]
903 Evaluate with shell the designated script with defined arguments
904 to find out the environment changes it does. Those changes ob‐
905 tained by comparing environment prior and after script evalua‐
906 tion are then translated into corresponding modulefile commands,
907 which are then applied during modulefile evaluation as if they
908 were directly written in it.
909 When modulefile is unloaded, environment changes done are re‐
911 served by evaluating in the unload context the resulting module‐
912 file commands, which were recorded in the __MODULES_LMSOURCESH
913 environment variable at load time.
914 Changes on environment variables, shell aliases, shell func‐
916 tions, shell completions and current working directory are
917 tracked.
918 Changes made on environment variable intended for Modules pri‐
920 vate use (e.g., LOADEDMODULES, _LMFILES_, __MODULES_*) are ig‐
921 nored.
922 Shell could be specified as a command name or a fully qualified
924 pathname. The following shells are supported: sh, dash, csh,
925 tcsh, bash, ksh, ksh93, zsh and fish.
926 system string
928 Run string command through shell. On Unix, command is passed to
929 the /bin/sh shell whereas on Windows it is passed to cmd.exe.
930 modulecmd.tcl redirects stdout to stderr since stdout would be
931 parsed by the evaluating shell. The exit status of the executed
932 command is returned.
933 uname field
935 Provide lookup of system information. Most field information are
936 retrieved from the tcl_platform array (see the tclvars(n) man
937 page). Uname will return the string unknown if information is
938 unavailable for the field.
939 uname will invoke the uname(1) command in order to get the oper‐
941 ating system version and domainname(1) to figure out the name of
942 the domain.
943 field values are:
945 • sysname: the operating system name
947 • nodename: the hostname
949 • domain: the name of the domain
951 • release: the operating system release
953 • version: the operating system version
955 • machine: a standard name that identifies the system's hardware
957 uncomplete name
959 Unsets completion for command name in the user's environment.
960 When a modulefile is unloaded, no operation is performed.
961 The following shells are supported: bash, tcsh and fish.
963 unset-alias alias-name
965 Unsets an alias with the name alias-name in the user's environ‐
966 ment.
967 unset-function function-name
969 Removes a function with the name function-name from the user's
970 environment.
971 unsetenv [options] variable [value]
973 Unsets environment variable. When a modulefile is unloaded, no
974 operation is performed unless if an optional value is defined,
975 in which case variable is to value. The unsetenv command changes
976 the process' environment like setenv.
977 If the --noop-on-unload option is set, no operation is performed
979 when modulefile is unloaded. If the --unset-on-unload option is
980 set, environment variable is also unset when modulefile is un‐
981 loaded. These behaviors are applied even if an optional value is
982 defined.
983 variant [--boolean] [--default value] name [value...]
985 Declare module variant name with list of accepted value and in‐
986 stantiate it in the ModuleVariant array variable.
987 Variant's value is selected through the module designation that
989 leads to the modulefile evaluation. See Advanced module version
990 specifiers section to learn how variants could be specified.
991 Selected variant value is transmitted to the evaluating module‐
993 file. A value must be specified for variant name and it must
994 corresponds to a value in the accepted value list if such list
995 is defined. Otherwise an error is raised. An exception is made
996 if modulefile is evaluated in display mode: no error is raised
997 if no value is specified for a given variant and variant is not
998 instantiated in the ModuleVariant array variable. When no list
999 of accepted value is defined, variant could be set to any value.
1000 When the --default option is set, variant name is set to the
1002 value associated with this option in case no value is specified
1003 for variant in module designation.
1004 If the --boolean option is set, variant name is defined as a
1006 Boolean variant. No list of accepted value should be defined in
1007 this case. All values recognized as Boolean value in Tcl are ac‐
1008 cepted (i.e., 1, true, t, yes, y, on, 0, false, f, no, n or
1009 off). Boolean variants are instantiated in ModuleVariant using
1010 Tcl canonical form of Boolean value (i.e., 0 or 1).
1011 A variant which is not defined as a Boolean variant cannot de‐
1013 fine Boolean values in its accepted value list, exception made
1014 for the 0 and 1 integers. An error is raised otherwise.
1015 A variant cannot be named version. An error is raised otherwise.
1017 versioncmp version1 version2
1019 Compare version string version1 against version string version2.
1020 Returns -1, 0 or 1 respectively if version1 is less than, equal
1021 to or greater than version2.
1022 x-resource [resource-string|filename]
1024 Merge resources into the X11 resource database. The resources
1025 are used to control look and behavior of X11 applications. The
1026 command will attempt to read resources from filename. If the ar‐
1027 gument isn't a valid file name, then string will be interpreted
1028 as a resource. Either filename or resource-string is then passed
1029 down to be xrdb(1) command.
1030 modulefiles that use this command, should in most cases contain
1032 one or more x-resource lines, each defining one X11 resource.
1033 The DISPLAY environment variable should be properly set and the
1034 X11 server should be accessible. If x-resource can't manipulate
1035 the X11 resource database, the modulefile will exit with an er‐
1036 ror message.
1037 Examples:
1039 x-resource /u2/staff/leif/.xres/Ileaf
1041 The content of the Ileaf file is merged into the X11 resource
1042 database.
1043 x-resource [glob ~/.xres/ileaf]
1045 The Tcl glob function is used to have the modulefile read
1046 different resource files for different users.
1047 x-resource {Ileaf.popup.saveUnder: True}
1049 Merge the Ileaf resource into the X11 resource database.
1050 Modulefiles and run-command (rc) files are differently interpreted. A
1052 limited number of the Modules specific Tcl commands are available for
1053 rc files interpretation since such files are intended to set parameters
1054 for modulefiles (like defining alias, hiding, tagging, etc) and not to
1055 change user environment. The following table summarizes the different
1056 commands available for each interpretation context.
1057 ┌───────────────────────────┬────────────────────────────┐
1059 │Commands available from │ Commands available from │
1060 │modulefile interpretation │ run-command (rc) file in‐ │
1061 │ │ terpretation │
1062 ├───────────────────────────┼────────────────────────────┤
1063 │All the Modules specific │ is-loaded, is-used, │
1064 │and standard Tcl commands │ module-alias, │
1065 │ │ module-forbid, │
1066 │ │ module-hide, module-info, │
1067 │ │ module-tag, │
1068 │ │ module-version, │
1069 │ │ module-virtual, system, │
1070 │ │ uname, versioncmp and │
1071 │ │ standard Tcl commands │
1072 └───────────────────────────┴────────────────────────────┘
1073 NOTE:
1075 Global and user run-command files are interpreted like modulefiles
1076 and benefit from all Modules specific Tcl commands. However it not
1077 advised to perform environment changes from such files.
1078
1080 ModulesCurrentModulefile
1081 The ModulesCurrentModulefile variable contains the full pathname
1082 of the modulefile being interpreted.
1083 ModulesVersion
1085 The ModulesVersion variable can be set in .version file to des‐
1086 ignate the name of the modulefile version which should be con‐
1087 sidered as default in current directory (see Locating Module‐
1088 files section below).
1089 ModuleTool
1091 The ModuleTool variable contains the name of the module imple‐
1092 mentation currently in use. The value of this variable is set to
1093 Modules for this implementation.
1094 ModuleToolVersion
1096 The ModuleToolVersion variable contains the version of the mod‐
1097 ule implementation currently in use. The value of this variable
1098 is set to 5.1.1 for this version of Modules.
1099 ModuleVariant
1101 The ModuleVariant array variable contains an element entry for
1102 each defined variant associated to the value of this variant
1103 (e.g., the $ModuleVariant(foo) syntax corresponds to the value
1104 of variant foo if defined). A Tcl evaluation error is obtained
1105 when accessing an undefined variant in ModuleVariant array. Use
1106 preferably the getvariant command to retrieve a variant value
1107 when this variant state is not known.
1108 The list of the currently defined variants can be retrieved with
1110 [array names ModuleVariant] Tcl code.
1111
1113 Every directory in MODULEPATH is searched to find the modulefile. A di‐
1114 rectory in MODULEPATH can have an arbitrary number of sub-directories.
1115 If the user names a modulefile to be loaded which is actually a direc‐
1116 tory, the directory is opened and a search begins for an actual module‐
1117 file. First, modulecmd.tcl looks for a file with the name .modulerc in
1118 the directory. If this file exists, its contents will be evaluated as
1119 if it was a modulefile to be loaded. You may place module-version,
1120 module-alias and module-virtual commands inside this file.
1121 Additionally, before seeking for .modulerc files in the module direc‐
1123 tory, the global modulerc file and the .modulerc file found at the root
1124 of the modulepath directory are sourced, too. If a named version de‐
1125 fault now exists for the modulefile to be loaded, the assigned module‐
1126 file now will be sourced. Otherwise the file .version is looked up in
1127 the module directory.
1128 If the .version file exists, it is opened and interpreted as Tcl code
1130 and takes precedence over a .modulerc file in the same directory. If
1131 the Tcl variable ModulesVersion is set by the .version file, mod‐
1132 ulecmd.tcl will use the name as if it specifies a modulefile in this
1133 directory. This will become the default modulefile in this case.
1134 ModulesVersion cannot refer to a modulefile located in a different di‐
1135 rectory.
1136 If ModulesVersion is a directory, the search begins anew down that di‐
1138 rectory. If the name does not match any files located in the current
1139 directory, the search continues through the remaining directories in
1140 MODULEPATH.
1141 Every .version and .modulerc file found is interpreted as Tcl code. The
1143 difference is that .version only applies to the current directory, and
1144 the .modulerc applies to the current directory and all subdirectories.
1145 Changes made in these files will affect the subsequently interpreted
1146 modulefile.
1147 If no default version may be figured out, an implicit default is se‐
1149 lected when this behavior is enabled (see MODULES_IMPLICIT_DEFAULT in
1150 module(1)). If disabled, module names should be fully qualified when no
1151 explicit default is defined for them, otherwise no default version is
1152 found and an error is returned. If enabled, then the highest numeri‐
1153 cally sorted modulefile, virtual module or module alias under the di‐
1154 rectory will be used. The dictionary comparison method of the lsort(n)
1155 Tcl command is used to achieve this sort. If highest numerically sorted
1156 element is an alias, search continues on its modulefile target.
1157 For example, it is possible for a user to have a directory named X11
1159 which simply contains a .version file specifying which version of X11
1160 is to be loaded. Such a file would look like:
1161 #%Module1.0
1163 ##
1164 ## The desired version of X11
1165 ##
1166 set ModulesVersion "R4"
1167 The equivalent .modulerc would look like:
1169 #%Module1.0
1171 ##
1172 ## The desired version of X11
1173 ##
1174 module-version "./R4" default
1175 If the extended default mechanism is enabled (see MODULES_EXTENDED_DE‐
1177 FAULT in module(1)) the module version specified is matched against
1178 starting portion of existing module versions, where portion is a sub‐
1179 string separated from the rest of version string by a . character.
1180 When the implicit default mechanism and the Advanced module version
1182 specifiers are both enabled, a default and latest symbolic versions are
1183 automatically defined for each module name (also at each directory
1184 level in case of deep modulefile). Unless a symbolic version, alias, or
1185 regular module version already exists for these version names.
1186 Every file in searched directories is checked to see if it begins with
1188 the Modules magic cookie (i.e., #%Module file signature) to determine
1189 if it is a modulefile (see DESCRIPTION section). When the mcookie_check
1190 configuration is set to eval, this check is skipped and all files in
1191 search directories are considered modulefiles.
1192 If user names a modulefile that cannot be found in the first modulepath
1194 directory, modulefile will be searched in next modulepath directory and
1195 so on until a matching modulefile is found. If search goes through a
1196 module alias or a symbolic version, this alias or symbol is resolved by
1197 first looking at the modulefiles in the modulepath where this alias or
1198 symbol is defined. If not found, resolution looks at the other mod‐
1199 ulepaths in their definition order.
1200 When locating modulefiles, if a .modulerc, a .version, a directory or a
1202 modulefile cannot be read during the search it is simply ignored with
1203 no error message produced. Visibility of modulefiles can thus be
1204 adapted to the rights the user has been granted. Exception is made when
1205 trying to directly access a directory or a modulefile. In this case,
1206 the access issue is returned as an error message.
1207 Depending on their name, their file permissions or the use of specific
1209 modulefile commands, modulefile, virtual module, module alias or sym‐
1210 bolic version may be set hidden which impacts available modules search
1211 or module selection processes (see Hiding modulefiles section below).
1212
1214 A modulefile, virtual module, module alias or symbolic version whose
1215 name or element in their name starts with a dot character (.) or who
1216 are targeted by a module-hide command are considered hidden. Hidden
1217 modules are not displayed or taken into account except if they are ex‐
1218 plicitly named (e.g., foo/1.2.3 or foo/.2.0 not foo). If module has
1219 been hidden with the --soft option of the module-hide command set, it
1220 is not considered hidden if the root name of the query to search it
1221 matches module root name (e.g., searching foo will return a foo/1.2.3
1222 modulefile targeted by a module-hide --soft command). If module has
1223 been hidden with the --hard option of the module-hide command set, it
1224 is always considered hidden thus it is never displayed nor taken into
1225 account even if it is explicitly named.
1226 A modulefile, virtual module, module alias or symbolic version who are
1228 targeted by a module-hide --hard command and a module-forbid command or
1229 whose file access permissions are restricted are considered hard-hidden
1230 and forbidden. Such modules are not displayed or taken into account.
1231 When explicitly named for evaluation selection, such modules are un‐
1232 veiled to return an access error.
1233 NOTE:
1235 When the mcookie_check configuration is set to eval, file access
1236 permissions are not checked thus files with restricted permissions
1237 are included in search results but still lead to error if evaluated.
1238 A symbolic version-name assigned to a hidden module is displayed or
1240 taken into account only if explicitly named and if module is not
1241 hard-hidden. Non-hidden module alias targeting a hidden modulefile ap‐
1242 pears like any other non-hidden module alias. Finally, a hidden sym‐
1243 bolic version targeting a non-hidden module is displayed or taken into
1244 account only if not hard-hidden and explicitly named to refer to its
1245 non-hidden target.
1246 The automatic version symbols (e.g., default and latest) are unaffected
1248 by hiding. Moreover when a regular default or latest version is set
1249 hidden, the corresponding automatic version symbol takes the left spot.
1250 For instance, if foo/default which targets foo/1.2.3 is set hard-hid‐
1251 den, the default automatic version symbol will be set onto foo/2.1.3,
1252 the highest available version of foo.
1253 When loading a modulefile or a virtual module targeted by a module-hide
1255 --hidden-loaded command, this module inherits the hidden-loaded tag.
1256 Hidden loaded modules are not reported among list sub-command results.
1257 If the --all is set on avail, aliases, whatis or search sub-commands,
1259 hidden modules are taken into account in search. Hard-hidden modules
1260 are unaffected by this option.
1261 If the --all is set on list sub-command, hidden loaded modules are in‐
1263 cluded in result output.
1264
1266 When the advanced module version specifiers mechanism is enabled (see
1267 MODULES_ADVANCED_VERSION_SPEC in module(1)), the specification of mod‐
1268 ulefile passed on Modules specific Tcl commands changes. After the
1269 module name a version constraint and variants may be added.
1270 Version specifiers
1272 After the module name a version constraint prefixed by the @ character
1273 may be added. It could be directly appended to the module name or sepa‐
1274 rated from it with a space character.
1275 Constraints can be expressed to refine the selection of module version
1277 to:
1278 • a single version with the @version syntax, for instance foo@1.2.3
1280 syntax will select module foo/1.2.3
1281 • a list of versions with the @version1,version2,... syntax, for in‐
1283 stance foo@1.2.3,1.10 will match modules foo/1.2.3 and foo/1.10
1284 • a range of versions with the @version1:, @:version2 and @ver‐
1286 sion1:version2 syntaxes, for instance foo@1.2: will select all ver‐
1287 sions of module foo greater than or equal to 1.2, foo@:1.3 will se‐
1288 lect all versions less than or equal to 1.3 and foo@1.2:1.3 matches
1289 all versions between 1.2 and 1.3 including 1.2 and 1.3 versions
1290 Advanced specification of single version or list of versions may bene‐
1292 fit from the activation of the extended default mechanism (see MOD‐
1293 ULES_EXTENDED_DEFAULT in module(1)) to use an abbreviated notation like
1294 @1 to refer to more precise version numbers like 1.2.3. Range of ver‐
1295 sions on its side natively handles abbreviated versions.
1296 In order to be specified in a range of versions or compared to a range
1298 of versions, the version major element should corresponds to a number.
1299 For instance 10a, 1.2.3, 1.foo are versions valid for range comparison
1300 whereas default or foo.2 versions are invalid for range comparison.
1301 Range of versions can be specified in version list, for instance
1303 foo@:1.2,1.4:1.6,1.8:. Such specification helps to exclude specific
1304 versions, like versions 1.3 and 1.7 in previous example.
1305 If the implicit default mechanism is also enabled (see MODULES_IM‐
1307 PLICIT_DEFAULT in module(1)), a default and latest symbolic versions
1308 are automatically defined for each module name (also at each directory
1309 level for deep modulefiles). These automatic version symbols are de‐
1310 fined unless a symbolic version, alias, or regular module version al‐
1311 ready exists for these default or latest version names. Using the
1312 mod@latest (or mod/latest) syntax ensures highest available version
1313 will be selected.
1314 Variants
1316 After the module name, variants can be specified. Module variants are
1317 alternative evaluation of the same modulefile. A variant is specified
1318 by associating a value to its name. This specification is then trans‐
1319 mitted to the evaluating modulefile which instantiates the variant in
1320 the ModuleVariant array variable when reaching the variant modulefile
1321 command declaring this variant.
1322 Variant can be specified with the name=value syntax where name is the
1324 declared variant name and value, the value this variant is set to when
1325 evaluating the modulefile.
1326 Boolean variants can be specified with the +name syntax to set this
1328 variant on and with the -name or ~name syntaxes to set this variant
1329 off. The -name syntax is not supported on ml(1) command as the minus
1330 sign already means to unload designated module. The ~name and +name
1331 syntaxes could also be defined appended to another specification word
1332 (e.g., the module name, version or another variant specification),
1333 whereas -name syntax must be the start of a new specification word.
1334 Boolean variants may also be specified with the name=value syntax.
1336 value should be set to 1, true, t, yes, y or on to enable the variant
1337 or it should be set to 0, false, f, no, n or off to disable the vari‐
1338 ant.
1339 Shortcuts may be used to abbreviate variant specification. The vari‐
1341 ant_shortcut configuration option associates shortcut character to
1342 variant name. With a shortcut defined, variant could be specified with
1343 the <shortcut>value syntax. For instance if character % is set as a
1344 shortcut for variant foo, the %value syntax is equivalent to the
1345 foo=value syntax.
1346 Specific characters used in variant specification syntax cannot be used
1348 as part of the name of a module. These specific characters are +, ~, =
1349 and all characters set as variant shortcut. Exception is made for +
1350 character which could be set one or several consecutive times at the
1351 end of module name (e.g., name+ or name++).
1352
1354 A modulefile may express dependencies on other modulefiles. Two kind of
1355 dependency exist: pre-requirement and conflict. The former means speci‐
1356 fied modulefiles should be loaded prior the modulefile that express the
1357 requirement. The latter means specified modulefiles should not be
1358 loaded for the modulefile that express the conflict to be loaded too.
1359 Pre-requirement could be expressed with prereq, prereq-any, prereq-all,
1361 depends-on, always-load, module load, module switch, module try-load or
1362 module load-any modulefile commands. When the auto_handling configura‐
1363 tion option is disabled, required modulefile should be manually loaded
1364 prior their dependent modulefile when expressed with the prereq,
1365 prereq-any, prereq-all or depends-on modulefile commands. For other
1366 commands or when auto_handling is enabled, pre-required modulefiles are
1367 automatically loaded.
1368 Conflict is expressed with conflict or module unload modulefile com‐
1370 mands. A conflicting loaded modulefile should be manually unloaded
1371 prior loading the modulefile that express such conflict when defined
1372 with conflict. It is automatically unloaded when expressed with module
1373 unload.
1374 It is strongly advised to define dependencies prior environment changes
1376 in a modulefile. Dependency resolution should be done before any envi‐
1377 ronment change to ensure the environment is getting set in the same or‐
1378 der whether pre-requirements are already loaded, or if they are auto‐
1379 matically loaded when loading the modulefile which depends on them, or
1380 if all loaded modules are reloaded or refreshed. This is especially im‐
1381 portant when the modulefile updates an environment variable also al‐
1382 tered by other modulefiles like PATH. As the order of the path elements
1383 in such variable defines priority, it is important that this order does
1384 not change depending on the way the modulefiles are loaded.
1385 module keeps environment consistent which means a modulefile cannot be
1387 loaded if its requirements are not loaded or if a conflicting module is
1388 loaded. In addition a loaded module cannot be unloaded if other loaded
1389 modules depends on it. The automated module handling mechanisms attempt
1390 to solve the dependencies expressed by loading or unloading additional
1391 modulefiles. When the --no-auto option is set on module command when
1392 loading or unload modulefile, automated module handling mechanisms are
1393 disabled and dependencies have to be solved manually. When dependencies
1394 are not satisfied, modulefile fails to load or unload.
1395 Adding the --not-req option when expressing dependencies in modulefile
1397 with the module command will attempt to load or unload the designated
1398 modulefile but it will not mark them as pre-requirement or conflict.
1399 By adding the --force option to the module command when loading or un‐
1401 loading modulefile, the consistency checks are by-passed. This option
1402 cannot be used when expressing dependencies in modulefiles. If a module
1403 has been force loaded whereas its requirements are not loaded or
1404 whereas a conflicting module is also loaded, the user environment is
1405 said inconsistent.
1406 Note that a pre-requirement should be found in the loaded module list
1408 prior its dependent module. User environment is considered inconsistent
1409 if pre-requirement module is found loaded after dependent module, as
1410 the environment changes may have been done in the wrong priority order.
1411 When user environment is considered inconsistent global operations
1413 achieved by refresh, reload and save sub-commands cannot perform. This
1414 mechanism is there to avoid the situation to worsen by re-evaluating
1415 all loaded modules or recording this environment.
1416 When the auto_handling configuration option is enabled, if missing
1418 pre-requirement modulefile gets loaded or conflicting modulefile gets
1419 unloaded the inconsistent loaded module will be automatically reloaded
1420 to make user environment consistent again.
1421
1423 Users can request help about a specific modulefile through the mod‐
1424 ule(1) command. The modulefile can print helpful information or start
1425 help oriented programs by defining a ModulesHelp subroutine. The sub‐
1426 routine will be called when the module help modulefile command is used.
1427
1429 Users can request test of a specific modulefile through the module(1)
1430 command. The modulefile can perform some sanity checks on its defini‐
1431 tion or on its underlying programs by defining a ModulesTest subrou‐
1432 tine. The subroutine will be called when the module test modulefile
1433 command is used. The subroutine should return 1 in case of success. If
1434 no or any other value is returned, test is considered failed.
1435
1437 The module display modulefile command will detail all changes that will
1438 be made to the environment. After displaying all of the environment
1439 changes modulecmd.tcl will call the ModulesDisplay subroutine. The Mod‐
1440 ulesDisplay subroutine is a good place to put additional descriptive
1441 information about the modulefile.
1442
1444 The modulecmd.tcl program supports Tcl modulefile written for Lmod, the
1445 alternative module implementation developed in Lua. Such modulefiles
1446 can be evaluated by Modules without raising error. Differences between
1447 the two implementations are listed below.
1448 The add-property, remove-property and extensions modulefile commands
1450 are evaluated as a no-operation command. No error is obtained if these
1451 commands are used in modulefiles but no change occurs.
1452 The break command does not accept any argument. A msg argument can be
1454 set on Lmod to provide a customized break error message.
1455 Use of reportError command aborts modulefile evaluation on Lmod. This
1457 command only reports an error message on Modules.
1458 The require-fullname command only aborts load modulefile evaluation
1460 whereas the Lmod implementation also aborts unload and display evalua‐
1461 tions.
1462 When processing a family command, the LMOD_FAMILY_<NAME> environment
1464 variable is also defined to be compatible with modulefiles or scripts
1465 relying on such variable.
1466 When unloading a modulefile, the pushenv command does not update the
1468 value of the environment variable if this modulefile was not defining
1469 the value currently in use.
1470 The third optional argument of append-path and prepend-path commands
1472 corresponds to a priority specification on Lmod whereas these two com‐
1473 mands accept multiple path element arguments on Modules.
1474 The prereq command is equivalent to the prereq-any command on Modules
1476 whereas on Lmod it is equivalent to the prereq-all command.
1477 If the auto_handling configuration option is disabled, the requirements
1479 defined with the depends-on command are not automatically loaded and an
1480 error is raised if none of these requirements are found loaded.
1481 On module load-any sub-command and modulefile command, a modulefile
1483 evaluation error is not reported and module load-any continues to the
1484 next modulefile instead of aborting the whole process. No attempt to
1485 load listed modulefiles is made if one of these modulefiles is found
1486 already loaded.
1487
1489 See the ENVIRONMENT section in the module(1) man page.
1490
1492 module(1), ml(1), Tcl(n), TclX(n), id(1), xrdb(1), exec(n), uname(1),
1493 domainname(1), tclvars(n), lsort(n)
1494
1496 Tcl was developed by John Ousterhout at the University of California at
1497 Berkeley.
1498 TclX was developed by Karl Lehenbauer and Mark Diekhans.
1500
1502 1996-1999 John L. Furlani & Peter W. Osel, 1998-2017 R.K.Owen,
1503 2002-2004 Mark Lakata, 2004-2017 Kent Mein, 2016-2022 Xavier Delaruelle
15045.1.1 2022-05-31 MODULEFILE(4)