1MODULEFILE(4)                Modules configuration               MODULEFILE(4)
2
3
4

NAME

6       modulefile - files containing Tcl code for the Modules package
7

DESCRIPTION

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
15       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
22       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
30       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
40       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

Modules Specific Tcl Commands

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
57       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
67              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
73              #%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
81              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
87              break
88
89
90       chdir directory
91              Set the current working directory to directory.
92
93
94       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
102
103       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
111              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
118
119       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
135       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
141       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
152              If the variable is not set, it is created.  When a modulefile is
153              unloaded, append-path and prepend-path become remove-path.
154
155       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
162       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
176              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
181              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
186       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
194       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
205       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
211              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
222                     Returns  1 if modulecmd's mode is modetype.  modetype can
223                     be: load, remove, display, help, whatis, switch, switch1,
224                     switch2, or switch3.
225
226              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
231              module-info specified
232                     Return  the  name  of  the  modulefile  specified  on the
233                     command line.
234
235              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
240              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
247              module-info alias name
248                     Returns the full module file name  to  which  the  module
249                     file alias name is assigned
250
251              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
258       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
264              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
269              The parameter module-file may be either
270
271                     a fully qualified modulefile with name and version
272                     a symbolic module file name
273                     another module file alias
274
275       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
281              The parameter module-file may be either
282
283                     a fully qualified modulefile with name and version
284                     a symbolic module file name
285                     another module file alias
286
287       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
296              The command may be one of the following
297
298                     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
312              The module parameter specifies a set of module files  using  TCL
313              regular expressions. For example
314
315                     .*  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
320              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
325              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
331       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
336              The level parameter specifies the user level and may be  one  of
337              the following values:
338
339                     advanced, adv - advanced user level
340                     expert, exp - expert user level
341                     novice, nov - novice user level
342
343       module-verbosity {on|off}
344              Switches verbose modulecmd message display on or off.
345
346       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
350              The error-weight parameter  specifies  the  error  level  to  be
351              logged.  It may be one of the following values:
352
353                     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
365              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
370                     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
384       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
390              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
394       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
403              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
408       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
413       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
419       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
427              uname  will invoke getdomainname in order to figure out the name
428              of the domain.
429
430              field values are:
431
432                     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
440       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
450              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
458              Examples:
459
460              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
464              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
468              x-resource {Ileaf.popup.saveUnder: True}
469                     Merge the Ileaf resource into the X11 resource database.
470

Modules Variables

472       The ModulesCurrentModulefile variable contains the full pathname of the
473       modulefile being interpreted.
474

Locating Modulefiles

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
498       Every .version  and .modulerc  file  found  is  Tcl  interpreted.   So,
499       changes  made  in  these  file will affect the subsequently interpreted
500       modulefile.
501
502       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
506       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
510              #%Module1.0
511              ##
512              ##  The desired version of X11
513              ##
514              set ModulesVersion "R4"
515

Modulefile Specific Help

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

Modulefile Display

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

ENVIRONMENT

531       ${MODULEPATH}
532              Path of directories containing modulefiles.
533

VERSION

535       3.2.13
536

SEE ALSO

538       module(1),  Tcl(3),  TclX(3),  xrdb(1),  cpp(1),  system(3),  uname(3),
539       gethostname(3) getdomainname(3)
540

NOTES

542       Tcl was developed by John Ousterhout at the University of California at
543       Berkeley.
544
545       TclX was developed by Karl Lehenbauer and Mark Diekhans.
546
547
548
549Modules version 3.2.13            2020-04-07                     MODULEFILE(4)
Impressum