Debian Codegraph @

doc/build/modulefile.5

raw
1 '\" t
2 .\" Man page generated from reStructuredText.
3 .
4 .
5 .nr rst2man-indent-level 0
6 .
7 .de1 rstReportMargin
8 \\$1 \\n[an-margin]
9 level \\n[rst2man-indent-level]
10 level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
11 -
12 \\n[rst2man-indent0]
13 \\n[rst2man-indent1]
14 \\n[rst2man-indent2]
15 ..
16 .de1 INDENT
17 .\" .rstReportMargin pre:
18 . RS \\$1
19 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
20 . nr rst2man-indent-level +1
21 .\" .rstReportMargin post:
22 ..
23 .de UNINDENT
24 . RE
25 .\" indent \\n[an-margin]
26 .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
27 .nr rst2man-indent-level -1
28 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
29 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
30 ..
31 .TH "MODULEFILE" "5" "2025-11-25" "5.6.1" "Modules"
32 .SH NAME
33 modulefile \- files containing Tcl code for the Modules package
34 .SH DESCRIPTION
35 .sp
36 \fImodulefiles\fP are written in the Tool Command Language, \fBTcl(n)\fP and
37 are interpreted by the \fBmodulecmd.tcl\fP program via the \fI\%module\fP
38 user interface. \fImodulefiles\fP can be loaded, unloaded, or switched on\-the\-fly
39 while the user is working; and can be used to implement site policies
40 regarding the access and use of applications.
41 .sp
42 A \fImodulefile\fP begins with the \fB#%Module\fP file signature, also called the
43 Modules magic cookie. A version number may be placed after this string. The
44 version number is useful as the \fImodulefile\fP format may change thus it
45 reflects the minimum version of \fBmodulecmd.tcl\fP required to interpret
46 the modulefile. If a version number doesn\(aqt exist, then \fBmodulecmd.tcl\fP
47 will assume the \fImodulefile\fP is compatible. Files without the magic cookie or
48 with a version number greater than the current version of
49 \fBmodulecmd.tcl\fP will not be interpreted. If the
50 \fI\%mcookie_version_check\fP configuration is disabled the version number
51 set is not checked.
52 .sp
53 Each \fImodulefile\fP contains the changes to a user\(aqs environment needed to
54 access an application. Tcl is a simple programming language which permits
55 \fImodulefiles\fP to be arbitrarily complex, depending upon the application\(aqs
56 and the \fImodulefile\fP writer\(aqs needs. If support for extended tcl (tclX)
57 has been configured for your installation of the Modules package, you may
58 use all the extended commands provided by tclX, too.
59 .sp
60 A typical \fImodulefile\fP is a simple bit of code that set or add entries
61 to the \fBPATH\fP, \fBMANPATH\fP, or other environment variables. A
62 Modulefile is evaluated against current \fBmodulecmd.tcl\fP\(aqs mode which
63 leads to specific evaluation results. For instance if the \fImodulefile\fP sets a
64 value to an environment variable, this variable is set when modulefile is
65 loaded and unset when modulefile is unloaded.
66 .sp
67 Tcl has conditional statements that are evaluated when the \fImodulefile\fP is
68 interpreted. This is very effective for managing path or environment changes
69 due to different OS releases or architectures. The user environment
70 information is encapsulated into a single \fImodulefile\fP kept in a central
71 location. The same \fImodulefile\fP is used by every user on any machine. So,
72 from the user\(aqs perspective, starting an application is exactly the same
73 irrespective of the machine or platform they are on.
74 .sp
75 \fImodulefiles\fP also hide the notion of different types of shells. From the
76 user\(aqs perspective, changing the environment for one shell looks exactly
77 the same as changing the environment for another shell. This is useful
78 for new or novice users and eliminates the need for statements such as \(dqif
79 you\(aqre using the C Shell do this ..., otherwise if you\(aqre using the Bourne
80 shell do this ...\(dq. Announcing and accessing new software is uniform and
81 independent of the user\(aqs shell. From the \fImodulefile\fP writer\(aqs perspective,
82 this means one set of information will take care of every type of shell.
83 .SH MODULES SPECIFIC TCL COMMANDS
84 .sp
85 The Modules Package uses commands which are extensions to the \(dqstandard\(dq
86 Tool Command Language \fBTcl(n)\fP package. Unless otherwise specified,
87 the Module commands return the empty string. Some commands behave differently
88 when a \fImodulefile\fP is loaded or unloaded. The command descriptions assume
89 the \fImodulefile\fP is being loaded.
90 .INDENT 0.0
91 .TP
92 .B add\-property name value
93 Associate module tag \fIvalue\fP to currently loading \fImodulefile\fP\&. Argument
94 \fIname\fP is ignored. See \fI\%module\-tag\fP command for more information on
95 tags.
96 .UNINDENT
97 .INDENT 0.0
98 .TP
99 .B always\-load [options] modulefile...
100 Load \fImodulefile\fP and apply the \fBkeep\-loaded\fP tag to it in order to avoid
101 the automatic unload of this \fImodulefile\fP when modules dependent of it are
102 unloaded.
103 .sp
104 \fI\%always\-load\fP command accepts the following options:
105 .INDENT 7.0
106 .IP \(bu 2
107 \fB\-\-modulepath modulepathlist\fP
108 .IP \(bu 2
109 \fB\-\-optional\fP
110 .IP \(bu 2
111 \fB\-\-tag taglist\fP
112 .UNINDENT
113 .sp
114 \fImodulefile\fP is declared as a requirement of currently loading module. This
115 command acts as an alias of \fI\%module load\fP command. If more
116 than one \fImodulefile\fP are specified, then this list acts as a Boolean AND
117 operation, which means all specified \fImodulefiles\fP are required.
118 .sp
119 When the \fB\-\-optional\fP option is set, each specified \fImodulefile\fP is
120 declared as an optional requirement. A \fImodulefile\fP that cannot be loaded,
121 will not stop the evaluation.
122 .sp
123 The \fB\-\-tag\fP option accepts a list of module tags to apply to \fImodulefile\fP
124 once loaded in addition to the \fBkeep\-loaded\fP tag. \fItaglist\fP corresponds to
125 the concatenation of multiple tags separated by colon character. \fItaglist\fP
126 should not contain tags inherited from \fImodulefile\fP state or from other
127 modulefile commands. If module is already loaded, tags from \fItaglist\fP are
128 added to the list of tags already applied to this module.
129 .sp
130 The \fB\-\-modulepath\fP option accepts a list of modulepath. \fImodulepathlist\fP
131 corresponds to the concatenation of multiple modulepaths separated by colon
132 character. When this option is set, required \fImodulefile\fP should be located
133 within one of the listed modulepaths. A path in this list may correspond to
134 the first path elements of an actual modulepath (e.g., \fB/path/to\fP will
135 match modulefiles located into the \fB/path/to/modulefiles\fP modulepath
136 directory).
137 .sp
138 If an attempt to load \fImodulefile\fP is performed and \fB\-\-modulepath\fP option
139 is set, \fImodulefile\fP will be searched in the enabled modulepaths whose start
140 match one of the specified paths and in the specified paths not matching any
141 enabled modulepaths. For instance if this option is set to
142 \fB/path/to:/another/path\fP and \fB/path/to/modulefiles\fP is currently the sole
143 enabled modulepath, \fImodulefile\fP will be searched into
144 \fB/path/to/modulefiles\fP and \fB/another/path\fP directories.
145 .UNINDENT
146 .INDENT 0.0
147 .TP
148 .B append\-path [\-d C|\-\-delim C|\-\-delim=C] [\-\-duplicates] variable value...
149 See \fI\%prepend\-path\fP\&.
150 .UNINDENT
151 .INDENT 0.0
152 .TP
153 .B break
154 This is not a Modules\-specific command, it\(aqs actually part of Tcl, which
155 has been overloaded similar to the \fI\%continue\fP and \fI\%exit\fP
156 commands to have the effect of causing the module not to be listed as loaded
157 and not affect other modules being loaded concurrently. All non\-environment
158 commands within the module will be performed up to this point. Processing
159 will continue on to the next module on the command line unless if
160 \fI\%abort_on_error\fP configuration option is enabled for running module
161 sub\-command. The \fI\%break\fP command will only have this effect if not
162 used within a Tcl loop though.
163 .sp
164 An example: Suppose that a full selection of \fImodulefiles\fP are needed for
165 various different architectures, but some of the \fImodulefiles\fP are not
166 needed and the user should be alerted. Having the unnecessary \fImodulefile\fP
167 be a link to the following \fBnotavail\fP \fImodulefile\fP will perform the task
168 as required.
169 .INDENT 7.0
170 .INDENT 3.5
171 .sp
172 .EX
173 #%Module
174
175 module\-help {This module does nothing but alert the user}
176 module\-help \(dqthat the [module\-info name] module is not available\(dq
177
178 module\-whatis {Notifies user that module is not available.}
179
180 set curMod [module\-info name]
181 if {[module\-info mode load]} {
182 puts stderr \(dqNote: \(aq$curMod\(aq is not available for [uname sysname].\(dq
183 }
184 break
185 .EE
186 .UNINDENT
187 .UNINDENT
188 .sp
189 Modulefile using \fI\%break\fP command when unloading may be unloaded anyway
190 if \fI\%\-\-force\fP option is set. To forbid the unload of a modulefile, it
191 is recommended to tag it \fBsuper\-sticky\fP with \fI\%module\-tag\fP command.
192 .UNINDENT
193 .INDENT 0.0
194 .TP
195 .B chdir directory
196 Set the current working directory to \fIdirectory\fP\&.
197 .UNINDENT
198 .INDENT 0.0
199 .TP
200 .B complete shell name body
201 Define shell completion for command \fIname\fP with specified \fIbody\fP if \fIshell\fP
202 is the current shell under which \fBmodulecmd.tcl\fP was invoked. \fIBody\fP
203 corresponds to argument options accepted by the shell command which
204 defines completion. When a \fImodulefile\fP is unloaded, \fI\%complete\fP
205 becomes \fI\%uncomplete\fP\&.
206 .sp
207 The following \fIshells\fP are supported: bash, tcsh, bash and fish. Please refer
208 to the documentation of these shells to learn how to define completion. The
209 command is ignored if an unsupported shell is specified.
210 .UNINDENT
211 .INDENT 0.0
212 .TP
213 .B conflict modulefile...
214 \fI\%conflict\fP controls whether or not the \fImodulefile\fP will be loaded.
215 The \fI\%conflict\fP command lists \fImodulefiles\fP which conflict with the
216 current \fImodulefile\fP\&. If a list contains more than one \fImodulefile\fP, then
217 each member of the list acts as a Boolean OR operation. Multiple
218 \fI\%conflict\fP commands may be used to create a Boolean AND operation. If
219 one of the requirements have not been satisfied, an error is reported and the
220 current \fImodulefile\fP makes no changes to the user\(aqs environment.
221 .sp
222 If an argument for \fI\%conflict\fP is a directory and any other
223 \fImodulefile\fP from that directory has been loaded, then a conflict will occur.
224 For example, specifying X11 as a \fI\%conflict\fP will stop X11/R4 and
225 X11/R5 from being loaded at the same time.
226 .sp
227 The parameter \fImodulefile\fP may also be a symbolic modulefile name or a
228 modulefile alias. It may also leverage a specific syntax to finely select
229 module version (see \fI\%Advanced module version specifiers\fP section below).
230 .sp
231 If the \fI\%conflict_unload\fP and \fI\%auto_handling\fP configuration
232 options are enabled, \fI\%conflict\fP will attempt to unload all loaded
233 modules that match specification. (see \fI\%Automated module handling
234 mechanisms\fP in \fI\%module\fP).
235 .UNINDENT
236 .INDENT 0.0
237 .TP
238 .B continue
239 This is not a modules specific command but another overloaded Tcl command
240 and is similar to the \fI\%break\fP or \fI\%exit\fP commands except the
241 module will be listed as loaded as well as performing any environment or Tcl
242 commands up to this point and then continuing on to the next module on
243 the command line. The \fI\%continue\fP command will only have this effect if
244 not used within a Tcl loop though.
245 .UNINDENT
246 .INDENT 0.0
247 .TP
248 .B depends\-on [options] modulefile...
249 Alias of \fI\%prereq\-all\fP command.
250 .UNINDENT
251 .INDENT 0.0
252 .TP
253 .B depends\-on\-any [options] modulefile...
254 Alias of \fI\%prereq\fP command.
255 .UNINDENT
256 .INDENT 0.0
257 .TP
258 .B exit [N]
259 This is not a modules specific command but another overloaded Tcl command
260 and is similar to the \fI\%break\fP or \fI\%continue\fP commands. However,
261 this command will cause the immediate cessation of this module. Any
262 additional modules on the command line will not be evaluated even if the
263 \fI\%abort_on_error\fP configuration option is disabled for running
264 module sub\-command. This module and the subsequent modules will not be listed
265 as loaded. No environment commands will be performed in the current module.
266 .UNINDENT
267 .INDENT 0.0
268 .TP
269 .B extensions modulefile...
270 Alias of \fI\%provide\fP command.
271 .UNINDENT
272 .INDENT 0.0
273 .TP
274 .B family name
275 Defines loading modulefile as a member of family \fIname\fP\&. Only one member of a
276 family could be loaded. Error is raised when attempting to load another
277 member of the same family \fIname\fP\&.
278 .sp
279 \fI\%family\fP corresponds to the definition of a \fI\%conflict\fP on
280 \fIname\fP and the definition of a \fI\%module\-alias\fP \fIname\fP targeting
281 currently loading module.
282 .sp
283 In addition, the \fI\%MODULES_FAMILY_<NAME>\fP environment variable is
284 defined and set to the currently loading module name minus version. This
285 variable helps to know what module provides for the family \fIname\fP in the
286 currently loaded environment. For instance if loading modulefile \fBfoo/1.0\fP
287 defines being member of the \fBbar\fP family, the
288 \fI\%MODULES_FAMILY_BAR\fP will be set to the
289 \fBfoo\fP value. For compatibility, the \fBLMOD_FAMILY_<NAME>\fP
290 environment variable is also defined and set to the same value than
291 \fI\%MODULES_FAMILY_<NAME>\fP\&.
292 .sp
293 \fIname\fP should be a non\-empty string only containing characters that could be
294 part of an environment variable name (i.e., \fI[a\-zA\-Z0\-9_]\fP).
295 .sp
296 If the \fI\%conflict_unload\fP and \fI\%auto_handling\fP configuration
297 options are enabled, an attempt to unload loaded module that defines the same
298 family is made. (see \fI\%Automated module handling
299 mechanisms\fP in \fI\%module\fP).
300 .UNINDENT
301 .INDENT 0.0
302 .TP
303 .B getenv [\-\-return\-value] variable [value]
304 Returns value of environment \fIvariable\fP\&. If \fIvariable\fP is not defined,
305 \fIvalue\fP is returned if set, an empty string is returned otherwise. The
306 \fI\%getenv\fP command should be preferred over the Tcl global variable
307 \fBenv\fP to query environment variables.
308 .sp
309 When modulefile is evaluated in \fIdisplay\fP mode, \fI\%getenv\fP returns
310 \fIvariable\fP name prefixed with dollar sign (e.g., \fB$variable\fP) unless if the
311 \fB\-\-return\-value\fP option is set. When this option is set the value of
312 environment \fIvariable\fP or defined fallback value is returned in \fIdisplay\fP
313 mode.
314 .UNINDENT
315 .INDENT 0.0
316 .TP
317 .B getvariant [\-\-return\-value] variant [value]
318 Returns value of designated \fIvariant\fP\&. If \fIvariant\fP is not defined, \fIvalue\fP
319 is returned if set, an empty string is returned otherwise. The
320 \fI\%getvariant\fP command should be preferred over the
321 \fI\%ModuleVariant\fP Tcl array to query a variant value.
322 .sp
323 When modulefile is evaluated in \fIdisplay\fP mode, \fI\%getvariant\fP returns
324 \fIvariant\fP name enclosed in curly braces (e.g., \fB{variant}\fP) unless if the
325 \fB\-\-return\-value\fP option is set. When this option is set the value of
326 \fIvariant\fP or defined fallback value is returned in \fIdisplay\fP mode.
327 .UNINDENT
328 .INDENT 0.0
329 .TP
330 .B haveDynamicMPATH
331 \fI\%haveDynamicMPATH\fP command signals that a modulefile modifies the
332 \fI\%MODULEPATH\fP environment variable. It is useful when the modulefile
333 conditionally updates \fI\%MODULEPATH\fP and is processed by Lmod tool.
334 .sp
335 Here in the Modules tool, this command is implemented as a \fIno\-operation\fP,
336 since the \fI\%spider\fP sub\-command evaluates the modulefile in the
337 context of the current user to determine whether \fI\%MODULEPATH\fP is
338 updated.
339 .UNINDENT
340 .INDENT 0.0
341 .TP
342 .B hide\-modulefile modulefile
343 Alias of \fI\%module\-hide\fP command.
344 .UNINDENT
345 .INDENT 0.0
346 .TP
347 .B hide\-version modulefile
348 Alias of \fI\%module\-hide\fP command.
349 .UNINDENT
350 .INDENT 0.0
351 .TP
352 .B is\-avail modulefile...
353 The \fI\%is\-avail\fP command returns a true value if any of the listed
354 \fImodulefiles\fP exists in enabled \fI\%MODULEPATH\fP\&. If a list contains more
355 than one \fImodulefile\fP, then each member acts as a boolean OR operation. If an
356 argument for \fI\%is\-avail\fP is a directory and a \fImodulefile\fP exists in
357 the directory \fI\%is\-avail\fP would return a true value.
358 .sp
359 The parameter \fImodulefile\fP may also be a symbolic modulefile name or a
360 modulefile alias. It may also leverage a specific syntax to finely select
361 module version (see \fI\%Advanced module version specifiers\fP section below).
362 .UNINDENT
363 .INDENT 0.0
364 .TP
365 .B is\-loaded [modulefile...]
366 The \fI\%is\-loaded\fP command returns a true value if any of the listed
367 \fImodulefiles\fP has been loaded or if any \fImodulefile\fP is loaded in case no
368 argument is provided. If a list contains more than one \fImodulefile\fP, then
369 each member acts as a boolean OR operation. If an argument for
370 \fI\%is\-loaded\fP is a directory and any \fImodulefile\fP from the directory has
371 been loaded \fI\%is\-loaded\fP would return a true value.
372 .sp
373 The parameter \fImodulefile\fP may also be a symbolic modulefile name or a
374 modulefile alias. It may also leverage a specific syntax to finely select
375 module version (see \fI\%Advanced module version specifiers\fP section below).
376 .UNINDENT
377 .INDENT 0.0
378 .TP
379 .B is\-saved [collection...]
380 The \fI\%is\-saved\fP command returns a true value if any of the listed
381 \fIcollections\fP exists or if any \fIcollection\fP exists in case no argument is
382 provided. If a list contains more than one \fIcollection\fP, then each member
383 acts as a boolean OR operation.
384 .sp
385 If \fI\%MODULES_COLLECTION_TARGET\fP is set, a suffix equivalent to the
386 value of this variable is appended to the passed \fIcollection\fP name. In case
387 no \fIcollection\fP argument is provided, a true value will only be returned if
388 a collection matching currently set target exists.
389 .UNINDENT
390 .INDENT 0.0
391 .TP
392 .B is\-used [directory...]
393 The \fI\%is\-used\fP command returns a true value if any of the listed
394 \fIdirectories\fP has been enabled in \fI\%MODULEPATH\fP or if any \fIdirectory\fP
395 is enabled in case no argument is provided. If a list contains more than one
396 \fIdirectory\fP, then each member acts as a boolean OR operation.
397 .UNINDENT
398 .INDENT 0.0
399 .TP
400 .B lsb\-release field
401 Provide certain Linux Standard Base (LSB) information. \fI\%lsb\-release\fP
402 will invoke the \fBlsb_release(1)\fP command to get each \fIfield\fP
403 information.
404 .sp
405 \fIfield\fP values are:
406 .INDENT 7.0
407 .IP \(bu 2
408 \fBid\fP: string id of distributor
409 .IP \(bu 2
410 \fBrelease\fP: release number of distribution
411 .IP \(bu 2
412 \fBcodename\fP: codename according to distribution release
413 .UNINDENT
414 .UNINDENT
415 .INDENT 0.0
416 .TP
417 .B module [sub\-command] [sub\-command\-options] [sub\-command\-args]
418 This command permits a \fImodulefile\fP to \fI\%load\fP or \fI\%unload\fP
419 other \fImodulefiles\fP or to \fI\%use\fP or \fI\%unuse\fP \fImodulepaths\fP\&. No
420 checks are made to ensure that the \fImodulefile\fP does not try to load itself.
421 Often it is useful to have a single \fImodulefile\fP that performs a number of
422 \fBmodule load\fP commands. For example, if every user on the system requires a
423 basic set of applications loaded, then a core \fImodulefile\fP would contain the
424 necessary \fBmodule load\fP commands.
425 .sp
426 The \fB\-\-not\-req\fP option may be set for the \fBload\fP, \fBtry\-load\fP,
427 \fBload\-any\fP, \fBunload\fP and \fBswitch\fP sub\-commands to inhibit the
428 definition of an implicit prereq or conflict requirement onto specified
429 modules.
430 .sp
431 On \fBtry\-load\fP sub\-command, \fImodulefiles\fP are considered optional prereq
432 requirement. However an error is raised if they cannot be loaded unless if
433 they are not found or forbidden.
434 .sp
435 The \fBload\-any\fP sub\-command loads one \fImodulefile\fP from the specified list.
436 An error is obtained if no \fImodulefile\fP from the list can be loaded. No
437 operation is performed if a \fImodulefile\fP from the list is found already
438 loaded.
439 .sp
440 The \fBunload\fP sub\-command unloads one matching \fImodulefile\fP for each module
441 specification provided as argument if \fI\%auto_handling\fP or
442 \fI\%conflict_unload\fP configuration options are disabled. When both
443 options are enabled, \fBunload\fP removes all loaded modules matching each
444 module specification. When both options are enabled, modules dependent of the
445 unloaded modules are also unloaded. Otherwise an error is raised if module to
446 unload has a dependent module loaded.
447 .sp
448 If the \fI\%require_via\fP configuration option is enabled, the \fBuse\fP
449 sub\-command defines a requirement of modulefiles stored in the added
450 modulepath onto current \fImodulefile\fP\&.
451 .sp
452 The \fBunuse\fP sub\-command accepts the \fB\-\-remove\-on\-unload\fP,
453 \fB\-\-noop\-on\-unload\fP, \fB\-\-append\-on\-unload\fP and \fB\-\-prepend\-on\-unload\fP
454 options to control the behavior to apply when \fImodulefile\fP is unloaded. See
455 \fI\%remove\-path\fP for further explanation.
456 .sp
457 The \fBload\fP, \fBtry\-load\fP, \fBload\-any\fP and \fBswitch\fP sub\-commands accept
458 the \fB\-\-tag\fP option to apply specified tags to \fImodulefile\fP once loaded.
459 Option accepts a concatenation of multiple module tags separated by colon
460 character. \fItaglist\fP should not contain tags inherited from \fImodulefile\fP
461 state or from other modulefile commands. If module is already loaded, tags
462 from \fItaglist\fP are added to the list of tags already applied to this module.
463 .sp
464 Command line switches \fI\%\-\-auto\fP, \fI\%\-\-no\-auto\fP and
465 \fI\%\-\-force\fP are ignored when passed to a \fI\%module\fP command set in
466 a \fImodulefile\fP\&.
467 .sp
468 Not all the \fIsub\-commands\fP described in the \fI\%Module Sub\-Commands\fP
469 section of the \fI\%module\fP man page are available when \fI\%module\fP
470 is used as a Modules specific Tcl command. The following table summarizes the
471 different sub\-commands available for each interpretation context.
472 .TS
473 box center;
474 l|l|l.
475 T{
476 Sub\-commands available from
477 modulefile interpretation
478 T} T{
479 Sub\-commands available from \fBinitrc\fP configuration
480 file and sourced
481 script file
482 T} T{
483 Sub\-commands available from run\-command (rc) file
484 interpretation
485 T}
486 _
487 T{
488 \fI\%load\fP,
489 \fI\%load\-any\fP,
490 \fI\%switch\fP,
491 \fI\%try\-load\fP,
492 \fI\%unload\fP,
493 \fI\%unuse\fP, \fI\%use\fP\&.
494 Also available but not recommended for use from regular
495 modulefile: \fI\%aliases\fP,
496 \fI\%avail\fP,
497 \fI\%display\fP,
498 \fI\%initadd\fP,
499 \fI\%initclear\fP,
500 \fI\%initlist\fP,
501 \fI\%initprepend\fP,
502 \fI\%initrm\fP,
503 \fI\%initswitch\fP,
504 \fI\%list\fP,
505 \fI\%purge\fP,
506 \fI\%reload\fP,
507 \fI\%restore\fP,
508 \fI\%save\fP,
509 \fI\%savelist\fP,
510 \fI\%saverm\fP,
511 \fI\%saveshow\fP,
512 \fI\%search\fP,
513 \fI\%test\fP,
514 \fI\%whatis\fP
515 T} T{
516 Same sub\-commands
517 available than for
518 modulefile and
519 \fI\%config\fP
520 sub\-command.
521 T} T{
522 \fINone\fP
523 T}
524 .TE
525 .UNINDENT
526 .INDENT 0.0
527 .TP
528 .B module\-alias name modulefile
529 Assigns the \fImodulefile\fP to the alias \fIname\fP\&. This command should be
530 placed in one of the \fBmodulecmd.tcl\fP rc files in order to provide
531 shorthand invocations of frequently used \fImodulefile\fP names.
532 .sp
533 The parameter \fImodulefile\fP may be either
534 .INDENT 7.0
535 .IP \(bu 2
536 a fully qualified \fImodulefile\fP with name and version
537 .IP \(bu 2
538 a symbolic \fImodulefile\fP name
539 .IP \(bu 2
540 another \fImodulefile\fP alias
541 .UNINDENT
542 .UNINDENT
543 .INDENT 0.0
544 .TP
545 .B module\-forbid [options] modulefile...
546 Forbid use of \fImodulefile\fP\&. An error is obtained when trying to evaluate a
547 forbidden module. This command should be placed in one of the
548 \fBmodulecmd.tcl\fP rc files.
549 .sp
550 \fI\%module\-forbid\fP command accepts the following options:
551 .INDENT 7.0
552 .IP \(bu 2
553 \fB\-\-after datetime\fP
554 .IP \(bu 2
555 \fB\-\-before datetime\fP
556 .IP \(bu 2
557 \fB\-\-not\-user {user...}\fP
558 .IP \(bu 2
559 \fB\-\-not\-group {group...}\fP
560 .IP \(bu 2
561 \fB\-\-user {user...}\fP
562 .IP \(bu 2
563 \fB\-\-group {group...}\fP
564 .IP \(bu 2
565 \fB\-\-message {text message}\fP
566 .IP \(bu 2
567 \fB\-\-nearly\-message {text message}\fP
568 .UNINDENT
569 .sp
570 If \fB\-\-after\fP option is set, forbidding is only effective after specified
571 date time. Following the same principle, if \fB\-\-before\fP option is set,
572 forbidding is only effective before specified date time. Accepted date time
573 format is \fBYYYY\-MM\-DD[THH:MM]\fP\&. If no time (\fBHH:MM\fP) is specified,
574 \fB00:00\fP is assumed. \fB\-\-after\fP and \fB\-\-before\fP options are not supported
575 on Tcl versions prior to 8.5.
576 .sp
577 If \fB\-\-not\-user\fP option is set, forbidding is not applied if the username of
578 the user currently running \fBmodulecmd.tcl\fP is part of the list of
579 username specified. Following the same approach, if \fB\-\-not\-group\fP option is
580 set, forbidding is not applied if current user is member of one of the groups
581 specified. When both options are set, forbidding is not applied if a match is
582 found for \fB\-\-not\-user\fP or \fB\-\-not\-group\fP\&.
583 .sp
584 If \fB\-\-user\fP option is set, forbidding is applied only if the username of
585 the user currently running \fBmodulecmd.tcl\fP is part of the list of
586 username specified. Following the same approach, if \fB\-\-group\fP option is
587 set, forbidding is applied only if current user is member of one of the
588 groups specified. When both options are set, forbidding is applied if a match
589 is found for \fB\-\-user\fP or \fB\-\-group\fP\&. If the same user name is set on both
590 \fB\-\-user\fP and \fB\-\-not\-user\fP options, \fB\-\-user\fP prevails over
591 \fB\-\-not\-user\fP\&. If the same group name is set on both \fB\-\-group\fP and
592 \fB\-\-not\-group\fP, \fB\-\-group\fP prevails over \fB\-\-not\-group\fP\&.
593 .sp
594 Error message returned when trying to evaluate a forbidden module can be
595 supplemented with the \fItext message\fP set through \fB\-\-message\fP option.
596 .sp
597 If \fB\-\-after\fP option is set, modules are considered \fInearly forbidden\fP
598 during a number of days defined by the \fI\%nearly_forbidden_days\fP
599 \fBmodulecmd.tcl\fP configuration option
600 (see \fI\%MODULES_NEARLY_FORBIDDEN_DAYS\fP), prior reaching the expiry
601 date fixed by \fB\-\-after\fP option. When a \fInearly forbidden\fP module is
602 evaluated a warning message is issued to inform module will soon be
603 forbidden. This warning message can be supplemented with the \fItext message\fP
604 set through \fB\-\-nearly\-message\fP option.
605 .sp
606 If a \fI\%module\-forbid\fP command applies to a \fImodulefile\fP also targeted
607 by a \fI\%module\-hide \-\-hard\fP command, this module is
608 unveiled when precisely named to return an access error.
609 .sp
610 Forbidden modules included in the result of \fI\%avail\fP or
611 \fI\%spider\fP sub\-commands are reported with a \fBforbidden\fP tag applied
612 to them. Nearly forbidden modules included in the result of \fI\%avail\fP,
613 \fI\%list\fP or \fI\%spider\fP sub\-commands are reported with a
614 \fBnearly\-forbidden\fP tag applied to them. See \fI\%Module tags\fP section in
615 \fI\%module\fP\&.
616 .sp
617 The parameter \fImodulefile\fP may leverage a specific syntax to finely select
618 module version (see \fI\%Advanced module version specifiers\fP section below). It
619 may also be a full path file name to precisely designate one module in a
620 specific modulepath.
621 .UNINDENT
622 .INDENT 0.0
623 .TP
624 .B module\-help string
625 Defines a string which is displayed in case of the invocation of the
626 \fI\%module help\fP command. This command takes no action on non\-help
627 \fImodulefile\fP evaluation.
628 .sp
629 Multi\-word \fIstring\fP should be enclosed in curly\-braces or double\-quotes.
630 There may be more than one \fI\%module\-help\fP command call in a
631 \fImodulefile\fP\&. In which case each command call is reported as a separate line.
632 .sp
633 If a \fImodulefile\fP also defines a \fBModulesHelp\fP procedure, the text defined
634 with \fI\%module\-help\fP is printed before running this procedure on
635 \fBhelp\fP evaluation mode.
636 .UNINDENT
637 .INDENT 0.0
638 .TP
639 .B module\-hide [options] modulefile...
640 Hide \fImodulefile\fP to exclude it from available module search or module
641 selection unless query refers to \fImodulefile\fP by its exact name. This command
642 should be placed in one of the \fBmodulecmd.tcl\fP rc files.
643 .sp
644 \fI\%module\-hide\fP command accepts the following options:
645 .INDENT 7.0
646 .IP \(bu 2
647 \fB\-\-soft|\-\-hard\fP
648 .IP \(bu 2
649 \fB\-\-hidden\-loaded\fP
650 .IP \(bu 2
651 \fB\-\-after datetime\fP
652 .IP \(bu 2
653 \fB\-\-before datetime\fP
654 .IP \(bu 2
655 \fB\-\-not\-user {user...}\fP
656 .IP \(bu 2
657 \fB\-\-not\-group {group...}\fP
658 .IP \(bu 2
659 \fB\-\-user {user...}\fP
660 .IP \(bu 2
661 \fB\-\-group {group...}\fP
662 .UNINDENT
663 .sp
664 When \fB\-\-soft\fP option is set, \fImodulefile\fP is also set hidden, but hiding is
665 disabled when search or selection query\(aqs root name matches module\(aqs root
666 name. This soft hiding mode enables to hide modulefiles from bare module
667 availability listing yet keeping the ability to select such module for load
668 with the regular resolution mechanism (i.e., no need to use module exact name
669 to select it)
670 .sp
671 When \fB\-\-hard\fP option is set, \fImodulefile\fP is also set hidden and stays
672 hidden even if search or selection query refers to \fImodulefile\fP by its exact
673 name.
674 .sp
675 When \fB\-\-hidden\-loaded\fP option is set, hidden state also applies to the
676 \fImodulefile\fP when it is loaded. Hidden loaded modules do not appear on
677 \fI\%list\fP sub\-command output, unless \fI\%\-\-all\fP option is set.
678 Their loading or unloading informational messages are not reported unless the
679 \fI\%verbosity of Modules\fP is set to a level higher
680 than \fBverbose\fP\&. Hidden loaded modules are detected in any cases by state
681 query commands like \fI\%is\-loaded\fP\&.
682 .sp
683 If \fB\-\-after\fP option is set, hiding is only effective after specified date
684 time. Following the same principle, if \fB\-\-before\fP option is set, hiding is
685 only effective before specified date time. Accepted date time format is
686 \fBYYYY\-MM\-DD[THH:MM]\fP\&. If no time (\fBHH:MM\fP) is specified, \fB00:00\fP is
687 assumed. \fB\-\-after\fP and \fB\-\-before\fP options are not supported on Tcl
688 versions prior to 8.5.
689 .sp
690 If \fB\-\-not\-user\fP option is set, hiding is not applied if the username of the
691 user currently running \fBmodulecmd.tcl\fP is part of the list of username
692 specified. Following the same approach, if \fB\-\-not\-group\fP option is set,
693 hiding is not applied if current user is member of one of the groups
694 specified. When both options are set, hiding is not applied if a match is
695 found for \fB\-\-not\-user\fP or \fB\-\-not\-group\fP\&.
696 .sp
697 If \fB\-\-user\fP option is set, hiding is applied only if the username of the
698 user currently running \fBmodulecmd.tcl\fP is part of the list of username
699 specified. Following the same approach, if \fB\-\-group\fP option is set, hiding
700 is applied only if current user is member of one of the groups specified.
701 When both options are set, hiding is applied if a match is found for
702 \fB\-\-user\fP or \fB\-\-group\fP\&. If the same user name is set on both \fB\-\-user\fP
703 and \fB\-\-not\-user\fP options, \fB\-\-user\fP prevails over \fB\-\-not\-user\fP\&. If the
704 same group name is set on both \fB\-\-group\fP and \fB\-\-not\-group\fP, \fB\-\-group\fP
705 prevails over \fB\-\-not\-group\fP\&.
706 .sp
707 If the \fI\%\-\-all\fP option is set on \fI\%avail\fP, \fI\%aliases\fP,
708 \fI\%whatis\fP, \fI\%search\fP or \fI\%spider\fP sub\-commands, hiding
709 is disabled thus hidden modulefiles are included in module search.
710 Hard\-hidden modules (i.e., declared hidden with \fB\-\-hard\fP option) are not
711 affected by \fI\%\-\-all\fP and stay hidden even if option is set.
712 \fI\%\-\-all\fP option does not apply to \fImodule selection\fP sub\-commands like
713 \fI\%load\fP\&. Thus in such context a hidden module should always be
714 referred by its exact full name (e.g., \fBfoo/1.2.3\fP not \fBfoo\fP) unless if
715 it has been hidden in \fB\-\-soft\fP mode. A hard\-hidden module cannot be
716 unveiled or selected in any case.
717 .sp
718 If several \fI\%module\-hide\fP commands target the same \fImodulefile\fP, the
719 strongest hiding level is retained which means if both a regular, a
720 \fB\-\-soft\fP hiding command match a given module, regular hiding mode is
721 considered. If both a regular and a \fB\-\-hard\fP hiding command match a given
722 module, hard hiding mode is retained. A set \fB\-\-hidden\-loaded\fP option is
723 retained even if the \fI\%module\-hide\fP statement on which it is declared
724 is superseded by a stronger \fI\%module\-hide\fP statement with no
725 \fB\-\-hidden\-loaded\fP option set.
726 .sp
727 Hidden modules included in the result of \fI\%avail\fP or \fI\%spider\fP
728 sub\-commands are reported with a \fBhidden\fP tag applied to them. Hidden
729 loaded modules included in the result of \fI\%list\fP sub\-command are
730 reported with a \fBhidden\-loaded\fP tag applied to them. This tag is not
731 reported on \fI\%avail\fP or \fI\%spider\fP sub\-commands context. See
732 \fI\%Module tags\fP section in \fI\%module\fP\&.
733 .sp
734 The parameter \fImodulefile\fP may also be a symbolic modulefile name or a
735 modulefile alias. It may also leverage a specific syntax to finely select
736 module version (see \fI\%Advanced module version specifiers\fP section below).
737 Moreover it may also be a full path file name to precisely designate one
738 module in a specific modulepath.
739 .UNINDENT
740 .INDENT 0.0
741 .TP
742 .B module\-info option [info\-args]
743 Provide information about the \fBmodulecmd.tcl\fP program\(aqs state. Some of
744 the information is specific to the internals of \fBmodulecmd.tcl\fP\&.
745 \fIoption\fP is the type of information to be provided, and \fIinfo\-args\fP are any
746 arguments needed.
747 .sp
748 \fBmodule\-info alias\fP name
749 .INDENT 7.0
750 .INDENT 3.5
751 Returns the full \fImodulefile\fP name to which the \fImodulefile\fP alias \fIname\fP
752 is assigned
753 .UNINDENT
754 .UNINDENT
755 .sp
756 \fBmodule\-info command\fP [commandname]
757 .INDENT 7.0
758 .INDENT 3.5
759 Returns the currently running \fBmodulecmd.tcl\fP\(aqs command as a string
760 if no \fIcommandname\fP is given.
761 .sp
762 Returns \fB1\fP if \fBmodulecmd.tcl\fP\(aqs command is \fIcommandname\fP\&.
763 \fIcommandname\fP can be: \fBload\fP, \fBunload\fP, \fBrefresh\fP, \fBreload\fP,
764 \fBsource\fP, \fBswitch\fP, \fBdisplay\fP, \fBavail\fP, \fBaliases\fP, \fBlist\fP,
765 \fBwhatis\fP, \fBsearch\fP, \fBpurge\fP, \fBrestore\fP, \fBhelp\fP, \fBtest\fP,
766 \fBtry\-load\fP, \fBload\-any\fP, \fBmod\-to\-sh\fP, \fBreset\fP, \fBstash\fP,
767 \fBstashpop\fP or \fBspider\fP\&.
768 .UNINDENT
769 .UNINDENT
770 .sp
771 \fBmodule\-info loaded\fP modulefile
772 .INDENT 7.0
773 .INDENT 3.5
774 Returns the names of currently loaded modules matching passed \fImodulefile\fP\&.
775 The parameter \fImodulefile\fP might either be a fully qualified \fImodulefile\fP
776 with name and version or just a directory which in case all loaded
777 \fImodulefiles\fP from the directory will be returned. The parameter
778 \fImodulefile\fP may also be a symbolic modulefile name or a modulefile alias.
779 .sp
780 This command only returns the name and version of designated loaded module.
781 The defined variants of the loaded module are not included in the returned
782 string.
783 .UNINDENT
784 .UNINDENT
785 .sp
786 \fBmodule\-info mode\fP [modetype]
787 .INDENT 7.0
788 .INDENT 3.5
789 Returns the current \fBmodulecmd.tcl\fP\(aqs mode as a string if no
790 \fImodetype\fP is given.
791 .sp
792 Returns \fB1\fP if \fBmodulecmd.tcl\fP\(aqs mode is \fImodetype\fP\&. \fImodetype\fP can
793 be: \fBload\fP, \fBunload\fP, \fBremove\fP (alias of \fBunload\fP), \fBswitch\fP,
794 \fBrefresh\fP, \fBnonpersist\fP (alias of \fBrefresh\fP), \fBdisplay\fP, \fBhelp\fP,
795 \fBtest\fP, \fBwhatis\fP or \fBscan\fP\&.
796 .UNINDENT
797 .UNINDENT
798 .sp
799 \fBmodule\-info name\fP
800 .INDENT 7.0
801 .INDENT 3.5
802 Return the name of the \fImodulefile\fP\&. This is not the full pathname for
803 \fImodulefile\fP\&. See the \fI\%Modules Variables\fP section for information on the
804 full pathname.
805 .sp
806 This command only returns the name and version of currently evaluating
807 \fImodulefile\fP\&. The defined variants are not included in the returned string.
808 See \fI\%getvariant\fP command or \fI\%ModuleVariant\fP array variable to
809 get defined variant values for currently evaluating \fImodulefile\fP\&.
810 .UNINDENT
811 .UNINDENT
812 .sp
813 \fBmodule\-info shell\fP [shellname]
814 .INDENT 7.0
815 .INDENT 3.5
816 Return the current shell under which \fBmodulecmd.tcl\fP was invoked if
817 no \fIshellname\fP is given. The current shell is the first parameter of
818 \fBmodulecmd.tcl\fP, which is normally hidden by the \fBmodule\fP
819 alias.
820 .sp
821 If a \fIshellname\fP is given, returns \fB1\fP if \fBmodulecmd.tcl\fP\(aqs current
822 shell is \fIshellname\fP, returns \fB0\fP otherwise. \fIshellname\fP can be: \fBsh\fP,
823 \fBbash\fP, \fBksh\fP, \fBzsh\fP, \fBcsh\fP, \fBtcsh\fP, \fBfish\fP, \fBcmd\fP, \fBpwsh\fP,
824 \fBtcl\fP, \fBperl\fP, \fBpython\fP, \fBruby\fP, \fBlisp\fP, \fBcmake\fP, \fBr\fP\&.
825 .UNINDENT
826 .UNINDENT
827 .sp
828 \fBmodule\-info shelltype\fP [shelltypename]
829 .INDENT 7.0
830 .INDENT 3.5
831 Return the family of the shell under which \fImodulefile\fP was invoked if no
832 \fIshelltypename\fP is given. As of \fI\%module\-info shell\fP this
833 depends on the first parameter of \fBmodulecmd.tcl\fP\&. The output reflects
834 a shell type determining the shell syntax of the commands produced by
835 \fBmodulecmd.tcl\fP\&.
836 .sp
837 If a \fIshelltypename\fP is given, returns \fB1\fP if \fBmodulecmd.tcl\fP\(aqs
838 current shell type is \fIshelltypename\fP, returns \fB0\fP otherwise.
839 \fIshelltypename\fP can be: \fBsh\fP, \fBcsh\fP, \fBfish\fP, \fBcmd\fP, \fBpwsh\fP,
840 \fBtcl\fP, \fBperl\fP, \fBpython\fP, \fBruby\fP, \fBlisp\fP, \fBcmake\fP, \fBr\fP\&.
841 .UNINDENT
842 .UNINDENT
843 .sp
844 \fBmodule\-info specified\fP
845 .INDENT 7.0
846 .INDENT 3.5
847 Return the module designation (name, version and variants) specified that
848 led to current \fImodulefile\fP evaluation.
849 .UNINDENT
850 .UNINDENT
851 .sp
852 \fBmodule\-info symbols\fP modulefile
853 .INDENT 7.0
854 .INDENT 3.5
855 Returns a list of all symbolic versions assigned to the passed
856 \fImodulefile\fP\&. The parameter \fImodulefile\fP might either be a full qualified
857 \fImodulefile\fP with name and version, another symbolic \fImodulefile\fP name
858 or a \fImodulefile\fP alias.
859 .UNINDENT
860 .UNINDENT
861 .sp
862 \fBmodule\-info tags\fP [tag]
863 .INDENT 7.0
864 .INDENT 3.5
865 Returns all tags assigned to currently evaluated \fImodulefile\fP as a list of
866 strings if no \fItag\fP name is given (see \fI\%Module tags\fP section in
867 \fI\%module\fP)
868 .sp
869 When tags are assigned to specific module variants, they are returned only
870 if this variant is the one currently evaluated.
871 .sp
872 Returns \fB1\fP if one of the tags applying to currently evaluated
873 \fImodulefile\fP is \fItag\fP\&. Returns \fB0\fP otherwise.
874 .UNINDENT
875 .UNINDENT
876 .sp
877 \fBmodule\-info type\fP
878 .INDENT 7.0
879 .INDENT 3.5
880 Returns either \fBC\fP or \fBTcl\fP to indicate which \fBmodule\fP command
881 is being executed, either the C version or the Tcl\-only version, to allow
882 the \fImodulefile\fP writer to handle any differences between the two.
883 .UNINDENT
884 .UNINDENT
885 .sp
886 \fBmodule\-info usergroups\fP [name]
887 .INDENT 7.0
888 .INDENT 3.5
889 Returns all the groups the user currently running \fBmodulecmd.tcl\fP is
890 member of as a list of strings if no \fIname\fP is given.
891 .sp
892 Returns \fB1\fP if one of the group current user running \fBmodulecmd.tcl\fP
893 is member of is \fIname\fP\&. Returns \fB0\fP otherwise.
894 .sp
895 If the Modules Tcl extension library is disabled, the \fBid(1)\fP
896 command is invoked to fetch groups of current user.
897 .UNINDENT
898 .UNINDENT
899 .sp
900 \fBmodule\-info username\fP [name]
901 .INDENT 7.0
902 .INDENT 3.5
903 Returns the username of the user currently running \fBmodulecmd.tcl\fP as
904 a string if no \fIname\fP is given.
905 .sp
906 Returns \fB1\fP if username of current user running \fBmodulecmd.tcl\fP is
907 \fIname\fP\&. Returns \fB0\fP otherwise.
908 .sp
909 If the Modules Tcl extension library is disabled, the \fBid(1)\fP
910 command is invoked to fetch username of current user.
911 .UNINDENT
912 .UNINDENT
913 .sp
914 \fBmodule\-info version\fP modulefile
915 .INDENT 7.0
916 .INDENT 3.5
917 Returns the physical module name and version of the passed symbolic
918 version \fImodulefile\fP\&. The parameter \fImodulefile\fP might either be a full
919 qualified \fImodulefile\fP with name and version, another symbolic \fImodulefile\fP
920 name or a \fImodulefile\fP alias.
921 .UNINDENT
922 .UNINDENT
923 .UNINDENT
924 .INDENT 0.0
925 .TP
926 .B module\-tag [options] tag modulefile...
927 Associate \fItag\fP to designated \fImodulefile\fP\&. This tag information will be
928 reported along \fImodulefile\fP on \fI\%avail\fP, \fI\%list\fP and
929 \fI\%spider\fP sub\-commands (see \fI\%Module tags\fP section in
930 \fI\%module\fP). Tag information can be queried during \fImodulefile\fP
931 evaluation with the \fI\%module\-info tags\fP modulefile
932 command. \fI\%module\-tag\fP commands should be placed in one of the
933 \fBmodulecmd.tcl\fP rc files.
934 .sp
935 \fI\%module\-tag\fP command accepts the following options:
936 .INDENT 7.0
937 .IP \(bu 2
938 \fB\-\-not\-user {user...}\fP
939 .IP \(bu 2
940 \fB\-\-not\-group {group...}\fP
941 .IP \(bu 2
942 \fB\-\-user {user...}\fP
943 .IP \(bu 2
944 \fB\-\-group {group...}\fP
945 .UNINDENT
946 .sp
947 If \fB\-\-not\-user\fP option is set, the tag is not applied if the username of
948 the user currently running \fBmodulecmd.tcl\fP is part of the list of
949 username specified. Following the same approach, if \fB\-\-not\-group\fP option is
950 set, the tag is not applied if current user is member of one of the groups
951 specified. When both options are set, the tag is not applied if a match is
952 found for \fB\-\-not\-user\fP or \fB\-\-not\-group\fP\&.
953 .sp
954 If \fB\-\-user\fP option is set, the tag is applied only if the username of the
955 user currently running \fBmodulecmd.tcl\fP is part of the list of username
956 specified. Following the same approach, if \fB\-\-group\fP option is set, the tag
957 is applied only if current user is member of one of the groups specified.
958 When both options are set, the tag is applied if a match is found for
959 \fB\-\-user\fP or \fB\-\-group\fP\&. If the same user name is set on both \fB\-\-user\fP
960 and \fB\-\-not\-user\fP options, \fB\-\-user\fP prevails over \fB\-\-not\-user\fP\&. If the
961 same group name is set on both \fB\-\-group\fP and \fB\-\-not\-group\fP, \fB\-\-group\fP
962 prevails over \fB\-\-not\-group\fP\&.
963 .sp
964 The parameter \fImodulefile\fP may also be a symbolic modulefile name or a
965 modulefile alias. It may also leverage a specific syntax to finely select
966 module version (see \fI\%Advanced module version specifiers\fP section below).
967 Moreover it may also be a full path file name to precisely designate one
968 module in a specific modulepath.
969 .sp
970 Tags inherited from other modulefile commands or module states cannot be set
971 with \fI\%module\-tag\fP\&. Otherwise an error is returned. Those special tags
972 are: \fBauto\-loaded\fP, \fBforbidden\fP, \fBhidden\fP, \fBhidden\-loaded\fP,
973 \fBloaded\fP, \fBnearly\-forbidden\fP and \fBwarning\fP\&.
974 .sp
975 When \fItag\fP equals \fBsticky\fP or \fBsuper\-sticky\fP, designated \fImodulefile\fP is
976 defined \fI\%Sticky modules\fP\&.
977 .sp
978 When \fItag\fP equals \fBkeep\-loaded\fP, designated \fImodulefile\fP is not
979 automatically unloaded when it has been auto\-loaded and its dependent modules
980 are getting unloaded.
981 .UNINDENT
982 .INDENT 0.0
983 .TP
984 .B module\-version modulefile version\-name...
985 Assigns the symbolic \fIversion\-name\fP to the \fImodulefile\fP\&. This command
986 should be placed in one of the \fBmodulecmd.tcl\fP rc files in order to
987 provide shorthand invocations of frequently used \fImodulefile\fP names.
988 .sp
989 The special \fIversion\-name\fP default specifies the default version to be
990 used for module commands, if no specific version is given. This replaces
991 the definitions made in the \fB\&.version\fP file in former
992 \fBmodulecmd.tcl\fP releases.
993 .sp
994 The parameter \fImodulefile\fP may be either
995 .INDENT 7.0
996 .IP \(bu 2
997 a fully or partially qualified \fImodulefile\fP with name / version. If
998 name is \fB\&.\fP (dot) then the current directory name is assumed to be the
999 module name. (Use this for deep \fImodulefile\fP directories.)
1000 .IP \(bu 2
1001 a symbolic \fImodulefile\fP name
1002 .IP \(bu 2
1003 another \fImodulefile\fP alias
1004 .UNINDENT
1005 .UNINDENT
1006 .INDENT 0.0
1007 .TP
1008 .B module\-virtual name modulefile
1009 Assigns the \fImodulefile\fP to the virtual module \fIname\fP\&. This command should be
1010 placed in rc files in order to define virtual modules.
1011 .sp
1012 A virtual module stands for a module \fIname\fP associated to a \fImodulefile\fP\&. The
1013 modulefile is the script interpreted when loading or unloading the virtual
1014 module which appears or can be found with its virtual name.
1015 .sp
1016 The parameter \fImodulefile\fP corresponds to the relative or absolute file
1017 location of a \fImodulefile\fP\&.
1018 .UNINDENT
1019 .INDENT 0.0
1020 .TP
1021 .B module\-warn [options] \-\-message {text message} modulefile...
1022 Print warning message when evaluating \fImodulefile\fP\&. This command could be
1023 placed in one of the \fBmodulecmd.tcl\fP rc files or within \fImodulefiles\fP\&.
1024 Warning is emitted when \fImodulefile\fP is evaluated in \fBload\fP, \fBdisplay\fP,
1025 \fBtest\fP, \fBhelp\fP\&.
1026 .sp
1027 \fI\%module\-warn\fP command accepts the following options:
1028 .INDENT 7.0
1029 .IP \(bu 2
1030 \fB\-\-after datetime\fP
1031 .IP \(bu 2
1032 \fB\-\-before datetime\fP
1033 .IP \(bu 2
1034 \fB\-\-not\-user {user...}\fP
1035 .IP \(bu 2
1036 \fB\-\-not\-group {group...}\fP
1037 .IP \(bu 2
1038 \fB\-\-user {user...}\fP
1039 .IP \(bu 2
1040 \fB\-\-group {group...}\fP
1041 .UNINDENT
1042 .sp
1043 If \fB\-\-after\fP option is set, warning is only effective after specified date
1044 time. Following the same principle, if \fB\-\-before\fP option is set, warning is
1045 only effective before specified date time. Accepted date time format is
1046 \fBYYYY\-MM\-DD[THH:MM]\fP\&. If no time (\fBHH:MM\fP) is specified, \fB00:00\fP is
1047 assumed. \fB\-\-after\fP and \fB\-\-before\fP options are not supported on Tcl
1048 versions prior to 8.5.
1049 .sp
1050 If \fB\-\-not\-user\fP option is set, warning is not applied if the username of
1051 the user currently running \fBmodulecmd.tcl\fP is part of the list of
1052 username specified. Following the same approach, if \fB\-\-not\-group\fP option is
1053 set, warning is not applied if current user is member of one of the groups
1054 specified. When both options are set, warning is not applied if a match is
1055 found for \fB\-\-not\-user\fP or \fB\-\-not\-group\fP\&.
1056 .sp
1057 If \fB\-\-user\fP option is set, warning is applied only if the username of the
1058 user currently running \fBmodulecmd.tcl\fP is part of the list of username
1059 specified. Following the same approach, if \fB\-\-group\fP option is set, warning
1060 is applied only if current user is member of one of the groups specified.
1061 When both options are set, warning is applied if a match is found for
1062 \fB\-\-user\fP or \fB\-\-group\fP\&. If the same user name is set on both \fB\-\-user\fP
1063 and \fB\-\-not\-user\fP options, \fB\-\-user\fP prevails over \fB\-\-not\-user\fP\&. If the
1064 same group name is set on both \fB\-\-group\fP and \fB\-\-not\-group\fP, \fB\-\-group\fP
1065 prevails over \fB\-\-not\-group\fP\&.
1066 .sp
1067 Modules in warning included in the result of \fI\%avail\fP, \fI\%list\fP
1068 or \fI\%spider\fP sub\-commands are reported with a \fBwarning\fP tag applied
1069 to them. See \fI\%Module tags\fP section in \fI\%module\fP\&.
1070 .sp
1071 The parameter \fImodulefile\fP may leverage a specific syntax to finely select
1072 module version (see \fI\%Advanced module version specifiers\fP section below). It
1073 may also be a full path file name to precisely designate one module in a
1074 specific modulepath.
1075 .UNINDENT
1076 .INDENT 0.0
1077 .TP
1078 .B module\-whatis string
1079 Defines a string which is displayed in case of the invocation of the
1080 \fI\%module whatis\fP command. There may be more than one
1081 \fI\%module\-whatis\fP line in a \fImodulefile\fP\&. This command takes no actions
1082 in case of \fI\%load\fP, \fI\%display\fP, etc. invocations of
1083 \fBmodulecmd.tcl\fP\&.
1084 .sp
1085 The \fIstring\fP parameter has to be enclosed in double\-quotes if there\(aqs more
1086 than one word specified. Words are defined to be separated by whitespace
1087 characters (space, tab, cr).
1088 .UNINDENT
1089 .INDENT 0.0
1090 .TP
1091 .B modulepath\-label directory label
1092 Assigns \fIlabel\fP string to modulepath \fIdirectory\fP\&. This \fIlabel\fP is used on
1093 \fI\%avail\fP, \fI\%whatis\fP, \fI\%search\fP and \fI\%spider\fP
1094 output to refer to the modulepath.
1095 .sp
1096 The parameter \fIdirectory\fP corresponds to a fully or partially qualified
1097 modulepath. If \fIdirectory\fP is \fB\&.\fP (dot) then the current directory of the
1098 modulerc file defining this command is assumed.
1099 .UNINDENT
1100 .INDENT 0.0
1101 .TP
1102 .B prepend\-path [\-d C|\-\-delim C|\-\-delim=C] [\-\-duplicates] variable value...
1103 Append or prepend \fIvalue\fP to environment \fIvariable\fP\&. The
1104 \fIvariable\fP is a colon, or \fIdelimiter\fP, separated list such as
1105 \fBPATH=directory:directory:directory\fP\&. The default delimiter is a colon
1106 \fB:\fP, but an arbitrary one can be given by the \fB\-\-delim\fP option. For
1107 example a space can be used instead (which will need to be handled in
1108 the Tcl specially by enclosing it in \fB\(dq \(dq\fP or \fB{ }\fP). A space, however,
1109 can not be specified by the \fB\-\-delim=C\fP form.
1110 .sp
1111 A reference counter environment variable is also set to know the number of
1112 times \fIvalue\fP has been added to environment \fIvariable\fP when it is added more
1113 than one time. This reference counter environment variable is named by
1114 prefixing \fIvariable\fP by \fI\%__MODULES_SHARE_\fP\&.
1115 .sp
1116 When \fIvalue\fP is already defined in environment \fIvariable\fP, it is not added
1117 again or moved at the end or at the beginning of \fIvariable\fP\&. Exception is
1118 made when the \fB\-\-duplicates\fP option is set in which case \fIvalue\fP is added
1119 again to \fIvariable\fP\&.
1120 .sp
1121 If the \fIvariable\fP is not set, it is created. When a \fImodulefile\fP is
1122 unloaded, \fI\%append\-path\fP and \fI\%prepend\-path\fP become
1123 \fI\%remove\-path\fP\&.
1124 .sp
1125 If \fIvalue\fP corresponds to the concatenation of multiple elements separated by
1126 colon, or \fIdelimiter\fP, character, each element is treated separately.
1127 .sp
1128 The provided \fIvalue\fP is used as\-is. If any path resolution is required, it
1129 must be performed within the \fImodulefile\fP itself. Use caution when including
1130 characters with special meanings in the shell context (such as \fB~\fP), as the
1131 shell may expand these paths automatically. This can prevent the
1132 corresponding entries from being properly removed when the \fImodulefile\fP is
1133 unloaded.
1134 .sp
1135 If the \fIvariable\fP is \fI\%MODULEPATH\fP and \fI\%require_via\fP
1136 configuration option is activated, the \fImodulefile\fP is considered a
1137 dependency by the loaded modulefiles stored in the added modulepaths.
1138 .UNINDENT
1139 .INDENT 0.0
1140 .TP
1141 .B prereq [options] modulefile...
1142 \fI\%prereq\fP controls whether or not the \fImodulefile\fP will be loaded. The
1143 \fI\%prereq\fP command lists \fImodulefiles\fP which must have been previously
1144 loaded before the current \fImodulefile\fP will be loaded. If a list contains
1145 more than one \fImodulefile\fP, then each member of the list acts as a Boolean OR
1146 operation. Multiple \fI\%prereq\fP commands may be used to create a Boolean
1147 AND operation. If one of the requirements have not been satisfied, an error
1148 is reported and the current \fImodulefile\fP makes no changes to the user\(aqs
1149 environment.
1150 .sp
1151 If an argument for \fI\%prereq\fP is a directory and any \fImodulefile\fP from
1152 the directory has been loaded, then the prerequisite is met. For example,
1153 specifying X11 as a \fI\%prereq\fP means that any version of X11, X11/R4 or
1154 X11/R5, must be loaded before proceeding.
1155 .sp
1156 The parameter \fImodulefile\fP may also be a symbolic modulefile name or a
1157 modulefile alias. It may also leverage a specific syntax to finely select
1158 module version (see \fI\%Advanced module version specifiers\fP section below).
1159 .sp
1160 \fI\%prereq\fP command accepts the following options:
1161 .INDENT 7.0
1162 .IP \(bu 2
1163 \fB\-\-modulepath modulepathlist\fP
1164 .IP \(bu 2
1165 \fB\-\-optional\fP
1166 .IP \(bu 2
1167 \fB\-\-tag taglist\fP
1168 .UNINDENT
1169 .sp
1170 When the \fB\-\-optional\fP option is set, the whole list of specified
1171 \fImodulefiles\fP is declared as an optional requirement list. Evaluation is not
1172 stopped if no \fImodulefile\fP from the list is loaded.
1173 .sp
1174 If the \fI\%auto_handling\fP configuration option is enabled
1175 \fI\%prereq\fP will attempt to load specified modulefile if not found loaded
1176 yet (see \fI\%Automated module handling mechanisms\fP
1177 in \fI\%module\fP).
1178 .sp
1179 The \fB\-\-tag\fP option accepts a list of module tags to apply to \fImodulefile\fP
1180 once loaded. \fItaglist\fP corresponds to the concatenation of multiple tags
1181 separated by colon character. \fItaglist\fP should not contain tags inherited
1182 from \fImodulefile\fP state or from other modulefile commands. If module is
1183 already loaded, tags from \fItaglist\fP are added to the list of tags already
1184 applied to this module.
1185 .sp
1186 The \fB\-\-modulepath\fP option accepts a list of modulepath. \fImodulepathlist\fP
1187 corresponds to the concatenation of multiple modulepaths separated by colon
1188 character. When this option is set, required \fImodulefile\fP should be located
1189 within one of the listed modulepaths. A path in this list may correspond to
1190 the first path elements of an actual modulepath (e.g., \fB/path/to\fP will
1191 match modulefiles located into the \fB/path/to/modulefiles\fP modulepath
1192 directory).
1193 .sp
1194 If an attempt to load \fImodulefile\fP is performed and \fB\-\-modulepath\fP option
1195 is set, \fImodulefile\fP will be searched in the enabled modulepaths whose start
1196 match one of the specified paths and in the specified paths not matching any
1197 enabled modulepaths. For instance if this option is set to
1198 \fB/path/to:/another/path\fP and \fB/path/to/modulefiles\fP is currently the sole
1199 enabled modulepath, \fImodulefile\fP will be searched into
1200 \fB/path/to/modulefiles\fP and \fB/another/path\fP directories.
1201 .UNINDENT
1202 .INDENT 0.0
1203 .TP
1204 .B prereq\-all [options] modulefile...
1205 Declare \fImodulefile\fP as a requirement of currently loading module. This
1206 command acts as an alias of \fI\%prereq\fP command. If more than one
1207 \fImodulefile\fP are specified, then this list acts as a Boolean AND operation,
1208 which means all specified \fImodulefiles\fP are required.
1209 .sp
1210 \fI\%prereq\-all\fP command accepts the following options:
1211 .INDENT 7.0
1212 .IP \(bu 2
1213 \fB\-\-modulepath modulepathlist\fP
1214 .IP \(bu 2
1215 \fB\-\-optional\fP
1216 .IP \(bu 2
1217 \fB\-\-tag taglist\fP
1218 .UNINDENT
1219 .sp
1220 When the \fB\-\-optional\fP option is set, each specified \fImodulefile\fP is
1221 declared as an optional requirement. A \fImodulefile\fP that cannot be loaded,
1222 will not stop the evaluation.
1223 .UNINDENT
1224 .INDENT 0.0
1225 .TP
1226 .B prereq\-any [options] modulefile...
1227 Alias of \fI\%prereq\fP command.
1228 .UNINDENT
1229 .INDENT 0.0
1230 .TP
1231 .B provide modulefile...
1232 Define each specified \fImodulefile\fP as a module alias of currently evaluating
1233 module. \fI\%provide\fP command helps to declare the additional elements
1234 included in a modulefile.
1235 .sp
1236 The \fI\%provide\fP command should be paired with a \fI\%conflict\fP
1237 command if the specified alias should be uniquely provided in the currently
1238 loaded environment.
1239 .sp
1240 Note: A module alias defined using \fI\%provide\fP command will not be
1241 recognized during module resolution. It is recommended to use the
1242 \fI\%module\-alias\fP command to define an alias that points to the default
1243 resolution target.
1244 .UNINDENT
1245 .INDENT 0.0
1246 .TP
1247 .B pushenv variable value
1248 Set environment \fIvariable\fP to \fIvalue\fP and save previous value of \fIvariable\fP
1249 to restore it when \fImodulefile\fP is unloaded. Like for \fI\%setenv\fP
1250 modulefile command, changes made to \fIvariable\fP with \fI\%pushenv\fP are
1251 applied to \fIvariable\fP in Tcl\(aqs \fBenv\fP array to update environment \fIvariable\fP
1252 value in current evaluation context.
1253 .sp
1254 When \fImodulefile\fP is unloaded, the \fIvalue\fP saved from the \fI\%pushenv\fP
1255 command of this modulefile is removed from saved value stack list. \fIvariable\fP
1256 is then set to the remaining \fIvalue\fP on top of the stack or it is unset if
1257 stack becomes empty.
1258 .sp
1259 Saved value stack list for \fIvariable\fP is stored in an environment variable
1260 which is named by prefixing \fIvariable\fP by \fI\%__MODULES_PUSHENV_\fP\&.
1261 .UNINDENT
1262 .INDENT 0.0
1263 .TP
1264 .B puts [\-nonewline] [channelId] string
1265 Writes the characters given by \fIstring\fP to the channel given by \fIchannelId\fP\&.
1266 This command is part of the regular set of Tcl commands but it is enhanced
1267 with specific features in the modulefile evaluation context. See the
1268 \fBputs(n)\fP Tcl man page for the basic description of this command.
1269 Specific features for modulefile evaluation context are described in the
1270 remainder of this section.
1271 .sp
1272 Content written to the \fBstderr\fP channel is rendered as output message
1273 produced by modulefile. Content written to the \fBstdout\fP channel is rendered
1274 as shell command evaluated in the user current shell environment. Content
1275 sent to \fBstdout\fP is spooled to be rendered after the environment changes
1276 made by modulefile.
1277 .sp
1278 When \fIchannelId\fP equals \fBprestdout\fP, content is rendered as shell command
1279 evaluated in current shell environment. This content is spooled and rendered
1280 prior any other environment changes.
1281 .sp
1282 When \fIchannelId\fP equals \fBlog\fP, content is sent to the log system through
1283 the defined \fI\%logger\fP command.
1284 .UNINDENT
1285 .INDENT 0.0
1286 .TP
1287 .B remove\-path [options] variable value... [\-\-append\-on\-unload|\-\-prepend\-on\-unload value...]
1288 Remove \fIvalue\fP from the colon, or \fIdelimiter\fP, separated list in
1289 \fIvariable\fP\&.
1290 .sp
1291 \fI\%remove\-path\fP command accepts the following options:
1292 .INDENT 7.0
1293 .IP \(bu 2
1294 \fB\-d C|\-\-delim C|\-\-delim=C\fP
1295 .IP \(bu 2
1296 \fB\-\-index\fP
1297 .IP \(bu 2
1298 \fB\-\-glob\fP
1299 .IP \(bu 2
1300 \fB\-\-remove\-on\-unload|\-\-noop\-on\-unload|\-\-append\-on\-unload|\-\-prepend\-on\-unload\fP
1301 .UNINDENT
1302 .sp
1303 See \fI\%prepend\-path\fP or \fI\%append\-path\fP for further
1304 explanation of using an arbitrary delimiter. Every string between colons, or
1305 delimiters, in \fIvariable\fP is compared to \fIvalue\fP\&. If the two match, \fIvalue\fP
1306 is removed from \fIvariable\fP if its reference counter is equal to 1 or unknown.
1307 .sp
1308 When \fB\-\-index\fP option is set, \fIvalue\fP refers to an index in \fIvariable\fP
1309 list. The string element pointed by this index is set for removal.
1310 .sp
1311 When \fB\-\-glob\fP option is set, \fIvalue\fP refers to a glob\-style pattern which
1312 is matched against values in \fIvariable\fP to find those to remove. \fB*\fP
1313 character in \fIvalue\fP matches any sequence of characters, including a null
1314 string. \fB?\fP character in \fIvalue\fP matches any single character. See
1315 \fBstring(n)\fP Tcl command for the full list of special characters.
1316 .sp
1317 When \fImodulefile\fP is unloaded, no operation is performed by default or if the
1318 \fB\-\-noop\-on\-unload\fP option is set. If the \fB\-\-remove\-on\-unload\fP option is
1319 set, \fIvalue\fP is removed. If the \fB\-\-append\-on\-unload\fP option is set, append
1320 back \fIvalue\fP removed at load time or specific \fIvalue\fP if any set. If the
1321 \fB\-\-prepend\-on\-unload\fP option is set, prepend back \fIvalue\fP removed at load
1322 time or specific \fIvalue\fP if any set. These options cannot be set if
1323 \fB\-\-index\fP option is also set. The \fB\-\-append\-on\-unload\fP and
1324 \fB\-\-prepend\-on\-unload\fP options cannot be set if \fB\-\-glob\fP option is also
1325 set.
1326 .sp
1327 Reference counter of \fIvalue\fP in \fIvariable\fP denotes the number of times
1328 \fIvalue\fP has been added to \fIvariable\fP\&. This information is stored in
1329 environment \fI\%__MODULES_SHARE_variable\fP\&. When
1330 attempting to remove \fIvalue\fP from \fIvariable\fP, relative reference counter is
1331 checked and \fIvalue\fP is removed only if counter is equal to 1 or not defined.
1332 Otherwise \fIvalue\fP is kept in \fIvariable\fP and reference counter is decreased by
1333 1. If counter equals 1 after being decreased, \fIvalue\fP and its counter are
1334 removed from reference counter variable.
1335 .sp
1336 If \fIvalue\fP corresponds to the concatenation of multiple elements separated by
1337 colon, or \fIdelimiter\fP, character, each element is treated separately.
1338 .sp
1339 An error is raised if \fIvalue\fP equals \fIdelimiter\fP character.
1340 .UNINDENT
1341 .INDENT 0.0
1342 .TP
1343 .B report string
1344 Output \fIstring\fP as a message during \fImodulefile\fP evaluation.
1345 .UNINDENT
1346 .INDENT 0.0
1347 .TP
1348 .B reportError string
1349 Output \fIstring\fP as an error message during \fImodulefile\fP evaluation and raise
1350 error count. \fI\%reportError\fP does not abort modulefile evaluation. Use
1351 the \fBerror(n)\fP Tcl command to abort evaluation in addition to emit
1352 an error message.
1353 .UNINDENT
1354 .INDENT 0.0
1355 .TP
1356 .B reportWarning string
1357 Output \fIstring\fP as a warning message during \fImodulefile\fP evaluation.
1358 .UNINDENT
1359 .INDENT 0.0
1360 .TP
1361 .B require\-fullname
1362 Abort \fIload\fP evaluation of \fImodulefile\fP if name specified to designate it is
1363 not the fully qualified one. Module alias or a symbolic version names are
1364 considered fully qualified names, exception made for the \fIdefault\fP symbol.
1365 .UNINDENT
1366 .INDENT 0.0
1367 .TP
1368 .B set\-alias alias\-name alias\-string
1369 Sets an alias with the name \fIalias\-name\fP in the user\(aqs environment to the
1370 string \fIalias\-string\fP\&. For some shells, aliases are not possible and the
1371 command has no effect (see \fI\%Shell support\fP section). When a \fImodulefile\fP is
1372 unloaded, \fI\%set\-alias\fP becomes \fI\%unset\-alias\fP\&.
1373 .UNINDENT
1374 .INDENT 0.0
1375 .TP
1376 .B set\-function function\-name function\-string
1377 Creates a function with the name \fIfunction\-name\fP in the user\(aqs environment
1378 with the function body \fIfunction\-string\fP\&. For some shells, functions are not
1379 possible and the command has no effect (see \fI\%Shell support\fP section). When a
1380 \fImodulefile\fP is unloaded, \fI\%set\-function\fP becomes
1381 \fI\%unset\-function\fP\&.
1382 .UNINDENT
1383 .INDENT 0.0
1384 .TP
1385 .B setenv [\-\-set\-if\-undef] variable value
1386 Set environment \fIvariable\fP to \fIvalue\fP\&. The \fI\%setenv\fP command will also
1387 change the process\(aq environment. A reference using Tcl\(aqs env associative
1388 array will reference changes made with the \fI\%setenv\fP command. Changes
1389 made using Tcl\(aqs \fBenv\fP associative array will \fBNOT\fP change the user\(aqs
1390 environment \fIvariable\fP like the \fI\%setenv\fP command. An environment
1391 change made this way will only affect the module parsing process. The
1392 \fI\%setenv\fP command is also useful for changing the environment prior to
1393 the \fBexec\fP or \fI\%system\fP command. When a \fImodulefile\fP is unloaded,
1394 \fI\%setenv\fP becomes \fI\%unsetenv\fP\&. If the environment \fIvariable\fP had
1395 been defined it will be overwritten while loading the \fImodulefile\fP\&. A
1396 subsequent \fI\%unload\fP will unset the environment \fIvariable\fP \- the
1397 previous value cannot be restored! (Unless you handle it explicitly or if you
1398 use the \fI\%pushenv\fP modulefile command instead of \fI\%setenv\fP)
1399 .sp
1400 When the \fB\-\-set\-if\-undef\fP option is set, environment variable is defined
1401 when \fImodulefile\fP is loaded only if not yet defined.
1402 .sp
1403 Any newline character in \fIvalue\fP is chopped if using \fIcsh\fP or \fItcsh\fP shells.
1404 .UNINDENT
1405 .INDENT 0.0
1406 .TP
1407 .B source\-sh [\-\-ignore eltlist] shell script [arg...]
1408 Evaluate with \fIshell\fP the designated \fIscript\fP with defined \fIarguments\fP to
1409 find out the environment changes it does. Those changes obtained by comparing
1410 environment prior and after \fIscript\fP evaluation are then translated into
1411 corresponding \fImodulefile\fP commands, which are then applied during modulefile
1412 evaluation as if they were directly written in it.
1413 .sp
1414 When modulefile is unloaded, environment changes done are reserved by
1415 evaluating in the \fBunload\fP context the resulting modulefile commands, which
1416 were recorded in the \fI\%__MODULES_LMSOURCESH\fP environment variable at
1417 \fBload\fP time.
1418 .sp
1419 Changes on environment variables, shell aliases, shell functions, shell
1420 completions and current working directory are tracked.
1421 .sp
1422 Changes made on environment variable intended for Modules private use (e.g.,
1423 \fI\%LOADEDMODULES\fP, \fI\%_LMFILES_\fP, \fB__MODULES_*\fP) are ignored.
1424 .sp
1425 \fIShell\fP could be specified as a command name or a fully qualified pathname.
1426 The following shells are supported: sh, dash, csh, tcsh, bash, ksh, ksh93,
1427 zsh and fish.
1428 .sp
1429 \fIShell\fP could also be set to \fBbash\-eval\fP\&. In this mode, bash shell \fIscript\fP
1430 is not sourced but the output resulting from its execution is evaluated to
1431 determine the environment changes it does.
1432 .sp
1433 The \fB\-\-ignore\fP option accepts a list of shell elements whose changes made
1434 by \fIscript\fP should be ignored. \fIeltlist\fP corresponds to the concatenation of
1435 multiple shell element separated by colon character. Accepted shell elements
1436 are: \fBenvvar\fP, \fBalias\fP, \fBfunction\fP, \fBchdir\fP and \fBcomplete\fP\&.
1437 .UNINDENT
1438 .INDENT 0.0
1439 .TP
1440 .B system string
1441 Run \fIstring\fP command through shell. On Unix, command is passed to the
1442 \fB/bin/sh\fP shell whereas on Windows it is passed to \fBcmd.exe\fP\&.
1443 \fBmodulecmd.tcl\fP redirects stdout to stderr since stdout would be parsed
1444 by the evaluating shell. The exit status of the executed command is returned.
1445 .UNINDENT
1446 .INDENT 0.0
1447 .TP
1448 .B uname field
1449 Provide lookup of system information. Most \fIfield\fP information are retrieved
1450 from the \fBtcl_platform\fP array (see the \fBtclvars(n)\fP man page).
1451 Uname will return the string \fBunknown\fP if information is unavailable for
1452 the \fIfield\fP\&.
1453 .sp
1454 \fI\%uname\fP will invoke the \fBuname(1)\fP command in order to get
1455 the operating system version and \fBdomainname(1)\fP to figure out the
1456 name of the domain.
1457 .sp
1458 \fIfield\fP values are:
1459 .INDENT 7.0
1460 .IP \(bu 2
1461 \fBsysname\fP: the operating system name
1462 .IP \(bu 2
1463 \fBnodename\fP: the hostname
1464 .IP \(bu 2
1465 \fBdomain\fP: the name of the domain
1466 .IP \(bu 2
1467 \fBrelease\fP: the operating system release
1468 .IP \(bu 2
1469 \fBversion\fP: the operating system version
1470 .IP \(bu 2
1471 \fBmachine\fP: a standard name that identifies the system\(aqs hardware
1472 .UNINDENT
1473 .UNINDENT
1474 .INDENT 0.0
1475 .TP
1476 .B uncomplete name
1477 Unsets completion for command \fIname\fP in the user\(aqs environment. When a
1478 \fImodulefile\fP is unloaded, no operation is performed.
1479 .sp
1480 The following shells are supported: bash, tcsh and fish.
1481 .UNINDENT
1482 .INDENT 0.0
1483 .TP
1484 .B unset\-alias alias\-name
1485 Unsets an alias with the name \fIalias\-name\fP in the user\(aqs environment.
1486 .UNINDENT
1487 .INDENT 0.0
1488 .TP
1489 .B unset\-function function\-name
1490 Removes a function with the name \fIfunction\-name\fP from the user\(aqs environment.
1491 .UNINDENT
1492 .INDENT 0.0
1493 .TP
1494 .B unsetenv [options] variable [value]
1495 Unsets environment \fIvariable\fP\&. When a \fImodulefile\fP is unloaded, no operation
1496 is performed unless if an optional \fIvalue\fP is defined, in which case
1497 \fIvariable\fP is set to \fIvalue\fP\&. The \fI\%unsetenv\fP command changes the
1498 process\(aq environment like \fI\%setenv\fP\&.
1499 .sp
1500 If the \fB\-\-noop\-on\-unload\fP option is set, no operation is performed when
1501 \fImodulefile\fP is unloaded. If the \fB\-\-unset\-on\-unload\fP option is set,
1502 environment \fIvariable\fP is also unset when \fImodulefile\fP is unloaded. These
1503 behaviors are applied even if an optional \fIvalue\fP is defined.
1504 .UNINDENT
1505 .INDENT 0.0
1506 .TP
1507 .B variant [\-\-boolean] [\-\-default value] name [value...]
1508 Declare \fI\%module variant\fP \fIname\fP with list of accepted
1509 \fIvalue\fP and instantiate it in the \fI\%ModuleVariant\fP array variable.
1510 .sp
1511 Variant\(aqs value is selected through the module designation that leads to the
1512 modulefile evaluation. See \fI\%Advanced module version specifiers\fP section to
1513 learn how variants could be specified.
1514 .sp
1515 Selected variant value is transmitted to the evaluating modulefile. A value
1516 must be specified for variant \fIname\fP and it must corresponds to a value in
1517 the accepted value list if such list is defined. Otherwise an error is
1518 raised. An exception is made if modulefile is evaluated in \fBdisplay\fP mode:
1519 no error is raised if no value is specified for a given variant and variant
1520 is not instantiated in the \fI\%ModuleVariant\fP array variable. When no
1521 list of accepted value is defined, variant could be set to any value.
1522 .sp
1523 When the \fB\-\-default\fP option is set, variant \fIname\fP is set to the \fIvalue\fP
1524 associated with this option in case no value is specified for variant in
1525 module designation.
1526 .sp
1527 If the \fB\-\-boolean\fP option is set, variant \fIname\fP is defined as a Boolean
1528 variant. No list of accepted value should be defined in this case. All values
1529 recognized as Boolean value in Tcl are accepted (i.e., \fB1\fP, \fBtrue\fP,
1530 \fBt\fP, \fByes\fP, \fBy\fP, \fBon\fP, \fB0\fP, \fBfalse\fP, \fBf\fP, \fBno\fP, \fBn\fP or
1531 \fBoff\fP). Boolean variants are instantiated in \fI\%ModuleVariant\fP using
1532 Tcl canonical form of Boolean value (i.e., \fB0\fP or \fB1\fP).
1533 .sp
1534 A variant which is not defined as a Boolean variant cannot define Boolean
1535 values in its accepted value list, exception made for the \fB0\fP and \fB1\fP
1536 integers. An error is raised otherwise.
1537 .sp
1538 Variant \fIname\fP should only be composed of characters part of the
1539 \fBA\-Za\-z0\-9_\-\fP range. Also, a variant name cannot start with \fB\-\fP (minus)
1540 character and the overall name cannot just be a number. An error is raised
1541 if specified \fIname\fP does not match these rules.
1542 .sp
1543 A variant cannot be named \fBversion\fP\&. An error is raised otherwise.
1544 .UNINDENT
1545 .INDENT 0.0
1546 .TP
1547 .B versioncmp version1 version2
1548 Compare version string \fIversion1\fP against version string \fIversion2\fP\&. Returns
1549 \fB\-1\fP, \fB0\fP or \fB1\fP respectively if \fIversion1\fP is less than, equal to or
1550 greater than \fIversion2\fP\&.
1551 .UNINDENT
1552 .INDENT 0.0
1553 .TP
1554 .B x\-resource [resource\-string|filename]
1555 Merge resources into the X11 resource database. The resources are used to
1556 control look and behavior of X11 applications. The command will attempt
1557 to read resources from \fIfilename\fP\&. If the argument isn\(aqt a valid file
1558 name, then string will be interpreted as a resource. Either \fIfilename\fP
1559 or \fIresource\-string\fP is then passed down to be \fBxrdb(1)\fP command.
1560 .sp
1561 \fImodulefiles\fP that use this command, should in most cases contain one or
1562 more \fI\%x\-resource\fP lines, each defining one X11 resource. The
1563 \fBDISPLAY\fP environment variable should be properly set and the X11
1564 server should be accessible. If \fI\%x\-resource\fP can\(aqt manipulate the X11
1565 resource database, the \fImodulefile\fP will exit with an error message.
1566 .sp
1567 Examples:
1568 .sp
1569 \fBx\-resource /u2/staff/leif/.xres/Ileaf\fP
1570 .INDENT 7.0
1571 .INDENT 3.5
1572 The content of the \fIIleaf\fP file is merged into the X11 resource database.
1573 .UNINDENT
1574 .UNINDENT
1575 .sp
1576 \fBx\-resource [glob ~/.xres/ileaf]\fP
1577 .INDENT 7.0
1578 .INDENT 3.5
1579 The Tcl glob function is used to have the \fImodulefile\fP read different
1580 resource files for different users.
1581 .UNINDENT
1582 .UNINDENT
1583 .sp
1584 \fBx\-resource {Ileaf.popup.saveUnder: True}\fP
1585 .INDENT 7.0
1586 .INDENT 3.5
1587 Merge the Ileaf resource into the X11 resource database.
1588 .UNINDENT
1589 .UNINDENT
1590 .UNINDENT
1591 .sp
1592 Modulefiles and run\-command (rc) files are differently interpreted. A limited
1593 number of the Modules specific Tcl commands are available for rc files
1594 interpretation since such files are intended to set parameters for modulefiles
1595 (like defining alias, hiding, tagging, etc) and not to change user
1596 environment. The following table summarizes the different commands available
1597 for each interpretation context.
1598 .TS
1599 box center;
1600 l|l.
1601 T{
1602 Commands available from
1603 modulefile interpretation
1604 T} T{
1605 Commands available from run\-command (rc) file
1606 interpretation
1607 T}
1608 _
1609 T{
1610 All the Modules specific
1611 and standard Tcl commands
1612 T} T{
1613 \fI\%hide\-modulefile\fP, \fI\%hide\-version\fP,
1614 \fI\%is\-loaded\fP, \fI\%is\-used\fP,
1615 \fI\%lsb\-release\fP, \fI\%module\-alias\fP,
1616 \fI\%module\-forbid\fP, \fI\%module\-hide\fP,
1617 \fI\%module\-info\fP, \fI\%module\-tag\fP,
1618 \fI\%module\-version\fP, \fI\%module\-virtual\fP,
1619 \fI\%module\-warn\fP, \fI\%modulepath\-label\fP,
1620 \fI\%system\fP, \fI\%uname\fP,
1621 \fI\%versioncmp\fP and standard Tcl commands
1622 T}
1623 .TE
1624 .sp
1625 \fBNOTE:\fP
1626 .INDENT 0.0
1627 .INDENT 3.5
1628 Global and user run\-command files are interpreted like modulefiles
1629 and benefit from all Modules specific Tcl commands. However it not advised
1630 to perform environment changes from such files.
1631 .UNINDENT
1632 .UNINDENT
1633 .SH MODULES VARIABLES
1634 .INDENT 0.0
1635 .TP
1636 .B ModulesCurrentModulefile
1637 The \fI\%ModulesCurrentModulefile\fP variable contains the full pathname of
1638 the \fImodulefile\fP being interpreted.
1639 .UNINDENT
1640 .INDENT 0.0
1641 .TP
1642 .B ModulesVersion
1643 The \fI\%ModulesVersion\fP variable can be set in \fB\&.version\fP file to
1644 designate the name of the \fImodulefile\fP version which should be considered
1645 as default in current directory (see \fI\%Locating Modulefiles\fP section below).
1646 .UNINDENT
1647 .INDENT 0.0
1648 .TP
1649 .B ModuleTool
1650 The \fI\%ModuleTool\fP variable contains the name of the \fImodule\fP
1651 implementation currently in use. The value of this variable is set to
1652 \fBModules\fP for this implementation.
1653 .UNINDENT
1654 .INDENT 0.0
1655 .TP
1656 .B ModuleToolVersion
1657 The \fI\%ModuleToolVersion\fP variable contains the version of the \fImodule\fP
1658 implementation currently in use. The value of this variable is set to
1659 \fB5.6.1\fP for this version of Modules.
1660 .UNINDENT
1661 .INDENT 0.0
1662 .TP
1663 .B ModuleVariant
1664 The \fI\%ModuleVariant\fP array variable contains an element entry for each
1665 defined variant associated to the value of this variant (e.g., the
1666 \fB$ModuleVariant(foo)\fP syntax corresponds to the value of variant \fBfoo\fP if
1667 defined). A Tcl evaluation error is obtained when accessing an undefined
1668 variant in \fI\%ModuleVariant\fP array. Use preferably the
1669 \fI\%getvariant\fP command to retrieve a variant value when this variant
1670 state is not known.
1671 .sp
1672 The list of the currently defined variants can be retrieved with
1673 \fB[array names ModuleVariant]\fP Tcl code.
1674 .UNINDENT
1675 .SH LOCATING MODULEFILES
1676 .sp
1677 Every directory in \fI\%MODULEPATH\fP is searched to find the
1678 \fImodulefile\fP\&. A directory in \fI\%MODULEPATH\fP can have an arbitrary number
1679 of sub\-directories. If the user names a \fImodulefile\fP to be loaded which
1680 is actually a directory, the directory is opened and a search begins for
1681 an actual \fImodulefile\fP\&. First, \fBmodulecmd.tcl\fP looks for a file with
1682 the name \fB\&.modulerc\fP in the directory. If this file exists, its contents
1683 will be evaluated as if it was a \fImodulefile\fP to be loaded. You may place
1684 \fI\%module\-version\fP, \fI\%module\-alias\fP and \fI\%module\-virtual\fP
1685 commands inside this file.
1686 .sp
1687 Additionally, before seeking for \fB\&.modulerc\fP files in the module
1688 directory, the global modulerc file and the \fB\&.modulerc\fP file found at
1689 the root of the modulepath directory are sourced, too. If a named version
1690 default now exists for the \fImodulefile\fP to be loaded, the assigned
1691 \fImodulefile\fP now will be sourced. Otherwise the file \fB\&.version\fP is
1692 looked up in the module directory.
1693 .sp
1694 If the \fB\&.version\fP file exists, it is opened and interpreted as Tcl code
1695 and takes precedence over a \fB\&.modulerc\fP file in the same directory. If
1696 the Tcl variable \fI\%ModulesVersion\fP is set by the \fB\&.version\fP file,
1697 \fBmodulecmd.tcl\fP will use the name as if it specifies a \fImodulefile\fP in
1698 this directory. This will become the default \fImodulefile\fP in this case.
1699 \fI\%ModulesVersion\fP cannot refer to a \fImodulefile\fP located in a different
1700 directory.
1701 .sp
1702 If \fI\%ModulesVersion\fP is a directory, the search begins anew down that
1703 directory. If the name does not match any files located in the current
1704 directory, the search continues through the remaining directories in
1705 \fI\%MODULEPATH\fP\&.
1706 .sp
1707 Every \fB\&.version\fP and \fB\&.modulerc\fP file found is interpreted as Tcl
1708 code. The difference is that \fB\&.version\fP only applies to the current
1709 directory, and the \fB\&.modulerc\fP applies to the current directory and all
1710 subdirectories. Changes made in these files will affect the subsequently
1711 interpreted \fImodulefile\fP\&.
1712 .sp
1713 If a \fB\&.modulecache\fP file is found at the root of a modulepath directory,
1714 this file is interpreted as Tcl code to learn all \fB\&.modulerc\fP,
1715 \fB\&.version\fP and modulefiles available. Modulepath content is read from
1716 \fI\%module cache\fP file. Modulepath directory is only walked
1717 through to check if limited access modulefiles or directories are available to
1718 current user.
1719 .sp
1720 If no default version may be figured out, an implicit default is selected when
1721 this behavior is enabled (see \fI\%MODULES_IMPLICIT_DEFAULT\fP in
1722 \fI\%module\fP). If disabled, module names should be fully qualified when no
1723 explicit default is defined for them, otherwise no default version is found
1724 and an error is returned. If enabled, then the highest numerically sorted
1725 \fImodulefile\fP, virtual module or module alias under the directory will be used.
1726 The dictionary comparison method of the \fBlsort(n)\fP Tcl command is
1727 used to achieve this sort. If highest numerically sorted element is an alias,
1728 search continues on its \fImodulefile\fP target.
1729 .sp
1730 For example, it is possible for a user to have a directory named X11 which
1731 simply contains a \fB\&.version\fP file specifying which version of X11 is to
1732 be loaded. Such a file would look like:
1733 .INDENT 0.0
1734 .INDENT 3.5
1735 .sp
1736 .EX
1737 #%Module
1738 set ModulesVersion R4
1739 .EE
1740 .UNINDENT
1741 .UNINDENT
1742 .sp
1743 The equivalent \fB\&.modulerc\fP would look like:
1744 .INDENT 0.0
1745 .INDENT 3.5
1746 .sp
1747 .EX
1748 #%Module
1749 module\-version ./R4 default
1750 .EE
1751 .UNINDENT
1752 .UNINDENT
1753 .sp
1754 If the extended default mechanism is enabled (see
1755 \fI\%MODULES_EXTENDED_DEFAULT\fP in \fI\%module\fP) the module version
1756 specified is matched against starting portion of existing module versions,
1757 where portion is a substring separated from the rest of version string by a
1758 \fB\&.\fP character.
1759 .sp
1760 When the implicit default mechanism and the \fI\%Advanced module version
1761 specifiers\fP are both enabled, a \fBdefault\fP and \fBlatest\fP symbolic versions
1762 are automatically defined for each module name (also at each directory level
1763 in case of deep \fImodulefile\fP). Unless a symbolic version, alias, or regular
1764 module version already exists for these version names.
1765 .sp
1766 Every file in searched directories is checked to see if it begins with the
1767 Modules magic cookie (i.e., \fB#%Module\fP file signature) to determine if it is
1768 a \fImodulefile\fP (see \fI\%DESCRIPTION\fP section). When the \fI\%mcookie_check\fP
1769 configuration is set to \fBeval\fP, this check is skipped and all files in
1770 search directories are considered \fImodulefiles\fP\&.
1771 .sp
1772 If user names a \fImodulefile\fP that cannot be found in the first \fImodulepath\fP
1773 directory, \fImodulefile\fP will be searched in next \fImodulepath\fP directory
1774 and so on until a matching \fImodulefile\fP is found. If search goes through
1775 a module alias or a symbolic version, this alias or symbol is resolved by
1776 first looking at the \fImodulefiles\fP in the \fImodulepath\fP where this alias or
1777 symbol is defined. If not found, resolution looks at the other \fImodulepaths\fP
1778 in their definition order.
1779 .sp
1780 When locating \fImodulefiles\fP, if a \fB\&.modulerc\fP, a \fB\&.version\fP, a
1781 directory or a \fImodulefile\fP cannot be read during the search it is simply
1782 ignored with no error message produced. Visibility of \fImodulefiles\fP can thus
1783 be adapted to the rights the user has been granted. Exception is made when
1784 trying to directly access a directory or a \fImodulefile\fP\&. In this case,
1785 the access issue is returned as an error message.
1786 .sp
1787 Depending on their name, their file permissions or the use of specific
1788 modulefile commands, \fImodulefile\fP, virtual module, module alias or symbolic
1789 version may be set hidden which impacts available modules search or module
1790 selection processes (see \fI\%Hiding modulefiles\fP section below).
1791 .SH HIDING MODULEFILES
1792 .sp
1793 A \fImodulefile\fP, virtual module, module alias or symbolic version whose name or
1794 element in their name starts with a dot character (\fB\&.\fP) or who are targeted
1795 by a \fI\%module\-hide\fP command are considered hidden. Hidden modules are
1796 not displayed or taken into account except if they are explicitly named (e.g.,
1797 \fBfoo/1.2.3\fP or \fBfoo/.2.0\fP not \fBfoo\fP). If module has been hidden with the
1798 \fB\-\-soft\fP option of the \fI\%module\-hide\fP command set, it is not
1799 considered hidden if the root name of the query to search it matches module
1800 root name (e.g., searching \fBfoo\fP will return a \fBfoo/1.2.3\fP modulefile
1801 targeted by a \fBmodule\-hide \-\-soft\fP command). If module has been hidden with
1802 the \fB\-\-hard\fP option of the \fI\%module\-hide\fP command set, it is always
1803 considered hidden thus it is never displayed nor taken into account even if
1804 it is explicitly named.
1805 .sp
1806 A \fImodulefile\fP, virtual module, module alias or symbolic version who are
1807 targeted by a \fI\%module\-hide \-\-hard\fP command and a
1808 \fI\%module\-forbid\fP command or whose file access permissions are restricted
1809 are considered hard\-hidden and forbidden. Such modules are not displayed or
1810 taken into account. When explicitly named for evaluation selection, such
1811 modules are unveiled to return an access error.
1812 .sp
1813 \fBNOTE:\fP
1814 .INDENT 0.0
1815 .INDENT 3.5
1816 When the \fI\%mcookie_check\fP configuration is set to \fBeval\fP,
1817 file access permissions are not checked thus files with restricted
1818 permissions are included in search results but still lead to error if
1819 evaluated.
1820 .UNINDENT
1821 .UNINDENT
1822 .sp
1823 A symbolic version\-name assigned to a hidden module is displayed or taken into
1824 account only if explicitly named and if module is not hard\-hidden. Non\-hidden
1825 module alias targeting a hidden \fImodulefile\fP appears like any other non\-hidden
1826 module alias. Finally, a hidden symbolic version targeting a non\-hidden module
1827 is displayed or taken into account only if not hard\-hidden and explicitly
1828 named to refer to its non\-hidden target.
1829 .sp
1830 The automatic version symbols (e.g., \fBdefault\fP and \fBlatest\fP) are
1831 unaffected by hiding. Moreover when a regular \fBdefault\fP or \fBlatest\fP
1832 version is set hidden, the corresponding automatic version symbol takes the
1833 left spot. For instance, if \fBfoo/default\fP which targets \fBfoo/1.2.3\fP is set
1834 hard\-hidden, the \fBdefault\fP automatic version symbol will be set onto
1835 \fBfoo/2.1.3\fP, the highest available version of \fBfoo\fP\&.
1836 .sp
1837 When loading a \fImodulefile\fP or a virtual module targeted by a
1838 \fI\%module\-hide \-\-hidden\-loaded\fP command, this module
1839 inherits the \fBhidden\-loaded\fP tag. Hidden loaded modules are not reported
1840 among \fI\%list\fP sub\-command results.
1841 .sp
1842 If the \fI\%\-\-all\fP option is set on \fI\%avail\fP, \fI\%aliases\fP,
1843 \fI\%whatis\fP, \fI\%search\fP or \fI\%spider\fP sub\-commands, hidden
1844 modules are taken into account in search. Hard\-hidden modules are unaffected
1845 by this option.
1846 .sp
1847 If the \fI\%\-\-all\fP option is set on \fI\%list\fP sub\-command, hidden
1848 loaded modules are included in result output.
1849 .sp
1850 A behavior equivalent to the use of the \fI\%\-\-all\fP option is obtained on
1851 \fI\%avail\fP, \fI\%list\fP and \fI\%spider\fP sub\-commands by adding
1852 the \fBhidden\fP element to the output configuration option controlling regular
1853 or terse reporting of these sub\-commands: \fI\%avail_output\fP,
1854 \fI\%avail_terse_output\fP, \fI\%list_output\fP,
1855 \fI\%list_terse_output\fP, \fI\%spider_output\fP,
1856 \fI\%spider_terse_output\fP\&.
1857 .SH ADVANCED MODULE VERSION SPECIFIERS
1858 .sp
1859 When the advanced module version specifiers mechanism is enabled (see
1860 \fI\%MODULES_ADVANCED_VERSION_SPEC\fP in \fI\%module\fP), the
1861 specification of modulefile passed on Modules specific Tcl commands changes.
1862 After the module name a version constraint and variants may be added.
1863 .SS Version specifiers
1864 .sp
1865 After the module name a version constraint prefixed by the \fB@\fP character may
1866 be added. It could be directly appended to the module name or separated from
1867 it with a space character.
1868 .sp
1869 Constraints can be expressed to refine the selection of module version to:
1870 .INDENT 0.0
1871 .IP \(bu 2
1872 a single version with the \fB@version\fP syntax, for instance \[email protected]\fP
1873 syntax will select module \fBfoo/1.2.3\fP
1874 .IP \(bu 2
1875 a list of versions with the \fB@version1,version2,...\fP syntax, for instance
1876 \[email protected],1.10\fP will match modules \fBfoo/1.2.3\fP and \fBfoo/1.10\fP
1877 .IP \(bu 2
1878 a range of versions with the \fB@version1:\fP, \fB@:version2\fP and
1879 \fB@version1:version2\fP syntaxes, for instance \[email protected]:\fP will select all
1880 versions of module \fBfoo\fP greater than or equal to \fB1.2\fP, \fBfoo@:1.3\fP
1881 will select all versions less than or equal to \fB1.3\fP and \[email protected]:1.3\fP
1882 matches all versions between \fB1.2\fP and \fB1.3\fP including \fB1.2\fP and
1883 \fB1.3\fP versions
1884 .UNINDENT
1885 .sp
1886 Advanced specification of single version or list of versions may benefit from
1887 the activation of the extended default mechanism (see
1888 \fI\%MODULES_EXTENDED_DEFAULT\fP in \fI\%module\fP) to use an abbreviated
1889 notation like \fB@1\fP to refer to more precise version numbers like \fB1.2.3\fP\&.
1890 Range of versions on its side natively handles abbreviated versions.
1891 .sp
1892 In order to be specified in a range of versions or compared to a range of
1893 versions, the version major element should corresponds to a number. For
1894 instance \fB10a\fP, \fB1.2.3\fP, \fB1.foo\fP are versions valid for range
1895 comparison whereas \fBdefault\fP or \fBfoo.2\fP versions are invalid for range
1896 comparison.
1897 .sp
1898 Range of versions can be specified in version list, for instance
1899 \fBfoo@:1.2,1.4:1.6,1.8:\fP\&. Such specification helps to exclude specific
1900 versions, like versions \fB1.3\fP and \fB1.7\fP in previous example.
1901 .sp
1902 If the implicit default mechanism is also enabled (see
1903 \fI\%MODULES_IMPLICIT_DEFAULT\fP in \fI\%module\fP), a \fBdefault\fP and
1904 \fBlatest\fP symbolic versions are automatically defined for each module name
1905 (also at each directory level for deep \fImodulefiles\fP). These automatic version
1906 symbols are defined unless a symbolic version, alias, or regular module
1907 version already exists for these \fBdefault\fP or \fBlatest\fP version names.
1908 Using the \fBmod@latest\fP (or \fBmod/latest\fP) syntax ensures highest available
1909 version will be selected.
1910 .SS Variants
1911 .sp
1912 After the module name, variants can be specified. \fI\%Module variants\fP are
1913 alternative evaluation of the same \fImodulefile\fP\&. A variant is specified by
1914 associating a value to its name. This specification is then transmitted to the
1915 evaluating \fImodulefile\fP which instantiates the variant in the
1916 \fI\%ModuleVariant\fP array variable when reaching the \fI\%variant\fP
1917 modulefile command declaring this variant.
1918 .sp
1919 Variant can be specified with the \fBname=value\fP syntax where \fIname\fP is the
1920 declared variant name and \fIvalue\fP, the value this variant is set to when
1921 evaluating the \fImodulefile\fP\&.
1922 .sp
1923 Boolean variants can be specified with the \fB+name\fP syntax to set this
1924 variant on and with the \fB\-name\fP or \fB~name\fP syntaxes to set this variant
1925 off. The \fB\-name\fP syntax is not supported on \fI\%ml\fP command as the
1926 minus sign already means to unload designated module. The \fB~name\fP and
1927 \fB+name\fP syntaxes could also be defined appended to another specification
1928 word (e.g., the module name, version or another variant specification),
1929 whereas \fB\-name\fP syntax must be the start of a new specification word.
1930 .sp
1931 Boolean variants may also be specified with the \fBname=value\fP syntax. \fIvalue\fP
1932 should be set to \fB1\fP, \fBtrue\fP, \fBt\fP, \fByes\fP, \fBy\fP or \fBon\fP to enable
1933 the variant or it should be set to \fB0\fP, \fBfalse\fP, \fBf\fP, \fBno\fP, \fBn\fP or
1934 \fBoff\fP to disable the variant.
1935 .sp
1936 Shortcuts may be used to abbreviate variant specification. The
1937 \fI\%variant_shortcut\fP configuration option associates shortcut character
1938 to variant name. With a shortcut defined, variant could be specified with the
1939 \fB<shortcut>value\fP syntax. For instance if character \fB%\fP is set as a
1940 shortcut for variant \fBfoo\fP, the \fB%value\fP syntax is equivalent to the
1941 \fBfoo=value\fP syntax.
1942 .sp
1943 Variant \fIname\fP should only be composed of characters part of the
1944 \fBA\-Za\-z0\-9_\-\fP range. Also, a variant name cannot start with \fB\-\fP (minus)
1945 character and the overall name cannot just be a number.
1946 .sp
1947 Specific characters used in variant specification syntax cannot be used as
1948 part of the name or version of a module. These specific characters are \fB+\fP,
1949 \fB~\fP, \fB=\fP and all characters set as variant shortcut. Exception is made for
1950 \fB+\fP and \fB~\fP characters if string that follows after does not correspond to
1951 a valid variant name (e.g., \fIname+\fP, \fIname++\fP, \fIname/version+1\fP).
1952 .SH DEPENDENCIES BETWEEN MODULEFILES
1953 .sp
1954 A modulefile may express dependencies on other modulefiles. Two kind of
1955 dependency exist: pre\-requirement and conflict. The former means specified
1956 modulefiles should be loaded prior the modulefile that express the
1957 requirement. The latter means specified modulefiles should not be loaded for
1958 the modulefile that express the conflict to be loaded too.
1959 .sp
1960 Pre\-requirement could be expressed with \fI\%prereq\fP, \fI\%prereq\-any\fP,
1961 \fI\%prereq\-all\fP, \fI\%depends\-on\fP, \fI\%depends\-on\-any\fP,
1962 \fI\%always\-load\fP, \fI\%module load\fP,
1963 \fI\%module switch\fP, \fI\%module try\-load\fP or
1964 \fI\%module load\-any\fP modulefile commands. When the
1965 \fI\%auto_handling\fP configuration option is disabled, required modulefile
1966 should be manually loaded prior their dependent modulefile when expressed with
1967 the \fI\%prereq\fP, \fI\%prereq\-any\fP, \fI\%prereq\-all\fP,
1968 \fI\%depends\-on\fP or \fI\%depends\-on\-any\fP modulefile commands. For other
1969 commands or when \fI\%auto_handling\fP is enabled, pre\-required modulefiles
1970 are automatically loaded.
1971 .sp
1972 Another form of pre\-requirement is expressed through the use of the modulefile
1973 commands \fI\%module use\fP, \fI\%append\-path
1974 MODULEPATH\fP, or \fI\%prepend\-path MODULEPATH\fP,
1975 when the \fI\%require_via\fP configuration option is enabled. In this
1976 context, a modulefile that adds a modulepath is treated as a requirement for
1977 the modulefiles loaded from that path. This pre\-requirement is considered when
1978 such modules are already loaded, helping to maintain consistency when
1979 attempting to unload a modulefile that enables a modulepath.
1980 .sp
1981 Conflict is expressed with \fI\%conflict\fP, \fI\%family\fP or
1982 \fI\%module unload\fP modulefile commands. When the
1983 \fI\%auto_handling\fP or \fI\%conflict_unload\fP configuration options
1984 are disabled, a conflicting loaded modulefile should be manually unloaded
1985 prior loading the modulefile that express such conflict when defined with
1986 \fI\%conflict\fP or \fI\%family\fP\&. It is automatically unloaded when
1987 expressed with \fI\%module unload\fP (unless dependent modulefiles
1988 are loaded) or if \fI\%auto_handling\fP and \fI\%conflict_unload\fP
1989 options are enabled. An error is raised when trying to load a module that is
1990 already loaded but with a different variant set or coming from a different
1991 modulepath. If both options are enabled the loaded module is automatically
1992 unloaded to satisfy the new set of variant or modulepath asked.
1993 .sp
1994 It is strongly advised to define dependencies prior environment changes in a
1995 modulefile. Dependency resolution should be done before any environment change
1996 to ensure the environment is getting set in the same order whether
1997 pre\-requirements are already loaded, or if they are automatically loaded when
1998 loading the modulefile which depends on them, or if all loaded modules are
1999 reloaded or refreshed. This is especially important when the modulefile
2000 updates an environment variable also altered by other modulefiles like
2001 \fBPATH\fP\&. As the order of the path elements in such variable defines
2002 priority, it is important that this order does not change depending on the way
2003 the modulefiles are loaded.
2004 .sp
2005 \fBmodule\fP keeps environment consistent which means a modulefile cannot
2006 be loaded if its requirements are not loaded or if a conflicting module is
2007 loaded. In addition a loaded module cannot be unloaded if other loaded modules
2008 depends on it. The \fI\%automated module handling
2009 mechanisms\fP attempt to solve the dependencies expressed
2010 by loading or unloading additional modulefiles. When the \fI\%\-\-no\-auto\fP
2011 option is set on \fBmodule\fP command when loading or unload modulefile,
2012 automated module handling mechanisms are disabled and dependencies have to be
2013 solved manually. When dependencies are not satisfied, modulefile fails to load
2014 or unload.
2015 .sp
2016 Adding the \fB\-\-not\-req\fP option when expressing dependencies in modulefile
2017 with the \fI\%module\fP command will attempt to load or unload the designated
2018 modulefile but it will not mark them as pre\-requirement or conflict.
2019 .sp
2020 Adding the \fB\-\-optional\fP option on \fI\%prereq\fP, \fI\%prereq\-any\fP,
2021 \fI\%prereq\-all\fP, \fI\%depends\-on\fP, \fI\%depends\-on\-any\fP or
2022 \fI\%always\-load\fP modulefile commands declares the pre\-requirement as
2023 optional. If an optional pre\-requirement is not found loaded or cannot be
2024 automatically loaded, the dependency expressed is yet considered satisfied.
2025 When an optional requirement is loaded afterward, the dependent module will
2026 get automatically reloaded if the \fI\%auto_handling\fP configuration
2027 option is enabled.
2028 .sp
2029 By adding the \fI\%\-\-force\fP option to the \fBmodule\fP command when
2030 loading or unloading modulefile, the consistency checks are by\-passed. This
2031 option cannot be used when expressing dependencies in modulefiles. If a module
2032 has been force loaded whereas its requirements are not loaded or whereas a
2033 conflicting module is also loaded, the user environment is said inconsistent.
2034 .sp
2035 Note that a pre\-requirement should be found in the loaded module list prior
2036 its dependent module. User environment is considered inconsistent if
2037 pre\-requirement module is found loaded after dependent module, as the
2038 environment changes may have been done in the wrong priority order.
2039 .sp
2040 When user environment is considered inconsistent global operations achieved by
2041 \fI\%refresh\fP, \fI\%reload\fP and \fI\%save\fP sub\-commands cannot
2042 perform. This mechanism is there to avoid the situation to worsen by
2043 re\-evaluating all loaded modules or recording this environment.
2044 .sp
2045 When the \fI\%auto_handling\fP configuration option is enabled, if missing
2046 pre\-requirement modulefile gets loaded or conflicting modulefile gets unloaded
2047 the inconsistent loaded module will be automatically reloaded to make user
2048 environment consistent again.
2049 .SH MODULEFILE SPECIFIC HELP
2050 .sp
2051 Users can request help about a specific \fImodulefile\fP through the
2052 \fI\%module\fP command. The \fImodulefile\fP can print helpful information or
2053 start help oriented programs by defining a \fBModulesHelp\fP subroutine. The
2054 subroutine will be called when the \fI\%module help modulefile\fP
2055 command is used.
2056 .sp
2057 Help text may also be defined within \fImodulefile\fP with \fI\%module\-help\fP
2058 command. Text defined such way is printed before evaluation of \fBModulesHelp\fP
2059 subroutine if any.
2060 .SH MODULEFILE SPECIFIC TEST
2061 .sp
2062 Users can request test of a specific \fImodulefile\fP through the \fI\%module\fP
2063 command. The \fImodulefile\fP can perform some sanity checks on its
2064 definition or on its underlying programs by defining a \fBModulesTest\fP
2065 subroutine. The subroutine will be called when the
2066 \fI\%module test modulefile\fP command is used. The subroutine should
2067 return 1 in case of success. If no or any other value is returned, test is
2068 considered failed.
2069 .SH MODULEFILE DISPLAY
2070 .sp
2071 The \fI\%module display modulefile\fP command will detail all
2072 changes that will be made to the environment. After displaying all of the
2073 environment changes \fBmodulecmd.tcl\fP will call the \fBModulesDisplay\fP
2074 subroutine. The \fBModulesDisplay\fP subroutine is a good place to put
2075 additional descriptive information about the \fImodulefile\fP\&.
2076 .SH COMPATIBILITY WITH LMOD TCL MODULEFILE
2077 .sp
2078 The \fBmodulecmd.tcl\fP program supports Tcl modulefile or modulerc written
2079 for Lmod, the alternative \fBmodule\fP implementation developed in Lua.
2080 Except for the specific cases listed below, such modulefiles can be evaluated
2081 by Modules without producing errors. Key differences between the two
2082 implementations are outlined below.
2083 .sp
2084 The \fBremove\-property\fP modulefile command is evaluated as a \fIno\-operation\fP
2085 command. No error is obtained if this command is used in modulefiles but no
2086 change occurs.
2087 .sp
2088 The \fI\%haveDynamicMPATH\fP is evaluated as a \fIno\-operation\fP modulefile
2089 command. If modulefile conditionally updates \fI\%MODULEPATH\fP environment
2090 variable, this command is needed to help Lmod know that modulefile changes
2091 \fI\%MODULEPATH\fP\&. \fI\%spider\fP sub\-command on Modules does not need
2092 this information as modulefile is evaluated in the context of the current
2093 user to determine whether \fI\%MODULEPATH\fP is updated.
2094 .sp
2095 The \fI\%break\fP command does not accept any argument. A \fBmsg\fP argument
2096 can be set on Lmod to provide a customized break error message.
2097 .sp
2098 The \fI\%setenv\fP, \fI\%unsetenv\fP, \fI\%prepend\-path\fP,
2099 \fI\%append\-path\fP, \fI\%remove\-path\fP, \fI\%pushenv\fP and \fBmodule\fP
2100 \fI\%load\fP, \fI\%load\-any\fP, \fI\%try\-load\fP
2101 and \fI\%unload\fP modulefile commands do not support the \fB\-\-mode\fP
2102 option. An error is raised if this option is used.
2103 .sp
2104 The \fI\%setenv\fP and \fI\%unsetenv\fP modulefile commands do not support
2105 the \fB\-\-respect\fP option. An error is raised if this option is used.
2106 .sp
2107 Use of \fI\%reportError\fP command aborts modulefile evaluation on Lmod. This
2108 command only reports an error message on Modules.
2109 .sp
2110 The \fI\%require\-fullname\fP command only aborts \fIload\fP modulefile evaluation
2111 whereas the Lmod implementation also aborts \fIunload\fP and \fIdisplay\fP
2112 evaluations.
2113 .sp
2114 When processing a \fI\%family\fP command, the \fBLMOD_FAMILY_<NAME>\fP
2115 environment variable is also defined to be compatible with modulefiles or
2116 scripts relying on such variable.
2117 .sp
2118 When unloading a modulefile, the \fI\%pushenv\fP command does not update the
2119 value of the environment variable if this modulefile was not defining the
2120 value currently in use.
2121 .sp
2122 The third optional argument of \fI\%append\-path\fP and \fI\%prepend\-path\fP
2123 commands corresponds to a priority specification on Lmod whereas these two
2124 commands accept multiple path element arguments on Modules.
2125 .sp
2126 The \fI\%prereq\fP command is equivalent to the \fI\%prereq\-any\fP command
2127 on Modules whereas on Lmod it is equivalent to the \fI\%prereq\-all\fP
2128 command.
2129 .sp
2130 If the \fI\%auto_handling\fP configuration option is disabled, the
2131 requirements defined with the \fI\%depends\-on\fP or \fI\%depends\-on\-any\fP
2132 commands are not automatically loaded and an error is raised if none of these
2133 requirements are found loaded.
2134 .sp
2135 If the \fI\%auto_handling\fP or \fI\%conflict_unload\fP configuration
2136 options are disabled, the conflicts defined with the \fI\%family\fP command
2137 are not automatically unloaded and an error is raised when trying to load a
2138 module defining a family already defined by a loaded module.
2139 .sp
2140 On \fI\%module load\-any\fP sub\-command and modulefile command, a
2141 modulefile evaluation error is not reported and \fI\%module
2142 load\-any\fP continues to the next modulefile instead of aborting the
2143 whole process. No attempt to load listed modulefiles is made if one of these
2144 modulefiles is found already loaded.
2145 .sp
2146 On \fI\%module try\-load\fP modulefile command, each modulefile
2147 specified is considered an optional pre\-requirement. If it is loaded
2148 afterward and if the \fI\%auto_handling\fP configuration option is enabled,
2149 the dependent module will get automatically reloaded.
2150 .SH SHELL SUPPORT
2151 .sp
2152 The \fBmodulecmd.tcl\fP program that evaluates \fImodulefiles\fP supports a
2153 variety of shells or languages: \fIsh\fP family shells (\fIsh\fP, \fIbash\fP, \fIksh\fP and
2154 \fIzsh\fP), \fIcsh\fP family shells (\fIcsh\fP and \fItcsh\fP), \fIfish\fP, \fIcmd\fP, \fIpwsh\fP,
2155 \fIpython\fP, \fIperl\fP, \fIruby\fP, \fItcl\fP, \fIcmake\fP, \fIr\fP, and \fIlisp\fP\&.
2156 .sp
2157 Modulefiles produce environment changes when evaluated, like defining an
2158 environment variable. The \fBmodulecmd.tcl\fP program outputs the
2159 corresponding code for the selected \(dqshell\(dq. Thereafter this code is evaluated
2160 by the \fBmodule\fP alias or function to update the current environment.
2161 .sp
2162 Depending on the \(dqshell\(dq kind, not all the environment changes that can be
2163 defined in modulefiles are supported. The following table summarizes the
2164 changes that are supported by the shells supported by \fBmodulecmd.tcl\fP\&.
2165 .TS
2166 box center;
2167 l|l|l|l|l|l|l.
2168 T{
2169 T} T{
2170 Environment variables
2171 (\fI\%setenv\fP,
2172 \fI\%unsetenv\fP,
2173 \fI\%pushenv\fP,
2174 \fI\%append\-path\fP,
2175 \fI\%prepend\-path\fP,
2176 \fI\%remove\-path\fP)
2177 T} T{
2178 Shell alias
2179 (\fI\%set\-alias\fP,
2180 \fI\%unset\-alias\fP)
2181 T} T{
2182 Shell functions
2183 (\fI\%set\-function\fP,
2184 \fI\%unset\-function\fP)
2185 T} T{
2186 Command completion
2187 (\fI\%complete\fP,
2188 \fI\%uncomplete\fP)
2189 T} T{
2190 \fI\%chdir\fP
2191 T} T{
2192 \fI\%x\-resource\fP
2193 T}
2194 _
2195 T{
2196 sh
2197 T} T{
2198 x
2199 T} T{
2200 x
2201 T} T{
2202 x
2203 T} T{
2204 T} T{
2205 x
2206 T} T{
2207 x
2208 T}
2209 _
2210 T{
2211 bash
2212 T} T{
2213 x
2214 T} T{
2215 x
2216 T} T{
2217 x
2218 T} T{
2219 x
2220 T} T{
2221 x
2222 T} T{
2223 x
2224 T}
2225 _
2226 T{
2227 ksh
2228 T} T{
2229 x
2230 T} T{
2231 x
2232 T} T{
2233 x
2234 T} T{
2235 T} T{
2236 x
2237 T} T{
2238 x
2239 T}
2240 _
2241 T{
2242 zsh
2243 T} T{
2244 x
2245 T} T{
2246 x
2247 T} T{
2248 x
2249 T} T{
2250 T} T{
2251 x
2252 T} T{
2253 x
2254 T}
2255 _
2256 T{
2257 csh
2258 T} T{
2259 x
2260 T} T{
2261 x
2262 T} T{
2263 T} T{
2264 T} T{
2265 x
2266 T} T{
2267 x
2268 T}
2269 _
2270 T{
2271 tcsh
2272 T} T{
2273 x
2274 T} T{
2275 x
2276 T} T{
2277 T} T{
2278 x
2279 T} T{
2280 x
2281 T} T{
2282 x
2283 T}
2284 _
2285 T{
2286 fish
2287 T} T{
2288 x
2289 T} T{
2290 x
2291 T} T{
2292 x
2293 T} T{
2294 x
2295 T} T{
2296 x
2297 T} T{
2298 x
2299 T}
2300 _
2301 T{
2302 cmd
2303 T} T{
2304 x
2305 T} T{
2306 x
2307 T} T{
2308 T} T{
2309 T} T{
2310 x
2311 T} T{
2312 T}
2313 _
2314 T{
2315 pwsh
2316 T} T{
2317 x
2318 T} T{
2319 x
2320 T} T{
2321 x
2322 T} T{
2323 x
2324 T} T{
2325 x
2326 T} T{
2327 T}
2328 _
2329 T{
2330 python
2331 T} T{
2332 x
2333 T} T{
2334 T} T{
2335 T} T{
2336 T} T{
2337 x
2338 T} T{
2339 x
2340 T}
2341 _
2342 T{
2343 perl
2344 T} T{
2345 x
2346 T} T{
2347 T} T{
2348 T} T{
2349 T} T{
2350 x
2351 T} T{
2352 x
2353 T}
2354 _
2355 T{
2356 ruby
2357 T} T{
2358 x
2359 T} T{
2360 T} T{
2361 T} T{
2362 T} T{
2363 x
2364 T} T{
2365 x
2366 T}
2367 _
2368 T{
2369 tcl
2370 T} T{
2371 x
2372 T} T{
2373 T} T{
2374 T} T{
2375 T} T{
2376 x
2377 T} T{
2378 x
2379 T}
2380 _
2381 T{
2382 cmake
2383 T} T{
2384 x
2385 T} T{
2386 T} T{
2387 T} T{
2388 T} T{
2389 T} T{
2390 x
2391 T}
2392 _
2393 T{
2394 r
2395 T} T{
2396 x
2397 T} T{
2398 T} T{
2399 T} T{
2400 T} T{
2401 x
2402 T} T{
2403 x
2404 T}
2405 _
2406 T{
2407 lisp
2408 T} T{
2409 x
2410 T} T{
2411 T} T{
2412 T} T{
2413 T} T{
2414 x
2415 T} T{
2416 x
2417 T}
2418 .TE
2419 .sp
2420 The \fI\%source\-sh\fP command evaluates a shell script and produces the
2421 modulefile commands corresponding to the environment changes made by this
2422 script. \fI\%source\-sh\fP is able to evaluate \fIsh\fP, \fIbash\fP, \fIksh\fP, \fIzsh\fP,
2423 \fIcsh\fP, \fItcsh\fP and \fIfish\fP shell scripts. \fI\%source\-sh\fP produces
2424 environment changes corresponding to the kinds listed in the above table.
2425 Based on the evaluated script, refer to the above table to know the
2426 environment changes that will be rendered for the shell specified to
2427 \fBmodulecmd.tcl\fP program.
2428 .SH ENVIRONMENT
2429 .sp
2430 See the \fI\%ENVIRONMENT\fP section in the
2431 \fI\%module\fP man page.
2432 .SH SEE ALSO
2433 .sp
2434 \fI\%module\fP, \fI\%ml\fP, \fI\%envml\fP, \fBTcl(n)\fP,
2435 \fBTclX(n)\fP, \fBid(1)\fP, \fBxrdb(1)\fP, \fBexec(n)\fP,
2436 \fBuname(1)\fP, \fBdomainname(1)\fP, \fBtclvars(n)\fP,
2437 \fBlsort(n)\fP, \fBstring(n)\fP
2438 .SH NOTES
2439 .sp
2440 Tcl was developed by John Ousterhout at the University of California
2441 at Berkeley.
2442 .sp
2443 TclX was developed by Karl Lehenbauer and Mark Diekhans.
2444 .SH COPYRIGHT
2445 1996-2025, Modules Contributors
2446 .\" Generated by docutils manpage writer.
2447 .