Debian Codegraph @

doc/source/design/lmod-tcl-modulefile-compat.rst

raw
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: