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 type
212 Returns either "C" or "Tcl" to indicate which module
213 command is being executed, either the "C" version or the
214 Tcl-only version, to allow the modulefile writer to
215 handle any differences between the two.
216 module-info flags
217 Returns the integer value of modulecmd's flags state.
218 module-info mode [modetype]
219 Returns the current modulecmd's mode as a string if no
220 modetype is given.
221 Returns 1 if modulecmd's mode is modetype. modetype can
223 be: load, remove, display, help, whatis, switch, switch1,
224 switch2, or switch3.
225 module-info name
227 Return the name of the modulefile. This is not the full
228 pathname for modulefile. See the Modules Variables
229 section for information on the full pathname.
230 module-info specified
232 Return the name of the modulefile specified on the
233 command line.
234 module-info shell
236 Return the current shell under which modulecmd was
237 invoked. This is the first parameter of modulecmd, which
238 is normally hidden by the module alias.
239 module-info shelltype
241 Return the family of the shell under which modulefile was
242 invoked. As of module-info shell this depends on the
243 first parameter of modulecmd. The output reflects a shell
244 type determining the shell syntax of the commands
245 produced by modulecmd.
246 module-info alias name
248 Returns the full module file name to which the module
249 file alias name is assigned
250 module-info version module-file
252 Returns a list of all symbolic versions assigned to the
253 passed module-file. The paremeter module-file might
254 either be a full qualified module file with name and
255 version, another symbolic module file name or a module
256 file alias.
257 module-version module-file version-name [version-name ...]
259 Assigns the symbolic version-name to the module file module-file
260 This command should be placed in one of the modulecmd rc files
261 in order to provide shorthand invocations of frequently used
262 module file names.
263 The special version-name default specifies the default version
265 to be used for module commands, if no specific version is given.
266 This replaces the definitions made in the .version file in
267 former modulecmd releases.
268 The parameter module-file may be either
270 a fully qualified modulefile with name and version
272 a symbolic module file name
273 another module file alias
274 module-alias name module-file
276 Assignes the module file module-file to the alias name. This
277 command should be placed in one of the modulecmd rc files in
278 order to provide shorthand invocations of frequently used module
279 file names.
280 The parameter module-file may be either
282 a fully qualified modulefile with name and version
284 a symbolic module file name
285 another module file alias
286 module-trace {on|off} [command [command ...]] [-module modulefile
288 [modulefile ...]]
289 Switches tracing on or off. Without parameters this command will
290 affect globally all tracing setups for all commands and
291 modulefiles. The command parameter may be used to affect tracing
292 of specified module commands only and the switch -module finally
293 limits the affect of the module-trace command to a well defined
294 set of module files.
295 The command may be one of the following
297 avail - 'module avail' command
299 clear - 'module clear' command
300 display - 'module display' command
301 init - 'module init' command
302 help - 'module help' command
303 list - 'module list' command
304 load - 'module load' command
305 purge - 'module purge' command
306 switch - 'module switch' command
307 unuse - 'module unuse' command
308 unload - 'module unload' command
309 update - 'module update' command
310 use - 'module use' command
311 The module parameter specifies a set of module files using TCL
313 regular expressions. For example
314 .* will affect all module files
316 */2.0 affects all module files at version 2.0
317 gnu/.* affects all versions of the gnu modulefile
318 gnu/2.0 affects only version 2.0 of the gnu modulefile
319 The module parameter is prepended to the current tracing pattern
321 list for the specified module command. It is evaluated from the
322 left to the right. The first matching pattern defines the
323 tracing parameter.
324 The internal trace pattern list is stored as a colon separated
326 list. In advanced user level only, colons may be specified on
327 the module parameter of the module-trace command. This will
328 directly take effect in the internal trace pattern list. In
329 novice or expert user level a warning messge will be generated.
330 module-user level
332 Defines the user level under wich module-cmd runs. This takes
333 effect on the error messages being produced and on the behavior
334 of modulecmd in case of detecting an outage.
335 The level parameter specifies the user level and may be one of
337 the following values:
338 advanced, adv - advanced user level
340 expert, exp - expert user level
341 novice, nov - novice user level
342 module-verbosity {on|off}
344 Switches verbose modulecmd message display on or off.
345 module-log error-weight log-facility
347 Defines whether error messages of the specified weight should be
348 logged and conditionally assignes a log-facility.
349 The error-weight parameter specifies the error level to be
351 logged. It may be one of the following values:
352 verb - verbose messages
354 info - informal messages
355 debug - debugging messages
356 trace - tracing output
357 warn - warnings
358 prob - problems (normally the modulecmd may be completed)
359 error - errors (which normally leads to unsuccessful end
360 of the modulecmd)
361 fatal - fatal system errors
362 panic - very fatal system errors, e.g. internal program
363 inconsistencies.
364 The log-facility parameter specifies the log destination. This
366 may either switch off logging for the specified error-weight,
367 direct log messages to a special stream or a file or specify a
368 syslog facility for logging. The following values are allowed:
369 stderr, stdout - predefined output streams for normal and
371 error outputs. Note, that stdout is normally used for
372 passing parameters to the invoking shell. Directing error
373 output to this stream might screw up the modulecmd
374 integration to your shell.
375 a syslog facility - directs logging to the syslog. See
376 syslog.conf(4) for detailed description of the valid
377 syslog facilities.
378 null, none - will suppress logging of the specified
379 error-weight.
380 a filename - is recognized by the first character being
381 either a '.' or a '/'. You must have write permission to
382 the file you specify.
383 module-whatis string
385 Defines a string which is displayed in case of the invocation of
386 the 'module whatis' command. There may be more than one module-
387 whatis line in a modulefile. This command takes no actions in
388 case of load, display, etc. invocations of modulecmd.
389 The string parameter has to be enclosed in double-quotes if
391 there's more than one word specified. Words are defined to be
392 separated by whitespace characters (space, tab, cr).
393 set-alias alias-name alias-string
395 Sets an alias or function with the name alias-name in the user's
396 environment to the string alias-string. Arguments can be
397 specified using the Bourne Shell style of function arguments.
398 If the string contains "$1", then this will become the first
399 argument when the alias is interpreted by the shell. The string
400 "$*" corresponds to all of the arguments given to the alias.
401 The character '$' may be escaped using the '\' character.
402 For some shells, aliases are not possible and the command has no
404 effect. For Bourne shell derivatives, a shell function will be
405 written (if supported) to give the impression of an alias. When
406 a modulefile is unloaded, set-alias becomes unset-alias.
407 unset-alias alias-name
409 Unsets an alias with the name alias-name in the user's
410 environment. If the shell supports functions then the shell is
411 instructed to unset function alias-name.
412 system string
414 Pass string to the C library routine system(3). For the
415 system(3) call modulecmd redirects stdout to stderr since stdout
416 would be parsed by the evaluating shell. The exit status of the
417 executed command is returned.
418 uname field
420 Provide fast lookup of system information on systems that
421 support uname(3). uname is significantly faster than using
422 system to execute a program to return host information. If
423 uname(3) is not available, gethostname(3) or some program will
424 make the nodename available. uname will return the string
425 "unknown" if information is unavailable for the field.
426 uname will invoke getdomainname in order to figure out the name
428 of the domain.
429 field values are:
431 sysname - the operating system name
433 nodename - the hostname
434 domain - the name of the domain
435 release - the operating system release
436 version - the operating system version
437 machine - a standard name that identifies the system's
438 hardware
439 x-resource resource-string
441 x-resource filename
442 Merge resources into the X11 resource database. The resources
443 are used to control look and behavior of X11 applications. The
444 command will attempt to read resources from filename. If the
445 argument isn't a valid file name, then string will be
446 interpreted as a resource. If a file is found, it will be
447 filtered through the cpp(1) preprocessor, just as xrdb(1) would
448 do.
449 modulefiles that use this command, should in most cases contain
451 one or more x-resource lines, each defining one X11 resource.
452 Reading resources from filename is much slower, due to the
453 preprocessing. The DISPLAY environment variable should be
454 properly set and the X11 server should be accessible. If x-
455 resource can't manipulate the X11 resource database, the
456 modulefile will exit with an error message.
457 Examples:
459 x-resource /u2/staff/leif/.xres/Ileaf
461 The file Ileaf is preprocessed by cpp(1) and the result
462 is merged into the X11 resource database.
463 x-resource [glob ~/.xres/ileaf]
465 The Tcl glob function is used to have the modulefile read
466 different resource files for different users.
467 x-resource {Ileaf.popup.saveUnder: True}
469 Merge the Ileaf resource into the X11 resource database.
470
472 The ModulesCurrentModulefile variable contains the full pathname of the
473 modulefile being interpreted.
474
476 Every directory in MODULEPATH is searched to find the modulefile. A
477 directory in MODULEPATH can have an arbitrary number of sub-
478 directories. If the user names a modulefile to be loaded which is
479 actually a directory, the directory is opened and a search begins for
480 an actual modulefile. First, modulecmd looks for a file with the name
481 .modulerc in the directory. If this file exists, its contents will be
482 evaluated as if it was a module file to be loaded. You may place
483 module-version and module-alias commands inside this file.
484 Additionally, before seeking for .modulerc files in the module
485 directory, the global .modulerc file is sourced, too. If a named
486 version default now exists for the module file to be loaded, the
487 assigned modulefile now will be sourced. Otherwise the file .version is
488 looked up in the directory. If the .version file exists, it is opened
489 and interpreted as Tcl code and takes precedence over a .modulerc file
490 in the same directory. If the Tcl variable ModulesVersion is set by
491 the .version file, modulecmd will use the name as if it specifies a
492 modulefile in the directory. This will become the default module file
493 in this case. If ModulesVersion is a directory, the search begins anew
494 down that directory. If the name does not match any files located in
495 the current directory, the search continues through the remaining
496 directories in MODULEPATH.
497 Every .version and .modulerc file found is Tcl interpreted. So,
499 changes made in these file will affect the subsequently interpreted
500 modulefile.
501 If no default version may be figured out, then the highest
503 lexicographically sorted modulefile under the directory using the 'C'
504 locale will be used.
505 For example, it is possible for a user to have a directory named X11
507 which simply contains a .version file specifying which version of X11
508 is to be loaded. Such a file would look like:
509 #%Module1.0
511 ##
512 ## The desired version of X11
513 ##
514 set ModulesVersion "R4"
515
517 Users can request help about a specific modulefile through the
518 module(1) command. The modulefile can print helpful information or
519 start help oriented programs by defining a ModulesHelp subroutine. The
520 subroutine will be called when the 'module help modulefile' command is
521 used.
522
524 The 'module display modulefile' command will detail all changes that
525 will be made to the environment. After displaying all of the
526 environment changes modulecmd will call the ModulesDisplay subroutine.
527 The ModulesDisplay subroutine is a good place to put additional
528 descriptive information about the modulefile.
529
531 ${MODULEPATH}
532 Path of directories containing modulefiles.
533
535 3.2.10
536
538 module(1), Tcl(3), TclX(3), xrdb(1), cpp(1), system(3), uname(3),
539 gethostname(3) getdomainname(3)
540
542 Tcl was developed by John Ousterhout at the University of California at
543 Berkeley.
544 TclX was developed by Karl Lehenbauer and Mark Diekhans.
546Modules version 3.2.10 July 2009 MODULEFILE(4)