Debian Codegraph @

doc/source/design/variants.rst

raw
1 .. _variants:
2
3 Variants
4 ========
5
6 Configuration
7 -------------
8
9 - Variant mechanism requires the :mconfig:`advanced_version_spec` option to be enabled
10
11 - Variants can be seen as an extension of the advanced module version specifiers
12
13
14 Specification
15 -------------
16
17 Defining
18 ^^^^^^^^
19
20 - variants are defined for modulefiles within concerned modulefiles with the :mfcmd:`variant` modulefile command
21
22 - variants are bound to the modulefile they target
23 - especially modulefile evaluation may be guided by the value selected for the variants
24 - so it makes more sense to have variants defined within modulefiles rather in modulercs
25
26 - ``variant --default? defaultval? --alias? {aliasname...?} name value? ...?``
27
28 - ``name`` restrained to the accepted variable name
29
30 - which should correspond to a sequence of one or more characters that are a letter, digit, underscore and minus sign
31 - first character cannot be a minus sign
32 - name as a whole cannot correspond to a number
33 - if we want to match Spack here also: ``[A-Za-z0-9_][A-Za-z0-9_-]*``
34 - raise error otherwise
35
36 - a variant ``name`` that has already been defined as variant or variant alias for this modulefile evaluation overwrites previous definition
37
38 - it is up to modulefile author to ensure there is no duplicate
39 - no need this way to check in ``modulecmd.tcl`` code if variant has already been defined
40
41 - may have a default value (when ``--default`` argument is passed)
42
43 - if not, variant is undefined
44 - argument ``--default`` should be associated a *defaultval* argument
45
46 - raise error otherwise
47
48 - default value should be part of possible value list if value list provided
49
50 - error is raised otherwise when default value is used, as it does not correspond to an accepted value
51
52 - ex: ``variant name --default 1.8 1.0 2.0``
53
54 - when no list of accepted value is provided, default value could be any value
55
56 - may be set as a Boolean variant (when ``--boolean`` argument is passed)
57
58 - a Boolean variant may equal *true* or *false*
59
60 - may have a list of accepted values
61
62 - unless if defined as a Boolean variant
63
64 - passed value(s) must correspond to those accepted
65
66 - raise error otherwise
67 - raised error is a global error to signal specification issue, not a modulefile error
68
69 - an error is raised if one or more accepted values are defined on a Boolean variant
70
71 - non-Boolean variants cannot define Boolean value in their accepted value list
72
73 - as Boolean values are translated to their canonical form (*0* or *1*) when specified
74 - an error is raised otherwise
75 - exception made for the *0* and *1* integers
76
77 - when no list of accepted value is provided it means any value is accepted
78
79 - it is up to the modulefile author to write the appropriate test after variant declaration to check that the value provided is acceptable
80
81 - may be aliased (when argument ``--alias`` is passed) in which case:
82
83 - argument ``--alias`` should be associated one or a list of alias names
84
85 - raise error otherwise
86
87 - defined alias names should be valid variant name (see spec above)
88
89 - raise error otherwise
90
91 - should not be already defined as variant or variant alias
92
93 - raise error otherwise
94
95 - variant alias could negate its target (when alias name is prefixed by ``-``)
96
97 - meaning if alias variant is set to ``false`` its target is set to ``true``
98 - only possible if targeted variant is Boolean
99
100 - raise error otherwise
101
102 - no support of ``~`` as an alternative negated prefix to only get one way to write negation
103
104 - require a value to be set
105
106 - raise error if no value set for variant (no value specified and no defined default)
107
108 - to validate variant value is coherent against other variant values or any other test
109
110 - it is up to the modulefile author to write the appropriate test after all variant declaration
111 - and then raise error if variant combination is not appropriate
112 - as there is no way to automatically determine when all variants are declared
113
114
115 Evaluating
116 ^^^^^^^^^^
117
118 - when reaching ``variant`` command in modulefile
119
120 - set a key ``name`` in array ``ModuleVariant`` if variant ``name`` has been specified or if it owns a default value
121
122 - variable ``ModuleVariant($name)`` is not defined if variant not specified and no default for it
123
124 - error is raised if used in this case
125
126 - if variant ``name`` can be aliased, if alias is set it specifies the value of variant ``name``
127
128 - evaluated from left to right, in case variant is set and also its aliases
129 - negating aliases sets its reversed value to Boolean variant
130
131 - variant alias is not instantiated in ``ModuleVariant`` array
132
133 - therefore accessing ``$ModuleVariant($aliasname)`` will raise an error
134
135 - raise error if variant ``name``:
136
137 - has been specified but passed value is incorrect
138 - is wrongly declared in modulefile (e.g., invalid name specified)
139
140 - then variable ``$ModuleVariant(name)`` could be used to adapt modulefile evaluation
141
142 - to know all variant currently set, use ``[array names ModuleVariant]``
143
144 - but beware that only the variant already evaluated will be set in array
145 - must use after all the ``variant`` to be set in the modulefile to accurately get all variant defined
146
147 - if variant accepted values are Booleans, variable could be directly used in conditional tests
148
149 - like ``if {$ModuleVariant($name)} {...``
150
151 - quoting Tcl doc, Booleans could have many forms:
152
153 - If string is any of *0*, *false*, *no*, or *off*, then Tcl_GetBoolean stores a zero value at ``*boolPtr``.
154 - If string is any of *1*, *true*, *yes*, or *on*, then 1 is stored at ``*boolPtr``.
155 - Any of these values may be abbreviated, and upper-case spellings are also acceptable
156
157 - variants with a :ref:`shortcut <variant-shortcut>` defined for them, are resolved to their full name and transmitted this way to the modulefile
158
159 - therefore no entry in ``ModuleVariant`` array is made for the shortcut name
160
161 - as special variant ``version`` will not be implemented on Modules 4.8, an error is raised if a variant is named ``version``
162
163 - to ensure no usage of this variant name will be made before its special mechanism availability
164
165 - special variant ``version`` is instantiated as variable ``ModuleVariant(version)`` if declared
166
167 - will be set to value that may be specified with the ``@`` shortcut
168 - will initially work as any other variant (accepted list of value, default value)
169
170 - using ``variant version --default 1.8 1.8 1.10``
171 - is equivalent of having two modulefiles *mod/1.8* and *mod/1.10*
172 - with a default defined: ``module-version mod/1.8 default``
173
174 - FUTURE: could be refined later on to accept range then select latest version or defined default if in range
175 - note that ``ModuleVariant(version)`` is set only if a ``version`` variant is declared in modulefile
176 - querying ``[module-info name]`` returns modulefile designation appended by the version variant: ``@versionvalue``
177
178 - at the end of the modulefile evaluation, if module specification contains a variant which is not defined in modulefile
179
180 - an error is raised
181
182 - for the different evaluation modes:
183
184 - *load*, *help* and *test* apply evaluation mechanism described above
185
186 - for the *help* and *test* modes it helps to see how the modulefile reacts to the different variant value
187
188 - *display* applies evaluation mechanism described above but allow variant to be unspecified
189
190 - to help learning all the variant defined by the modulefile
191 - as a result unspecified variant is not instantiated in the ``ModuleVariant`` array variable
192 - with unspecified variant a user will not accurately see how the modulefile reacts to the different variant value
193
194 - evaluation error is obtained if accessing the ``ModuleVariant`` array variable for an unspecified variant
195
196 - on *display* mode, the ``variant`` command is reported in addition of its evaluation
197
198 - *unload* evaluates the mechanism described above but the specified variants are fetched from loaded module persistent information
199
200 - ``version`` variant value is fetched from the module specification to identify the module to unload
201 - other variant specification on the unload command are dropped once matching loaded module is identified
202
203 - however this specification remains available when querying ``[module-info specified]``
204
205 - variant values are defined within modulefile context by the evaluation of the ``variant`` modulefile commands
206
207 - like it is done during a *load* modulefile evaluation
208 - this way variables related to variant are instantiated the same way whether module is loading or unloading
209 - so it is easier for modulefile author to understand how the modulefile code is evaluated
210
211 - variant evaluated during modulefile unload may produce an error
212
213 - if variant value not found defined or if value recorded in persistency does not match an allowed value
214 - should encourage variants to be consistent between the load and unload evaluation phases
215
216 - *whatis* ignores all variants from the module specification (only the module names are retained)
217
218 - like for ``setenv`` or ``*-path`` modulefile commands on this mode, ``variant`` will set the ``ModuleVariant`` array with a empty string for each variant defined in the modulefile
219 - this is done to avoid the *undefined variable* error if these variables are used later in the modulefile
220 - however variant specified in module specification is used to filter modules to evaluate in *whatis* mode thanks to the *extra match search* mechanism
221 - FUTURE: if the different ``version`` variant values are considered as different modulefiles in the future, then *whatis* may evaluates the ``version`` variant from module specification
222
223 getvariant
224 """"""""""
225
226 - A :mfcmd:`getvariant` modulefile command is added following the same principle than :mfcmd:`getenv`
227
228 - A variant name is passed as argument
229 - Corresponding variant value is returned if it is defined
230 - If not defined the *value if not defined* argument is returned
231 - By default *value if not defined* argument equals to the empty string
232
233 - ``getvariant`` should be preferred to accessing variant value in ``ModuleVariant`` array
234
235 - On display evaluation mode, ``getvariant`` returns the variant name enclosed in curly braces
236
237 - Which helps to report where the variant is used in environment variable content
238 - The variant name and enclosing curly braces are graphically enhanced with ``va`` SGR code
239
240
241 Persistency
242 ^^^^^^^^^^^
243
244 - once a module is loaded its defined variants are made persistent in user environment
245
246 - to keep track of how loaded modules were evaluated
247 - and enable query commands on these loaded modules without need to reevaluate modulefile
248
249 - variants defined are made persistent in :envvar:`__MODULES_LMVARIANT` environment variable
250
251 - following same approach than for :envvar:`__MODULES_LMPREREQ`
252 - each loaded module with defined variants (default value or specifically set) will expose:
253
254 - these variants value
255 - and if the value is the default one and if this default was specifically asked
256 - in a record with following syntax:
257 - ``loadedmodule&boolvariantname1|isbooleanvariant|isdefaultvalue&variantname2|value2|value3...|isbooleanvariant|isdefaultvalue``
258
259 - for each variant it is recorded if the variant is a Boolean variant
260
261 - which enables to compare value in a Boolean way
262 - and to report variant value with the *+variant* or *-variant* syntax
263
264 - for each variant it is recorded if the value set corresponds to the variant default value or not
265
266 - such information is useful to save collection when pin version mechanism is disabled
267 - on such setup the variant definition should not recorded in collection if this is the default value which is set
268
269 - in addition to know if the variant value is default or not, it is recorded if the default value was:
270
271 - specifically asked (*isdefaultvalue=1*)
272 - or automatically set (*isdefaultvalue=2*)
273 - this information will be useful in the FUTURE to determine if a variant may be automatically swapped by another
274
275 - each *loadedmodule* record are joined in ``__MODULES_LMVARIANT`` separated by ``:`` character
276
277 - variant alias are also made persistent in :envvar:`__MODULES_LMVARIANTALTNAME` environment variable
278
279 - each loaded module with defined variants (default value or specifically set) which could be aliased will expose their aliases in a record with following syntax
280
281 - ``loadedmodule&variantname1|aliasname1|-aliasname2&variant2|aliasname3...``
282
283 - each loadedmodule record are joined in ``__MODULES_LMVARIANTALTNAME`` separated by ``:`` character
284
285 - when persistency information is corrupted
286
287 - a missing or non Boolean ``isdefaultvalue`` information means variant value is not the default
288 - a missing or non Boolean ``isbooleanvariant`` information means variant is not a Boolean variant
289 - a non-Boolean value set on a Boolean variant means variant equals *0*
290
291 - Boolean variants are stored in the form ``+name`` or ``-name``
292
293 - which enables to determine this variant is of Boolean type
294 - and check against query using different Boolean representations
295
296 - like ``serial=0``, ``serial=on``, ``serial=false``, etc.
297
298 - when the special variant ``version`` is defined for a loaded module
299
300 - the value of this variant is part of loaded module identification
301 - ``@versionvalue`` is appended to the module name, for instance ``[email protected]``
302 - such identification is then recorded in persistency variables to designate loaded module (like ``LOADEDMODULES``, ``__MODULES_LMPREREQ``, ``__MODULES_LMVARIANT``, etc)
303 - this way in case a modulefile allows the load of two of its versions in the user environment, it is possible to distinguish these two loaded versions (to unload one of them for instance)
304 - with this identification, it is possible to distinguish a traditional module (identified by ``mod/version``) from a module using ``version`` variant (identified by ``mod@version``)
305 - note that if a modulefile ``mod/1.2`` defines a ``version`` variant, it will be identified as ``mod/1.2@versionvalue``
306
307 - so the ``version`` variant should not be defined if each version of the module has its own modulefile
308 - ``version`` variant is useful if a single modulefile is used to instantiate every version of the module
309
310 - FUTURE: when it will be possible to override the shortcut for ``version`` variant it will be important to identify version value in loaded module identification string
311 with a designation that is not dependent of the selected shortcut
312
313 - loaded module identification stops at the module name and ``version`` variant (if defined)
314
315 - other variants are not considered as part of the identification
316 - as it is not foreseen useful to have the same module loaded multiple times with different variant values, unless for ``version`` variant
317
318
319 Specifying
320 ^^^^^^^^^^
321
322 - following Spack spec
323
324 - see https://github.com/spack/spack/blob/develop/lib/spack/spack/spec.py
325 - or https://spack.readthedocs.io/en/latest/basic_usage.html#variants
326 - this specs covers all needs to specify variant on Modules
327 - Spack users are already familiar with it,
328 - it copes very well with command-line typing, avoiding most problematic characters
329
330 - that are interpreted by shells (like < or >)
331
332 - specification for one module could
333
334 - be almost condensed into one word *[email protected]+debug*
335 - or be expanded into multiple *hdf5 @1.8 +debug*
336
337 - same grammar used whatever the context
338
339 - command-line or as argument to modulefile command (like command)
340
341 - variants are specified whether
342
343 - as specific words (separated by " ")
344 - or as suffix to module name
345
346 - change command specifications which were previously accepting list of modules
347
348 - like *module1 module2 module3*
349 - now these modules could express variants appended to their name
350
351 - like *[email protected]+debug module2~shared module3*
352
353 - or these variants could be defined as words next to module name
354
355 - like *[email protected] +debug module2 shared=false module3*
356
357 - as a consequence it denies:
358
359 - use of *+*, *~* and *=* in module names
360 - and use of *-* as first character of module names
361
362 - also a command-line argument starting with the *-* character is not anymore considered as an invalid option
363
364 - it is considered as an element of the module specification (potential negated boolean variant)
365 - unless if set prior the sub-command designation
366 - or set on sub-commands that do not accept module specification as argument
367
368 - such change requires an option to be enabled to avoid breaking compat
369
370 - this is why to enable variant, the ``advanced_version_spec`` option has to be enabled
371
372 - a valued-variant is specified by *name=value*
373
374 - this kind of variant cannot be directly appended to module name
375 - thus it must be specified as a separate word
376
377 - a Boolean variant can be specified with its bare name prefixed by *+*, *-* or *~*
378
379 - when directly appended to module name string (no space) only *+* and *~* are recognized
380
381 - *-* in this case is retained as part of previous name/value
382
383 - the negation prefix *-* is not supported on the :command:`ml` command
384
385 - as this *-* prefix means to unload a module on this command
386
387 - negation prefix plus Boolean variant name should not equal a command-line option short form
388
389 - command-line option takes precedence
390 - for instance the ``-t`` will always be treated as ``--terse`` and not the negation of a ``t`` variant
391
392 - beware that the negation prefix *~* when used as a separate word may trigger the tilde resolution of the currently running shell
393
394 - if a username matches a Boolean variant name, using the ``~name`` form on the shell command-line will leads to the resolution of the HOME directory path of user ``name``
395
396 - module name could end with one or more *+* characters
397
398 - it could be distinguished from a Boolean variant specification as no character should follow these trailing *+*
399
400 - Boolean variant could also be specified using the *name=value* form
401
402 - in which case, it should be written as a separate word
403 - value could be any syntax recognized as a true or false string
404
405 - false: *0*, *false*, *no*, or *off*
406 - true: *1*, *true*, *yes*, or *on*
407 - Any of these values may be abbreviated, and upper-case spellings are also acceptable.
408
409 - when specified Boolean value is translated to its canonical form (*0* or *1*)
410
411 - variant may be specified with a shortcut if any set (see :ref:`variant-shortcut`)
412
413 - a shortcut is appended to the module designation word or specified as separate word, combined or not with other variant
414
415 - for instance for the ``@`` shortcut: *module@versspec+boolvar*, *module+boolvar@versspec*, *module +boolvar@versspec*
416
417 - even if a shortcut is set, the variant could also be expressed as valued variant name
418
419 - in case variant is specified multiple times
420
421 - on selection context, lastly mentioned (read from left to right) value is retained (it overwrites previous values)
422
423 - a *merge all passed values in list* is not the methodology retained here
424
425 - same handling way whatever the variant properties
426
427 - like *name=value1 name=value2*
428
429 - or *name=value name=value*
430 - or *name=value1,value2 name=value3*
431 - or *name=value1 name=value2,value3*
432 - or *@vers1 version=vers2*
433 - or for boolean *+name~name*
434 - or *~name -name*
435 - or *~name name=value1 name=value2,value3*
436 - or in case of variant aliases *+name~aliastoname*
437
438 - at the specification time variant aliases are not known
439
440 - so the full module specification has to be transmitted toward the modulefile to determine what is the value at the most right position
441 - for instance *name=value1 aliasname=value2* with *aliasname* being an alias of *name*
442 - specification can just be cleared from the obvious duplicates (same variant name defined multiple times on the line)
443
444 - on search context, all specifications form an *AND* operation
445
446 - *name=value1 name=value2* means find modules defining *value1* and *value2* as available values for *name* variant
447
448 - on search context, several values may be set on one variant criterion
449
450 - like *name=value1,value2*
451 - which means find modules defining either *value1* or *value2* as available value for *name* variant
452 - an error is obtained if performed on selection context
453
454 - on search context, variant criterion may be prefixed by ``not:`` string
455
456 - like *not:name=value1,value2*
457 - which means find modules not defining variant *name* or not providing *value1* and *value2* as available value
458 - an error is obtained if performed on selection context
459
460 - when special characters like *?* or \* are used in variant name or value
461
462 - they are treated literally, no wildcard meaning is applied
463 - like currently done when specifying module version on command-line
464
465 - which leads to errors as no corresponding module is found::
466
467 $ module load loc_dv6/*
468 ERROR: Unable to locate a modulefile for 'loc_dv6/*'
469
470 - when a variant is specified but it does not correspond to a variant defined in the evaluated modulefile
471
472 - an error is raised at the end of modulefile evaluation
473 - need to wait for the end of modulefile evaluation to be sure the variant is defined nowhere in modulefile code
474
475 - special variant ``version`` has to be specified with ``@`` shortcut or by its full variant name (``version=value``)
476
477 - traditional separator character ``/`` cannot be used to specify variant version
478 - if used, a modulefile named ``mod/version`` will be searched and a *module not found* error will be raised
479
480 - specification may be passed to commands to verify a given module and variant combination is loaded
481
482 - which should be performed without evaluating modulefiles
483 - like for ``is-loaded`` sub-command:
484
485 - ``module is-loaded hdf5+parallel``
486 - or ``[email protected] parallel=true``
487 - or ``hdf5 -serial``
488 - or ``hdf5 serial=0``
489
490 - checks rely on the content of the ``__MODULES_LMVARIANT`` and ``__MODULES_LMVARIANTALTNAME`` variables
491
492 - which store variants set for loaded modules and eventual variant aliases of variant set
493
494 - with this information it is possible to compare query against what is loaded
495
496 - a variant specified on query which is not part of the variables means a different module/variant combination
497
498 - even if variant from query is not valid for module, which cannot be known
499
500 - verification mechanism of a sub-command like ``is-loaded`` should be preserved
501
502 - which means a query not mentioning a specific value for a variant should match a loaded module which specify a variant value that differs from this variant default
503
504 - the module identification part in specification may be resolved from a symbolic version or a module alias to an actual modulefile
505
506 - the ``@loaded`` specification is translated into the name, version and variant list of corresponding loaded module
507
508 - for instance ``mod/3.0 foo=val1`` is loaded so ``mod@loaded`` is translated into ``mod/3.0 foo=val1``
509 - in case the ``@loaded`` specification is followed by variant specified, those variant specifications are ignored
510 - following the above example, ``mod@loaded foo=val2`` is translated into ``mod/3.0 foo=val1``
511
512 - variant can also be specified to designate module on :mfcmd:`module-tag`, :mfcmd:`module-hide` or :mfcmd:`module-forbid` commands
513
514 - tags may only apply when a given variant of a module is loaded
515 - it may be useful to decommission a given variant of a module prior others
516 - or to forbid the use of a given variant to some users
517
518 - variants specified on search context are taken into account to filter results
519
520 - due to the :ref:`extra-match-search` mechanism
521 - it concerns the ``avail``, ``spider``, ``whatis`` and ``paths`` sub-commands
522 - only available modules matching the variant specification will be retained
523 - for instance ``avail mod foo=var`` returns all versions of *mod* module where a variant *foo* is defined with *var* as a possible value
524 - exception is made for ``is-avail`` and ``path`` search sub-command
525
526 - as they are more module selection commands rather an available module search commands
527 - it does not take info account variants defined within module specification
528
529 - these search commands (except ``is-avail`` and ``path``) allow module specification without module name and version
530
531 - only variant name and value specified (e.g., ``module avail foo=var``)
532 - only modules declaring such variant with such version will be retained in result
533
534 - variants specified on loaded module list context are taken into account to filter results
535
536 - concerns ``list`` sub-command
537 - not related to *extra match search* as comparison is made against loaded modules not content of available modules
538 - only loaded modules matching the variant specification will be retained
539 - module specification without module name and version is allowed on this context
540
541 - only variant name and value specified (e.g., ``module list foo=var``)
542 - only loaded modules declaring such variant set with this version will be retained in result
543
544 - variant cannot be specified over the :mfcmd:`module-alias`, :mfcmd:`module-version`, :mfcmd:`module-virtual` commands
545
546 - variant passed as argument to :mfcmd:`module-info` ``alias``, ``version`` or ``symbols`` will not match anything
547
548 - ``module-info loaded`` only accepts modulefile as argument, not variant specification
549
550 - it also only return loaded module name and version, without the variant set
551
552
553 Variant in requirement specification
554 """"""""""""""""""""""""""""""""""""
555
556 - :mfcmd:`prereq`/:mfcmd:`conflict` specification
557
558 - could consolidate different variation set for same module on the same prereq/conflict list
559
560 - to indicate a preferred order (if available)
561 - like ``prereq netcdf -debug netcdf +debug``
562 - or ``prereq netcdf var=val1 netcdf var=val2 netcdf``
563
564 - in last example, could not currently consolidate definition into ``prereq netcdf var=val1,val2,default``
565
566 - in case of requirement alternatives, all possibilities should be written as independent
567
568 - like ``prereq module@vers variant=val1 module@vers variant=val2``
569
570 - to clearly indicate a priority order to apply when for instance attempting to load these requirements
571 - FUTURE: a value selection mechanism, like when selecting a module version among others, would help here
572
573 - prereq/conflict persistency
574
575 - :envvar:`__MODULES_LMPREREQ` and :envvar:`__MODULES_LMCONFLICT` content should reflect specified variant constraint
576
577 - it could be expressed in these variables as it is specified over the prereq/conflict modulefile commands
578
579 - for instance ``__MODULES_LMPREREQ=hdf5/1.10&[email protected] +shared variant=name&netcdf``
580 - use of characters `` ``, ``+``, ``~``, ``,`` is not an issue
581
582 - as delimiters characters in these environment variables are ``:``, ``&`` and ``|``
583
584
585 .. _variant-shortcut:
586
587 Variant shortcut
588 """"""""""""""""
589
590 - shortcuts can be set to abbreviate variant names and simplify their specification
591
592 - a shortcut abbreviates ``name=`` into a unique character
593 - when using shortcut, variant value is specified as ``<shortcut>value``
594 - for instance, if the ``%`` is set as the shortcut for a ``toolchain`` variant, value ``foss21a`` is specified as ``%foss21a``
595
596 - shortcut can be set through the :mconfig:`variant_shortcut` configuration option
597
598 - this option holds a colon separated list of shortcut definitions
599 - each definition have the following form: ``variantname=shortcut_character``
600 - for instance: ``toolchain=%:foo=^``
601
602 - shortcut must be:
603
604 - a single character
605 - excluding characters already used for other concerns or in module names or version specifications (*-*, *+*, *~*, */*, *@*, *=*, *:*, *,*, *[a-zA-Z0-9]*)
606 - when set through ``config`` sub-command or ``--with-variant-shortcut`` installation option: an error is raised when a shortcut is badly specified
607 - if a badly specified shortcut ends up in modulecmd configuration, it is purely ignored
608
609 - shortcut does not apply to Boolean variants
610
611 - as shortcuts are intended to be a prefix, they do not add benefit compared to *-*, *+* or *~* Boolean prefixes
612 - however a shortcut could be defined on a boolean variant (e.g., ``%true`` or ``%0``)
613
614 - by default, when ``advanced_version_spec`` is enabled, the ``@`` character is set as a shortcut for the ``version`` variant
615
616 - this shortcut is not referred in ``MODULES_VARIANT_SHORTCUT`` thus it cannot be unset
617 - FUTURE: superseding of this ``@`` shortcut in ``MODULES_VARIANT_SHORTCUT`` may be introduced in the future
618
619 - but currently entries in ``MODULES_VARIANT_SHORTCUT`` for ``version`` variant are ignored
620
621 - variant shortcuts could be used on the command-line or within modulefiles even if it is not recommended to use them in the latter case
622
623 - as if user updates the ``variant_shortcut`` configuration option, it will broke underlying modulefiles using a de-configured shortcuts
624
625 - module designation in collection does not use variant shortcuts
626
627 - when shortcut configuration is changed it should not impact collection definition
628
629
630 Reporting
631 ^^^^^^^^^
632
633 - Defined variants are reported on ``list`` sub-command results
634
635 - Reported joined to modulefile name, within curly braces
636 - Each variant definition separated by a colon
637 - For instance ``module/version{vr=val:+boolvr}``
638
639 - Variants are reported by default on ``list`` sub-command
640
641 - as they qualify what exact flavor of the module is loaded
642 - so it enables users to really catch what has been loaded exactly
643 - They can be removed from output using the :ref:`output configuration<output-configuration>` mechanism
644
645 - Variants defined by modulefiles may be reported on ``avail`` sub-command
646
647 - Not by default, if ``variant`` value is added to ``avail_output`` or ``avail_terse_output``
648 - Or if ``variantifspec`` value is added to ``avail_output`` or
649 ``avail_terse_output`` and a variant is specified in search query
650 - It requires an :ref:`extra-match-search`
651 - Which in turns requires more processing time as modulefiles are evaluated
652 - Having cache file available helps to reduce the I/O load caused by such process
653
654 - Variants defined by modulefiles may be reported on ``spider`` sub-command
655
656 - Not by default, if ``variant`` value is added to ``spider_output`` or
657 ``spider_terse_output``
658 - Or if ``variantifspec`` value is added to ``spider_output`` or
659 ``spider_terse_output`` and a variant is specified in search query
660 - It requires an :ref:`extra-match-search`
661 - Which in turns requires more processing time as modulefiles are evaluated
662 - Having cache file available helps to reduce the I/O load caused by such process
663
664 - A specific color key is defined to highlight variants: ``va``
665
666 - Variant report depends on variant type
667
668 - valued variant: ``variant=value``
669 - boolean variant: ``+variant`` or ``-variant``
670 - valued variant with shortcut set: ``<shortcut>value`` (for instance if ``%`` is a defined shortcut: ``%value``)
671 - in case a shortcut is defined over a Boolean variant, Boolean report prevails over shortcut
672
673 - On ``avail`` and ``spider``, all possible values of variant are reported
674
675 - Values are separated from each other with ``,`` character
676 - Boolean variant are reported as valued variant with ``on`` and ``off`` values reported
677 - Example: ``mod/1.0{variant=val1,val2,boolvariant=on,off:%val1,val2}``
678 - A ``*`` value is reported in possible value list for free-value variant
679
680 - To indicate all values are possible
681 - Loaded variant value and default variant value are also reported if any
682
683 - Variant aliases are not reported
684
685 - to keep output tight
686
687 - Special variant ``version`` is reported right after the module name
688
689 - with ``@`` shortcut
690 - using variant highlight color if any
691 - for instance: ``module@version{othervariant=value}``
692
693 - Variants are reported on the *Loading*, *Unloading* and *Switching* informational messages
694
695 - As they qualify what exact flavor of the module is loaded, unloaded or switched
696 - They are put along the module name and version designation
697 - They are reported using their short form, like for ``list`` sub-command to keep output tight
698 - Separated between each other by space character
699 - Each variant specification is enclosed between single quotes if it contains a space character
700 - The whole variant specification is enclosed between curly braces (``{}``) and separated from module name version by space character
701
702 - Easier this way to distinguish variant specification from module name version on informational messages where multiple module designation are reported
703
704 - These designations have to be recorded
705
706 - prior module evaluation and based on variant specification (passed as argument) in order to be ready for any report prior the end of modulefile evaluation (in case of error for instance)
707 - then refined after module evaluation with the variant accurately set in loaded environment
708
709 - Variants are also reported along module name and version in the :mconfig:`auto_handling` informational messages
710
711
712 Recording collection
713 ^^^^^^^^^^^^^^^^^^^^
714
715 - The variant specification set for loaded modules has to be recorded when saving it in a collection
716
717 - Restoring such environment should apply the variant specified on the module to load
718 - Lines like the following one could now be found in collection: ``module load [email protected] +parallel``
719 - Important to distinguish multiple modules specified on a single line from a module specified with variant defined
720
721 - In case the :mconfig:`collection_pin_version` configuration option is disabled variant set to their default value should not be recorded in collection
722
723 - Following the same scheme than for module version
724 - When saving collection, the *is-default-value* information stored in persistency variable (``__MODULES_LMVARIANT``) helps to know whether the value set to a variant is or not the default one
725 - The save mechanism will rely on this information to exclude or not the variant specification in the generated collection output
726 - Within this *is-default-value* hint, the *was-this-default-specified-by-user* sub-information is not preserved when saving collection
727
728 - if collection is not pinned, default value is excluded whether it was specifically set by user or not
729
730
731 Comparing module specification including variants
732 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
733
734 - When a module specification has to be compared on a non-loaded or non-loading modules context
735
736 - If this specification contains variants
737
738 - Applies especially to the search commands taking a module specification as argument
739 - Specified variants are taken into account through :ref:`extra-match-search` mechanism
740
741 - Once matching name and version are found
742 - A *scan* evaluation is made on them
743 - Only those declaring specified variants and values are retained in results
744
745 - It applies to ``avail``, ``spider``, ``whatis`` and ``paths`` sub-commands
746 - Exception is made for ``is-avail`` and ``path`` sub-commands
747
748 - do not trigger *extra match search* process
749 - even if variant specified in module specification argument
750
751 - If this specification does not contain variant
752
753 - There is no variant set on non-loaded or non-loading modules we are comparing to
754 - Match is performed over module name and version
755
756 - When a module specification has to be compared against loaded or loading modules
757
758 - If this specification contains variants
759
760 - It should be matched against the variants set on loaded or loading modules
761 - No variant set for loaded or loading module means no match
762
763 - If this specification does not contain variant
764
765 - Loaded or loading modules match is only made on their name
766 - No comparison occurs over the variants set on loaded or loading modules
767
768 - To compare variant set on loaded or loading modules
769
770 - A ``ismodlo`` flag is added to the ``modEq`` procedure
771 - With this flag it is known if ``modEq`` operates on a:
772
773 - non-loaded or non-loading context (0),
774 - loading context (1)
775 - loaded context (2)
776
777 - Variants set on loading or loaded modules will be fetched in case ``ismodlo`` is equal to 1 or 2
778 - Loaded or loading modules are passed to ``modEq`` by their name/version designation
779
780 - No change here
781 - And no change required in all procedures that perform such comparison
782
783 - Alternative names should also be tested like main module name with variants set
784
785 - As the alternative names currently apply to module name and version only
786 - Name and version could be compared on their own
787 - Then variants could be compared
788 - Which means all applying names are compared then if a match is found variants are compared
789
790 - Specific comparison occurs when restoring collection
791
792 - When a collection is restored an unspecified variant for a given module to load means this variant has to be set at its default value
793 - So when comparing against loaded environment, an unspecified variant in collection only matches if variant set on loaded environment is the default one
794 - Collection procedures now rely on the ``modEq`` procedure
795
796 - ``ismodlo`` flag is set to ``3`` to indicate a collection context
797 - This collection context leads to also compare simplified module names (in addition to alternative names)
798 - And to treat an unspecified variant on tested pattern as a default variant value
799
800 - There is no need to compare variants on following procedures
801
802 - ``getLoadedWithClosestName``
803
804 - Find a loaded module whose name and version is the closest to passed specification
805 - Variant specified on loaded modules or on specification is ignored here
806
807 - ``modStartNb``
808
809 - Only used to compare module name and versions
810 - Used by ``getLoadedWithClosestName`` and ``isModuleHidden``
811
812 - ``modEqStatic``
813
814 - Always used over non-loaded or non-loading context
815 - Used by ``findModules`` and ``getModules``
816
817 - ``getEqArrayKey``
818 - ``cmdModuleSearch``
819 - ``cmdModuleSwitch``
820 - ``getModules``
821
822 - Unless if module specification contains a variant definition, which
823 triggers an *extra match search* process
824 - Used by ``cmdModuleAvail``, ``getPathToModule``, ``isStickinessReloading``,
825 ``cmdModulePaths``, ``cmdModuleSearch`` and ``cmdModuleAliases``
826
827 - ``getPathToModule``
828
829 - Which calls to ``getModules``
830 - Used by ``cmdModulePath``, ``cmdModuleSearch``, ``cmdModuleSwitch``, ``cmdModuleLoad``,
831 ``cmdModuleUnload``, ``cmdModuleTest``, ``cmdModuleHelp``, ``getAllModuleResolvedName``,
832 ``is-avail``, ``getSimplifiedLoadedModuleList`` and ``cmdModuleDisplay``
833
834 - ``getAllModuleResolvedName``
835
836 - Variant comparison is needed on following procedures
837
838 - ``setModuleDependency``
839 - ``getUnmetDependentLoadedModuleList``
840 - ``getDirectDependentList``
841 - ``cmdModuleLoad``
842 - ``cmdModuleList``
843 - ``conflict``
844 - ``getLoadedMatchingName``
845 - ``doesModuleConflict``
846 - ``getModuleTag``
847
848 - Useful when a tag is defined only when a specific variant is set
849
850 - ``collectModuleTag``
851
852 - Useful when a tag is defined only when a specific variant is set
853
854 - ``getModuleHidingLevel``
855
856 - Useful when a module with a specific variant value set is defined hidden
857 - FUTURE: if variants are reported on ``avail``, hiding a variant specific value
858 would have an effect on this sub-command
859
860 - ``isModuleHidden``
861
862 - Useful when a module with a specific variant value set is defined hidden
863 - FUTURE: if variants are reported on ``avail``, hiding a variant specific value
864 would have an effect on this sub-command
865
866
867 Specific impact
868 ^^^^^^^^^^^^^^^
869
870 - When loading a module with variant, if this module is already loaded but with a different variant set an error is raised
871
872 - Tags applying specifically on variants do not appear over ``avail`` or ``spider`` results
873
874 - Even when variants are processed on ``avail`` mode
875 - However if a module is loaded and tags apply to the variant selected, these tags will appear on the module designation within ``avail`` result
876
877 - Forbidding a specific variant of a module will not exclude it from search results
878
879 - The module will still be reported on ``avail``, ``spider`` or evaluated on ``whatis``
880 - Even if this specific variant is searched
881 - As search sub-commands report all possible variants of available modules
882
883 - Hiding a specific variant of a module will not hide the module from search results
884
885 - Even if this specific variant is searched
886 - As search sub-commands report all possible variants of available modules
887
888 - Sticky modules can be swapped by another sticky modules if the stickiness applies to the generic module name
889
890 - It stays true even if module has variants
891 - Which means if stickiness designate module version or several versions, sticky module cannot be changed once loaded
892 - Variant change cannot either occur
893 - FUTURE: this may be revised to allow variant change if needs arise
894
895 - Stickiness can be defined over specific variant value, like any other tag
896
897 - In case stickiness applies to the default value of a variant
898 - When swapping sticky modules by another still matching the sticky rule
899 - The variant with default value has to be explicitly specified for the swap to be allowed
900
901 - As it cannot be guessed prior loading module that the default value of the variant will match the sticky rule
902 - It applies to both sticky module swap context: ``restore`` and ``switch``
903
904 - On ``module-info tags``, currently defined tags need to get fetched when called
905
906 - As variant specified prior ``module-info tags`` call may change the list of tags that apply
907 - Especially when a variant inherits its default value as it is not specified when loading module
908
909 - ``module-info specified`` returns module name version and variants specified to designate the currently evaluating module
910
911 - ``module-info name`` only returns module name and version, variants are not part of the result
912
913 - Variants can be fetched in the ``ModuleVariant`` array within evaluation context
914
915
916 Corner cases
917 ------------
918
919 - When loading a variant which is an optional requirement for an already loaded module
920
921 - If this optional requirement is loaded without specifying its variant value to get the default variant value
922 - Currently it is not seen as an optional requirement at the load time
923 - Thus dependent module is not reloaded
924 - FUTURE: the *deps* evaluation mode that will be triggered prior module load may fix this current limitation
925
926 .. vim:set tabstop=2 shiftwidth=2 expandtab autoindent: