1MODULEFILE(4) Modules configuration MODULEFILE(4)
2
6 modulefile - files containing Tcl code for the Modules package
7
9 modulefiles are written in the Tool Command Language, Tcl(3) and are
10 interpreted by the modulecmd program via the module(1) user interface.
11 modulefiles can be loaded, unloaded, or switched on-the-fly while the
12 user is working; and can be used to implement site policies regarding
13 the access and use of applications.
14 A modulefile begins with the magic cookie, '#%Module'. A version
16 number may be placed after this string. The version number is useful
17 as the modulefile format may change. If a version number doesn't
18 exist, then modulecmd will assume the modulefile is compatible with the
19 latest version. The current modulefile version is 1.0. Files without
20 the magic cookie will not be interpreted by modulecmd.
21 Each modulefile contains the changes to a user's environment needed to
23 access an application. Tcl is a simple programming language which
24 permits modulefiles to be arbitrarily complex, depending upon the
25 application's and the modulefile writer's needs. If support for
26 extended tcl (tclX) has been configured for your installation of the
27 Modules package, you may use all the extended commands provided by
28 tclX, too.
29 A typical modulefile is a simple bit of code that set or add entries to
31 the PATH, MANPATH, or other environment variables. Tcl has conditional
32 statements that are evaluated when the modulefile is loaded. This is
33 very effective for managing path or environment changes due to
34 different OS releases or architectures. The user environment
35 information is encapsulated into a single modulefile kept in a central
36 location. The same modulefile is used by every user on any machine.
37 So, 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
41 the user's perspective, changing the environment for one shell looks
42 exactly the same as changing the environment for another shell. This
43 is useful for new or novice users and eliminates the need for
44 statements such as "if you're using the C Shell do this ..., otherwise
45 if you're using the Bourne shell do this ..." Announcing and accessing
46 new software is uniform and independent of the user's shell. From the
47 modulefile writer's perspective, this means one set of information will
48 take care of every type of shell.
49
51 The Modules Package uses commands which are extensions to the
52 "standard" Tool Command Language Tcl(3) package. Unless otherwise
53 specified, the Module commands return the empty string. Some commands
54 behave differently when a modulefile is loaded or unloaded. The
55 command descriptions assume the modulefile is being loaded.
56 break
58 This is not a Modules-specific command, it's actually part of
59 Tcl, which has been overloaded similar to the continue and exit
60 commands to have the effect of causing the module not to be
61 listed as loaded and not affect other modules being loaded
62 concurrently. All non-environment commands within the module
63 will be performed up to this point and processing will continue
64 on to the next module on the command line. The break command
65 will only have this effect if not used within a Tcl loop though.
66 An example: Suppose that a full selection of modulefiles are
68 needed for various different architectures, but some of the
69 modulefiles are not needed and the user should be alerted.
70 Having the unnecessary modulefile be a link to the following
71 notavail modulefile will perform 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
88 chdir directory
91 Set the current working directory to directory.
92 continue
95 This is not a modules specific command but another overloaded
96 Tcl command and is similar to the break or exit commands except
97 the module will be listed as loaded as well as performing any
98 environment or Tcl commands up to this point and then continuing
99 on to the next module on the command line. The continue command
100 will only have this effect if not used within a Tcl loop though.
101 exit [N]
104 This is not a modules specific command but another overloaded
105 Tcl command and is similar to the break or continue commands.
106 However, this command will cause the immediate cessation of this
107 module and any additional ones on the command line. This module
108 and the subsequent modules will not be listed as loaded. No
109 environment commands will be performed in the current module.
110 The integer value N after the exit command will be used as an
112 command exit value; however, some shells (bash being one of
113 them) do not carry this value through an eval though. For bash
114 and those Bourne shells (/bin/sh) being emulated by the bash
115 will have return a non-zero value as a result of test 0 = 1
116 being appended to the evaluate string.
117 setenv variable value
120 Set environment variable to value. The setenv command will also
121 change the process' environment. A reference using Tcl's env
122 associative array will reference changes made with the setenv
123 command. Changes made using Tcl's env associative array will
124 NOT change the user's environment variable like the setenv
125 command. An environment change made this way will only affect
126 the module parsing process. The setenv command is also useful
127 for changing the environment prior to the exec or system
128 command. When a modulefile is unloaded, setenv becomes
129 unsetenv. If the environment variable had been defined it will
130 be overwritten while loading the modulefile. A subsequent
131 unload will unset the environment variable - the previous value
132 cannot be restored! (Unless you handle it explicitly ... see
133 below.)
134 unsetenv variable [value]
136 Unsets environment variable. However, if there is an optional
137 value, then when unloading a module, it will set variable to
138 value. The unsetenv command changes the process' environment
139 like setenv.
140 append-path [ -d C | --delim C | --delim=C ] variable value
142 prepend-path [ -d C | --delim C | --delim=C ] variable value
143 Append or prepend value to environment variable. The variable
144 is a colon, or delimiter, separated list such as
145 "PATH=directory:directory:directory". The default delimiter is
146 a colon ':', but an arbitrary one can be given by the --delim
147 option. For example a space can be used instead (which will
148 need to be handled in the Tcl specially by enclosing it in " "
149 or { }). A space, however, can not be specified by the
150 --delim=C form.
151 If the variable is not set, it is created. When a modulefile is
153 unloaded, append-path and prepend-path become remove-path.
154 remove-path [ -d C | --delim C | --delim=C ] variable value
156 Remove value from the colon, or delimiter, separated list in
157 variable. See prepend-path or append-path for further
158 explanation of using an arbitrary delimiter. Every string
159 between colons, or delimiters, in variable is compared to value.
160 If the two match, value is removed from variable.
161 prereq modulefile [ modulefile ... ]
163 conflict modulefile [ modulefile ... ]
164 prereq and conflict control whether or not the modulefile will
165 be loaded. The prereq command lists modulefiles which must have
166 been previously loaded before the current modulefile will be
167 loaded. Similarly, the conflict command lists modulefiles which
168 conflict with the current modulefile. If a list contains more
169 than one modulefile, then each member of the list acts as a
170 Boolean OR operation. Multiple prereq and conflict commands may
171 be used to create a Boolean AND operation. If one of the
172 requirements have not been satisfied, an error is reported and
173 the current modulefile makes no changes to the user's
174 environment.
175 If an argument for prereq is a directory and any modulefile from
177 the directory has been loaded, then the prerequisite is met.
178 For example, specifying X11 as a prereq means that any version
179 of X11, X11/R4 or X11/R5, must be loaded before proceeding.
180 If an argument for conflict is a directory and any other
182 modulefile from that directory has been loaded, then a conflict
183 will occur. For example, specifying X11 as a conflict will stop
184 X11/R4 and X11/R5 from being loaded at the same time.
185 is-loaded modulefile [ modulefile ... ]
187 The is-loaded command returns a true value if any of the listed
188 modulefiles has been loaded. If a list contains more than one
189 modulefile, then each member acts as a boolean OR operation. If
190 an argument for is-loaded is a directory and any modulefile from
191 the directory has been loaded is-loaded would return a true
192 value.
193 module [ sub-command ] [ sub-command-args ]
195 Contains the same sub-commands as described in the module(1) man
196 page in the Module Sub-Commands section. This command permits a
197 modulefile to load or remove other modulefiles. No checks are
198 made to ensure that the modulefile does not try to load itself.
199 Often it is useful to have a single modulefile that performs a
200 number of module load commands. For example, if every user on
201 the system requires a basic set of applications loaded, then a
202 core modulefile would contain the necessary module load
203 commands.
204 module-info option [ info-args ]
206 Provide information about the modulecmd program's state. Some
207 of the information is specific to the internals of modulecmd.
208 option is the type of information to be provided, and info-args
209 are any arguments needed.
210 module-info flags
212 Returns the integer value of modulecmd's flags state.
213 module-info mode [modetype]
214 Returns the current modulecmd's mode as a string if no
215 modetype is given.
216 Returns 1 if modulecmd's mode is modetype. modetype can
218 be: load, remove, display, help, whatis, switch, switch1,
219 switch2, or switch3.
220 module-info name
222 Return the name of the modulefile. This is not the full
223 pathname for modulefile. See the Modules Variables
224 section for information on the full pathname.
225 module-info specified
227 Return the name of the modulefile specified on the
228 command line.
229 module-info shell
231 Return the current shell under which modulecmd was
232 invoked. This is the first parameter of modulecmd, which
233 is normally hidden by the module alias.
234 module-info shelltype
236 Return the family of the shell under which modulefile was
237 invoked. As of module-info shell this depends on the
238 first parameter of modulecmd. The output reflects a shell
239 type determining the shell syntax of the commands
240 produced by modulecmd.
241 module-info alias name
243 Returns the full module file name to which the module
244 file alias name is assigned
245 module-info version module-file
247 Returns a list of all symbolic versions assigned to the
248 passed module-file. The paremeter module-file might
249 either be a full qualified module file with name and
250 version, another symbolic module file name or a module
251 file alias.
252 module-version module-file version-name [version-name ...]
254 Assigns the symbolic version-name to the module file module-file
255 This command should be placed in one of the modulecmd rc files
256 in order to provide shorthand invocations of frequently used
257 module file names.
258 The special version-name default specifies the default version
260 to be used for module commands, if no specific version is given.
261 This replaces the definitions made in the .version file in
262 former modulecmd releases.
263 The parameter module-file may be either
265 a fully qualified modulefile with name and version
267 a symbolic module file name
268 another module file alias
269 module-alias name module-file
271 Assignes the module file module-file to the alias name. This
272 command should be placed in one of the modulecmd rc files in
273 order to provide shorthand invocations of frequently used module
274 file names.
275 The parameter module-file may be either
277 a fully qualified modulefile with name and version
279 a symbolic module file name
280 another module file alias
281 module-trace {on|off} [command [command ...]] [-module modulefile
283 [modulefile ...]]
284 Switches tracing on or off. Without parameters this command will
285 affect globally all tracing setups for all commands and
286 modulefiles. The command parameter may be used to affect tracing
287 of specified module commands only and the switch -module finally
288 limits the affect of the module-trace command to a well defined
289 set of module files.
290 The command may be one of the following
292 avail - 'module avail' command
294 clear - 'module clear' command
295 display - 'module display' command
296 init - 'module init' command
297 help - 'module help' command
298 list - 'module list' command
299 load - 'module load' command
300 purge - 'module purge' command
301 switch - 'module switch' command
302 unuse - 'module unuse' command
303 unload - 'module unload' command
304 update - 'module update' command
305 use - 'module use' command
306 The module parameter specifies a set of module files using TCL
308 regular expressions. For example
309 .* will affect all module files
311 */2.0 affects all module files at version 2.0
312 gnu/.* affects all versions of the gnu modulefile
313 gnu/2.0 affects only version 2.0 of the gnu modulefile
314 The module parameter is prepended to the current tracing pattern
316 list for the specified module command. It is evaluated from the
317 left to the right. The first matching pattern defines the
318 tracing parameter.
319 The internal trace pattern list is stored as a colon separated
321 list. In advanced user level only, colons may be specified on
322 the module parameter of the module-trace command. This will
323 directly take effect in the internal trace pattern list. In
324 novice or expert user level a warning messge will be generated.
325 module-user level
327 Defines the user level under wich module-cmd runs. This takes
328 effect on the error messages being produced and on the behavior
329 of modulecmd in case of detecting an outage.
330 The level parameter specifies the user level and may be one of
332 the following values:
333 advanced, adv - advanced user level
335 expert, exp - expert user level
336 novice, nov - novice user level
337 module-verbosity {on|off}
339 Switches verbose modulecmd message display on or off.
340 module-log error-weight log-facility
342 Defines whether error messages of the specified weight should be
343 logged and conditionally assignes a log-facility.
344 The error-weight parameter specifies the error level to be
346 logged. It may be one of the following values:
347 verb - verbose messages
349 info - informal messages
350 debug - debugging messages
351 trace - tracing output
352 warn - warnings
353 prob - problems (normally the modulecmd may be completed)
354 error - errors (which normally leads to unsuccessful end
355 of the modulecmd)
356 fatal - fatal system errors
357 panic - very fatal system errors, e.g. internal program
358 inconsistencies.
359 The log-facility parameter specifies the log destination. This
361 may either switch off logging for the specified error-weight,
362 direct log messages to a special stream or a file or specify a
363 syslog facility for logging. The following values are allowed:
364 stderr, stdout - predefined output streams for normal and
366 error outputs. Note, that stdout is normally used for
367 passing parameters to the invoking shell. Directing error
368 output to this stream might screw up the modulecmd
369 integration to your shell.
370 a syslog facility - directs logging to the syslog. See
371 syslog.conf(4) for detailed description of the valid
372 syslog facilities.
373 null, none - will suppress logging of the specified
374 error-weight.
375 a filename - is recognized by the first character being
376 either a '.' or a '/'. You must have write permission to
377 the file you specify.
378 module-whatis string
380 Defines a string which is displayed in case of the invocation of
381 the 'module whatis' command. There may be more than one module-
382 whatis line in a modulefile. This command takes no actions in
383 case of load, display, etc. invocations of modulecmd.
384 The string parameter has to be enclosed in double-quotes if
386 there's more than one word specified. Words are defined to be
387 separated by whitespace characters (space, tab, cr).
388 set-alias alias-name alias-string
390 Sets an alias or function with the name alias-name in the user's
391 environment to the string alias-string. Arguments can be
392 specified using the Bourne Shell style of function arguments.
393 If the string contains "$1", then this will become the first
394 argument when the alias is interpreted by the shell. The string
395 "$*" corresponds to all of the arguments given to the alias.
396 The character '$' may be escaped using the '\' character.
397 For some shells, aliases are not possible and the command has no
399 effect. For Bourne shell derivatives, a shell function will be
400 written (if supported) to give the impression of an alias. When
401 a modulefile is unloaded, set-alias becomes unset-alias.
402 unset-alias alias-name
404 Unsets an alias with the name alias-name in the user's
405 environment. If the shell supports functions then the shell is
406 instructed to unset function alias-name.
407 system string
409 Pass string to the C library routine system(3). For the
410 system(3) call modulecmd redirects stdout to stderr since stdout
411 would be parsed by the evaluating shell. The exit status of the
412 executed command is returned.
413 uname field
415 Provide fast lookup of system information on systems that
416 support uname(3). uname is significantly faster than using
417 system to execute a program to return host information. If
418 uname(3) is not available, gethostname(3) or some program will
419 make the nodename available. uname will return the string
420 "unknown" if information is unavailable for the field.
421 uname will invoke getdomainname in order to figure out the name
423 of the domain.
424 field values are:
426 sysname - the operating system name
428 nodename - the hostname
429 domain - the name of the domain
430 release - the operating system release
431 version - the operating system version
432 machine - a standard name that identifies the system's
433 hardware
434 x-resource resource-string
436 x-resource filename
437 Merge resources into the X11 resource database. The resources
438 are used to control look and behavior of X11 applications. The
439 command will attempt to read resources from filename. If the
440 argument isn't a valid file name, then string will be
441 interpreted as a resource. If a file is found, it will be
442 filtered through the cpp(1) preprocessor, just as xrdb(1) would
443 do.
444 modulefiles that use this command, should in most cases contain
446 one or more x-resource lines, each defining one X11 resource.
447 Reading resources from filename is much slower, due to the
448 preprocessing. The DISPLAY environment variable should be
449 properly set and the X11 server should be accessible. If x-
450 resource can't manipulate the X11 resource database, the
451 modulefile will exit with an error message.
452 Examples:
454 x-resource /u2/staff/leif/.xres/Ileaf
456 The file Ileaf is preprocessed by cpp(1) and the result
457 is merged into the X11 resource database.
458 x-resource [glob ~/.xres/ileaf]
460 The Tcl glob function is used to have the modulefile read
461 different resource files for different users.
462 x-resource {Ileaf.popup.saveUnder: True}
464 Merge the Ileaf resource into the X11 resource database.
465
467 The ModulesCurrentModulefile variable contains the full pathname of the
468 modulefile being interpreted.
469
471 Every directory in MODULEPATH is searched to find the modulefile. A
472 directory in MODULEPATH can have an arbitrary number of sub-
473 directories. If the user names a modulefile to be loaded which is
474 actually a directory, the directory is opened and a search begins for
475 an actual modulefile. First, modulecmd looks for a file with the name
476 .modulerc in the directory. If this file exists, its contents will be
477 evaluated as if it was a module file to be loaded. You may place
478 module-version and module-alias commands inside this file.
479 Additionally, before seeking for .modulerc files in the module
480 directory, the global .modulerc file is sourced, too. If a named
481 version default now exists for the module file to be loaded, the
482 assigned modulefile now will be sourced. Otherwise the file .version is
483 looked up in the directory. If the .version file exists, it is opened
484 and interpreted as Tcl code and takes precedence over a .modulerc file
485 in the same directory. If the Tcl variable ModulesVersion is set by
486 the .version file, modulecmd will use the name as if it specifies a
487 modulefile in the directory. This will become the default module file
488 in this case. If ModulesVersion is a directory, the search begins anew
489 down that directory. If the name does not match any files located in
490 the current directory, the search continues through the remaining
491 directories in MODULEPATH.
492 Every .version and .modulerc file found is Tcl interpreted. So,
494 changes made in these file will affect the subsequently interpreted
495 modulefile.
496 If no default version may be figured out, then the highest
498 lexicographically sorted modulefile under the directory will be used.
499 For example, it is possible for a user to have a directory named X11
501 which simply contains a .version file specifying which version of X11
502 is to be loaded. Such a file would look like:
503 #%Module1.0
505 ##
506 ## The desired version of X11
507 ##
508 set ModulesVersion "R4"
509
511 Users can request help about a specific modulefile through the
512 module(1) command. The modulefile can print helpful information or
513 start help oriented programs by defining a ModulesHelp subroutine. The
514 subroutine will be called when the 'module help modulefile' command is
515 used.
516
518 The 'module display modulefile' command will detail all changes that
519 will be made to the environment. After displaying all of the
520 environment changes modulecmd will call the ModulesDisplay subroutine.
521 The ModulesDisplay subroutine is a good place to put additional
522 descriptive information about the modulefile.
523
525 ${MODULEPATH}
526 Path of directories containing modulefiles.
527
529 3.2.8
530
532 module(1), Tcl(3), TclX(3), xrdb(1), cpp(1), system(3), uname(3),
533 gethostname(3) getdomainname(3)
534
536 Tcl was developed by John Ousterhout at the University of California at
537 Berkeley.
538 TclX was developed by Karl Lehenbauer and Mark Diekhans.
540Modules version 3.2.8 July 2009 MODULEFILE(4)