| 1 |
.. _lmod-tcl-modulefile-compat: |
| 2 |
|
| 3 |
Lmod Tcl modulefile compatibility |
| 4 |
================================= |
| 5 |
|
| 6 |
- Goal is to be able to evaluate with :command:`modulecmd.tcl` a Tcl |
| 7 |
modulefile generated for Lmod |
| 8 |
|
| 9 |
- No evaluation error |
| 10 |
- Be as close as possible to the behavior of Lmod |
| 11 |
|
| 12 |
- Starting with Modules v5.1, the following Tcl modulefile commands from Lmod |
| 13 |
are now supported. This document describes their implementation and behavior |
| 14 |
in Modules v5.1 and later. |
| 15 |
|
| 16 |
- ``add-property`` |
| 17 |
- ``remove-property`` |
| 18 |
- ``extensions`` |
| 19 |
- ``depends-on`` |
| 20 |
- ``prereq-any`` |
| 21 |
- ``always-load`` |
| 22 |
- ``module load-any`` |
| 23 |
- ``pushenv`` |
| 24 |
- ``require-fullname`` |
| 25 |
- ``family`` |
| 26 |
- ``hide-version`` |
| 27 |
- ``hide-modulefile`` |
| 28 |
|
| 29 |
- See :ref:`Compatibility with Lmod Tcl modulefile` section in |
| 30 |
:ref:`modulefile(5)` man page for the current state of support. |
| 31 |
|
| 32 |
|
| 33 |
``add-property``/``remove-property`` |
| 34 |
------------------------------------ |
| 35 |
|
| 36 |
- Property mechanism of Lmod does not completely fit into Modules tag |
| 37 |
mechanism: |
| 38 |
|
| 39 |
- Property are first defined in a global RC file |
| 40 |
- Then associated to a given modulefile with ``add-property`` command |
| 41 |
- Could be unset with ``remove-property`` |
| 42 |
- Defined as a key-value |
| 43 |
|
| 44 |
- As of Modules version 5.1, these commands are implemented as a no-operation |
| 45 |
command (``nop``) |
| 46 |
|
| 47 |
- No error raised if used |
| 48 |
- And no warning message to avoid polluting output |
| 49 |
|
| 50 |
- These commands are intended for use only within modulefile evaluation |
| 51 |
context (not within modulerc) |
| 52 |
|
| 53 |
- An update is made on Modules version 5.6: argument *value* of |
| 54 |
mfcmd:`add-property` is converted to :mfcmd:`module-tag` onto loading |
| 55 |
modulefile |
| 56 |
|
| 57 |
- Argument *name* is ignored as it seems *value* is the deterministic |
| 58 |
information (can be understood just by itself) |
| 59 |
- Argument *value* is split as sometimes multiple values are aggregated with |
| 60 |
``:`` separator |
| 61 |
- ``remove-property`` stays as a no-op operation as Modules does not have |
| 62 |
a tag-withdrawn mechanism (and it does not seem useful) |
| 63 |
- ``add-property`` is no-op during scan evaluation mode as module tags |
| 64 |
search does not currently trigger an extra match search |
| 65 |
|
| 66 |
|
| 67 |
``extensions`` |
| 68 |
-------------- |
| 69 |
|
| 70 |
- Extension mechanism is an additional information added on ``avail`` and |
| 71 |
``spider`` sub-command output |
| 72 |
|
| 73 |
- Requires to evaluate modulefile on ``avail`` processing |
| 74 |
- Not used to load the modulefile declaring them when an extension name is |
| 75 |
passed to ``load`` sub-command or ``depends-on`` modulefile command |
| 76 |
|
| 77 |
- This command was first implemented as a no-operation command (``nop``) in |
| 78 |
Modules 5.1 |
| 79 |
|
| 80 |
- No error raised if used |
| 81 |
- And no warning message to avoid polluting output |
| 82 |
|
| 83 |
- This command is intended for use only within modulefile evaluation context |
| 84 |
(not within modulerc) |
| 85 |
|
| 86 |
- Starting Modules 5.6, this command is made an alias onto :mfcmd:`provide` |
| 87 |
modulefile command. See :ref:`provide` for details. |
| 88 |
|
| 89 |
|
| 90 |
``prereq-any`` |
| 91 |
-------------- |
| 92 |
|
| 93 |
- This command is an alias over ``prereq`` command |
| 94 |
|
| 95 |
- In Lmod, ``prereq`` acts as a *prereq-all* |
| 96 |
- Whereas on Modules ``prereq`` acts already as a *prereq-any* |
| 97 |
|
| 98 |
- This command is intended for use only within modulefile evaluation context |
| 99 |
(not within modulerc) |
| 100 |
|
| 101 |
|
| 102 |
``require-fullname`` |
| 103 |
-------------------- |
| 104 |
|
| 105 |
- Raise an error if modulefile has been designed with implicit or explicit |
| 106 |
default name |
| 107 |
|
| 108 |
- This error aborts modulefile evaluation |
| 109 |
- Occurs for instance if ``foo/1.0`` is loaded with ``foo`` or |
| 110 |
``foo/default`` name |
| 111 |
- Which means ``require-fullname`` has precedence over explicitly set |
| 112 |
default version |
| 113 |
- If an alias or a symbolic version (other than ``default``) point to the |
| 114 |
modulefile, no error occurs if modulefile is designated using these |
| 115 |
alternative names. |
| 116 |
|
| 117 |
- ``require-fullname`` is implemented to only apply on *load* evaluation mode |
| 118 |
|
| 119 |
- On Lmod, it applies on *load*, *unload*, and *display* modes |
| 120 |
- It seems important not to apply the constraint on *unload* and *display* |
| 121 |
modes to ease user's experience |
| 122 |
|
| 123 |
- This command is intended for use only within modulefile evaluation context |
| 124 |
(not within modulerc) |
| 125 |
|
| 126 |
|
| 127 |
``depends-on`` |
| 128 |
-------------- |
| 129 |
|
| 130 |
- Auto load one or more modules said as dependencies when modulefile is |
| 131 |
evaluated in *load* mode |
| 132 |
|
| 133 |
- Corresponds to the *Requirement Load* module auto handling mechanism. |
| 134 |
- Semantically this command corresponds to a requirement declaration. |
| 135 |
- Make it an alias over :mfcmd:`prereq` but with each argument set as a |
| 136 |
*prereq*all* not a *prereq-any*. |
| 137 |
- If :mconfig:`auto_handling` option is disabled, requirement will not be |
| 138 |
loaded and an error is raised. This will be different than Lmod as |
| 139 |
with Modules the modulefile commands defines the semantic (*this is |
| 140 |
a dependency*) then the automation is defined by the module command |
| 141 |
configuration, not by the modulefile like done in Lmod. |
| 142 |
|
| 143 |
- Auto unload the dependency modules when modulefile is unloaded if no other |
| 144 |
loaded module depends on them |
| 145 |
|
| 146 |
- Corresponds to the *Useless Requirement Unload* module auto handling |
| 147 |
mechanism |
| 148 |
- Like for *load* evaluation, automation is configured at the module |
| 149 |
command level, not by individual modulefiles |
| 150 |
|
| 151 |
- This command is intended for use only within modulefile evaluation context |
| 152 |
(not within modulerc) |
| 153 |
|
| 154 |
|
| 155 |
``always-load`` |
| 156 |
--------------- |
| 157 |
|
| 158 |
- Auto load on or more modules said as dependencies when modulefile is |
| 159 |
evaluated in *load* mode |
| 160 |
|
| 161 |
- Semantically this command corresponds to a requirement declaration. |
| 162 |
- Make it an alias over :mfcmd:`module load<module>` |
| 163 |
- Add ``keep-loaded`` tag to the modules loaded this way |
| 164 |
- When several modules are specified, it acts as an *AND* operation, which |
| 165 |
means all specified modules are required |
| 166 |
|
| 167 |
- When modulefile is unloaded, the *always-load* modules are not automatically |
| 168 |
unloaded as they own the ``keep-loaded`` tag |
| 169 |
|
| 170 |
- This command is intended for use only within modulefile evaluation context |
| 171 |
(not within modulerc) |
| 172 |
|
| 173 |
|
| 174 |
``module load-any`` |
| 175 |
------------------- |
| 176 |
|
| 177 |
- Auto load first valid module in a list when modulefile is evaluated in |
| 178 |
*load* mode |
| 179 |
|
| 180 |
- Semantically this command corresponds to a requirement declaration. |
| 181 |
- Acting as an *OR* operation |
| 182 |
- Evaluation stops after first module in list loaded |
| 183 |
|
| 184 |
- Whether called from a modulefile evaluation context or from top |
| 185 |
evaluation context |
| 186 |
- Different than Lmod that apply the :subcmd:`load` sub-command |
| 187 |
behavior when called from top evaluation context and does not stop |
| 188 |
after first modulefile loaded |
| 189 |
|
| 190 |
- If the evaluation of first module to load in list ends in error |
| 191 |
|
| 192 |
- When called from a modulefile evaluation context |
| 193 |
|
| 194 |
- Error is silenced |
| 195 |
- Next module in list is tried |
| 196 |
- It behaves this way like a :mfcmd:`prereq` command with |
| 197 |
auto_handling mode enabled |
| 198 |
- Proceed this way whatever the auto_handling state |
| 199 |
- Different than Lmod that aborts modulefile evaluation |
| 200 |
|
| 201 |
- Otherwise when called from top evaluation context |
| 202 |
|
| 203 |
- Error message is reported |
| 204 |
- Next module in list is tried |
| 205 |
- Different than Lmod that aborts processing |
| 206 |
|
| 207 |
- If first modules to load are unknown |
| 208 |
|
| 209 |
- No message reported |
| 210 |
- ``load-any`` continues until finding a module in the specified list |
| 211 |
|
| 212 |
- If a module in the list is already loaded |
| 213 |
|
| 214 |
- When called from a modulefile evaluation context |
| 215 |
|
| 216 |
- ``load-any`` is not performed as requirement is considered |
| 217 |
already satisfied |
| 218 |
- Better cope this way with the expressed requirement |
| 219 |
- It behaves this way like a :mfcmd:`prereq` command |
| 220 |
- Proceed this way whatever the auto_handling state |
| 221 |
- Different behavior than Lmod that still proceed to load the |
| 222 |
module in the list from the left to the right until loading one |
| 223 |
or finding one loaded |
| 224 |
|
| 225 |
- Otherwise when called from top evaluation context |
| 226 |
|
| 227 |
- An attempt to load first module in list is still issued |
| 228 |
- And pursued from left to right until loading one module or |
| 229 |
finding one loaded |
| 230 |
|
| 231 |
- ``load-any`` acts similarly to ``try-load`` but with an *OR* operation |
| 232 |
behavior instead of an *AND* operation |
| 233 |
|
| 234 |
- An error is obtained if none of the listed modules can be loaded if |
| 235 |
none of their load attempt generated an error message |
| 236 |
|
| 237 |
- If no argument is provided an error is obtained, like done for |
| 238 |
``try-load`` |
| 239 |
|
| 240 |
- When modulefile is unloaded, an attempt to unload all specified module is |
| 241 |
made |
| 242 |
|
| 243 |
- Correspond to the behavior of a ``module unload`` |
| 244 |
- Modules which are still depended by other loaded modules will not be |
| 245 |
unloaded |
| 246 |
|
| 247 |
- This command is intended for use only within modulefile evaluation context |
| 248 |
(not within modulerc) |
| 249 |
|
| 250 |
|
| 251 |
``module try-load`` |
| 252 |
------------------- |
| 253 |
|
| 254 |
- ``try-load`` sub-command and modulefile command has been introduced in |
| 255 |
Modules version 4.8. |
| 256 |
|
| 257 |
- ``try-load`` modulefile command acts as an individual ``prereq`` for each |
| 258 |
modulefile specified. |
| 259 |
|
| 260 |
- Each modulefile specified is considered optional requirement, as no error is |
| 261 |
raised if they cannot be found. |
| 262 |
|
| 263 |
- No message is reported in case of *not found* or *forbidden* errors |
| 264 |
- Other kind of error are raised the usual way |
| 265 |
- An update is made on version 5.2 to record each modulefile specified on |
| 266 |
``try-load`` as optional requirement even if their load attempt did not |
| 267 |
succeed. |
| 268 |
- With this change, if the optional requirement is loaded later on, the |
| 269 |
module declaring the ``try-load`` command will be automatically reloaded |
| 270 |
(if ``auto_handling`` is enabled) to take the new availability of its |
| 271 |
optional requirement into account. |
| 272 |
|
| 273 |
|
| 274 |
``family`` |
| 275 |
---------- |
| 276 |
|
| 277 |
- Defines membership in family *name* and ensures that only one member of a |
| 278 |
given family is currently loaded. |
| 279 |
|
| 280 |
- Semantically this command corresponds to the definition of both: |
| 281 |
|
| 282 |
- a conflict on family *name* |
| 283 |
- a module alias *name* over currently loading module |
| 284 |
|
| 285 |
- Also defines the :envvar:`MODULES_FAMILY_\<NAME\>` environment variable set |
| 286 |
to the currently loading module name minus its version number. |
| 287 |
|
| 288 |
- As family *name* is used in environment variable name, it requires that |
| 289 |
*name* should only use characters that are accepted there |
| 290 |
- Accepted characters for family *name* are *[a-zA-Z0-9_]* |
| 291 |
- An error is generated in case other kind of characters are found in |
| 292 |
specified family *name* |
| 293 |
|
| 294 |
- The :envvar:`LMOD_FAMILY_\<NAME\>` environment variable is also set in |
| 295 |
addition to :envvar:`MODULES_FAMILY_\<NAME\>` and set to the same value. |
| 296 |
This way existing scripts or modulefiles relying on this variable do not |
| 297 |
need to be changed to be compatible with Modules. |
| 298 |
|
| 299 |
- When modulefile is unloaded, the ``MODULES_FAMILY_<NAME>`` and |
| 300 |
``LMOD_FAMILY_<NAME>`` environment variables are unset |
| 301 |
|
| 302 |
- This command is intended for use only within modulefile evaluation context |
| 303 |
(not within modulerc) |
| 304 |
|
| 305 |
|
| 306 |
``pushenv`` |
| 307 |
----------- |
| 308 |
|
| 309 |
- Sets an environment variable with a value specified as argument but saves |
| 310 |
the previous value set to restore it when modulefile is unloaded. |
| 311 |
|
| 312 |
- Use a :envvar:`__MODULES_PUSHENV_\<VAR\>` environment variable as a stack to |
| 313 |
record the previous values of environment variable ``<VAR>``. |
| 314 |
|
| 315 |
- Each element in this Modules-specific variable is the combination of the |
| 316 |
currently evaluating modulename and pushed value. |
| 317 |
|
| 318 |
- Combination joined with the ampersand character |
| 319 |
- Each element in variable separated by colon character |
| 320 |
|
| 321 |
- When unloading, the value set by this module is removed not the value on |
| 322 |
top of the list. |
| 323 |
- Different than Lmod that restores the value on top of the stack even if |
| 324 |
unloading module were not the one defining the top value currently in |
| 325 |
use. |
| 326 |
|
| 327 |
- When saving value set before any module |
| 328 |
|
| 329 |
- An empty module name is used to push to the stack. |
| 330 |
- When restoring this initial value, initial entry in stack is also |
| 331 |
cleared (as no other module unload will unset it). |
| 332 |
|
| 333 |
- It is not expected that for the same environment variable, :mfcmd:`pushenv` |
| 334 |
is mixed with: |
| 335 |
|
| 336 |
- ``setenv``, ``unsetenv`` |
| 337 |
- ``append-path``, ``prepend-path``, ``remove-path`` |
| 338 |
- These other modulefile commands clear the pushenv stack environment |
| 339 |
variable (like ``setenv``/``unsetenv`` clear the reference counter |
| 340 |
environment variable of the ``*-path`` commands) |
| 341 |
|
| 342 |
- It is not expected that :mfcmd:`pushenv` is called multiple times for the |
| 343 |
same environment variable in the same modulefile |
| 344 |
|
| 345 |
- Inconsistent results may be obtained if environment variable value is |
| 346 |
used in modulefile to set other variables. |
| 347 |
- Especially that unload evaluation of modulefile will not process the |
| 348 |
``pushenv`` commands in the reverse order but in the script order. |
| 349 |
- When checked during modulefile evaluation, lastly defined value remains |
| 350 |
- However the operation is consistent at the end of modulefile evaluation, |
| 351 |
as all values are withdrawn from stack and a value defined somewhere |
| 352 |
else is restored. |
| 353 |
- pushenv stack environment variable correctly handles multiple entries |
| 354 |
coming from same modulefile, even multiple identical values. |
| 355 |
|
| 356 |
- For Lua modulefiles, Lmod handles a specific ``false`` value which clears |
| 357 |
environment variable |
| 358 |
|
| 359 |
- Lmod does not implement this for Tcl modulefile |
| 360 |
- Maybe because ``false`` cannot be distinguished from any other value |
| 361 |
- So this specific behavior is also not supported on Modules |
| 362 |
|
| 363 |
- This command is intended for use only within modulefile evaluation context |
| 364 |
(not within modulerc) |
| 365 |
|
| 366 |
|
| 367 |
``hide-version``/``hide-modulefile`` |
| 368 |
------------------------------------ |
| 369 |
|
| 370 |
- Hide given module name and version or modulefile's full path name. |
| 371 |
|
| 372 |
- Accept one argument, a string that designates: |
| 373 |
|
| 374 |
- a module name and version for :mfcmd:`hide-version` |
| 375 |
- the full path name of a modulefile for :mfcmd:`hide-modulefile` |
| 376 |
|
| 377 |
- These two commands are implemented by simply calling :mfcmd:`module-hide` |
| 378 |
|
| 379 |
- These commands are intended for use only within modulerc evaluation context |
| 380 |
(not within modulefile) |
| 381 |
|
| 382 |
|
| 383 |
``--mode`` option |
| 384 |
----------------- |
| 385 |
|
| 386 |
Lmod introduced on version ``8.7.60`` the ``--mode`` option (short name |
| 387 |
``-m`` or ``-mode``) for the following modulefile commands: |
| 388 |
|
| 389 |
* ``setenv`` |
| 390 |
* ``unsetenv`` |
| 391 |
* ``prepend-path`` |
| 392 |
* ``append-path`` |
| 393 |
* ``remove-path`` |
| 394 |
* ``pushenv`` |
| 395 |
* ``module load`` |
| 396 |
* ``module load-any`` |
| 397 |
* ``module try-load`` |
| 398 |
* ``module unload`` |
| 399 |
|
| 400 |
See :ref:`mode-select` design documentation to learn about this option. |
| 401 |
|
| 402 |
This ``--mode`` option is not supported currently on Modules and an error is |
| 403 |
raised when it is used in modulefiles. |
| 404 |
|
| 405 |
|
| 406 |
``--respect`` option |
| 407 |
-------------------- |
| 408 |
|
| 409 |
Lmod has the ``--respect`` option (short name ``-r`` or ``-respect``) for the |
| 410 |
following modulefile commands: |
| 411 |
|
| 412 |
* ``setenv`` |
| 413 |
* ``unsetenv`` |
| 414 |
|
| 415 |
This option on ``setenv`` does not change the environment variable value, if |
| 416 |
this variable is already defined. On ``unsetenv``, environment variable is not |
| 417 |
unset if its current value does not equal the one specified on ``unsetenv`` |
| 418 |
command. |
| 419 |
|
| 420 |
This ``--respect`` option is not supported currently on Modules and an error |
| 421 |
is raised when it is used in modulefiles. |
| 422 |
|
| 423 |
|
| 424 |
.. vim:set tabstop=2 shiftwidth=2 expandtab autoindent: |