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