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 magic cookie, #%Module. A version number
16 may be placed after this string. The version number is useful as the
17 modulefile format may change thus it reflects the minimum version of
18 modulecmd.tcl required to interpret the modulefile. If a version number
19 doesn't exist, then modulecmd.tcl will assume the modulefile is compat‐
20 ible. Files without the magic cookie or with a version number greater
21 than the current version of modulecmd.tcl will not be interpreted. If
22 the mcookie_version_check configuration is disabled the version number
23 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 append-path [-d C|--delim C|--delim=C] [--duplicates] variable value...
65 See prepend-path.
66 break This is not a Modules-specific command, it's actually part of
68 Tcl, which has been overloaded similar to the continue and exit
69 commands to have the effect of causing the module not to be
70 listed as loaded and not affect other modules being loaded con‐
71 currently. All non-environment commands within the module will
72 be performed up to this point and processing will continue on to
73 the next module on the command line. The break command will only
74 have this effect if not used within a Tcl loop though.
75 An example: Suppose that a full selection of modulefiles are
77 needed for various different architectures, but some of the mod‐
78 ulefiles are not needed and the user should be alerted. Having
79 the unnecessary modulefile be a link to the following notavail
80 modulefile will perform the task as required.
81 #%Module1.0
83 ## notavail modulefile
84 ##
85 proc ModulesHelp { } {
86 puts stderr "This module does nothing but alert the user"
87 puts stderr "that the [module-info name] module is not available"
88 }
89 module-whatis "Notifies user that module is not available."
91 set curMod [module-info name]
92 if { [ module-info mode load ] } {
93 puts stderr "Note: '$curMod' is not available for [uname sysname]."
94 }
95 break
96 chdir directory
98 Set the current working directory to directory.
99 conflict modulefile...
101 prereq and conflict control whether or not the modulefile will
102 be loaded. The prereq command lists modulefiles which must have
103 been previously loaded before the current modulefile will be
104 loaded. Similarly, the conflict command lists modulefiles which
105 conflict with the current modulefile. If a list contains more
106 than one modulefile, then each member of the list acts as a
107 Boolean OR operation. Multiple prereq and conflict commands may
108 be used to create a Boolean AND operation. If one of the re‐
109 quirements have not been satisfied, an error is reported and the
110 current modulefile makes no changes to the user's environment.
111 If an argument for prereq is a directory and any modulefile from
113 the directory has been loaded, then the prerequisite is met. For
114 example, specifying X11 as a prereq means that any version of
115 X11, X11/R4 or X11/R5, must be loaded before proceeding.
116 If an argument for conflict is a directory and any other module‐
118 file from that directory has been loaded, then a conflict will
119 occur. For example, specifying X11 as a conflict will stop
120 X11/R4 and X11/R5 from being loaded at the same time.
121 The parameter modulefile may also be a symbolic modulefile name
123 or a modulefile alias. It may also leverage a specific syntax to
124 finely select module version (see Advanced module version speci‐
125 fiers section below).
126 continue
128 This is not a modules specific command but another overloaded
129 Tcl command and is similar to the break or exit commands except
130 the module will be listed as loaded as well as performing any
131 environment or Tcl commands up to this point and then continuing
132 on to the next module on the command line. The continue command
133 will only have this effect if not used within a Tcl loop though.
134 exit [N]
136 This is not a modules specific command but another overloaded
137 Tcl command and is similar to the break or continue commands.
138 However, this command will cause the immediate cessation of this
139 module and any additional ones on the command line. This module
140 and the subsequent modules will not be listed as loaded. No en‐
141 vironment commands will be performed in the current module.
142 getenv variable [value]
144 Returns value of environment variable. If variable is not de‐
145 fined, value is returned if set, an empty string is returned
146 otherwise. The getenv command should be preferred over the Tcl
147 global variable env to query environment variables.
148 When modulefile is evaluated in display mode, getenv returns
150 variable name prefixed with dollar sign (e.g., $variable).
151 getvariant variant [value]
153 Returns value of designated variant. If variant is not defined,
154 value is returned if set, an empty string is returned otherwise.
155 The getvariant command should be preferred over the
156 ModuleVariant Tcl array to query a variant value.
157 When modulefile is evaluated in display mode, getvariant returns
159 variant name enclosed in curly braces (e.g., {variant}).
160 is-avail modulefile...
162 The is-avail command returns a true value if any of the listed
163 modulefiles exists in enabled MODULEPATH. If a list contains
164 more than one modulefile, then each member acts as a boolean OR
165 operation. If an argument for is-avail is a directory and a mod‐
166 ulefile exists in the directory is-avail would return a true
167 value.
168 The parameter modulefile may also be a symbolic modulefile name
170 or a modulefile alias. It may also leverage a specific syntax to
171 finely select module version (see Advanced module version speci‐
172 fiers section below).
173 is-loaded [modulefile...]
175 The is-loaded command returns a true value if any of the listed
176 modulefiles has been loaded or if any modulefile is loaded in
177 case no argument is provided. If a list contains more than one
178 modulefile, then each member acts as a boolean OR operation. If
179 an argument for is-loaded is a directory and any modulefile from
180 the directory has been loaded is-loaded would return a true
181 value.
182 The parameter modulefile may also be a symbolic modulefile name
184 or a modulefile alias. It may also leverage a specific syntax to
185 finely select module version (see Advanced module version speci‐
186 fiers section below).
187 is-saved [collection...]
189 The is-saved command returns a true value if any of the listed
190 collections exists or if any collection exists in case no argu‐
191 ment is provided. If a list contains more than one collection,
192 then each member acts as a boolean OR operation.
193 If MODULES_COLLECTION_TARGET is set, a suffix equivalent to the
195 value of this variable is appended to the passed collection
196 name. In case no collection argument is provided, a true value
197 will only be returned if a collection matching currently set
198 target exists.
199 is-used [directory...]
201 The is-used command returns a true value if any of the listed
202 directories has been enabled in MODULEPATH or if any directory
203 is enabled in case no argument is provided. If a list contains
204 more than one directory, then each member acts as a boolean OR
205 operation.
206 module [sub-command] [sub-command-options] [sub-command-args]
208 Contains the same sub-commands as described in the module(1) man
209 page in the Module Sub-Commands section. Exception made for the
210 following sub-commands that can only be used outside of a mod‐
211 ulefile context: path, paths, autoinit, help, clear, sh-to-mod,
212 edit, config, refresh and source. Also the following sub-com‐
213 mands cannot be used but have a modulefile command counterpart:
214 prepend-path, append-path, remove-path, is-loaded, is-saved,
215 is-used, is-avail and info-loaded.
216 This command permits a modulefile to load or unload other mod‐
218 ulefiles. No checks are made to ensure that the modulefile does
219 not try to load itself. Often it is useful to have a single mod‐
220 ulefile that performs a number of module load commands. For ex‐
221 ample, if every user on the system requires a basic set of ap‐
222 plications loaded, then a core modulefile would contain the nec‐
223 essary module load commands.
224 The --not-req option may be set for the load, unload and switch
226 sub-commands to inhibit the definition of an implicit prereq or
227 conflict requirement onto specified modules.
228 On try-load sub-command, if specified modulefile is not found
230 thus loaded, no implicit prereq requirement is defined over this
231 module.
232 Command line switches --auto, --no-auto and --force are ignored
234 when passed to a module command set in a modulefile.
235 Changed in version 4.7: Sub-command option --no-req added
236 Changed in version 5.0: source sub-command is not allowed
239 anymore and source Tcl command should be used instead
240 module-alias name modulefile
243 Assigns the modulefile to the alias name. This command should be
244 placed in one of the modulecmd.tcl rc files in order to provide
245 shorthand invocations of frequently used modulefile names.
246 The parameter modulefile may be either
248 • a fully qualified modulefile with name and version
250 • a symbolic modulefile name
252 • another modulefile alias
254 module-forbid [options] modulefile...
256 Forbid use of modulefile. An error is obtained when trying to
257 evaluate a forbidden module. This command should be placed in
258 one of the modulecmd.tcl rc files.
259 module-forbid command accepts the following options:
261 • --after datetime
263 • --before datetime
265 • --not-user {user...}
267 • --not-group {group...}
269 • --message {text message}
271 • --nearly-message {text message}
273 If --after option is set, forbidding is only effective after
275 specified date time. Following the same principle, if --before
276 option is set, forbidding is only effective before specified
277 date time. Accepted date time format is YYYY-MM-DD[THH:MM]. If
278 no time (HH:MM) is specified, 00:00 is assumed. --after and
279 --before options are not supported on Tcl versions prior to 8.5.
280 If --not-user option is set, forbidding is not applied if the
282 username of the user currently running modulecmd.tcl is part of
283 the list of username specified. Following the same approach, if
284 --not-group option is set, forbidding is not applied if current
285 user is member of one the group specified. When both options are
286 set, forbidding is not applied if a match is found for
287 --not-user or --not-group.
288 Error message returned when trying to evaluate a forbidden mod‐
290 ule can be supplemented with the text message set through --mes‐
291 sage option.
292 If --after option is set, modules are considered nearly forbid‐
294 den during a number of days defined by the nearly_forbidden_days
295 modulecmd.tcl configuration option (see MODULES_NEARLY_FORBID‐
296 DEN_DAYS), prior reaching the expiry date fixed by --after op‐
297 tion. When a nearly forbidden module is evaluated a warning mes‐
298 sage is issued to inform module will soon be forbidden. This
299 warning message can be supplemented with the text message set
300 through --nearly-message option.
301 If a module-forbid command applies to a modulefile also targeted
303 by a module-hide --hard command, this module is unveiled when
304 precisely named to return an access error.
305 Forbidden modules included in the result of an avail sub-command
307 are reported with a forbidden tag applied to them. Nearly for‐
308 bidden modules included in the result of an avail or a list
309 sub-command are reported with a nearly-forbidden tag applied to
310 them. See Module tags section in module(1).
311 The parameter modulefile may leverage a specific syntax to
313 finely select module version (see Advanced module version speci‐
314 fiers section below).
315 module-hide [options] modulefile...
317 Hide modulefile to exclude it from available module search or
318 module selection unless query refers to modulefile by its exact
319 name. This command should be placed in one of the modulecmd.tcl
320 rc files.
321 module-hide command accepts the following options:
323 • --soft|--hard
325 • --hidden-loaded
327 • --after datetime
329 • --before datetime
331 • --not-user {user...}
333 • --not-group {group...}
335 When --soft option is set, modulefile is also set hidden, but
337 hiding is disabled when search or selection query's root name
338 matches module's root name. This soft hiding mode enables to
339 hide modulefiles from bare module availability listing yet keep‐
340 ing the ability to select such module for load with the regular
341 resolution mechanism (i.e., no need to use module exact name to
342 select it)
343 When --hard option is set, modulefile is also set hidden and
345 stays hidden even if search or selection query refers to module‐
346 file by its exact name.
347 When --hidden-loaded option is set, hidden state also applies to
349 the modulefile when it is loaded. Hidden loaded modules do not
350 appear on list sub-command output, unless --all option is set.
351 Their loading or unloading informational messages are not re‐
352 ported unless the verbosity of Modules is set to a level higher
353 than verbose. Hidden loaded modules are detected in any cases by
354 state query commands like is-loaded.
355 If --after option is set, hiding is only effective after speci‐
357 fied date time. Following the same principle, if --before option
358 is set, hiding is only effective before specified date time. Ac‐
359 cepted date time format is YYYY-MM-DD[THH:MM]. If no time
360 (HH:MM) is specified, 00:00 is assumed. --after and --before op‐
361 tions are not supported on Tcl versions prior to 8.5.
362 If --not-user option is set, hiding is not applied if the user‐
364 name of the user currently running modulecmd.tcl is part of the
365 list of username specified. Following the same approach, if
366 --not-group option is set, hiding is not applied if current user
367 is member of one the group specified. When both options are
368 set, hiding is not applied if a match is found for --not-user or
369 --not-group.
370 If the --all option is set on avail, aliases, whatis or search
372 sub-commands, hiding is disabled thus hidden modulefiles are in‐
373 cluded in module search. Hard-hidden modules (i.e., declared
374 hidden with --hard option) are not affected by --all and stay
375 hidden even if option is set. --all option does not apply to
376 module selection sub-commands like load. Thus in such context a
377 hidden module should always be referred by its exact full name
378 (e.g., foo/1.2.3 not foo) unless if it has been hidden in --soft
379 mode. A hard-hidden module cannot be unveiled or selected in any
380 case.
381 If several module-hide commands target the same modulefile, the
383 strongest hiding level is retained which means if both a regu‐
384 lar, a --soft hiding command match a given module, regular hid‐
385 ing mode is considered. If both a regular and a --hard hiding
386 command match a given module, hard hiding mode is retained. A
387 set --hidden-loaded option is retained even if the module-hide
388 statement on which it is declared is superseded by a stronger
389 module-hide statement with no --hidden-loaded option set.
390 Hidden modules included in the result of an avail sub-command
392 are reported with a hidden tag applied to them. Hidden loaded
393 modules included in the result of a list sub-command are re‐
394 ported with a hidden-loaded tag applied to them. This tag is not
395 reported on avail sub-command context. See Module tags section
396 in module(1).
397 The parameter modulefile may also be a symbolic modulefile name
399 or a modulefile alias. It may also leverage a specific syntax to
400 finely select module version (see Advanced module version speci‐
401 fiers section below).
402 module-info option [info-args]
404 Provide information about the modulecmd.tcl program's state.
405 Some of the information is specific to the internals of mod‐
406 ulecmd.tcl. option is the type of information to be provided,
407 and info-args are any arguments needed.
408 module-info alias name
410 Returns the full modulefile name to which the modulefile
411 alias name is assigned
412 module-info command [commandname]
414 Returns the currently running modulecmd.tcl's command as a
415 string if no commandname is given.
416 Returns 1 if modulecmd.tcl's command is commandname. com‐
418 mandname can be: load, unload, refresh, reload, source,
419 switch, display, avail, aliases, list, whatis, search, purge,
420 restore, help, test or try-load.
421 module-info loaded modulefile
423 Returns the names of currently loaded modules matching passed
424 modulefile. The parameter modulefile might either be a fully
425 qualified modulefile with name and version or just a direc‐
426 tory which in case all loaded modulefiles from the directory
427 will be returned. The parameter modulefile may also be a sym‐
428 bolic modulefile name or a modulefile alias.
429 This command only returns the name and version of designated
431 loaded module. The defined variants of the loaded module are
432 not included in the returned string.
433 module-info mode [modetype]
435 Returns the current modulecmd.tcl's mode as a string if no
436 modetype is given.
437 Returns 1 if modulecmd.tcl's mode is modetype. modetype can
439 be: load, unload, remove (alias of unload), switch, refresh,
440 nonpersist (alias of refresh), display, help, test or whatis.
441 module-info name
443 Return the name of the modulefile. This is not the full path‐
444 name for modulefile. See the Modules Variables section for
445 information on the full pathname.
446 This command only returns the name and version of currently
448 evaluating modulefile. The defined variants are not included
449 in the returned string. See getvariant command or
450 ModuleVariant array variable to get defined variant values
451 for currently evaluating modulefile.
452 module-info shell [shellname]
454 Return the current shell under which modulecmd.tcl was in‐
455 voked if no shellname is given. The current shell is the
456 first parameter of modulecmd.tcl, which is normally hidden by
457 the module alias.
458 If a shellname is given, returns 1 if modulecmd.tcl's current
460 shell is shellname, returns 0 otherwise. shellname can be:
461 sh, bash, ksh, zsh, csh, tcsh, fish, tcl, perl, python, ruby,
462 lisp, cmake, r.
463 module-info shelltype [shelltypename]
465 Return the family of the shell under which modulefile was in‐
466 voked if no shelltypename is given. As of module-info shell
467 this depends on the first parameter of modulecmd.tcl. The
468 output reflects a shell type determining the shell syntax of
469 the commands produced by modulecmd.tcl.
470 If a shelltypename is given, returns 1 if modulecmd.tcl's
472 current shell type is shelltypename, returns 0 otherwise.
473 shelltypename can be: sh, csh, fish, tcl, perl, python, ruby,
474 lisp, cmake, r.
475 module-info specified
477 Return the module designation (name, version and variants)
478 specified that led to current modulefile evaluation.
479 module-info symbols modulefile
481 Returns a list of all symbolic versions assigned to the
482 passed modulefile. The parameter modulefile might either be
483 a full qualified modulefile with name and version, another
484 symbolic modulefile name or a modulefile alias.
485 module-info tags [tag]
487 Returns all tags assigned to currently evaluated modulefile
488 as a list of strings if no tag name is given (see Module tags
489 section in module(1))
490 When tags are assigned to specific module variants, they are
492 returned only if this variant is the one currently evaluated.
493 Returns 1 if one of the tags applying to currently evaluated
495 modulefile is tag. Returns 0 otherwise.
496 module-info type
498 Returns either C or Tcl to indicate which module command is
499 being executed, either the C version or the Tcl-only ver‐
500 sion, to allow the modulefile writer to handle any differ‐
501 ences between the two.
502 module-info usergroups [name]
504 Returns all the groups the user currently running mod‐
505 ulecmd.tcl is member of as a list of strings if no name is
506 given.
507 Returns 1 if one of the group current user running mod‐
509 ulecmd.tcl is member of is name. Returns 0 otherwise.
510 If the Modules Tcl extension library is disabled, the id(1)
512 command is invoked to fetch groups of current user.
513 module-info username [name]
515 Returns the username of the user currently running mod‐
516 ulecmd.tcl as a string if no name is given.
517 Returns 1 if username of current user running modulecmd.tcl
519 is name. Returns 0 otherwise.
520 If the Modules Tcl extension library is disabled, the id(1)
522 command is invoked to fetch username of current user.
523 module-info version modulefile
525 Returns the physical module name and version of the passed
526 symbolic version modulefile. The parameter modulefile might
527 either be a full qualified modulefile with name and version,
528 another symbolic modulefile name or a modulefile alias.
529 module-tag [options] tag modulefile...
531 Associate tag to designated modulefile. This tag information
532 will be reported along modulefile on avail and list sub-commands
533 (see Module tags section in module(1)). Tag information can be
534 queried during modulefile evaluation with the module-info tags
535 modulefile command. module-tag commands should be placed in one
536 of the modulecmd.tcl rc files.
537 module-tag command accepts the following options:
539 • --not-user {user...}
541 • --not-group {group...}
543 If --not-user option is set, the tag is not applied if the user‐
545 name of the user currently running modulecmd.tcl is part of the
546 list of username specified. Following the same approach, if
547 --not-group option is set, the tag is not applied if current
548 user is member of one the group specified. When both options are
549 set, the tag is not applied if a match is found for --not-user
550 or --not-group.
551 The parameter modulefile may also be a symbolic modulefile name
553 or a modulefile alias. It may also leverage a specific syntax to
554 finely select module version (see Advanced module version speci‐
555 fiers section below).
556 Tags inherited from other modulefile commands or module states
558 cannot be set with module-tag. Otherwise an error is returned.
559 Those special tags are: auto-loaded, forbidden, hidden, hid‐
560 den-loaded, loaded and nearly-forbidden.
561 When tag equals sticky or super-sticky, designated modulefile
563 are defined Sticky modules.
564 module-version modulefile version-name...
566 Assigns the symbolic version-name to the modulefile. This com‐
567 mand should be placed in one of the modulecmd.tcl rc files in
568 order to provide shorthand invocations of frequently used mod‐
569 ulefile names.
570 The special version-name default specifies the default version
572 to be used for module commands, if no specific version is given.
573 This replaces the definitions made in the .version file in for‐
574 mer modulecmd.tcl releases.
575 The parameter modulefile may be either
577 • a fully or partially qualified modulefile with name / version.
579 If name is . (dot) then the current directory name is assumed
580 to be the module name. (Use this for deep modulefile directo‐
581 ries.)
582 • a symbolic modulefile name
584 • another modulefile alias
586 module-virtual name modulefile
588 Assigns the modulefile to the virtual module name. This command
589 should be placed in rc files in order to define virtual modules.
590 A virtual module stands for a module name associated to a mod‐
592 ulefile. The modulefile is the script interpreted when loading
593 or unloading the virtual module which appears or can be found
594 with its virtual name.
595 The parameter modulefile corresponds to the relative or absolute
597 file location of a modulefile.
598 module-whatis string
600 Defines a string which is displayed in case of the invocation of
601 the module whatis command. There may be more than one
602 module-whatis line in a modulefile. This command takes no ac‐
603 tions in case of load, display, etc. invocations of mod‐
604 ulecmd.tcl.
605 The string parameter has to be enclosed in double-quotes if
607 there's more than one word specified. Words are defined to be
608 separated by whitespace characters (space, tab, cr).
609 prepend-path [-d C|--delim C|--delim=C] [--duplicates] variable
611 value...
612 Append or prepend value to environment variable. The variable is
613 a colon, or delimiter, separated list such as PATH=directory:di‐
614 rectory:directory. The default delimiter is a colon :, but an
615 arbitrary one can be given by the --delim option. For example a
616 space can be used instead (which will need to be handled in the
617 Tcl specially by enclosing it in " " or { }). A space, however,
618 can not be specified by the --delim=C form.
619 A reference counter environment variable is also set to know the
621 number of times value has been added to environment variable
622 when it is added more than one time. This reference counter en‐
623 vironment variable is named by prefixing variable by __MOD‐
624 ULES_SHARE_.
625 When value is already defined in environment variable, it is not
627 added again or moved at the end or at the beginning of variable.
628 Exception is made when the --duplicates option is set in which
629 case value is added again to variable.
630 If the variable is not set, it is created. When a modulefile is
632 unloaded, append-path and prepend-path become remove-path.
633 If value corresponds to the concatenation of multiple elements
635 separated by colon, or delimiter, character, each element is
636 treated separately.
637 prereq modulefile...
639 See conflict.
640 remove-path [-d C|--delim C|--delim=C] [--index] variable value...
642 Remove value from the colon, or delimiter, separated list in
643 variable. See prepend-path or append-path for further explana‐
644 tion of using an arbitrary delimiter. Every string between
645 colons, or delimiters, in variable is compared to value. If the
646 two match, value is removed from variable if its reference
647 counter is equal to 1 or unknown.
648 When --index option is set, value refers to an index in variable
650 list. The string element pointed by this index is set for re‐
651 moval.
652 Reference counter of value in variable denotes the number of
654 times value has been added to variable. This information is
655 stored in environment __MODULES_SHARE_variable. When attempting
656 to remove value from variable, relative reference counter is
657 checked and value is removed only if counter is equal to 1 or
658 not defined. Otherwise value is kept in variable and reference
659 counter is decreased by 1. If counter equals 1 after being de‐
660 creased, value and its counter are removed from reference
661 counter variable.
662 If value corresponds to the concatenation of multiple elements
664 separated by colon, or delimiter, character, each element is
665 treated separately.
666 set-alias alias-name alias-string
668 Sets an alias or function with the name alias-name in the user's
669 environment to the string alias-string. For some shells, aliases
670 are not possible and the command has no effect. When a module‐
671 file is unloaded, set-alias becomes unset-alias.
672 set-function function-name function-string
674 Creates a function with the name function-name in the user's en‐
675 vironment with the function body function-string. For some
676 shells, functions are not possible and the command has no ef‐
677 fect. When a modulefile is unloaded, set-function becomes
678 unset-function.
679 setenv variable value
681 Set environment variable to value. The setenv command will also
682 change the process' environment. A reference using Tcl's env as‐
683 sociative array will reference changes made with the setenv com‐
684 mand. Changes made using Tcl's env associative array will NOT
685 change the user's environment variable like the setenv command.
686 An environment change made this way will only affect the module
687 parsing process. The setenv command is also useful for changing
688 the environment prior to the exec or system command. When a mod‐
689 ulefile is unloaded, setenv becomes unsetenv. If the environment
690 variable had been defined it will be overwritten while loading
691 the modulefile. A subsequent unload will unset the environment
692 variable - the previous value cannot be restored! (Unless you
693 handle it explicitly ... see below.)
694 source-sh shell script [arg...]
696 Evaluate with shell the designated script with defined arguments
697 to find out the environment changes it does. Those changes ob‐
698 tained by comparing environment prior and after script evalua‐
699 tion are then translated into corresponding modulefile commands,
700 which are then applied during modulefile evaluation as if they
701 were directly written in it.
702 When modulefile is unloaded, environment changes done are re‐
704 served by evaluating in the unload context the resulting module‐
705 file commands, which were recorded in the __MODULES_LMSOURCESH
706 environment variable at load time.
707 Changes on environment variables, shell aliases, shell functions
709 and current working directory are tracked.
710 Shell could be specified as a command name or a fully qualified
712 pathname. The following shells are supported: sh, dash, csh,
713 tcsh, bash, ksh, ksh93, zsh and fish.
714 system string
716 Run string command through shell. On Unix, command is passed to
717 the /bin/sh shell whereas on Windows it is passed to cmd.exe.
718 modulecmd.tcl redirects stdout to stderr since stdout would be
719 parsed by the evaluating shell. The exit status of the executed
720 command is returned.
721 uname field
723 Provide lookup of system information. Most field information are
724 retrieved from the tcl_platform array (see the tclvars(n) man
725 page). Uname will return the string unknown if information is
726 unavailable for the field.
727 uname will invoke the uname(1) command in order to get the oper‐
729 ating system version and domainname(1) to figure out the name of
730 the domain.
731 field values are:
733 • sysname: the operating system name
735 • nodename: the hostname
737 • domain: the name of the domain
739 • release: the operating system release
741 • version: the operating system version
743 • machine: a standard name that identifies the system's hardware
745 unset-alias alias-name
747 Unsets an alias with the name alias-name in the user's environ‐
748 ment.
749 unset-function function-name
751 Removes a function with the name function-name from the user's
752 environment.
753 unsetenv variable [value]
755 Unsets environment variable. When a modulefile is unloaded, no
756 operation is performed unless if an optional value is defined,
757 in which case variable is to value. The unsetenv command changes
758 the process' environment like setenv.
759 variant [--boolean] [--default value] name value...
761 Declare module variant name with list of accepted value and in‐
762 stantiate it in the ModuleVariant array variable.
763 Variant's value is selected through the module designation that
765 leads to the modulefile evaluation. See Advanced module version
766 specifiers section to learn how variants could be specified.
767 Selected variant value is transmitted to the evaluating module‐
769 file. A value must be specified for variant name and it must
770 corresponds to a value in the accepted value list. Otherwise an
771 error is raised. An exception is made if modulefile is evaluated
772 in display mode: no error is raised if no value is specified for
773 a given variant and variant is not instantiated in the
774 ModuleVariant array variable.
775 When the --default option is set, variant name is set to the
777 value associated with this option in case no value is specified
778 for variant in module designation.
779 If the --boolean option is set, variant name is defined as a
781 Boolean variant. No list of accepted value should be defined in
782 this case. All values recognized as Boolean value in Tcl are ac‐
783 cepted (i.e., 1, true, t, yes, y, on, 0, false, f, no, n or
784 off). Boolean variants are instantiated in ModuleVariant using
785 Tcl canonical form of Boolean value (i.e., 0 or 1).
786 A variant which is not defined as a Boolean variant cannot de‐
788 fine Boolean values in its accepted value list, exception made
789 for the 0 and 1 integers. An error is raised otherwise.
790 A variant cannot be named version. An error is raised otherwise.
792 versioncmp version1 version2
794 Compare version string version1 against version string version2.
795 Returns -1, 0 or 1 respectively if version1 is less than, equal
796 to or greater than version2.
797 x-resource [resource-string|filename]
799 Merge resources into the X11 resource database. The resources
800 are used to control look and behavior of X11 applications. The
801 command will attempt to read resources from filename. If the ar‐
802 gument isn't a valid file name, then string will be interpreted
803 as a resource. Either filename or resource-string is then passed
804 down to be xrdb(1) command.
805 modulefiles that use this command, should in most cases contain
807 one or more x-resource lines, each defining one X11 resource.
808 The DISPLAY environment variable should be properly set and the
809 X11 server should be accessible. If x-resource can't manipulate
810 the X11 resource database, the modulefile will exit with an er‐
811 ror message.
812 Examples:
814 x-resource /u2/staff/leif/.xres/Ileaf
816 The content of the Ileaf file is merged into the X11 resource
817 database.
818 x-resource [glob ~/.xres/ileaf]
820 The Tcl glob function is used to have the modulefile read
821 different resource files for different users.
822 x-resource {Ileaf.popup.saveUnder: True}
824 Merge the Ileaf resource into the X11 resource database.
825
827 ModulesCurrentModulefile
828 The ModulesCurrentModulefile variable contains the full pathname
829 of the modulefile being interpreted.
830 ModuleTool
832 The ModuleTool variable contains the name of the module imple‐
833 mentation currently in use. The value of this variable is set to
834 Modules for this implementation.
835 ModuleToolVersion
837 The ModuleToolVersion variable contains the version of the mod‐
838 ule implementation currently in use. The value of this variable
839 is set to 5.0.1 for this version of Modules.
840 ModuleVariant
842 The ModuleVariant array variable contains an element entry for
843 each defined variant associated to the value of this variant
844 (e.g., the $ModuleVariant(foo) syntax corresponds to the value
845 of variant foo if defined). A Tcl evaluation error is obtained
846 when accessing an undefined variant in ModuleVariant array. Use
847 preferably the getvariant command to retrieve a variant value
848 when this variant state is not known.
849 The list of the currently defined variants can be retrieved with
851 [array names ModuleVariant] Tcl code.
852
854 Every directory in MODULEPATH is searched to find the modulefile. A di‐
855 rectory in MODULEPATH can have an arbitrary number of sub-directories.
856 If the user names a modulefile to be loaded which is actually a direc‐
857 tory, the directory is opened and a search begins for an actual module‐
858 file. First, modulecmd.tcl looks for a file with the name .modulerc in
859 the directory. If this file exists, its contents will be evaluated as
860 if it was a modulefile to be loaded. You may place module-version,
861 module-alias and module-virtual commands inside this file.
862 Additionally, before seeking for .modulerc files in the module direc‐
864 tory, the global modulerc file and the .modulerc file found at the root
865 of the modulepath directory are sourced, too. If a named version de‐
866 fault now exists for the modulefile to be loaded, the assigned module‐
867 file now will be sourced. Otherwise the file .version is looked up in
868 the module directory.
869 If the .version file exists, it is opened and interpreted as Tcl code
871 and takes precedence over a .modulerc file in the same directory. If
872 the Tcl variable ModulesVersion is set by the .version file, mod‐
873 ulecmd.tcl will use the name as if it specifies a modulefile in this
874 directory. This will become the default modulefile in this case. Mod‐
875 ulesVersion cannot refer to a modulefile located in a different direc‐
876 tory.
877 If ModulesVersion is a directory, the search begins anew down that di‐
879 rectory. If the name does not match any files located in the current
880 directory, the search continues through the remaining directories in
881 MODULEPATH.
882 Every .version and .modulerc file found is interpreted as Tcl code. The
884 difference is that .version only applies to the current directory, and
885 the .modulerc applies to the current directory and all subdirectories.
886 Changes made in these files will affect the subsequently interpreted
887 modulefile.
888 If no default version may be figured out, an implicit default is se‐
890 lected when this behavior is enabled (see MODULES_IMPLICIT_DEFAULT in
891 module(1)). If disabled, module names should be fully qualified when no
892 explicit default is defined for them, otherwise no default version is
893 found and an error is returned. If enabled, then the highest numeri‐
894 cally sorted modulefile, virtual module or module alias under the di‐
895 rectory will be used. The dictionary comparison method of the lsort(n)
896 Tcl command is used to achieve this sort. If highest numerically sorted
897 element is an alias, search continues on its modulefile target.
898 For example, it is possible for a user to have a directory named X11
900 which simply contains a .version file specifying which version of X11
901 is to be loaded. Such a file would look like:
902 #%Module1.0
904 ##
905 ## The desired version of X11
906 ##
907 set ModulesVersion "R4"
908 The equivalent .modulerc would look like:
910 #%Module1.0
912 ##
913 ## The desired version of X11
914 ##
915 module-version "./R4" default
916 If the extended default mechanism is enabled (see MODULES_EXTENDED_DE‐
918 FAULT in module(1)) the module version specified is matched against
919 starting portion of existing module versions, where portion is a sub‐
920 string separated from the rest of version string by a . character.
921 When the implicit default mechanism and the Advanced module version
923 specifiers are both enabled, a default and latest symbolic versions are
924 automatically defined for each module name (also at each directory
925 level in case of deep modulefile). Unless a symbolic version, alias, or
926 regular module version already exists for these version names.
927 If user names a modulefile that cannot be found in the first modulepath
929 directory, modulefile will be searched in next modulepath directory and
930 so on until a matching modulefile is found. If search goes through a
931 module alias or a symbolic version, this alias or symbol is resolved by
932 first looking at the modulefiles in the modulepath where this alias or
933 symbol is defined. If not found, resolution looks at the other mod‐
934 ulepaths in their definition order.
935 When locating modulefiles, if a .modulerc, a .version, a directory or a
937 modulefile cannot be read during the search it is simply ignored with
938 no error message produced. Visibility of modulefiles can thus be
939 adapted to the rights the user has been granted. Exception is made when
940 trying to directly access a directory or a modulefile. In this case,
941 the access issue is returned as an error message.
942 Depending on their name, their file permissions or the use of specific
944 modulefile commands, modulefile, virtual module, module alias or sym‐
945 bolic version may be set hidden which impacts available modules search
946 or module selection processes (see Hiding modulefiles section below).
947
949 A modulefile, virtual module, module alias or symbolic version whose
950 name or element in their name starts with a dot character (.) or who
951 are targeted by a module-hide command are considered hidden. Hidden
952 modules are not displayed or taken into account except if they are ex‐
953 plicitly named (e.g., foo/1.2.3 or foo/.2.0 not foo). If module has
954 been hidden with the --soft option of the module-hide command set, it
955 is not considered hidden if the root name of the query to search it
956 matches module root name (e.g., searching foo will return a foo/1.2.3
957 modulefile targeted by a module-hide --soft command). If module has
958 been hidden with the --hard option of the module-hide command set, it
959 is always considered hidden thus it is never displayed nor taken into
960 account even if it is explicitly named.
961 A modulefile, virtual module, module alias or symbolic version who are
963 targeted by a module-hide --hard command and a module-forbid command or
964 whose file access permissions are restricted are considered hard-hidden
965 and forbidden. Such modules are not displayed or taken into account.
966 When explicitly named for evaluation selection, such modules are un‐
967 veiled to return an access error.
968 A symbolic version-name assigned to a hidden module is displayed or
970 taken into account only if explicitly named and if module is not
971 hard-hidden. Non-hidden module alias targeting a hidden modulefile ap‐
972 pears like any other non-hidden module alias. Finally, a hidden sym‐
973 bolic version targeting a non-hidden module is displayed or taken into
974 account only if not hard-hidden and explicitly named to refer to its
975 non-hidden target.
976 The automatic version symbols (e.g., default and latest) are unaffected
978 by hiding. Moreover when a regular default or latest version is set
979 hidden, the corresponding automatic version symbol takes the left spot.
980 For instance, if foo/default which targets foo/1.2.3 is set hard-hid‐
981 den, the default automatic version symbol will be set onto foo/2.1.3,
982 the highest available version of foo.
983 When loading a modulefile or a virtual module targeted by a module-hide
985 --hidden-loaded command, this module inherits the hidden-loaded tag.
986 Hidden loaded modules are not reported among list sub-command results.
987 If the --all is set on avail, aliases, whatis or search sub-commands,
989 hidden modules are taken into account in search. Hard-hidden modules
990 are unaffected by this option.
991 If the --all is set on list sub-command, hidden loaded modules are in‐
993 cluded in result output.
994
996 When the advanced module version specifiers mechanism is enabled (see
997 MODULES_ADVANCED_VERSION_SPEC in module(1)), the specification of mod‐
998 ulefile passed on Modules specific Tcl commands changes. After the
999 module name a version constraint and variants may be added.
1000 Version specifiers
1002 After the module name a version constraint prefixed by the @ character
1003 may be added. It could be directly appended to the module name or sepa‐
1004 rated from it with a space character.
1005 Constraints can be expressed to refine the selection of module version
1007 to:
1008 • a single version with the @version syntax, for instance foo@1.2.3
1010 syntax will select module foo/1.2.3
1011 • a list of versions with the @version1,version2,... syntax, for in‐
1013 stance foo@1.2.3,1.10 will match modules foo/1.2.3 and foo/1.10
1014 • a range of versions with the @version1:, @:version2 and @ver‐
1016 sion1:version2 syntaxes, for instance foo@1.2: will select all ver‐
1017 sions of module foo greater than or equal to 1.2, foo@:1.3 will se‐
1018 lect all versions less than or equal to 1.3 and foo@1.2:1.3 matches
1019 all versions between 1.2 and 1.3 including 1.2 and 1.3 versions
1020 Advanced specification of single version or list of versions may bene‐
1022 fit from the activation of the extended default mechanism (see MOD‐
1023 ULES_EXTENDED_DEFAULT in module(1)) to use an abbreviated notation like
1024 @1 to refer to more precise version numbers like 1.2.3. Range of ver‐
1025 sions on its side natively handles abbreviated versions.
1026 In order to be specified in a range of versions or compared to a range
1028 of versions, the version major element should corresponds to a number.
1029 For instance 10a, 1.2.3, 1.foo are versions valid for range comparison
1030 whereas default or foo.2 versions are invalid for range comparison.
1031 Range of versions can be specified in version list, for instance
1033 foo@:1.2,1.4:1.6,1.8:. Such specification helps to exclude specific
1034 versions, like versions 1.3 and 1.7 in previous example.
1035 If the implicit default mechanism is also enabled (see MODULES_IM‐
1037 PLICIT_DEFAULT in module(1)), a default and latest symbolic versions
1038 are automatically defined for each module name (also at each directory
1039 level for deep modulefiles). These automatic version symbols are de‐
1040 fined unless a symbolic version, alias, or regular module version al‐
1041 ready exists for these default or latest version names. Using the
1042 mod@latest (or mod/latest) syntax ensures highest available version
1043 will be selected.
1044 Variants
1046 After the module name, variants can be specified. Module variants are
1047 alternative evaluation of the same modulefile. A variant is specified
1048 by associating a value to its name. This specification is then trans‐
1049 mitted to the evaluating modulefile which instantiates the variant in
1050 the ModuleVariant array variable when reaching the variant modulefile
1051 command declaring this variant.
1052 Variant can be specified with the name=value syntax where name is the
1054 declared variant name and value, the value this variant is set to when
1055 evaluating the modulefile.
1056 Boolean variants can be specified with the +name syntax to set this
1058 variant on and with the -name or ~name syntaxes to set this variant
1059 off. The -name syntax is not supported on ml(1) command as the minus
1060 sign already means to unload designated module. The ~name and +name
1061 syntaxes could also be defined appended to another specification word
1062 (e.g., the module name, version or another variant specification),
1063 whereas -name syntax must be the start of a new specification word.
1064 Boolean variants may also be specified with the name=value syntax.
1066 value should be set to 1, true, t, yes, y or on to enable the variant
1067 or it should be set to 0, false, f, no, n or off to disable the vari‐
1068 ant.
1069 Shortcuts may be used to abbreviate variant specification. The vari‐
1071 ant_shortcut configuration option associates shortcut character to
1072 variant name. With a shortcut defined, variant could be specified with
1073 the <shortcut>value syntax. For instance if character % is set as a
1074 shortcut for variant foo, the %value syntax is equivalent to the
1075 foo=value syntax.
1076 Specific characters used in variant specification syntax cannot be used
1078 as part of the name of a module. These specific characters are +, ~, =
1079 and all characters set as variant shortcut. Exception is made for +
1080 character which could be set one or several consecutive times at the
1081 end of module name (e.g., name+ or name++).
1082
1084 Users can request help about a specific modulefile through the mod‐
1085 ule(1) command. The modulefile can print helpful information or start
1086 help oriented programs by defining a ModulesHelp subroutine. The sub‐
1087 routine will be called when the module help modulefile command is used.
1088
1090 Users can request test of a specific modulefile through the module(1)
1091 command. The modulefile can perform some sanity checks on its defini‐
1092 tion or on its underlying programs by defining a ModulesTest subrou‐
1093 tine. The subroutine will be called when the module test modulefile
1094 command is used. The subroutine should return 1 in case of success. If
1095 no or any other value is returned, test is considered failed.
1096
1098 The module display modulefile command will detail all changes that will
1099 be made to the environment. After displaying all of the environment
1100 changes modulecmd.tcl will call the ModulesDisplay subroutine. The Mod‐
1101 ulesDisplay subroutine is a good place to put additional descriptive
1102 information about the modulefile.
1103
1105 See the ENVIRONMENT section in the module(1) man page.
1106
1108 module(1), ml(1), Tcl(n), TclX(n), id(1), xrdb(1), exec(n), uname(1),
1109 domainname(1), tclvars(n), lsort(n)
1110
1112 Tcl was developed by John Ousterhout at the University of California at
1113 Berkeley.
1114 TclX was developed by Karl Lehenbauer and Mark Diekhans.
1116
1118 1996-1999 John L. Furlani & Peter W. Osel, 1998-2017 R.K.Owen,
1119 2002-2004 Mark Lakata, 2004-2017 Kent Mein, 2016-2021 Xavier Delaruelle
11205.0.1 2021-10-16 MODULEFILE(4)