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