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