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, _UNDEFINED_ is returned other‐
146 wise. The getenv command should be preferred over the Tcl global
147 variable env to query environment variables.
148 is-avail modulefile...
150 The is-avail command returns a true value if any of the listed
151 modulefiles exists in enabled MODULEPATH. If a list contains
152 more than one modulefile, then each member acts as a boolean OR
153 operation. If an argument for is-avail is a directory and a mod‐
154 ulefile exists in the directory is-avail would return a true
155 value.
156 The parameter modulefile may also be a symbolic modulefile name
158 or a modulefile alias. It may also leverage a specific syntax to
159 finely select module version (see Advanced module version speci‐
160 fiers section below).
161 is-loaded [modulefile...]
163 The is-loaded command returns a true value if any of the listed
164 modulefiles has been loaded or if any modulefile is loaded in
165 case no argument is provided. If a list contains more than one
166 modulefile, then each member acts as a boolean OR operation. If
167 an argument for is-loaded is a directory and any modulefile from
168 the directory has been loaded is-loaded would return a true
169 value.
170 The parameter modulefile may also be a symbolic modulefile name
172 or a modulefile alias. It may also leverage a specific syntax to
173 finely select module version (see Advanced module version speci‐
174 fiers section below).
175 is-saved [collection...]
177 The is-saved command returns a true value if any of the listed
178 collections exists or if any collection exists in case no argu‐
179 ment is provided. If a list contains more than one collection,
180 then each member acts as a boolean OR operation.
181 If MODULES_COLLECTION_TARGET is set, a suffix equivalent to the
183 value of this variable is appended to the passed collection
184 name. In case no collection argument is provided, a true value
185 will only be returned if a collection matching currently set
186 target exists.
187 is-used [directory...]
189 The is-used command returns a true value if any of the listed
190 directories has been enabled in MODULEPATH or if any directory
191 is enabled in case no argument is provided. If a list contains
192 more than one directory, then each member acts as a boolean OR
193 operation.
194 module [sub-command] [sub-command-options] [sub-command-args]
196 Contains the same sub-commands as described in the module(1) man
197 page in the Module Sub-Commands section. This command permits a
198 modulefile to load or unload other modulefiles. No checks are
199 made to ensure that the modulefile does not try to load itself.
200 Often it is useful to have a single modulefile that performs a
201 number of module load commands. For example, if every user on
202 the system requires a basic set of applications loaded, then a
203 core modulefile would contain the necessary module load com‐
204 mands.
205 The --not-req option may be set for the load, unload and switch
207 sub-commands to inhibit the definition of an implicit prereq or
208 conflict requirement onto specified modules.
209 Command line switches --auto, --no-auto and --force are ignored
211 when passed to a module command set in a modulefile.
212 module-alias name modulefile
214 Assigns the modulefile to the alias name. This command should be
215 placed in one of the modulecmd.tcl rc files in order to provide
216 shorthand invocations of frequently used modulefile names.
217 The parameter modulefile may be either
219 • a fully qualified modulefile with name and version
221 • a symbolic modulefile name
223 • another modulefile alias
225 module-forbid [options] modulefile...
227 Forbid use of modulefile. An error is obtained when trying to
228 evaluate a forbidden module. This command should be placed in
229 one of the modulecmd.tcl rc files.
230 module-forbid command accepts the following options:
232 • --after datetime
234 • --before datetime
236 • --not-user {user...}
238 • --not-group {group...}
240 • --message {text message}
242 • --nearly-message {text message}
244 If --after option is set, forbidding is only effective after
246 specified date time. Following the same principle, if --before
247 option is set, forbidding is only effective before specified
248 date time. Accepted date time format is YYYY-MM-DD[THH:MM]. If
249 no time (HH:MM) is specified, 00:00 is assumed. --after and
250 --before options are not supported on Tcl versions prior to 8.5.
251 If --not-user option is set, forbidding is not applied if the
253 username of the user currently running modulecmd.tcl is part of
254 the list of username specified. Following the same approach, if
255 --not-group option is set, forbidding is not applied if current
256 user is member of one the group specified. When both options are
257 set, forbidding is not applied if a match is found for
258 --not-user or --not-group.
259 Error message returned when trying to evaluate a forbidden mod‐
261 ule can be supplemented with the text message set through --mes‐
262 sage option.
263 If --after option is set, modules are considered nearly forbid‐
265 den during a number of days defined by the nearly_forbidden_days
266 modulecmd.tcl configuration option (see MODULES_NEARLY_FORBID‐
267 DEN_DAYS), prior reaching the expiry date fixed by --after op‐
268 tion. When a nearly forbidden module is evaluated a warning mes‐
269 sage is issued to inform module will soon be forbidden. This
270 warning message can be supplemented with the text message set
271 through --nearly-message option.
272 If a module-forbid command applies to a modulefile also targeted
274 by a module-hide --hard command, this module is unveiled when
275 precisely named to return an access error.
276 Forbidden modules included in the result of an avail sub-command
278 are reported with a forbidden tag applied to them. Nearly for‐
279 bidden modules included in the result of an avail or a list
280 sub-command are reported with a nearly-forbidden tag applied to
281 them. See Module tags section in module(1).
282 The parameter modulefile may leverage a specific syntax to
284 finely select module version (see Advanced module version speci‐
285 fiers section below).
286 module-hide [options] modulefile...
288 Hide modulefile to exclude it from available module search or
289 module selection unless query refers to modulefile by its exact
290 name. This command should be placed in one of the modulecmd.tcl
291 rc files.
292 module-hide command accepts the following options:
294 • --soft|--hard
296 • --hidden-loaded
298 • --after datetime
300 • --before datetime
302 • --not-user {user...}
304 • --not-group {group...}
306 When --soft option is set, modulefile is also set hidden, but
308 hiding is disabled when search or selection query's root name
309 matches module's root name. This soft hiding mode enables to
310 hide modulefiles from bare module availability listing yet keep‐
311 ing the ability to select such module for load with the regular
312 resolution mechanism (i.e., no need to use module exact name to
313 select it)
314 When --hard option is set, modulefile is also set hidden and
316 stays hidden even if search or selection query refers to module‐
317 file by its exact name.
318 When --hidden-loaded option is set, hidden state also applies to
320 the modulefile when it is loaded. Hidden loaded modules do not
321 appear on list sub-command output, unless --all option is set.
322 Their loading or unloading informational messages are not re‐
323 ported unless the verbosity of Modules is set to a level higher
324 than verbose. Hidden loaded modules are detected in any cases by
325 state query commands like is-loaded.
326 If --after option is set, hiding is only effective after speci‐
328 fied date time. Following the same principle, if --before option
329 is set, hiding is only effective before specified date time. Ac‐
330 cepted date time format is YYYY-MM-DD[THH:MM]. If no time
331 (HH:MM) is specified, 00:00 is assumed. --after and --before op‐
332 tions are not supported on Tcl versions prior to 8.5.
333 If --not-user option is set, hiding is not applied if the user‐
335 name of the user currently running modulecmd.tcl is part of the
336 list of username specified. Following the same approach, if
337 --not-group option is set, hiding is not applied if current user
338 is member of one the group specified. When both options are
339 set, hiding is not applied if a match is found for --not-user or
340 --not-group.
341 If the --all option is set on avail, aliases, whatis or search
343 sub-commands, hiding is disabled thus hidden modulefiles are in‐
344 cluded in module search. Hard-hidden modules (i.e., declared
345 hidden with --hard option) are not affected by --all and stay
346 hidden even if option is set. --all option does not apply to
347 module selection sub-commands like load. Thus in such context a
348 hidden module should always be referred by its exact full name
349 (e.g., foo/1.2.3 not foo) unless if it has been hidden in --soft
350 mode. A hard-hidden module cannot be unveiled or selected in any
351 case.
352 If several module-hide commands target the same modulefile, the
354 strongest hiding level is retained which means if both a regu‐
355 lar, a --soft hiding command match a given module, regular hid‐
356 ing mode is considered. If both a regular and a --hard hiding
357 command match a given module, hard hiding mode is retained. A
358 set --hidden-loaded option is retained even if the module-hide
359 statement on which it is declared is superseded by a stronger
360 module-hide statement with no --hidden-loaded option set.
361 Hidden modules included in the result of an avail sub-command
363 are reported with a hidden tag applied to them. Hidden loaded
364 modules included in the result of a list sub-command are re‐
365 ported with a hidden-loaded tag applied to them. This tag is not
366 reported on avail sub-command context. See Module tags section
367 in module(1).
368 The parameter modulefile may also be a symbolic modulefile name
370 or a modulefile alias. It may also leverage a specific syntax to
371 finely select module version (see Advanced module version speci‐
372 fiers section below).
373 module-info option [info-args]
375 Provide information about the modulecmd.tcl program's state.
376 Some of the information is specific to the internals of mod‐
377 ulecmd.tcl. option is the type of information to be provided,
378 and info-args are any arguments needed.
379 module-info alias name
381 Returns the full modulefile name to which the modulefile
382 alias name is assigned
383 module-info command [commandname]
385 Returns the currently running modulecmd.tcl's command as a
386 string if no commandname is given.
387 Returns 1 if modulecmd.tcl's command is commandname. com‐
389 mandname can be: load, unload, reload, source, switch, dis‐
390 play, avail, aliases, list, whatis, search, purge, restore,
391 help or test.
392 module-info loaded modulefile
394 Returns the names of currently loaded modules matching passed
395 modulefile. The parameter modulefile might either be a fully
396 qualified modulefile with name and version or just a direc‐
397 tory which in case all loaded modulefiles from the directory
398 will be returned. The parameter modulefile may also be a sym‐
399 bolic modulefile name or a modulefile alias.
400 module-info mode [modetype]
402 Returns the current modulecmd.tcl's mode as a string if no
403 modetype is given.
404 Returns 1 if modulecmd.tcl's mode is modetype. modetype can
406 be: load, unload, remove, switch, display, help, test or
407 whatis.
408 module-info name
410 Return the name of the modulefile. This is not the full path‐
411 name for modulefile. See the Modules Variables section for
412 information on the full pathname.
413 module-info shell [shellname]
415 Return the current shell under which modulecmd.tcl was in‐
416 voked if no shellname is given. The current shell is the
417 first parameter of modulecmd.tcl, which is normally hidden by
418 the module alias.
419 If a shellname is given, returns 1 if modulecmd.tcl's current
421 shell is shellname, returns 0 otherwise. shellname can be:
422 sh, bash, ksh, zsh, csh, tcsh, fish, tcl, perl, python, ruby,
423 lisp, cmake, r.
424 module-info shelltype [shelltypename]
426 Return the family of the shell under which modulefile was in‐
427 voked if no shelltypename is given. As of module-info shell
428 this depends on the first parameter of modulecmd.tcl. The
429 output reflects a shell type determining the shell syntax of
430 the commands produced by modulecmd.tcl.
431 If a shelltypename is given, returns 1 if modulecmd.tcl's
433 current shell type is shelltypename, returns 0 otherwise.
434 shelltypename can be: sh, csh, fish, tcl, perl, python, ruby,
435 lisp, cmake, r.
436 module-info specified
438 Return the name of the modulefile specified on the command
439 line.
440 module-info symbols modulefile
442 Returns a list of all symbolic versions assigned to the
443 passed modulefile. The parameter modulefile might either be
444 a full qualified modulefile with name and version, another
445 symbolic modulefile name or a modulefile alias.
446 module-info tags [tag]
448 Returns all tags assigned to currently evaluated modulefile
449 as a list of strings if no tag name is given (see Module tags
450 section in module(1))
451 Returns 1 if one of the tags applying to currently evaluated
453 modulefile is tag. Returns 0 otherwise.
454 module-info type
456 Returns either C or Tcl to indicate which module command is
457 being executed, either the C version or the Tcl-only ver‐
458 sion, to allow the modulefile writer to handle any differ‐
459 ences between the two.
460 module-info usergroups [name]
462 Returns all the groups the user currently running mod‐
463 ulecmd.tcl is member of as a list of strings if no name is
464 given.
465 Returns 1 if one of the group current user running mod‐
467 ulecmd.tcl is member of is name. Returns 0 otherwise.
468 If the Modules Tcl extension library is disabled, the id(1)
470 command is invoked to fetch groups of current user.
471 module-info username [name]
473 Returns the username of the user currently running mod‐
474 ulecmd.tcl as a string if no name is given.
475 Returns 1 if username of current user running modulecmd.tcl
477 is name. Returns 0 otherwise.
478 If the Modules Tcl extension library is disabled, the id(1)
480 command is invoked to fetch username of current user.
481 module-info version modulefile
483 Returns the physical module name and version of the passed
484 symbolic version modulefile. The parameter modulefile might
485 either be a full qualified modulefile with name and version,
486 another symbolic modulefile name or a modulefile alias.
487 module-tag [options] tag modulefile...
489 Associate tag to designated modulefile. This tag information
490 will be reported along modulefile on avail and list sub-commands
491 (see Module tags section in module(1)). Tag information can be
492 queried during modulefile evaluation with the module-info tags
493 modulefile command. module-tag commands should be placed in one
494 of the modulecmd.tcl rc files.
495 module-tag command accepts the following options:
497 • --not-user {user...}
499 • --not-group {group...}
501 If --not-user option is set, the tag is not applied if the user‐
503 name of the user currently running modulecmd.tcl is part of the
504 list of username specified. Following the same approach, if
505 --not-group option is set, the tag is not applied if current
506 user is member of one the group specified. When both options are
507 set, the tag is not applied if a match is found for --not-user
508 or --not-group.
509 The parameter modulefile may also be a symbolic modulefile name
511 or a modulefile alias. It may also leverage a specific syntax to
512 finely select module version (see Advanced module version speci‐
513 fiers section below).
514 Tags inherited from other modulefile commands or module states
516 cannot be set with module-tag. Otherwise an error is returned.
517 Those special tags are: auto-loaded, forbidden, hidden, hid‐
518 den-loaded, loaded and nearly-forbidden.
519 When tag equals sticky or super-sticky, designated modulefile
521 are defined Sticky modules.
522 module-version modulefile version-name...
524 Assigns the symbolic version-name to the modulefile. This com‐
525 mand should be placed in one of the modulecmd.tcl rc files in
526 order to provide shorthand invocations of frequently used mod‐
527 ulefile names.
528 The special version-name default specifies the default version
530 to be used for module commands, if no specific version is given.
531 This replaces the definitions made in the .version file in for‐
532 mer modulecmd.tcl releases.
533 The parameter modulefile may be either
535 • a fully or partially qualified modulefile with name / version.
537 If name is . (dot) then the current directory name is assumed
538 to be the module name. (Use this for deep modulefile directo‐
539 ries.)
540 • a symbolic modulefile name
542 • another modulefile alias
544 module-virtual name modulefile
546 Assigns the modulefile to the virtual module name. This command
547 should be placed in rc files in order to define virtual modules.
548 A virtual module stands for a module name associated to a mod‐
550 ulefile. The modulefile is the script interpreted when loading
551 or unloading the virtual module which appears or can be found
552 with its virtual name.
553 The parameter modulefile corresponds to the relative or absolute
555 file location of a modulefile.
556 module-whatis string
558 Defines a string which is displayed in case of the invocation of
559 the module whatis command. There may be more than one
560 module-whatis line in a modulefile. This command takes no ac‐
561 tions in case of load, display, etc. invocations of mod‐
562 ulecmd.tcl.
563 The string parameter has to be enclosed in double-quotes if
565 there's more than one word specified. Words are defined to be
566 separated by whitespace characters (space, tab, cr).
567 prepend-path [-d C|--delim C|--delim=C] [--duplicates] variable
569 value...
570 Append or prepend value to environment variable. The variable is
571 a colon, or delimiter, separated list such as PATH=directory:di‐
572 rectory:directory. The default delimiter is a colon :, but an
573 arbitrary one can be given by the --delim option. For example a
574 space can be used instead (which will need to be handled in the
575 Tcl specially by enclosing it in " " or { }). A space, however,
576 can not be specified by the --delim=C form.
577 A reference counter environment variable is also set to increase
579 the number of times value has been added to environment vari‐
580 able. This reference counter environment variable is named by
581 suffixing variable by _modshare.
582 When value is already defined in environment variable, it is not
584 added again except if --duplicates option is set.
585 If the variable is not set, it is created. When a modulefile is
587 unloaded, append-path and prepend-path become remove-path.
588 If value corresponds to the concatenation of multiple elements
590 separated by colon, or delimiter, character, each element is
591 treated separately.
592 prereq modulefile...
594 See conflict.
595 remove-path [-d C|--delim C|--delim=C] [--index] variable value...
597 Remove value from the colon, or delimiter, separated list in
598 variable. See prepend-path or append-path for further explana‐
599 tion of using an arbitrary delimiter. Every string between
600 colons, or delimiters, in variable is compared to value. If the
601 two match, value is removed from variable if its reference
602 counter is equal to 1 or unknown.
603 When --index option is set, value refers to an index in variable
605 list. The string element pointed by this index is set for re‐
606 moval.
607 Reference counter of value in variable denotes the number of
609 times value has been added to variable. This information is
610 stored in environment variable_modshare. When attempting to re‐
611 move value from variable, relative reference counter is checked
612 and value is removed only if counter is equal to 1 or not de‐
613 fined. Otherwise value is kept in variable and reference counter
614 is decreased by 1.
615 If value corresponds to the concatenation of multiple elements
617 separated by colon, or delimiter, character, each element is
618 treated separately.
619 set-alias alias-name alias-string
621 Sets an alias or function with the name alias-name in the user's
622 environment to the string alias-string. For some shells, aliases
623 are not possible and the command has no effect. When a module‐
624 file is unloaded, set-alias becomes unset-alias.
625 set-function function-name function-string
627 Creates a function with the name function-name in the user's en‐
628 vironment with the function body function-string. For some
629 shells, functions are not possible and the command has no ef‐
630 fect. When a modulefile is unloaded, set-function becomes
631 unset-function.
632 setenv variable value
634 Set environment variable to value. The setenv command will also
635 change the process' environment. A reference using Tcl's env as‐
636 sociative array will reference changes made with the setenv com‐
637 mand. Changes made using Tcl's env associative array will NOT
638 change the user's environment variable like the setenv command.
639 An environment change made this way will only affect the module
640 parsing process. The setenv command is also useful for changing
641 the environment prior to the exec or system command. When a mod‐
642 ulefile is unloaded, setenv becomes unsetenv. If the environment
643 variable had been defined it will be overwritten while loading
644 the modulefile. A subsequent unload will unset the environment
645 variable - the previous value cannot be restored! (Unless you
646 handle it explicitly ... see below.)
647 source-sh shell script [arg...]
649 Evaluate with shell the designated script with defined arguments
650 to find out the environment changes it does. Those changes ob‐
651 tained by comparing environment prior and after script evalua‐
652 tion are then translated into corresponding modulefile commands,
653 which are then applied during modulefile evaluation as if they
654 were directly written in it.
655 When modulefile is unloaded, environment changes done are re‐
657 served by evaluating in the unload context the resulting module‐
658 file commands, which were recorded in the MODULES_LMSOURCESH en‐
659 vironment variable at load time.
660 Changes on environment variables, shell aliases, shell functions
662 and current working directory are tracked.
663 Shell could be specified as a command name or a fully qualified
665 pathname. The following shells are supported: sh, dash, csh,
666 tcsh, bash, ksh, ksh93, zsh and fish.
667 system string
669 Run string command through shell. On Unix, command is passed to
670 the /bin/sh shell whereas on Windows it is passed to cmd.exe.
671 modulecmd.tcl redirects stdout to stderr since stdout would be
672 parsed by the evaluating shell. The exit status of the executed
673 command is returned.
674 uname field
676 Provide lookup of system information. Most field information are
677 retrieved from the tcl_platform array (see the tclvars(n) man
678 page). Uname will return the string unknown if information is
679 unavailable for the field.
680 uname will invoke the uname(1) command in order to get the oper‐
682 ating system version and domainname(1) to figure out the name of
683 the domain.
684 field values are:
686 • sysname: the operating system name
688 • nodename: the hostname
690 • domain: the name of the domain
692 • release: the operating system release
694 • version: the operating system version
696 • machine: a standard name that identifies the system's hardware
698 unset-alias alias-name
700 Unsets an alias with the name alias-name in the user's environ‐
701 ment.
702 unset-function function-name
704 Removes a function with the name function-name from the user's
705 environment.
706 unsetenv variable [value]
708 Unsets environment variable. However, if there is an optional
709 value, then when unloading a module, it will set variable to
710 value. The unsetenv command changes the process' environment
711 like setenv.
712 versioncmp version1 version2
714 Compare version string version1 against version string version2.
715 Returns -1, 0 or 1 respectively if version1 is less than, equal
716 to or greater than version2.
717 x-resource [resource-string|filename]
719 Merge resources into the X11 resource database. The resources
720 are used to control look and behavior of X11 applications. The
721 command will attempt to read resources from filename. If the ar‐
722 gument isn't a valid file name, then string will be interpreted
723 as a resource. Either filename or resource-string is then passed
724 down to be xrdb(1) command.
725 modulefiles that use this command, should in most cases contain
727 one or more x-resource lines, each defining one X11 resource.
728 The DISPLAY environment variable should be properly set and the
729 X11 server should be accessible. If x-resource can't manipulate
730 the X11 resource database, the modulefile will exit with an er‐
731 ror message.
732 Examples:
734 x-resource /u2/staff/leif/.xres/Ileaf
736 The content of the Ileaf file is merged into the X11 resource
737 database.
738 x-resource [glob ~/.xres/ileaf]
740 The Tcl glob function is used to have the modulefile read
741 different resource files for different users.
742 x-resource {Ileaf.popup.saveUnder: True}
744 Merge the Ileaf resource into the X11 resource database.
745
747 ModulesCurrentModulefile
748 The ModulesCurrentModulefile variable contains the full pathname
749 of the modulefile being interpreted.
750 ModuleTool
752 The ModuleTool variable contains the name of the module imple‐
753 mentation currently in use. The value of this variable is set to
754 Modules for this implementation.
755 ModuleToolVersion
757 The ModuleToolVersion variable contains the version of the mod‐
758 ule implementation currently in use. The value of this variable
759 is set to 4.7.1 for this version of Modules.
760
762 Every directory in MODULEPATH is searched to find the modulefile. A di‐
763 rectory in MODULEPATH can have an arbitrary number of sub-directories.
764 If the user names a modulefile to be loaded which is actually a direc‐
765 tory, the directory is opened and a search begins for an actual module‐
766 file. First, modulecmd.tcl looks for a file with the name .modulerc in
767 the directory. If this file exists, its contents will be evaluated as
768 if it was a modulefile to be loaded. You may place module-version,
769 module-alias and module-virtual commands inside this file.
770 Additionally, before seeking for .modulerc files in the module direc‐
772 tory, the global modulerc file and the .modulerc file found at the root
773 of the modulepath directory are sourced, too. If a named version de‐
774 fault now exists for the modulefile to be loaded, the assigned module‐
775 file now will be sourced. Otherwise the file .version is looked up in
776 the module directory.
777 If the .version file exists, it is opened and interpreted as Tcl code
779 and takes precedence over a .modulerc file in the same directory. If
780 the Tcl variable ModulesVersion is set by the .version file, mod‐
781 ulecmd.tcl will use the name as if it specifies a modulefile in this
782 directory. This will become the default modulefile in this case. Mod‐
783 ulesVersion cannot refer to a modulefile located in a different direc‐
784 tory.
785 If ModulesVersion is a directory, the search begins anew down that di‐
787 rectory. If the name does not match any files located in the current
788 directory, the search continues through the remaining directories in
789 MODULEPATH.
790 Every .version and .modulerc file found is interpreted as Tcl code. The
792 difference is that .version only applies to the current directory, and
793 the .modulerc applies to the current directory and all subdirectories.
794 Changes made in these files will affect the subsequently interpreted
795 modulefile.
796 If no default version may be figured out, an implicit default is se‐
798 lected when this behavior is enabled (see MODULES_IMPLICIT_DEFAULT in
799 module(1)). If disabled, module names should be fully qualified when no
800 explicit default is defined for them, otherwise no default version is
801 found and an error is returned. If enabled, then the highest numeri‐
802 cally sorted modulefile, virtual module or module alias under the di‐
803 rectory will be used. The dictionary comparison method of the lsort(n)
804 Tcl command is used to achieve this sort. If highest numerically sorted
805 element is an alias, search continues on its modulefile target.
806 For example, it is possible for a user to have a directory named X11
808 which simply contains a .version file specifying which version of X11
809 is to be loaded. Such a file would look like:
810 #%Module1.0
812 ##
813 ## The desired version of X11
814 ##
815 set ModulesVersion "R4"
816 The equivalent .modulerc would look like:
818 #%Module1.0
820 ##
821 ## The desired version of X11
822 ##
823 module-version "./R4" default
824 If the extended default mechanism is enabled (see MODULES_EXTENDED_DE‐
826 FAULT in module(1)) the module version specified is matched against
827 starting portion of existing module versions, where portion is a sub‐
828 string separated from the rest of version string by a . character.
829 When the implicit default mechanism and the Advanced module version
831 specifiers are both enabled, a default and latest symbolic versions are
832 automatically defined for each module name (also at each directory
833 level in case of deep modulefile). Unless a symbolic version, alias, or
834 regular module version already exists for these version names.
835 If user names a modulefile that cannot be found in the first modulepath
837 directory, modulefile will be searched in next modulepath directory and
838 so on until a matching modulefile is found. If search goes through a
839 module alias or a symbolic version, this alias or symbol is resolved by
840 first looking at the modulefiles in the modulepath where this alias or
841 symbol is defined. If not found, resolution looks at the other mod‐
842 ulepaths in their definition order.
843 When locating modulefiles, if a .modulerc, a .version, a directory or a
845 modulefile cannot be read during the search it is simply ignored with
846 no error message produced. Visibility of modulefiles can thus be
847 adapted to the rights the user has been granted. Exception is made when
848 trying to directly access a directory or a modulefile. In this case,
849 the access issue is returned as an error message.
850 Depending on their name, their file permissions or the use of specific
852 modulefile commands, modulefile, virtual module, module alias or sym‐
853 bolic version may be set hidden which impacts available modules search
854 or module selection processes (see Hiding modulefiles section below).
855
857 A modulefile, virtual module, module alias or symbolic version whose
858 name or element in their name starts with a dot character (.) or who
859 are targeted by a module-hide command are considered hidden. Hidden
860 modules are not displayed or taken into account except if they are ex‐
861 plicitly named (e.g., foo/1.2.3 or foo/.2.0 not foo). If module has
862 been hidden with the --soft option of the module-hide command set, it
863 is not considered hidden if the root name of the query to search it
864 matches module root name (e.g., searching foo will return a foo/1.2.3
865 modulefile targeted by a module-hide --soft command). If module has
866 been hidden with the --hard option of the module-hide command set, it
867 is always considered hidden thus it is never displayed nor taken into
868 account even if it is explicitly named.
869 A modulefile, virtual module, module alias or symbolic version who are
871 targeted by a module-hide --hard command and a module-forbid command or
872 whose file access permissions are restricted are considered hard-hidden
873 and forbidden. Such modules are not displayed or taken into account.
874 When explicitly named for evaluation selection, such modules are un‐
875 veiled to return an access error.
876 A symbolic version-name assigned to a hidden module is displayed or
878 taken into account only if explicitly named and if module is not
879 hard-hidden. Non-hidden module alias targeting a hidden modulefile ap‐
880 pears like any other non-hidden module alias. Finally, a hidden sym‐
881 bolic version targeting a non-hidden module is displayed or taken into
882 account only if not hard-hidden and explicitly named to refer to its
883 non-hidden target.
884 The automatic version symbols (e.g., default and latest) are unaffected
886 by hiding. Moreover when a regular default or latest version is set
887 hidden, the corresponding automatic version symbol takes the left spot.
888 For instance, if foo/default which targets foo/1.2.3 is set hard-hid‐
889 den, the default automatic version symbol will be set onto foo/2.1.3,
890 the highest available version of foo.
891 When loading a modulefile or a virtual module targeted by a module-hide
893 --hidden-loaded command, this module inherits the hidden-loaded tag.
894 Hidden loaded modules are not reported among list sub-command results.
895 If the --all is set on avail, aliases, whatis or search sub-commands,
897 hidden modules are taken into account in search. Hard-hidden modules
898 are unaffected by this option.
899 If the --all is set on list sub-command, hidden loaded modules are in‐
901 cluded in result output.
902
904 When the advanced module version specifiers mechanism is enabled (see
905 MODULES_ADVANCED_VERSION_SPEC in module(1)), the specification of mod‐
906 ulefile passed on Modules specific Tcl commands changes. After the
907 module name a version constraint prefixed by the @ character may be
908 added. It could be directly appended to the module name or separated
909 from it with a space character.
910 Constraints can be expressed to refine the selection of module version
912 to:
913 • a single version with the @version syntax, for instance foo@1.2.3
915 syntax will select module foo/1.2.3
916 • a list of versions with the @version1,version2,... syntax, for in‐
918 stance foo@1.2.3,1.10 will match modules foo/1.2.3 and foo/1.10
919 • a range of versions with the @version1:, @:version2 and @ver‐
921 sion1:version2 syntaxes, for instance foo@1.2: will select all ver‐
922 sions of module foo greater than or equal to 1.2, foo@:1.3 will se‐
923 lect all versions less than or equal to 1.3 and foo@1.2:1.3 matches
924 all versions between 1.2 and 1.3 including 1.2 and 1.3 versions
925 Advanced specification of single version or list of versions may bene‐
927 fit from the activation of the extended default mechanism (see MOD‐
928 ULES_EXTENDED_DEFAULT in module(1)) to use an abbreviated notation like
929 @1 to refer to more precise version numbers like 1.2.3. Range of ver‐
930 sions on its side natively handles abbreviated versions.
931 In order to be specified in a range of versions or compared to a range
933 of versions, the version major element should corresponds to a number.
934 For instance 10a, 1.2.3, 1.foo are versions valid for range comparison
935 whereas default or foo.2 versions are invalid for range comparison.
936 If the implicit default mechanism is also enabled (see MODULES_IM‐
938 PLICIT_DEFAULT in module(1)), a default and latest symbolic versions
939 are automatically defined for each module name (also at each directory
940 level for deep modulefiles). These automatic version symbols are de‐
941 fined unless a symbolic version, alias, or regular module version al‐
942 ready exists for these default or latest version names. Using the
943 mod@latest (or mod/latest) syntax ensures highest available version
944 will be selected.
945
947 Users can request help about a specific modulefile through the mod‐
948 ule(1) command. The modulefile can print helpful information or start
949 help oriented programs by defining a ModulesHelp subroutine. The sub‐
950 routine will be called when the module help modulefile command is used.
951
953 Users can request test of a specific modulefile through the module(1)
954 command. The modulefile can perform some sanity checks on its defini‐
955 tion or on its underlying programs by defining a ModulesTest subrou‐
956 tine. The subroutine will be called when the module test modulefile
957 command is used. The subroutine should return 1 in case of success. If
958 no or any other value is returned, test is considered failed.
959
961 The module display modulefile command will detail all changes that will
962 be made to the environment. After displaying all of the environment
963 changes modulecmd.tcl will call the ModulesDisplay subroutine. The Mod‐
964 ulesDisplay subroutine is a good place to put additional descriptive
965 information about the modulefile.
966
968 See the ENVIRONMENT section in the module(1) man page.
969
971 module(1), ml(1), Tcl(n), TclX(n), id(1), xrdb(1), exec(n), uname(1),
972 domainname(1), tclvars(n), lsort(n)
973
975 Tcl was developed by John Ousterhout at the University of California at
976 Berkeley.
977 TclX was developed by Karl Lehenbauer and Mark Diekhans.
979
981 1996-1999 John L. Furlani & Peter W. Osel, 1998-2017 R.K.Owen,
982 2002-2004 Mark Lakata, 2004-2017 Kent Mein, 2016-2021 Xavier Delaruelle
9834.7.1 2021-04-06 MODULEFILE(4)