Debian Codegraph @

doc/build/modulefile.5

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