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.
22 Each modulefile contains the changes to a user's environment needed to
24 access an application. Tcl is a simple programming language which per‐
25 mits modulefiles to be arbitrarily complex, depending upon the applica‐
26 tion's and the modulefile writer's needs. If support for extended tcl
27 (tclX) has been configured for your installation of the Modules pack‐
28 age, you may use all the extended commands provided by tclX, too.
29 A typical modulefiles is a simple bit of code that set or add entries
31 to the PATH, MANPATH, or other environment variables. Tcl has condi‐
32 tional statements that are evaluated when the modulefile is loaded.
33 This is very effective for managing path or environment changes due to
34 different OS releases or architectures. The user environment informa‐
35 tion is encapsulated into a single modulefile kept in a central loca‐
36 tion. The same modulefile is used by every user on any machine. So,
37 from the user's perspective, starting an application is exactly the
38 same irrespective of the machine or platform they are on.
39 modulefiles also hide the notion of different types of shells. From the
41 user's perspective, changing the environment for one shell looks
42 exactly the same as changing the environment for another shell. This is
43 useful for new or novice users and eliminates the need for statements
44 such as "if you're using the C Shell do this ..., otherwise if you're
45 using the Bourne shell do this ...". Announcing and accessing new soft‐
46 ware is uniform and independent of the user's shell. From the module‐
47 file writer's perspective, this means one set of information will take
48 care of every type of shell.
49
51 The Modules Package uses commands which are extensions to the "stan‐
52 dard" Tool Command Language Tcl(n) package. Unless otherwise specified,
53 the Module commands return the empty string. Some commands behave dif‐
54 ferently when a modulefile is loaded or unloaded. The command descrip‐
55 tions assume the modulefile is being loaded.
56 break
58 This is not a Modules-specific command, it's actually part of Tcl,
59 which has been overloaded similar to the continue and exit commands
60 to have the effect of causing the module not to be listed as loaded
61 and not affect other modules being loaded concurrently. All
62 non-environment commands within the module will be performed up to
63 this point and processing will continue on to the next module on the
64 command line. The break command will only have this effect if not
65 used within a Tcl loop though.
66 An example: Suppose that a full selection of modulefiles are needed
68 for various different architectures, but some of the modulefiles are
69 not needed and the user should be alerted. Having the unnecessary
70 modulefile be a link to the following notavail modulefile will per‐
71 form the task as required.
72 #%Module1.0
74 ## notavail modulefile
75 ##
76 proc ModulesHelp { } {
77 puts stderr "This module does nothing but alert the user"
78 puts stderr "that the [module-info name] module is not available"
79 }
80 module-whatis "Notifies user that module is not available."
82 set curMod [module-info name]
83 if { [ module-info mode load ] } {
84 puts stderr "Note: '$curMod' is not available for [uname sysname]."
85 }
86 break
87 chdir directory
89 Set the current working directory to directory.
90 continue
92 This is not a modules specific command but another overloaded Tcl
93 command and is similar to the break or exit commands except the mod‐
94 ule will be listed as loaded as well as performing any environment
95 or Tcl commands up to this point and then continuing on to the next
96 module on the command line. The continue command will only have this
97 effect if not used within a Tcl loop though.
98 exit [N]
100 This is not a modules specific command but another overloaded Tcl
101 command and is similar to the break or continue commands. However,
102 this command will cause the immediate cessation of this module and
103 any additional ones on the command line. This module and the subse‐
104 quent modules will not be listed as loaded. No environment commands
105 will be performed in the current module.
106 setenv variable value
108 Set environment variable to value. The setenv command will also
109 change the process' environment. A reference using Tcl's env asso‐
110 ciative array will reference changes made with the setenv command.
111 Changes made using Tcl's env associative array will NOT change the
112 user's environment variable like the setenv command. An environment
113 change made this way will only affect the module parsing process.
114 The setenv command is also useful for changing the environment prior
115 to the exec or system command. When a modulefile is unloaded, setenv
116 becomes unsetenv. If the environment variable had been defined it
117 will be overwritten while loading the modulefile. A subsequent
118 unload will unset the environment variable - the previous value can‐
119 not be restored! (Unless you handle it explicitly ... see below.)
120 unsetenv variable [value]
122 Unsets environment variable. However, if there is an optional value,
123 then when unloading a module, it will set variable to value. The
124 unsetenv command changes the process' environment like setenv.
125 getenv variable [value]
127 Returns value of environment variable. If variable is not defined
128 value is returned if set _UNDEFINED_ is returned elsewhere. getenv
129 command should be preferred over Tcl global variable env to query
130 environment variables.
131 append-path [-d C|--delim C|--delim=C] [--duplicates] variable value...
133 See prepend-path.
134 prepend-path [-d C|--delim C|--delim=C] [--duplicates] variable
136 value...
137 Append or prepend value to environment variable. The variable is a
138 colon, or delimiter, separated list such as PATH=directory:direc‐
139 tory:directory. The default delimiter is a colon ':', but an arbi‐
140 trary one can be given by the --delim option. For example a space
141 can be used instead (which will need to be handled in the Tcl spe‐
142 cially by enclosing it in " " or { }). A space, however, can not be
143 specified by the --delim=C form.
144 A reference counter environment variable is also set to increase the
146 number of times value has been added to environment variable. This
147 reference counter environment variable is named by suffixing vari‐
148 able by _modshare.
149 When value is already defined in environement variable, it is not
151 added again except if --duplicates option is set.
152 If the variable is not set, it is created. When a modulefile is
154 unloaded, append-path and prepend-path become remove-path.
155 If value corresponds to the concatenation of multiple elements sepa‐
157 rated by colon, or delimiter, character, each element is treated
158 separately.
159 remove-path [-d C|--delim C|--delim=C] [--index] variable value...
161 Remove value from the colon, or delimiter, separated list in vari‐
162 able. See prepend-path or append-path for further explanation of
163 using an arbitrary delimiter. Every string between colons, or delim‐
164 iters, in variable is compared to value. If the two match, value is
165 removed from variable if its reference counter is equal to 1 or
166 unknown.
167 When --index option is set, value refers to an index in variable
169 list. The string element pointed by this index is set for removal.
170 Reference counter of value in variable denotes the number of times
172 value has been added to variable. This information is stored in
173 environment variable_modshare. When attempting to remove value from
174 variable, relative reference counter is checked and value is removed
175 only if counter is equal to 1 or not defined. Elsewhere value is
176 kept in variable and reference counter is decreased by 1.
177 If value corresponds to the concatenation of multiple elements sepa‐
179 rated by colon, or delimiter, character, each element is treated
180 separately.
181 prereq modulefile...
183 See conflict.
184 conflict modulefile...
186 prereq and conflict control whether or not the modulefile will be
187 loaded. The prereq command lists modulefiles which must have been
188 previously loaded before the current modulefile will be loaded. Sim‐
189 ilarly, the conflict command lists modulefiles which conflict with
190 the current modulefile. If a list contains more than one modulefile,
191 then each member of the list acts as a Boolean OR operation. Multi‐
192 ple prereq and conflict commands may be used to create a Boolean AND
193 operation. If one of the requirements have not been satisfied, an
194 error is reported and the current modulefile makes no changes to the
195 user's environment.
196 If an argument for prereq is a directory and any modulefile from the
198 directory has been loaded, then the prerequisite is met. For exam‐
199 ple, specifying X11 as a prereq means that any version of X11,
200 X11/R4 or X11/R5, must be loaded before proceeding.
201 If an argument for conflict is a directory and any other modulefile
203 from that directory has been loaded, then a conflict will occur. For
204 example, specifying X11 as a conflict will stop X11/R4 and X11/R5
205 from being loaded at the same time.
206 The parameter modulefile may also be a symbolic modulefile name or a
208 modulefile alias.
209 is-loaded [modulefile...]
211 The is-loaded command returns a true value if any of the listed mod‐
212 ulefiles has been loaded or if any modulefile is loaded in case no
213 argument is provided. If a list contains more than one modulefile,
214 then each member acts as a boolean OR operation. If an argument for
215 is-loaded is a directory and any modulefile from the directory has
216 been loaded is-loaded would return a true value.
217 The parameter modulefile may also be a symbolic modulefile name or a
219 modulefile alias.
220 is-saved [collection...]
222 The is-saved command returns a true value if any of the listed col‐
223 lections exists or if any collection exists in case no argument is
224 provided. If a list contains more than one collection, then each
225 member acts as a boolean OR operation.
226 If MODULES_COLLECTION_TARGET is set, a suffix equivalent to the
228 value of this variable is appended to the passed collection name. In
229 case no collection argument is provided, a true value will only be
230 returned if a collection matching currently set target exists.
231 is-used [directory...]
233 The is-used command returns a true value if any of the listed direc‐
234 tories has been enabled in MODULEPATH or if any directory is enabled
235 in case no argument is provided. If a list contains more than one
236 directory, then each member acts as a boolean OR operation.
237 is-avail modulefile...
239 The is-avail command returns a true value if any of the listed mod‐
240 ulefiles exists in enabled MODULEPATH. If a list contains more than
241 one modulefile, then each member acts as a boolean OR operation. If
242 an argument for is-avail is a directory and a modulefile exists in
243 the directory is-avail would return a true value.
244 The parameter modulefile may also be a symbolic modulefile name or a
246 modulefile alias.
247 module [sub-command] [sub-command-args]
249 Contains the same sub-commands as described in the module(1) man
250 page in the Module Sub-Commands section. This command permits a mod‐
251 ulefile to load or unload other modulefiles. No checks are made to
252 ensure that the modulefile does not try to load itself. Often it is
253 useful to have a single modulefile that performs a number of module
254 load commands. For example, if every user on the system requires a
255 basic set of applications loaded, then a core modulefile would con‐
256 tain the necessary module load commands.
257 Command line switches --auto, --no-auto and --force are ignored when
259 passed to a module command set in a modulefile.
260 module-info option [info-args]
262 Provide information about the modulecmd.tcl program's state. Some of
263 the information is specific to the internals of modulecmd.tcl.
264 option is the type of information to be provided, and info-args are
265 any arguments needed.
266 module-info type
268 Returns either "C" or "Tcl" to indicate which module command is
269 being executed, either the "C" version or the Tcl-only version,
270 to allow the modulefile writer to handle any differences between
271 the two.
272 module-info mode [modetype]
274 Returns the current modulecmd.tcl's mode as a string if no mode‐
275 type is given.
276 Returns 1 if modulecmd.tcl's mode is modetype. modetype can be:
278 load, unload, remove, switch, display, help, test or whatis.
279 module-info command [commandname]
281 Returns the currently running modulecmd.tcl's command as a
282 string if no commandname is given.
283 Returns 1 if modulecmd.tcl's command is commandname. commandname
285 can be: load, unload, reload, source, switch, display, avail,
286 aliases, list, whatis, search, purge, restore, help or test.
287 module-info name
289 Return the name of the modulefile. This is not the full pathname
290 for modulefile. See the Modules Variables section for informa‐
291 tion on the full pathname.
292 module-info specified
294 Return the name of the modulefile specified on the command line.
295 module-info shell [shellname]
297 Return the current shell under which modulecmd.tcl was invoked
298 if no shellname is given. The current shell is the first parame‐
299 ter of modulecmd.tcl, which is normally hidden by the module
300 alias.
301 If a shellname is given, returns 1 if modulecmd.tcl's current
303 shell is shellname, returns 0 elsewhere. shellname can be: sh,
304 bash, ksh, zsh, csh, tcsh, fish, tcl, perl, python, ruby, lisp,
305 cmake, r.
306 module-info shelltype [shelltypename]
308 Return the family of the shell under which modulefile was
309 invoked if no shelltypename is given. As of module-info shell
310 this depends on the first parameter of modulecmd.tcl. The output
311 reflects a shell type determining the shell syntax of the com‐
312 mands produced by modulecmd.tcl.
313 If a shelltypename is given, returns 1 if modulecmd.tcl's cur‐
315 rent shell type is shelltypename, returns 0 elsewhere. shell‐
316 typename can be: sh, csh, fish, tcl, perl, python, ruby, lisp,
317 cmake, r.
318 module-info alias name
320 Returns the full modulefile name to which the modulefile alias
321 name is assigned
322 module-info version modulefile
324 Returns the physical module name and version of the passed sym‐
325 bolic version modulefile. The parameter modulefile might either
326 be a full qualified modulefile with name and version, another
327 symbolic modulefile name or a modulefile alias.
328 module-info symbols modulefile
330 Returns a list of all symbolic versions assigned to the passed
331 modulefile. The parameter modulefile might either be a full
332 qualified modulefile with name and version, another symbolic
333 modulefile name or a modulefile alias.
334 module-info loaded modulefile
336 Returns the names of currently loaded modules matching passed
337 modulefile. The parameter modulefile might either be a fully
338 qualified modulefile with name and version or just a directory
339 which in case all loaded modulefiles from the directory will be
340 returned. The parameter modulefile may also be a symbolic mod‐
341 ulefile name or a modulefile alias.
342 module-version modulefile version-name...
344 Assigns the symbolic version-name to the modulefile. This command
345 should be placed in one of the modulecmd.tcl rc files in order to
346 provide shorthand invocations of frequently used modulefile names.
347 The special version-name default specifies the default version to be
349 used for module commands, if no specific version is given. This
350 replaces the definitions made in the .version file in former mod‐
351 ulecmd.tcl releases.
352 The parameter modulefile may be either
354 · a fully or partially qualified modulefile with name / version. If
356 name is '.' then the current directory name is assumed to be the
357 module name. (Use this for deep modulefile directories.)
358 · a symbolic modulefile name
360 · another modulefile alias
362 module-alias name modulefile
364 Assigns the modulefile to the alias name. This command should be
365 placed in one of the modulecmd.tcl rc files in order to provide
366 shorthand invocations of frequently used modulefile names.
367 The parameter modulefile may be either
369 · a fully qualified modulefile with name and version
371 · a symbolic modulefile name
373 · another modulefile alias
375 module-virtual name modulefile
377 Assigns the modulefile to the virtual module name. This command
378 should be placed in rc files in order to define virtual modules.
379 A virtual module stands for a module name associated to a module‐
381 file. The modulefile is the script interpreted when loading or
382 unloading the virtual module which appears or can be found with its
383 virtual name.
384 The parameter modulefile corresponds to the relative or absolute
386 file location of a modulefile.
387 module-whatis string
389 Defines a string which is displayed in case of the invocation of the
390 module whatis command. There may be more than one module-whatis line
391 in a modulefile. This command takes no actions in case of load, dis‐
392 play, etc. invocations of modulecmd.tcl.
393 The string parameter has to be enclosed in double-quotes if there's
395 more than one word specified. Words are defined to be separated by
396 whitespace characters (space, tab, cr).
397 set-alias alias-name alias-string
399 Sets an alias or function with the name alias-name in the user's
400 environment to the string alias-string. For some shells, aliases are
401 not possible and the command has no effect. When a modulefile is
402 unloaded, set-alias becomes unset-alias.
403 unset-alias alias-name
405 Unsets an alias with the name alias-name in the user's environment.
406 set-function function-name function-string
408 Creates a function with the name function-name in the user's envi‐
409 ronment with the function body function-string. For some shells,
410 functions are not possible and the command has no effect. When a
411 modulefile is unloaded, set-function becomes unset-function.
412 unset-function function-name
414 Removes a function with the name function-name from the user's envi‐
415 ronment.
416 system string
418 Run string command through shell. On Unix, command is passed to the
419 /bin/sh shell whereas on Windows it is passed to cmd.exe. mod‐
420 ulecmd.tcl redirects stdout to stderr since stdout would be parsed
421 by the evaluating shell. The exit status of the executed command is
422 returned.
423 uname field
425 Provide lookup of system information. Most field information are
426 retrieved from the tcl_platform array (see tclvars(n) man page).
427 Uname will return the string "unknown" if information is unavailable
428 for the field.
429 uname will invoke uname(1) command in order to get the operating
431 system version and domainname(1) to figure out the name of the
432 domain.
433 field values are:
435 · sysname: the operating system name
437 · nodename: the hostname
439 · domain: the name of the domain
441 · release: the operating system release
443 · version: the operating system version
445 · machine: a standard name that identifies the system's hardware
447 x-resource [resource-string|filename]
449 Merge resources into the X11 resource database. The resources are
450 used to control look and behavior of X11 applications. The command
451 will attempt to read resources from filename. If the argument isn't
452 a valid file name, then string will be interpreted as a resource.
453 Either filename or resource-string is then passed down to be xrdb(1)
454 command.
455 modulefiles that use this command, should in most cases contain one
457 or more x-resource lines, each defining one X11 resource. The DIS‐
458 PLAY environment variable should be properly set and the X11 server
459 should be accessible. If x-resource can't manipulate the X11
460 resource database, the modulefile will exit with an error message.
461 Examples:
463 x-resource /u2/staff/leif/.xres/Ileaf
465 The content of the Ileaf file is merged into the X11 resource
466 database.
467 x-resource [glob ~/.xres/ileaf]
469 The Tcl glob function is used to have the modulefile read dif‐
470 ferent resource files for different users.
471 x-resource {Ileaf.popup.saveUnder: True}
473 Merge the Ileaf resource into the X11 resource database.
474
476 The ModulesCurrentModulefile variable contains the full pathname of the
477 modulefile being interpreted.
478
480 Every directory in MODULEPATH is searched to find the modulefile. A
481 directory in MODULEPATH can have an arbitrary number of sub-directo‐
482 ries. If the user names a modulefile to be loaded which is actually a
483 directory, the directory is opened and a search begins for an actual
484 modulefile. First, modulecmd.tcl looks for a file with the name .mod‐
485 ulerc in the directory. If this file exists, its contents will be eval‐
486 uated as if it was a modulefile to be loaded. You may place module-ver‐
487 sion, module-alias and module-virtual commands inside this file.
488 Additionally, before seeking for .modulerc files in the module direc‐
490 tory, the global modulerc file is sourced, too. If a named version
491 default now exists for the modulefile to be loaded, the assigned mod‐
492 ulefile now will be sourced. Otherwise the file .version is looked up
493 in the directory.
494 If the .version file exists, it is opened and interpreted as Tcl code
496 and takes precedence over a .modulerc file in the same directory. If
497 the Tcl variable ModulesVersion is set by the .version file, mod‐
498 ulecmd.tcl will use the name as if it specifies a modulefile in this
499 directory. This will become the default modulefile in this case. Mod‐
500 ulesVersion cannot refer to a modulefile located in a different direc‐
501 tory.
502 If ModulesVersion is a directory, the search begins anew down that
504 directory. If the name does not match any files located in the current
505 directory, the search continues through the remaining directories in
506 MODULEPATH.
507 Every .version and .modulerc file found is Tcl interpreted. The differ‐
509 ence is that .version only applies to the current directory, and the
510 .modulerc applies to the current directory and all subdirectories.
511 Changes made in these files will affect the subsequently interpreted
512 modulefile.
513 If no default version may be figured out, then the highest numerically
515 sorted modulefile, virtual module or module alias under the directory
516 will be used. The dictionary comparison method of the lsort(n) Tcl com‐
517 mand is used to achieve this sort. If highest numerically sorted ele‐
518 ment is an alias, search continues on its modulefile target.
519 For example, it is possible for a user to have a directory named X11
521 which simply contains a .version file specifying which version of X11
522 is to be loaded. Such a file would look like:
523 #%Module1.0
525 ##
526 ## The desired version of X11
527 ##
528 set ModulesVersion "R4"
529 The equivalent .modulerc would look like:
531 #%Module1.0
533 ##
534 ## The desired version of X11
535 ##
536 module-version "./R4" default
537 If user names a modulefile that cannot be found in the first modulepath
539 directory, modulefile will be searched in next modulepath directory and
540 so on until a matching modulefile is found. If search goes through a
541 module alias or a symbolic version, this alias or symbol is resolved by
542 first looking at the modulefiles in the modulepath where this alias or
543 symbol is defined. If not found, resolution looks at the other mod‐
544 ulepaths in their definition order.
545 When locating modulefiles, if a .modulerc, a .version, a directory or a
547 modulefile cannot be read during the search it is simply ignored with
548 no error message produced. Visibility of modulefiles can thus be
549 adapted to the rights the user has been granted. Exception is made when
550 trying to directly access a directory or a modulefile. In this case,
551 the access issue is returned as an error message.
552 A modulefile whose name or element in its name starts with a '.' dot is
554 considered hidden. Hidden modulefile is not displayed or taken into
555 account except if it is explicitly named. By inheritance, a symbolic
556 version-name assigned to a hidden modulefile is displayed or taken into
557 account only if explicitly named. Module alias targeting a hidden mod‐
558 ulefile appears like any other module alias.
559
561 Users can request help about a specific modulefile through the mod‐
562 ule(1) command. The modulefile can print helpful information or start
563 help oriented programs by defining a ModulesHelp subroutine. The sub‐
564 routine will be called when the module help modulefile command is used.
565
567 Users can request test of a specific modulefile through the module(1)
568 command. The modulefile can perform some sanity checks on its defini‐
569 tion or on its underlying programs by defining a ModulesTest subrou‐
570 tine. The subroutine will be called when the module test modulefile
571 command is used. The subroutine should return 1 in case of success. If
572 no or any other value is returned, test is considered failed.
573
575 The module display modulefile command will detail all changes that will
576 be made to the environment. After displaying all of the environment
577 changes modulecmd.tcl will call the ModulesDisplay subroutine. The Mod‐
578 ulesDisplay subroutine is a good place to put additional descriptive
579 information about the modulefile.
580
582 MODULEPATH
583 Path of directories containing modulefiles.
584
586 module(1), Tcl(n), TclX(n), xrdb(1), exec(n), uname(1), domainname(1),
587 tclvars(n), lsort(n)
588
590 Tcl was developed by John Ousterhout at the University of California at
591 Berkeley.
592 TclX was developed by Karl Lehenbauer and Mark Diekhans.
594
596 1996-1999 John L. Furlani & Peter W. Osel, 1998-2017 R.K.Owen,
597 2002-2004 Mark Lakata, 2004-2017 Kent Mein, 2016-2019 Xavier Delaruelle
5984.2.4 2019-04-26 MODULEFILE(4)