1MODULEFILE(4)                       Modules                      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(n) and are
10       interpreted by the modulecmd.tcl program via the module(1) user  inter‐
11       face. modulefiles can be loaded, unloaded, or switched on-the-fly while
12       the user is working; and can be used to implement site policies regard‐
13       ing the access and use of applications.
14
15       A  modulefile  begins with the magic cookie, #%Module. A version number
16       may be placed after this string. The version number is  useful  as  the
17       modulefile  format  may  change thus it reflects the minimum version of
18       modulecmd.tcl required to interpret the modulefile. If a version number
19       doesn't exist, then modulecmd.tcl will assume the modulefile is compat‐
20       ible. Files without the magic cookie or with a version  number  greater
21       than  the  current version of modulecmd.tcl will not be interpreted. If
22       the mcookie_version_check configuration is disabled the version  number
23       set is not checked.
24
25       Each  modulefile contains the changes to a user's environment needed to
26       access an application. Tcl is a simple programming language which  per‐
27       mits modulefiles to be arbitrarily complex, depending upon the applica‐
28       tion's and the modulefile writer's needs. If support for  extended  tcl
29       (tclX)  has  been configured for your installation of the Modules pack‐
30       age, you may use all the extended commands provided by tclX, too.
31
32       A typical modulefile is a simple bit of code that set or add entries to
33       the  PATH,  MANPATH,  or  other  environment variables. A Modulefile is
34       evaluated against current modulecmd.tcl's mode which leads to  specific
35       evaluation  results.  For instance if the modulefile sets a value to an
36       environment variable, this variable is set when  modulefile  is  loaded
37       and unset when modulefile is unloaded.
38
39       Tcl  has  conditional statements that are evaluated when the modulefile
40       is interpreted. This is very effective for managing path or environment
41       changes  due  to different OS releases or architectures. The user envi‐
42       ronment information is encapsulated into a single modulefile kept in  a
43       central  location. The same modulefile is used by every user on any ma‐
44       chine. So, from the user's perspective, starting an application is  ex‐
45       actly the same irrespective of the machine or platform they are on.
46
47       modulefiles also hide the notion of different types of shells. From the
48       user's perspective, changing the environment for one  shell  looks  ex‐
49       actly  the  same as changing the environment for another shell. This is
50       useful for new or novice users and eliminates the need  for  statements
51       such  as  "if you're using the C Shell do this ..., otherwise if you're
52       using the Bourne shell do this ...". Announcing and accessing new soft‐
53       ware  is  uniform and independent of the user's shell. From the module‐
54       file writer's perspective, this means one set of information will  take
55       care of every type of shell.
56

MODULES SPECIFIC TCL COMMANDS

58       The  Modules  Package  uses commands which are extensions to the "stan‐
59       dard" Tool Command Language Tcl(n) package. Unless otherwise specified,
60       the  Module commands return the empty string. Some commands behave dif‐
61       ferently when a modulefile is loaded or unloaded. The command  descrip‐
62       tions assume the modulefile is being loaded.
63
64       append-path [-d C|--delim C|--delim=C] [--duplicates] variable value...
65              See prepend-path.
66
67       break  This  is  not  a Modules-specific command, it's actually part of
68              Tcl, which has been overloaded similar to the continue and  exit
69              commands  to  have  the  effect  of causing the module not to be
70              listed as loaded and not affect other modules being loaded  con‐
71              currently.  All  non-environment commands within the module will
72              be performed up to this point and processing will continue on to
73              the next module on the command line. The break command will only
74              have this effect if not used within a Tcl loop though.
75
76              An example: Suppose that a full  selection  of  modulefiles  are
77              needed for various different architectures, but some of the mod‐
78              ulefiles are not needed and the user should be  alerted.  Having
79              the  unnecessary  modulefile be a link to the following notavail
80              modulefile will perform the task as required.
81
82                 #%Module1.0
83                 ## notavail modulefile
84                 ##
85                 proc ModulesHelp { } {
86                     puts stderr "This module does nothing but alert the user"
87                     puts stderr "that the [module-info name] module is not available"
88                 }
89
90                 module-whatis "Notifies user that module is not available."
91                 set curMod [module-info name]
92                 if { [ module-info mode load ] } {
93                     puts stderr "Note: '$curMod' is not available for [uname sysname]."
94                 }
95                 break
96
97       chdir directory
98              Set the current working directory to directory.
99
100       conflict modulefile...
101              prereq and conflict control whether or not the  modulefile  will
102              be  loaded. The prereq command lists modulefiles which must have
103              been previously loaded before the  current  modulefile  will  be
104              loaded.  Similarly, the conflict command lists modulefiles which
105              conflict with the current modulefile. If a  list  contains  more
106              than  one  modulefile,  then  each  member of the list acts as a
107              Boolean OR operation. Multiple prereq and conflict commands  may
108              be  used  to  create  a Boolean AND operation. If one of the re‐
109              quirements have not been satisfied, an error is reported and the
110              current modulefile makes no changes to the user's environment.
111
112              If an argument for prereq is a directory and any modulefile from
113              the directory has been loaded, then the prerequisite is met. For
114              example,  specifying  X11  as a prereq means that any version of
115              X11, X11/R4 or X11/R5, must be loaded before proceeding.
116
117              If an argument for conflict is a directory and any other module‐
118              file  from  that directory has been loaded, then a conflict will
119              occur.  For example, specifying X11  as  a  conflict  will  stop
120              X11/R4 and X11/R5 from being loaded at the same time.
121
122              The  parameter modulefile may also be a symbolic modulefile name
123              or a modulefile alias. It may also leverage a specific syntax to
124              finely select module version (see Advanced module version speci‐
125              fiers section below).
126
127       continue
128              This is not a modules specific command  but  another  overloaded
129              Tcl  command and is similar to the break or exit commands except
130              the module will be listed as loaded as well  as  performing  any
131              environment or Tcl commands up to this point and then continuing
132              on to the next module on the command line. The continue  command
133              will only have this effect if not used within a Tcl loop though.
134
135       exit [N]
136              This  is  not  a modules specific command but another overloaded
137              Tcl command and is similar to the break  or  continue  commands.
138              However, this command will cause the immediate cessation of this
139              module and any additional ones on the command line. This  module
140              and  the subsequent modules will not be listed as loaded. No en‐
141              vironment commands will be performed in the current module.
142
143       getenv variable [value]
144              Returns value of environment variable. If variable  is  not  de‐
145              fined,  value is returned if set, _UNDEFINED_ is returned other‐
146              wise. The getenv command should be preferred over the Tcl global
147              variable env to query environment variables.
148
149       is-avail modulefile...
150              The  is-avail  command returns a true value if any of the listed
151              modulefiles exists in enabled MODULEPATH.  If  a  list  contains
152              more  than one modulefile, then each member acts as a boolean OR
153              operation. If an argument for is-avail is a directory and a mod‐
154              ulefile  exists  in  the  directory is-avail would return a true
155              value.
156
157              The parameter modulefile may also be a symbolic modulefile  name
158              or a modulefile alias. It may also leverage a specific syntax to
159              finely select module version (see Advanced module version speci‐
160              fiers section below).
161
162       is-loaded [modulefile...]
163              The  is-loaded command returns a true value if any of the listed
164              modulefiles has been loaded or if any modulefile  is  loaded  in
165              case  no  argument is provided. If a list contains more than one
166              modulefile, then each member acts as a boolean OR operation.  If
167              an argument for is-loaded is a directory and any modulefile from
168              the directory has been loaded  is-loaded  would  return  a  true
169              value.
170
171              The  parameter modulefile may also be a symbolic modulefile name
172              or a modulefile alias. It may also leverage a specific syntax to
173              finely select module version (see Advanced module version speci‐
174              fiers section below).
175
176       is-saved [collection...]
177              The is-saved command returns a true value if any of  the  listed
178              collections  exists or if any collection exists in case no argu‐
179              ment is provided. If a list contains more than  one  collection,
180              then each member acts as a boolean OR operation.
181
182              If  MODULES_COLLECTION_TARGET is set, a suffix equivalent to the
183              value of this variable is  appended  to  the  passed  collection
184              name.  In  case no collection argument is provided, a true value
185              will only be returned if a  collection  matching  currently  set
186              target exists.
187
188       is-used [directory...]
189              The  is-used  command  returns a true value if any of the listed
190              directories has been enabled in MODULEPATH or if  any  directory
191              is  enabled  in case no argument is provided. If a list contains
192              more than one directory, then each member acts as a  boolean  OR
193              operation.
194
195       module [sub-command] [sub-command-options] [sub-command-args]
196              Contains the same sub-commands as described in the module(1) man
197              page in the Module Sub-Commands section. This command permits  a
198              modulefile  to  load  or unload other modulefiles. No checks are
199              made to ensure that the modulefile does not try to load  itself.
200              Often  it  is useful to have a single modulefile that performs a
201              number of module load commands. For example, if  every  user  on
202              the  system  requires a basic set of applications loaded, then a
203              core modulefile would contain the  necessary  module  load  com‐
204              mands.
205
206              The  --not-req option may be set for the load, unload and switch
207              sub-commands to inhibit the definition of an implicit prereq  or
208              conflict requirement onto specified modules.
209
210              Command  line switches --auto, --no-auto and --force are ignored
211              when passed to a module command set in a modulefile.
212
213       module-alias name modulefile
214              Assigns the modulefile to the alias name. This command should be
215              placed  in one of the modulecmd.tcl rc files in order to provide
216              shorthand invocations of frequently used modulefile names.
217
218              The parameter modulefile may be either
219
220              • a fully qualified modulefile with name and version
221
222              • a symbolic modulefile name
223
224              • another modulefile alias
225
226       module-forbid [options] modulefile...
227              Forbid use of modulefile. An error is obtained  when  trying  to
228              evaluate  a  forbidden  module. This command should be placed in
229              one of the modulecmd.tcl rc files.
230
231              module-forbid command accepts the following options:
232
233--after datetime
234
235--before datetime
236
237--not-user {user...}
238
239--not-group {group...}
240
241--message {text message}
242
243--nearly-message {text message}
244
245              If --after option is set, forbidding  is  only  effective  after
246              specified  date  time. Following the same principle, if --before
247              option is set, forbidding is  only  effective  before  specified
248              date  time.  Accepted date time format is YYYY-MM-DD[THH:MM]. If
249              no time (HH:MM) is specified,  00:00  is  assumed.  --after  and
250              --before options are not supported on Tcl versions prior to 8.5.
251
252              If  --not-user  option  is set, forbidding is not applied if the
253              username of the user currently running modulecmd.tcl is part  of
254              the  list of username specified. Following the same approach, if
255              --not-group option is set, forbidding is not applied if  current
256              user is member of one the group specified. When both options are
257              set,  forbidding  is  not  applied  if  a  match  is  found  for
258              --not-user or --not-group.
259
260              Error  message returned when trying to evaluate a forbidden mod‐
261              ule can be supplemented with the text message set through --mes‐
262              sage option.
263
264              If  --after option is set, modules are considered nearly forbid‐
265              den during a number of days defined by the nearly_forbidden_days
266              modulecmd.tcl  configuration  option (see MODULES_NEARLY_FORBID‐
267              DEN_DAYS), prior reaching the expiry date fixed by  --after  op‐
268              tion. When a nearly forbidden module is evaluated a warning mes‐
269              sage is issued to inform module will  soon  be  forbidden.  This
270              warning  message  can  be supplemented with the text message set
271              through --nearly-message option.
272
273              If a module-forbid command applies to a modulefile also targeted
274              by  a  module-hide  --hard command, this module is unveiled when
275              precisely named to return an access error.
276
277              Forbidden modules included in the result of an avail sub-command
278              are  reported  with a forbidden tag applied to them. Nearly for‐
279              bidden modules included in the result of  an  avail  or  a  list
280              sub-command  are reported with a nearly-forbidden tag applied to
281              them. See Module tags section in module(1).
282
283              The parameter modulefile  may  leverage  a  specific  syntax  to
284              finely select module version (see Advanced module version speci‐
285              fiers section below).
286
287       module-hide [options] modulefile...
288              Hide modulefile to exclude it from available  module  search  or
289              module  selection unless query refers to modulefile by its exact
290              name. This command should be placed in one of the  modulecmd.tcl
291              rc files.
292
293              module-hide command accepts the following options:
294
295--soft|--hard
296
297--hidden-loaded
298
299--after datetime
300
301--before datetime
302
303--not-user {user...}
304
305--not-group {group...}
306
307              When  --soft  option  is set, modulefile is also set hidden, but
308              hiding is disabled when search or selection  query's  root  name
309              matches  module's  root  name.  This soft hiding mode enables to
310              hide modulefiles from bare module availability listing yet keep‐
311              ing  the ability to select such module for load with the regular
312              resolution mechanism (i.e., no need to use module exact name  to
313              select it)
314
315              When  --hard  option  is  set, modulefile is also set hidden and
316              stays hidden even if search or selection query refers to module‐
317              file by its exact name.
318
319              When --hidden-loaded option is set, hidden state also applies to
320              the modulefile when it is loaded. Hidden loaded modules  do  not
321              appear  on  list sub-command output, unless --all option is set.
322              Their loading or unloading informational messages  are  not  re‐
323              ported  unless the verbosity of Modules is set to a level higher
324              than verbose. Hidden loaded modules are detected in any cases by
325              state query commands like is-loaded.
326
327              If  --after option is set, hiding is only effective after speci‐
328              fied date time. Following the same principle, if --before option
329              is set, hiding is only effective before specified date time. Ac‐
330              cepted date  time  format  is  YYYY-MM-DD[THH:MM].  If  no  time
331              (HH:MM) is specified, 00:00 is assumed. --after and --before op‐
332              tions are not supported on Tcl versions prior to 8.5.
333
334              If --not-user option is set, hiding is not applied if the  user‐
335              name  of the user currently running modulecmd.tcl is part of the
336              list of username specified.  Following  the  same  approach,  if
337              --not-group option is set, hiding is not applied if current user
338              is member of one the group specified.   When  both  options  are
339              set, hiding is not applied if a match is found for --not-user or
340              --not-group.
341
342              If the --all option is set on avail, aliases, whatis  or  search
343              sub-commands, hiding is disabled thus hidden modulefiles are in‐
344              cluded in module search.  Hard-hidden  modules  (i.e.,  declared
345              hidden  with  --hard  option) are not affected by --all and stay
346              hidden even if option is set. --all option  does  not  apply  to
347              module  selection sub-commands like load. Thus in such context a
348              hidden module should always be referred by its exact  full  name
349              (e.g., foo/1.2.3 not foo) unless if it has been hidden in --soft
350              mode. A hard-hidden module cannot be unveiled or selected in any
351              case.
352
353              If  several module-hide commands target the same modulefile, the
354              strongest hiding level is retained which means if both  a  regu‐
355              lar,  a --soft hiding command match a given module, regular hid‐
356              ing mode is considered. If both a regular and  a  --hard  hiding
357              command  match  a  given module, hard hiding mode is retained. A
358              set --hidden-loaded option is retained even if  the  module-hide
359              statement  on  which  it is declared is superseded by a stronger
360              module-hide statement with no --hidden-loaded option set.
361
362              Hidden modules included in the result of  an  avail  sub-command
363              are  reported  with  a hidden tag applied to them. Hidden loaded
364              modules included in the result of a  list  sub-command  are  re‐
365              ported with a hidden-loaded tag applied to them. This tag is not
366              reported on avail sub-command context. See Module  tags  section
367              in module(1).
368
369              The  parameter modulefile may also be a symbolic modulefile name
370              or a modulefile alias. It may also leverage a specific syntax to
371              finely select module version (see Advanced module version speci‐
372              fiers section below).
373
374       module-info option [info-args]
375              Provide information about  the  modulecmd.tcl  program's  state.
376              Some  of  the  information  is specific to the internals of mod‐
377              ulecmd.tcl.  option is the type of information to  be  provided,
378              and info-args are any arguments needed.
379
380              module-info alias name
381                 Returns  the  full  modulefile  name  to which the modulefile
382                 alias name is assigned
383
384              module-info command [commandname]
385                 Returns the currently running modulecmd.tcl's  command  as  a
386                 string if no commandname is given.
387
388                 Returns  1  if  modulecmd.tcl's command is commandname.  com‐
389                 mandname can be: load, unload, reload, source,  switch,  dis‐
390                 play,  avail,  aliases, list, whatis, search, purge, restore,
391                 help or test.
392
393              module-info loaded modulefile
394                 Returns the names of currently loaded modules matching passed
395                 modulefile.  The parameter modulefile might either be a fully
396                 qualified modulefile with name and version or just  a  direc‐
397                 tory  which in case all loaded modulefiles from the directory
398                 will be returned. The parameter modulefile may also be a sym‐
399                 bolic modulefile name or a modulefile alias.
400
401              module-info mode [modetype]
402                 Returns  the  current  modulecmd.tcl's mode as a string if no
403                 modetype is given.
404
405                 Returns 1 if modulecmd.tcl's mode is modetype.  modetype  can
406                 be:  load,  unload,  remove,  switch,  display, help, test or
407                 whatis.
408
409              module-info name
410                 Return the name of the modulefile. This is not the full path‐
411                 name  for  modulefile.  See the Modules Variables section for
412                 information on the full pathname.
413
414              module-info shell [shellname]
415                 Return the current shell under which  modulecmd.tcl  was  in‐
416                 voked  if  no  shellname  is  given. The current shell is the
417                 first parameter of modulecmd.tcl, which is normally hidden by
418                 the module alias.
419
420                 If a shellname is given, returns 1 if modulecmd.tcl's current
421                 shell is shellname, returns 0 otherwise.  shellname  can  be:
422                 sh, bash, ksh, zsh, csh, tcsh, fish, tcl, perl, python, ruby,
423                 lisp, cmake, r.
424
425              module-info shelltype [shelltypename]
426                 Return the family of the shell under which modulefile was in‐
427                 voked  if  no shelltypename is given. As of module-info shell
428                 this depends on the first  parameter  of  modulecmd.tcl.  The
429                 output  reflects a shell type determining the shell syntax of
430                 the commands produced by modulecmd.tcl.
431
432                 If a shelltypename is given,  returns  1  if  modulecmd.tcl's
433                 current  shell  type  is  shelltypename, returns 0 otherwise.
434                 shelltypename can be: sh, csh, fish, tcl, perl, python, ruby,
435                 lisp, cmake, r.
436
437              module-info specified
438                 Return  the  name  of the modulefile specified on the command
439                 line.
440
441              module-info symbols modulefile
442                 Returns a list of  all  symbolic  versions  assigned  to  the
443                 passed  modulefile.  The parameter modulefile might either be
444                 a full qualified modulefile with name  and  version,  another
445                 symbolic modulefile name or a modulefile alias.
446
447              module-info tags [tag]
448                 Returns  all  tags assigned to currently evaluated modulefile
449                 as a list of strings if no tag name is given (see Module tags
450                 section in module(1))
451
452                 Returns  1 if one of the tags applying to currently evaluated
453                 modulefile is tag. Returns 0 otherwise.
454
455              module-info type
456                 Returns either C or Tcl to indicate which module  command  is
457                 being   executed,  either  the C version or the Tcl-only ver‐
458                 sion, to allow the modulefile writer to  handle  any  differ‐
459                 ences between the two.
460
461              module-info usergroups [name]
462                 Returns  all  the  groups  the  user  currently  running mod‐
463                 ulecmd.tcl is member of as a list of strings if  no  name  is
464                 given.
465
466                 Returns  1  if  one  of  the  group current user running mod‐
467                 ulecmd.tcl is member of is name. Returns 0 otherwise.
468
469                 If the Modules Tcl extension library is disabled,  the  id(1)
470                 command is invoked to fetch groups of current user.
471
472              module-info username [name]
473                 Returns  the  username  of  the  user  currently running mod‐
474                 ulecmd.tcl as a string if no name is given.
475
476                 Returns 1 if username of current user  running  modulecmd.tcl
477                 is name. Returns 0 otherwise.
478
479                 If  the  Modules Tcl extension library is disabled, the id(1)
480                 command is invoked to fetch username of current user.
481
482              module-info version modulefile
483                 Returns the physical module name and version  of  the  passed
484                 symbolic  version modulefile.  The parameter modulefile might
485                 either be a full qualified modulefile with name and  version,
486                 another symbolic modulefile name or a modulefile alias.
487
488       module-tag [options] tag modulefile...
489              Associate  tag  to  designated  modulefile. This tag information
490              will be reported along modulefile on avail and list sub-commands
491              (see  Module  tags section in module(1)). Tag information can be
492              queried during modulefile evaluation with the  module-info  tags
493              modulefile command.  module-tag commands should be placed in one
494              of the modulecmd.tcl rc files.
495
496              module-tag command accepts the following options:
497
498--not-user {user...}
499
500--not-group {group...}
501
502              If --not-user option is set, the tag is not applied if the user‐
503              name  of the user currently running modulecmd.tcl is part of the
504              list of username specified.  Following  the  same  approach,  if
505              --not-group  option  is  set,  the tag is not applied if current
506              user is member of one the group specified. When both options are
507              set,  the  tag is not applied if a match is found for --not-user
508              or --not-group.
509
510              The parameter modulefile may also be a symbolic modulefile  name
511              or a modulefile alias. It may also leverage a specific syntax to
512              finely select module version (see Advanced module version speci‐
513              fiers section below).
514
515              Tags  inherited  from other modulefile commands or module states
516              cannot be set with module-tag. Otherwise an error  is  returned.
517              Those  special  tags  are:  auto-loaded, forbidden, hidden, hid‐
518              den-loaded, loaded and nearly-forbidden.
519
520              When tag equals sticky or  super-sticky,  designated  modulefile
521              are defined Sticky modules.
522
523       module-version modulefile version-name...
524              Assigns  the  symbolic version-name to the modulefile. This com‐
525              mand should be placed in one of the modulecmd.tcl  rc  files  in
526              order  to  provide shorthand invocations of frequently used mod‐
527              ulefile names.
528
529              The special version-name default specifies the  default  version
530              to be used for module commands, if no specific version is given.
531              This replaces the definitions made in the .version file in  for‐
532              mer modulecmd.tcl releases.
533
534              The parameter modulefile may be either
535
536              • a fully or partially qualified modulefile with name / version.
537                If name is . (dot) then the current directory name is  assumed
538                to  be the module name. (Use this for deep modulefile directo‐
539                ries.)
540
541              • a symbolic modulefile name
542
543              • another modulefile alias
544
545       module-virtual name modulefile
546              Assigns the modulefile to the virtual module name. This  command
547              should be placed in rc files in order to define virtual modules.
548
549              A  virtual  module stands for a module name associated to a mod‐
550              ulefile. The modulefile is the script interpreted  when  loading
551              or  unloading  the  virtual module which appears or can be found
552              with its virtual name.
553
554              The parameter modulefile corresponds to the relative or absolute
555              file location of a modulefile.
556
557       module-whatis string
558              Defines a string which is displayed in case of the invocation of
559              the  module  whatis  command.  There  may  be  more   than   one
560              module-whatis  line  in  a modulefile. This command takes no ac‐
561              tions in  case  of  load,  display,  etc.  invocations  of  mod‐
562              ulecmd.tcl.
563
564              The  string  parameter  has  to  be enclosed in double-quotes if
565              there's more than one word specified. Words are  defined  to  be
566              separated by whitespace characters (space, tab, cr).
567
568       prepend-path   [-d   C|--delim   C|--delim=C]  [--duplicates]  variable
569       value...
570              Append or prepend value to environment variable. The variable is
571              a colon, or delimiter, separated list such as PATH=directory:di‐
572              rectory:directory. The default delimiter is a colon  :,  but  an
573              arbitrary  one can be given by the --delim option. For example a
574              space can be used instead (which will need to be handled in  the
575              Tcl  specially by enclosing it in " " or { }). A space, however,
576              can not be specified by the --delim=C form.
577
578              A reference counter environment variable is also set to increase
579              the  number  of  times value has been added to environment vari‐
580              able. This reference counter environment variable  is  named  by
581              suffixing variable by _modshare.
582
583              When value is already defined in environment variable, it is not
584              added again except if --duplicates option is set.
585
586              If the variable is not set, it is created. When a modulefile  is
587              unloaded, append-path and prepend-path become remove-path.
588
589              If  value  corresponds to the concatenation of multiple elements
590              separated by colon, or delimiter,  character,  each  element  is
591              treated separately.
592
593       prereq modulefile...
594              See conflict.
595
596       remove-path [-d C|--delim C|--delim=C] [--index] variable value...
597              Remove  value  from  the  colon, or delimiter, separated list in
598              variable. See prepend-path or append-path for  further  explana‐
599              tion  of  using  an  arbitrary  delimiter.  Every string between
600              colons, or delimiters, in variable is compared to value. If  the
601              two  match,  value  is  removed  from  variable if its reference
602              counter is equal to 1 or unknown.
603
604              When --index option is set, value refers to an index in variable
605              list.  The  string  element pointed by this index is set for re‐
606              moval.
607
608              Reference counter of value in variable  denotes  the  number  of
609              times  value  has  been  added  to variable. This information is
610              stored in environment variable_modshare. When attempting to  re‐
611              move  value from variable, relative reference counter is checked
612              and value is removed only if counter is equal to 1  or  not  de‐
613              fined. Otherwise value is kept in variable and reference counter
614              is decreased by 1.
615
616              If value corresponds to the concatenation of  multiple  elements
617              separated  by  colon,  or  delimiter, character, each element is
618              treated separately.
619
620       set-alias alias-name alias-string
621              Sets an alias or function with the name alias-name in the user's
622              environment to the string alias-string. For some shells, aliases
623              are not possible and the command has no effect. When  a  module‐
624              file is unloaded, set-alias becomes unset-alias.
625
626       set-function function-name function-string
627              Creates a function with the name function-name in the user's en‐
628              vironment with  the  function  body  function-string.  For  some
629              shells,  functions  are  not possible and the command has no ef‐
630              fect.  When  a  modulefile  is  unloaded,  set-function  becomes
631              unset-function.
632
633       setenv variable value
634              Set  environment variable to value. The setenv command will also
635              change the process' environment. A reference using Tcl's env as‐
636              sociative array will reference changes made with the setenv com‐
637              mand. Changes made using Tcl's env associative  array  will  NOT
638              change  the user's environment variable like the setenv command.
639              An environment change made this way will only affect the  module
640              parsing  process. The setenv command is also useful for changing
641              the environment prior to the exec or system command. When a mod‐
642              ulefile is unloaded, setenv becomes unsetenv. If the environment
643              variable had been defined it will be overwritten  while  loading
644              the  modulefile.  A subsequent unload will unset the environment
645              variable - the previous value cannot be  restored!  (Unless  you
646              handle it explicitly ... see below.)
647
648       source-sh shell script [arg...]
649              Evaluate with shell the designated script with defined arguments
650              to find out the environment changes it does. Those  changes  ob‐
651              tained  by  comparing environment prior and after script evalua‐
652              tion are then translated into corresponding modulefile commands,
653              which  are  then applied during modulefile evaluation as if they
654              were directly written in it.
655
656              When modulefile is unloaded, environment changes  done  are  re‐
657              served by evaluating in the unload context the resulting module‐
658              file commands, which were recorded in the MODULES_LMSOURCESH en‐
659              vironment variable at load time.
660
661              Changes on environment variables, shell aliases, shell functions
662              and current working directory are tracked.
663
664              Shell could be specified as a command name or a fully  qualified
665              pathname.   The  following  shells are supported: sh, dash, csh,
666              tcsh, bash, ksh, ksh93, zsh and fish.
667
668       system string
669              Run string command through shell. On Unix, command is passed  to
670              the  /bin/sh  shell  whereas on Windows it is passed to cmd.exe.
671              modulecmd.tcl redirects stdout to stderr since stdout  would  be
672              parsed  by the evaluating shell. The exit status of the executed
673              command is returned.
674
675       uname field
676              Provide lookup of system information. Most field information are
677              retrieved  from  the  tcl_platform array (see the tclvars(n) man
678              page).  Uname will return the string unknown if  information  is
679              unavailable for the field.
680
681              uname will invoke the uname(1) command in order to get the oper‐
682              ating system version and domainname(1) to figure out the name of
683              the domain.
684
685              field values are:
686
687sysname: the operating system name
688
689nodename: the hostname
690
691domain: the name of the domain
692
693release: the operating system release
694
695version: the operating system version
696
697machine: a standard name that identifies the system's hardware
698
699       unset-alias alias-name
700              Unsets  an alias with the name alias-name in the user's environ‐
701              ment.
702
703       unset-function function-name
704              Removes a function with the name function-name from  the  user's
705              environment.
706
707       unsetenv variable [value]
708              Unsets  environment  variable.  However, if there is an optional
709              value, then when unloading a module, it  will  set  variable  to
710              value.  The  unsetenv  command  changes the process' environment
711              like setenv.
712
713       versioncmp version1 version2
714              Compare version string version1 against version string version2.
715              Returns  -1, 0 or 1 respectively if version1 is less than, equal
716              to or greater than version2.
717
718       x-resource [resource-string|filename]
719              Merge resources into the X11 resource  database.  The  resources
720              are  used  to control look and behavior of X11 applications. The
721              command will attempt to read resources from filename. If the ar‐
722              gument  isn't a valid file name, then string will be interpreted
723              as a resource. Either filename or resource-string is then passed
724              down to be xrdb(1) command.
725
726              modulefiles  that use this command, should in most cases contain
727              one or more x-resource lines, each defining  one  X11  resource.
728              The  DISPLAY environment variable should be properly set and the
729              X11 server should be accessible. If x-resource can't  manipulate
730              the  X11 resource database, the modulefile will exit with an er‐
731              ror message.
732
733              Examples:
734
735              x-resource /u2/staff/leif/.xres/Ileaf
736                 The content of the Ileaf file is merged into the X11 resource
737                 database.
738
739              x-resource [glob ~/.xres/ileaf]
740                 The  Tcl  glob  function  is used to have the modulefile read
741                 different resource files for different users.
742
743              x-resource {Ileaf.popup.saveUnder: True}
744                 Merge the Ileaf resource into the X11 resource database.
745

MODULES VARIABLES

747       ModulesCurrentModulefile
748              The ModulesCurrentModulefile variable contains the full pathname
749              of the modulefile being interpreted.
750
751       ModuleTool
752              The  ModuleTool  variable contains the name of the module imple‐
753              mentation currently in use. The value of this variable is set to
754              Modules for this implementation.
755
756       ModuleToolVersion
757              The  ModuleToolVersion variable contains the version of the mod‐
758              ule implementation currently in use. The value of this  variable
759              is set to 4.7.1 for this version of Modules.
760

LOCATING MODULEFILES

762       Every directory in MODULEPATH is searched to find the modulefile. A di‐
763       rectory in MODULEPATH can have an arbitrary number of  sub-directories.
764       If  the user names a modulefile to be loaded which is actually a direc‐
765       tory, the directory is opened and a search begins for an actual module‐
766       file.  First, modulecmd.tcl looks for a file with the name .modulerc in
767       the directory. If this file exists, its contents will be  evaluated  as
768       if  it  was  a  modulefile  to be loaded. You may place module-version,
769       module-alias and module-virtual commands inside this file.
770
771       Additionally, before seeking for .modulerc files in the  module  direc‐
772       tory, the global modulerc file and the .modulerc file found at the root
773       of the modulepath directory are sourced, too. If a  named  version  de‐
774       fault  now exists for the modulefile to be loaded, the assigned module‐
775       file now will be sourced. Otherwise the file .version is looked  up  in
776       the module directory.
777
778       If  the  .version file exists, it is opened and interpreted as Tcl code
779       and takes precedence over a .modulerc file in the  same  directory.  If
780       the  Tcl  variable  ModulesVersion  is  set  by the .version file, mod‐
781       ulecmd.tcl will use the name as if it specifies a  modulefile  in  this
782       directory.  This will become the default modulefile in this case.  Mod‐
783       ulesVersion cannot refer to a modulefile located in a different  direc‐
784       tory.
785
786       If  ModulesVersion is a directory, the search begins anew down that di‐
787       rectory. If the name does not match any files located  in  the  current
788       directory,  the  search  continues through the remaining directories in
789       MODULEPATH.
790
791       Every .version and .modulerc file found is interpreted as Tcl code. The
792       difference  is that .version only applies to the current directory, and
793       the .modulerc applies to the current directory and all  subdirectories.
794       Changes  made  in  these files will affect the subsequently interpreted
795       modulefile.
796
797       If no default version may be figured out, an implicit  default  is  se‐
798       lected  when  this behavior is enabled (see MODULES_IMPLICIT_DEFAULT in
799       module(1)). If disabled, module names should be fully qualified when no
800       explicit  default  is defined for them, otherwise no default version is
801       found and an error is returned. If enabled, then  the  highest  numeri‐
802       cally  sorted  modulefile, virtual module or module alias under the di‐
803       rectory will be used.  The dictionary comparison method of the lsort(n)
804       Tcl command is used to achieve this sort. If highest numerically sorted
805       element is an alias, search continues on its modulefile target.
806
807       For example, it is possible for a user to have a  directory  named  X11
808       which  simply  contains a .version file specifying which version of X11
809       is to be loaded. Such a file would look like:
810
811          #%Module1.0
812          ##
813          ##  The desired version of X11
814          ##
815          set ModulesVersion "R4"
816
817       The equivalent .modulerc would look like:
818
819          #%Module1.0
820          ##
821          ##  The desired version of X11
822          ##
823          module-version "./R4" default
824
825       If the extended default mechanism is enabled (see  MODULES_EXTENDED_DE‐
826       FAULT  in  module(1))  the  module version specified is matched against
827       starting portion of existing module versions, where portion is  a  sub‐
828       string separated from the rest of version string by a . character.
829
830       When  the  implicit  default  mechanism and the Advanced module version
831       specifiers are both enabled, a default and latest symbolic versions are
832       automatically  defined  for  each  module  name (also at each directory
833       level in case of deep modulefile). Unless a symbolic version, alias, or
834       regular module version already exists for these version names.
835
836       If user names a modulefile that cannot be found in the first modulepath
837       directory, modulefile will be searched in next modulepath directory and
838       so  on  until  a matching modulefile is found. If search goes through a
839       module alias or a symbolic version, this alias or symbol is resolved by
840       first  looking at the modulefiles in the modulepath where this alias or
841       symbol is defined. If not found, resolution looks  at  the  other  mod‐
842       ulepaths in their definition order.
843
844       When locating modulefiles, if a .modulerc, a .version, a directory or a
845       modulefile cannot be read during the search it is simply  ignored  with
846       no  error  message  produced.  Visibility  of  modulefiles  can thus be
847       adapted to the rights the user has been granted. Exception is made when
848       trying  to  directly  access a directory or a modulefile. In this case,
849       the access issue is returned as an error message.
850
851       Depending on their name, their file permissions or the use of  specific
852       modulefile  commands,  modulefile, virtual module, module alias or sym‐
853       bolic version may be set hidden which impacts available modules  search
854       or module selection processes (see Hiding modulefiles section below).
855

HIDING MODULEFILES

857       A  modulefile,  virtual  module, module alias or symbolic version whose
858       name or element in their name starts with a dot character  (.)  or  who
859       are  targeted  by  a  module-hide command are considered hidden. Hidden
860       modules are not displayed or taken into account except if they are  ex‐
861       plicitly  named  (e.g.,  foo/1.2.3  or foo/.2.0 not foo). If module has
862       been hidden with the --soft option of the module-hide command  set,  it
863       is  not  considered  hidden  if the root name of the query to search it
864       matches module root name (e.g., searching foo will return  a  foo/1.2.3
865       modulefile  targeted  by  a  module-hide --soft command). If module has
866       been hidden with the --hard option of the module-hide command  set,  it
867       is  always  considered hidden thus it is never displayed nor taken into
868       account even if it is explicitly named.
869
870       A modulefile, virtual module, module alias or symbolic version who  are
871       targeted by a module-hide --hard command and a module-forbid command or
872       whose file access permissions are restricted are considered hard-hidden
873       and  forbidden.  Such  modules are not displayed or taken into account.
874       When explicitly named for evaluation selection, such  modules  are  un‐
875       veiled to return an access error.
876
877       A  symbolic  version-name  assigned  to a hidden module is displayed or
878       taken into account only if  explicitly  named  and  if  module  is  not
879       hard-hidden.  Non-hidden module alias targeting a hidden modulefile ap‐
880       pears like any other non-hidden module alias. Finally,  a  hidden  sym‐
881       bolic  version targeting a non-hidden module is displayed or taken into
882       account only if not hard-hidden and explicitly named to  refer  to  its
883       non-hidden target.
884
885       The automatic version symbols (e.g., default and latest) are unaffected
886       by hiding. Moreover when a regular default or  latest  version  is  set
887       hidden, the corresponding automatic version symbol takes the left spot.
888       For instance, if foo/default which targets foo/1.2.3 is  set  hard-hid‐
889       den,  the  default automatic version symbol will be set onto foo/2.1.3,
890       the highest available version of foo.
891
892       When loading a modulefile or a virtual module targeted by a module-hide
893       --hidden-loaded  command,  this  module inherits the hidden-loaded tag.
894       Hidden loaded modules are not reported among list sub-command results.
895
896       If the --all is set on avail, aliases, whatis or  search  sub-commands,
897       hidden  modules  are  taken into account in search. Hard-hidden modules
898       are unaffected by this option.
899
900       If the --all is set on list sub-command, hidden loaded modules are  in‐
901       cluded in result output.
902

ADVANCED MODULE VERSION SPECIFIERS

904       When  the  advanced module version specifiers mechanism is enabled (see
905       MODULES_ADVANCED_VERSION_SPEC in module(1)), the specification of  mod‐
906       ulefile  passed  on  Modules  specific Tcl commands changes.  After the
907       module name a version constraint prefixed by the  @  character  may  be
908       added.  It  could  be directly appended to the module name or separated
909       from it with a space character.
910
911       Constraints can be expressed to refine the selection of module  version
912       to:
913
914       • a  single  version  with  the @version syntax, for instance foo@1.2.3
915         syntax will select module foo/1.2.3
916
917       • a list of versions with the @version1,version2,...  syntax,  for  in‐
918         stance foo@1.2.3,1.10 will match modules foo/1.2.3 and foo/1.10
919
920       • a  range  of  versions  with  the  @version1:,  @:version2  and @ver‐
921         sion1:version2 syntaxes, for instance foo@1.2: will select  all  ver‐
922         sions  of  module foo greater than or equal to 1.2, foo@:1.3 will se‐
923         lect all versions less than or equal to 1.3 and  foo@1.2:1.3  matches
924         all versions between 1.2 and 1.3 including 1.2 and 1.3 versions
925
926       Advanced  specification of single version or list of versions may bene‐
927       fit from the activation of the extended  default  mechanism  (see  MOD‐
928       ULES_EXTENDED_DEFAULT in module(1)) to use an abbreviated notation like
929       @1 to refer to more precise version numbers like 1.2.3.  Range of  ver‐
930       sions on its side natively handles abbreviated versions.
931
932       In  order to be specified in a range of versions or compared to a range
933       of versions, the version major element should corresponds to a  number.
934       For  instance 10a, 1.2.3, 1.foo are versions valid for range comparison
935       whereas default or foo.2 versions are invalid for range comparison.
936
937       If the implicit default mechanism  is  also  enabled  (see  MODULES_IM‐
938       PLICIT_DEFAULT  in  module(1)),  a default and latest symbolic versions
939       are automatically defined for each module name (also at each  directory
940       level  for  deep  modulefiles). These automatic version symbols are de‐
941       fined unless a symbolic version, alias, or regular module  version  al‐
942       ready  exists  for  these  default  or latest version names.  Using the
943       mod@latest (or mod/latest) syntax  ensures  highest  available  version
944       will be selected.
945

MODULEFILE SPECIFIC HELP

947       Users  can  request  help  about a specific modulefile through the mod‐
948       ule(1) command. The modulefile can print helpful information  or  start
949       help  oriented  programs by defining a ModulesHelp subroutine. The sub‐
950       routine will be called when the module help modulefile command is used.
951

MODULEFILE SPECIFIC TEST

953       Users can request test of a specific modulefile through  the  module(1)
954       command.  The  modulefile can perform some sanity checks on its defini‐
955       tion or on its underlying programs by defining  a  ModulesTest  subrou‐
956       tine.  The  subroutine  will  be called when the module test modulefile
957       command is used. The subroutine should return 1 in case of success.  If
958       no or any other value is returned, test is considered failed.
959

MODULEFILE DISPLAY

961       The module display modulefile command will detail all changes that will
962       be made to the environment. After displaying  all  of  the  environment
963       changes modulecmd.tcl will call the ModulesDisplay subroutine. The Mod‐
964       ulesDisplay subroutine is a good place to  put  additional  descriptive
965       information about the modulefile.
966

ENVIRONMENT

968       See the ENVIRONMENT section in the module(1) man page.
969

SEE ALSO

971       module(1),  ml(1),  Tcl(n), TclX(n), id(1), xrdb(1), exec(n), uname(1),
972       domainname(1), tclvars(n), lsort(n)
973

NOTES

975       Tcl was developed by John Ousterhout at the University of California at
976       Berkeley.
977
978       TclX was developed by Karl Lehenbauer and Mark Diekhans.
979
981       1996-1999  John  L.  Furlani  &  Peter  W.  Osel,  1998-2017  R.K.Owen,
982       2002-2004 Mark Lakata, 2004-2017 Kent Mein, 2016-2021 Xavier Delaruelle
983
984
985
986
9874.7.1                             2021-04-06                     MODULEFILE(4)
Impressum