modulefile.4(4)
modulefile - files containing Tcl code for The Modules package
As shipped in IRIX 6.5.5. Unchanged since IRIX 6.5.
This page could not be fully tidied (no-header-or-footer); it is shown as printed.
USMID @(#)modules/doc/modulefile.4 22.1 09/27/96 11:38:48 MODULEFILE(4) Modules 2.2.1 Modules NAME modulefile - files containing Tcl code for The Modules package DESCRIPTION modulefiles are written in the Tool Command Language, Tcl(3) , and are interpreted by the modulecmd program via the module(1) user interface. modulefiles can be loaded, unloaded, or switched on-the-fly while the user is working. A modulefile begins with the magic cookie, '#%Module'. A version number may be placed after this string. The version number is useful as the format of modulefiles may change. If a version number doesn't exist, then modulecmd will assume the modulefile is compatible with the latest version. The current version for modulefiles is 1.0. Files without the magic cookie will not be interpreted by modulecmd. Each modulefile contains the changes to a user's environment needed to access an application. Tcl is a simple programming language which permits modulefiles to be arbitrarily complex, depending upon the application's and the modulefile writer's needs. modulefiles can be used to implement site policies regarding the access and use of applications. A typical modulefiles is a simple bit of code that set or add entries to the PATH, MANPATH, or other environment variables. Tcl has conditional statements that are evaluated when the modulefile is loaded. This is very effective for managing path or environment changes due to different OS releases or architectures. The user environment information is encapsulated into a single modulefile kept in a central location. The same modulefile is used by every user on any machine. So, from the user's perspective, starting an application is exactly the same irregardless of the machine or platform they are on. modulefiles also hide the notion of different types of shells. From the user's perspective, changing the environment for one shell looks exactly the same as changing the environment for another shell. This is useful for new or novice users and eliminates the need for statements such as "if you're using the C Shell do this ..., otherwise if you're using the Bourne shell do this ..." Announcing and accessing new software is uniform and independent of the user's shell. From the modulefile writer's perspective, this means one set of information will take care of every type of shell. Modules Specific Tcl Commands The Modules Package uses commands which are extensions to the "standard" Tcl(3) package. Unless otherwise specified, the Module commands return the empty string. Some commands behave differently when a modulefile is loaded or unloaded. The command descriptions assume the modulefile is being loaded. setenv variable value Set environment variable to value. The setenv command will also change the process' environment. A reference using Tcl's env associative array will reference changes made with the setenv command. Changes made using Tcl's env associative array will NOT change the user's environment variable like the setenv command. An environment change made this way will only affect the module parsing process. The setenv command is also useful for changing the environment prior to the exec or system command. When a modulefile is unloaded, setenv becomes unsetenv. unsetenv variable Unsets environment variable. The unsetenv command changes the process' environment like setenv. append-path variable value prepend-path variable value Append or prepend value to environment variable. The variable is a colon separated list such as "PATH=directory:directory:directory". If the variable is not set, it is created. When a modulefile is unloaded, append-path and prepend-path become remove-path. remove-path variable value Remove value from the colon separated list in variable. Every string between colons in variable is compared to value. If the two match, value is removed from variable. prereq modulefile [ modulefile ... ] conflict modulefile [ modulefile ... ] prereq and conflict control whether or not the modulefile will be loaded. The prereq command lists modulefiles which must have been previously loaded before the current modulefile will be loaded. Similarly, the conflict command lists modulefiles which conflict with the current modulefile. If a list contains more than one modulefile, then each member of the list acts as a Boolean OR operation. Multiple prereq and conflict commands may be used to create a Boolean AND operation. If one of the requirements have not been satisfied, an error is reported and the current modulefile makes no changes to the user's environment. If an argument for prereq is a directory and any modulefile from the directory has been loaded, then the prerequisite is met. For example, specifying X11 as a prereq means that any version of X11, X11/R4 or X11/R5, must be loaded before proceeding. If an argument for conflict is a directory and any other modulefile from that directory has been loaded, then a conflict will occur. For example, specifying X11 as a conflict will stop X11/R4 and X11/R5 from being loaded at the same time. module [ sub-command ] [ sub-command-args ] Contains the same sub-commands as described in the module(1) man page in the Module Sub-Commands section. This command permits a modulefile to load or remove other modulefiles. No checks are made to ensure that the modulefile does not try to load itself. Often it is useful to have a single modulefile that performs a number of module load commands. For example, if every user on the system requires a basic set of applications loaded, then a core modulefile would contain the necessary module load commands. module-info option [ info-args ] Provide information about the modulecmd program's state. Some of the information is specific to the internals of modulecmd. option is the type of information to be provided, and info-args are any arguments needed. module-info flags Returns the integer value of modulecmd's flags state. module-info mode modetype Returns 1 if modulecmd's mode is modetype. modetype can be: load, remove, display, switch, switch1, switch2, or switch3. module-info name Return the name of the modulefile. This is not the full pathname for modulefile. See the Modules Variables section for information on the full pathname. set-alias alias-name alias-string Sets an alias or function with the name alias-name in the user's environment to the string alias-string. Arguments can be specified using the Bourne Shell style of function arguments. If the string contains "$1", then this will become the first argument when the alias is interpreted by the shell. The string "$*" corresponds to all of the arguments given to the alias. The character '$' may be escaped using the '\' character. For some shells, aliases are not possible and the command has no effect. For Bourne shell derelicts, a shell function will be written (if supported) to give the impression of an alias. When a modulefile is unloaded, set-alias becomes unset-alias. unset-alias alias-name Unsets an alias with the name alias-name in the user's environment. If the shell supports functions then the shell is instructed to unset function alias-name. system string Pass string to the C library routine system(3). For the system(3) call modulecmd redirects stdout to stderr since stdout would be parsed by the evaluating shell. The exit status of the executed command is returned. uname field Provide fast lookup of system information on systems that support uname(3). uname is significantly faster than using system to execute a program to return host information. If uname(3) is not available, gethostname(3) or some program will make the nodename available. uname will return the string "unknown" if information is unavailable for the field. field values are: sysname - the operating system name nodename - the hostname release - the operating system release version - the operating system version machine - a standard name that identifies the system's hardware x-resource resource-string x-resource filename Merge resources into the X11 resource database. The resources are used to control look and behavior of X11 applications. The command will attempt to read resources from filename. If the argument isn't a valid file name, then string will be interpreted as a resource. If a file is found, it will be filtered through the cpp(1) preprocessor, just as xrdb(1) would do. modulefiles that use this command, should in most cases contain one or more x-resource lines, each defining one X11 resource. Reading resources from filename is much slower, due to the preprocessing. The DISPLAY environment variable should be properly set and the X11 server should be accessible. If x- resource can't manipulate the X11 resource database, the modulefile will exit with an error message. Examples: x-resource /u2/staff/leif/.xres/Ileaf The file Ileaf is preprocessed by cpp(1) and the result is merged into the X11 resource database. x-resource [glob ~/.xres/ileaf] The Tcl glob function is used to have the modulefile read different resource files for different users. x-resource {Ileaf.popup.saveUnder: True} Merge the Ileaf resource into the X11 resource database. Modules Variables The ModulesCurrentModulefile variable contains the full pathname of the modulefile being interpreted. Locating Modulefiles Every directory in MODULEPATH is searched to find the modulefile. A directory in MODULEPATH can have an arbitrary number of sub- directories. If the user names a modulefile to be loaded which is actually a directory, the directory is opened and a search begins for an actual modulefile. First, modulecmd looks for a file with the name .version in the directory. If the .version file exists, it is opened and interpreted as Tcl code. If the Tcl variable ModulesVersion is set by the .version file, modulecmd will use the name as if it specifies a modulefile in the directory. If ModulesVersion is a directory, the search begins anew down that directory. If the name does not match any files located in the current directory, the search continues through the remaining directories in MODULEPATH. Every .version file found is Tcl interpreted. So, changes made in the .version file will affect the subsequently interpreted modulefile. If the .version file does not set ModulesVersion, then the highest lexicographically sorted modulefile under the directory will be used. For example, it is possible for a user to have a directory named X11 which simply contains a .version file specifying which version of X11 is to be loaded. Such a file would look like: #%Module1.0 ## ## The desired version of X11 ## set ModulesVersion "R4" Modulefile Specific Help Users can request help about a specific modulefile through the module(1) command. The modulefile can print helpful information or start help oriented programs by defining a ModulesHelp subroutine. The subroutine will be called when the 'module help modulefile' command is used. Modulefile Display The 'module display modulefile' command will detail all changes that will be made to the environment. After displaying all of the environment changes modulecmd will call the ModulesDisplay subroutine. The ModulesDisplay subroutine is a good place to put additional descriptive information about the modulefile. ENVIRONMENT ${MODULEPATH} Path of directories containing modulefiles. SEE ALSO module(1), Tcl(3), xrdb(1), cpp(1), system(3), uname(3), gethostname(3) NOTES Tcl was developed by John Ousterhout at the University of California at Berkeley.