| 1 |
.. _module-tags: |
| 2 |
|
| 3 |
Module tags |
| 4 |
=========== |
| 5 |
|
| 6 |
Configuration |
| 7 |
------------- |
| 8 |
|
| 9 |
- No specific configuration |
| 10 |
|
| 11 |
Specification |
| 12 |
------------- |
| 13 |
|
| 14 |
- Introduce one new modulefile command to set tags on modulefiles: :mfcmd:`module-tag` |
| 15 |
|
| 16 |
- A tag is a piece of information associated to individual modulefiles |
| 17 |
- That is reported along module name on ``avail``, ``spider`` or ``list`` sub-command results |
| 18 |
- This piece of information could lead to specific behaviors when handling modulefile over the different module sub-commands or modulefile evaluation modes |
| 19 |
|
| 20 |
- For instance, a module with a ``sticky`` tag set on it cannot be unloaded |
| 21 |
|
| 22 |
- Tag may also be set manually with the :option:`--tag` sub-command option |
| 23 |
|
| 24 |
- Applies to :subcmd:`load`, :subcmd:`try-load`, :subcmd:`load-any` and :subcmd:`switch` sub-commands |
| 25 |
- When directly used from the terminal session or within modulefile |
| 26 |
- Applies to :mfcmd:`always-load`, :mfcmd:`depends-on`, :mfcmd:`prereq`, :mfcmd:`prereq-all` and :mfcmd:`prereq-any` modulefile commands |
| 27 |
|
| 28 |
- 3 different kind of tag exist: |
| 29 |
|
| 30 |
- Those inherited from module state, consequence of a specific modulefile command or module action |
| 31 |
|
| 32 |
- This kind of tag cannot be defined with the ``module-tag`` command |
| 33 |
|
| 34 |
- An error is returned otherwise |
| 35 |
- Specific modulefile command should be used instead as such tag may have specific properties that should also be defined along |
| 36 |
- Easier for everybody to only have one way to define such tags and not 2 different commands |
| 37 |
|
| 38 |
- Every tag holding specific properties should have its dedicated modulefile command to define it |
| 39 |
|
| 40 |
- Those set with ``module-tag`` or ``--tag`` option that lead to a specific behavior |
| 41 |
- Those set with ``module-tag`` or ``--tag`` option that are purely informational, no specific behavior |
| 42 |
|
| 43 |
- Tags inherited from module state: |
| 44 |
|
| 45 |
- ``hidden``: module not visible, not reported by default in ``avail`` and ``spider`` result (tag acquired through :mfcmd:`module-hide`) |
| 46 |
- ``hidden-loaded``: loaded module not reported by default in ``list`` result (tag acquired through ``module-hide --hidden-loaded`` or ``--tag`` option) |
| 47 |
- ``forbidden``: module that cannot be loaded (tag acquired through :mfcmd:`module-forbid`) |
| 48 |
- ``nearly-forbidden``: module that soon cannot be loaded (tag acquired through ``module-forbid``) |
| 49 |
- ``loaded``: loaded module |
| 50 |
- ``auto-loaded``: module automatically loaded by another module |
| 51 |
- ``warning``: warning message reported on load (tag acquired through ``module-warn``) |
| 52 |
|
| 53 |
- Tags set with ``module-tag`` or ``--tag`` option associated to a specific behavior: |
| 54 |
|
| 55 |
- ``sticky``: loaded module cannot be unloaded unless forced or reloaded or when restoring a collection or initial environment (see :ref:`sticky-modules`) |
| 56 |
- ``super-sticky``: loaded module cannot be unloaded even if forced, it stills can be unloaded if reloaded afterward (see :ref:`sticky-modules`) |
| 57 |
- ``keep-loaded``: auto_handling mechanism does not unload auto-loaded module |
| 58 |
|
| 59 |
- Tags inherited from module state cannot be set with ``module-tag`` command |
| 60 |
|
| 61 |
- An error is otherwise thrown |
| 62 |
|
| 63 |
- Tags inherited from module state cannot be set with ``--tag`` option |
| 64 |
|
| 65 |
- Exception made for ``hidden-loaded`` tag |
| 66 |
- An error is otherwise thrown |
| 67 |
|
| 68 |
- Modules project may introduce in the future new tags inherited from new states or new specific behaviors |
| 69 |
|
| 70 |
- These new tags will supersede tags set by users using the same naming |
| 71 |
|
| 72 |
|
| 73 |
Defining |
| 74 |
^^^^^^^^ |
| 75 |
|
| 76 |
- ``module-tag [options] tag modspec...`` |
| 77 |
|
| 78 |
- Apply ``tag`` to all modules matching ``modspec`` module specification |
| 79 |
- :ref:`advanced-module-version-specifiers` are supported if relative module option is enabled |
| 80 |
- Full path module specification is not supported, as modulerc are not evaluated when reaching a modulefile specified as full path |
| 81 |
- One tag could be applied to multiple module specifications with a single ``module-tag`` command call |
| 82 |
|
| 83 |
- ``module-tag`` accepts the following options: |
| 84 |
|
| 85 |
- ``--not-user``: specify a list of users unaffected by specified tagging |
| 86 |
- ``--not-group``: specify a list of groups whose member are unaffected by specified tagging |
| 87 |
- ``--user``: specify a list of users specifically affected by specified tagging |
| 88 |
- ``--group``: specify a list of groups whose member are specifically affected by specified tagging |
| 89 |
|
| 90 |
- ``--user``, ``--group``, ``--not-user`` and ``--not-group`` specification is only supported on Unix platform |
| 91 |
|
| 92 |
- These options raise an error when used on Windows platform |
| 93 |
- In which case relative ``module-tag`` command is made ineffective as well as remaining content of the modulerc script hosting them |
| 94 |
- Error message is clearly seen when trying to load related modules and indicate where to find the erroneous command |
| 95 |
|
| 96 |
- ``--user`` and ``--group`` options prevail over ``--not-user`` and ``--not-group`` options |
| 97 |
|
| 98 |
- When ``--user`` or ``--group`` is set, exclusion list from ``--not-user`` and ``--not-group`` are ignored |
| 99 |
|
| 100 |
- ``module-tag`` is intended to be used in modulerc files |
| 101 |
|
| 102 |
- to be easily fetched during ``avail`` and ``spider`` sub-commands processing |
| 103 |
- they also need to be enabled in modulefile context as global/user rc files are evaluated as modulefile, not modulerc |
| 104 |
- it enables to dissociate environment changes described in the modulefile from the properties of this modulefile |
| 105 |
|
| 106 |
- as these properties are usually site-specific |
| 107 |
- and modulefile are automatically generated by a build tool |
| 108 |
- but properties are not always related and set by the build tool |
| 109 |
|
| 110 |
- ``module load --tag tag modspec...`` |
| 111 |
|
| 112 |
- Apply ``tag`` to the loading module selected through ``modspec`` module specification |
| 113 |
- Available from all loading module sub-commands (``load``, ``try-load``, ``load-any`` and ``switch``) |
| 114 |
- Option is preferably written: |
| 115 |
|
| 116 |
- ``--tag=tag`` when called from command-line |
| 117 |
- ``--tag tag`` when called from modulefile |
| 118 |
- but both syntaxes work from both locations |
| 119 |
|
| 120 |
- Multiple tags can be set at once by providing a tag list separated by ``:`` |
| 121 |
|
| 122 |
- e.g., ``--tag foo:bar`` or ``--tag=foo:bar`` |
| 123 |
|
| 124 |
|
| 125 |
Persistency |
| 126 |
^^^^^^^^^^^ |
| 127 |
|
| 128 |
- The :envvar:`__MODULES_LMTAG` environment variable holds all tag information applying to loaded modules |
| 129 |
|
| 130 |
- Following the same syntax scheme than ``__MODULES_LMCONFLICT`` |
| 131 |
- For instance ``module/vers&tag&tag:module2&tag`` |
| 132 |
|
| 133 |
- The ``loaded`` tag is not recorded in ``__MODULES_LMTAG`` environment variable |
| 134 |
|
| 135 |
- As it obviously applies to all loaded modules defined in ``LOADEDMODULES`` environment variable |
| 136 |
|
| 137 |
- The ``auto-loaded`` tag is now recorded in ``__MODULES_LMTAG`` environment variable |
| 138 |
|
| 139 |
- Before version 5.0, this tag was not recorded and auto loaded modules where listed in the ``__MODULES_LMNOTUASKED`` environment variable |
| 140 |
- This environment variable has been removed in Modules 5.0 |
| 141 |
|
| 142 |
- Tags applied to loaded modules are saved in collection |
| 143 |
|
| 144 |
- Saving tags in collection is introduced in Modules 5.1 |
| 145 |
- When one or more tags are set on a module to save, the |
| 146 |
``--tag=tag1:tag2`` option is added |
| 147 |
|
| 148 |
- After ``module load`` |
| 149 |
- And before module specification |
| 150 |
|
| 151 |
- When option ``--tag=`` is found on a module to restore |
| 152 |
|
| 153 |
- Defined tags are transmitted to apply them to the module to load |
| 154 |
|
| 155 |
- With this change, the ``--notuasked`` option used in collection |
| 156 |
previously to indicate module has been auto loaded is replaced by |
| 157 |
``--tag=auto-loaded`` option |
| 158 |
|
| 159 |
- No difference is made between tags set manually (through ``--tag`` |
| 160 |
option) or tags set in modulerc (through ``module-tag`` or loaded module |
| 161 |
states): both kind of tags are recorded in collection |
| 162 |
|
| 163 |
- The :mconfig:`collection_pin_tag` configuration option determines what tags |
| 164 |
should be recorded in collection |
| 165 |
|
| 166 |
- When disabled (default), only the tags set through ``--tag`` option or |
| 167 |
resulting from the way the module has been loaded (``auto-loaded`` and |
| 168 |
``keep-loaded`` tags) are recorded in collections |
| 169 |
- When enabled, all tags applying to modules are recorded |
| 170 |
- Exception made for ``nearly-forbidden`` tag, as its temporal meaning |
| 171 |
is not fit for being saved |
| 172 |
- Changing default value of :mconfig:`collection_pin_tag` defines the |
| 173 |
:envvar:`MODULES_COLLECTION_PIN_TAG` variable |
| 174 |
|
| 175 |
- The :envvar:`__MODULES_LMEXTRATAG` environment variable holds all tags |
| 176 |
applying to loaded modules that have been set through the ``--tag`` option |
| 177 |
|
| 178 |
- It helps to distinguish these specifically set tags from the others |
| 179 |
- To only record these tags and those resulting from the way the module |
| 180 |
has been loaded (like ``auto-loaded``) in collections by default |
| 181 |
- The following tags set with ``--tag`` option but which describe a |
| 182 |
specific state of loaded module are excluded from |
| 183 |
``__MODULES_LMEXTRATAG`` record: |
| 184 |
|
| 185 |
- ``auto-loaded`` |
| 186 |
- ``keep-loaded`` |
| 187 |
|
| 188 |
- When a collection saved with ``collection_pin_tag`` option enabled is |
| 189 |
restored all tags set are then considered extra tags (as they are found set |
| 190 |
through the ``--tag`` option). |
| 191 |
|
| 192 |
|
| 193 |
Reporting |
| 194 |
^^^^^^^^^ |
| 195 |
|
| 196 |
- Defined tags are reported on ``avail``, ``spider`` and ``list`` sub-command results |
| 197 |
|
| 198 |
- Reported along modulefile name, within angle brackets (following the HTML tag fashion) |
| 199 |
- Each tag separated by a colon |
| 200 |
- For instance ``module/version <tag1:tag2>`` |
| 201 |
- Tags are right-aligned on each column |
| 202 |
- One space character at least separates module name and version or list of symbolic version from tag list |
| 203 |
|
| 204 |
- Defines tags are reported on module evaluation message block |
| 205 |
|
| 206 |
- Applies to *Loading*, *Unloading*, *Refreshing*, *Tagging* message blocks |
| 207 |
- Only for the module designation set in the header of the block |
| 208 |
|
| 209 |
- Not on the error message, or list of requirement loaded/unloaded |
| 210 |
- To avoid overloading the output |
| 211 |
|
| 212 |
- Tags are reported the same way than on ``list`` sub-command |
| 213 |
- If load evaluation fails, the tags are not reported as they were not yet set |
| 214 |
|
| 215 |
- Tags applying to module alias are reported on ``avail`` and ``spider`` reports only |
| 216 |
|
| 217 |
- Where the module alias stands for itself in the report |
| 218 |
- On ``list`` reports, alias is reported along its modulefile target |
| 219 |
|
| 220 |
- So the tags applying to the alias are not reported |
| 221 |
- Also these tags of the alias are not inherited by alias' target |
| 222 |
|
| 223 |
- Tags applying to symbolic version are never reported |
| 224 |
|
| 225 |
- As symbols are never reported alone on ``avail``, ``spider`` or ``list`` reports |
| 226 |
- Always reported along their modulefile target |
| 227 |
- Also these tags of the symbolic versions are not inherited by symbol's target |
| 228 |
|
| 229 |
- Some tags are not reported on ``avail`` and ``spider`` outputs: |
| 230 |
|
| 231 |
- ``hidden-loaded``: correspond to hiding module from loaded list, not from available list |
| 232 |
|
| 233 |
- Some tags are not reported on ``list`` output: |
| 234 |
|
| 235 |
- ``loaded``: as every modules reported on ``list`` are loaded |
| 236 |
- ``forbidden``: forbidden module cannot be loaded, so it cannot be found among loaded module list |
| 237 |
- ``hidden``: correspond to hiding module from availabilities, not from loaded list |
| 238 |
|
| 239 |
- When reported in JSON output format |
| 240 |
|
| 241 |
- tags are listed under the ``tags`` key |
| 242 |
|
| 243 |
- Default ``--long`` report does not contain tag information |
| 244 |
|
| 245 |
- Not to exceed the 80-column output limit by default |
| 246 |
|
| 247 |
Abbreviations |
| 248 |
""""""""""""" |
| 249 |
|
| 250 |
- Tag abbreviations are used to translate tag names when reporting them on ``avail``, ``spider`` or ``list`` sub-command output |
| 251 |
|
| 252 |
- The :mconfig:`tag_abbrev` configuration defines the abbreviations to apply to each tag |
| 253 |
|
| 254 |
- Set by default at configure time to ``auto-loaded=aL:loaded=L:hidden=H:hidden-loaded=H:forbidden=F:nearly-forbidden=nF:sticky=S:super-sticky=sS:keep-loaded=kL:warning=W`` |
| 255 |
|
| 256 |
- Note that by default, *hidden* and *hidden-loaded* tags share the same abbreviation, as they operate on separate contexts (respectively avail and list contexts) |
| 257 |
|
| 258 |
- Configuration value consists in a ``key=val`` pair value, each key pair are separated by a ``:`` character |
| 259 |
|
| 260 |
- Follow the same syntax than ``colors`` configuration |
| 261 |
|
| 262 |
- If an existing tag name is not part of the configuration, it means no abbreviation applies to it |
| 263 |
|
| 264 |
- If a tag name has an empty string abbreviation defined it is not reported |
| 265 |
|
| 266 |
- Unless if there is an SGR color configuration defined for this tag |
| 267 |
|
| 268 |
- The :envvar:`MODULES_TAG_ABBREV` environment variable is used to set a specific value for ``tag_abbrev`` configuration |
| 269 |
|
| 270 |
- If ``MODULES_TAG_ABBREV`` is set to an empty string, no tag abbreviation applies |
| 271 |
|
| 272 |
- In case default value or environment value of ``tag_abbrev`` is badly set |
| 273 |
|
| 274 |
- a warning message is returned |
| 275 |
- value is ignored |
| 276 |
- if nor the environment nor the default value is correct then no abbreviation applies to tag |
| 277 |
|
| 278 |
- Tags are not translated to their defined abbreviation in JSON output format |
| 279 |
|
| 280 |
SGR |
| 281 |
""" |
| 282 |
|
| 283 |
- If a tag name or tag abbreviation has an SGR code defined in the color list, this SGR code is applied to the module name this tag refer to |
| 284 |
|
| 285 |
- Tag name or abbreviation is not reported by itself in this case |
| 286 |
- As it is now represented by the SGR applied to module name |
| 287 |
- If an abbreviation exists for a tag, SGR code should be defined for this abbreviation in color list |
| 288 |
|
| 289 |
- An SGR code set for tag full name does not apply on the abbreviation of this tag |
| 290 |
|
| 291 |
- If multiple tags apply to the same modules and have an SGR code defined for them in the color list |
| 292 |
|
| 293 |
- All these SGR codes are rendered one after the other over the module name |
| 294 |
- For instance if 2 tags apply, the first one will be rendered over the first half of the module name, the second tag over the second half of |
| 295 |
|
| 296 |
- Tags use by default background color change to stand out |
| 297 |
|
| 298 |
- As module kind (alias, directory, etc) is mainly represented with foreground color change by default, |
| 299 |
|
| 300 |
- In case if there are more tags to graphically render than character in module name |
| 301 |
|
| 302 |
- The remaining tags are reported by there name or abbreviation and SGR applies over this name or abbreviation |
| 303 |
|
| 304 |
- The :envvar:`MODULES_TAG_COLOR_NAME` environment variable is used to define the tags whose name (or abbreviation if set) should be reported |
| 305 |
|
| 306 |
- Their name does not vanish if a SGR code is defined in the color list for them |
| 307 |
- Their SGR code is not rendered over the module name |
| 308 |
- Instead the SGR is applied to the reported tag name (or tag abbreviation if set) |
| 309 |
- ``MODULES_TAG_COLOR_NAME`` is bound to the :mconfig:`tag_color_name` configuration |
| 310 |
- ``MODULES_TAG_COLOR_NAME`` contains the list of tag name (or abbreviation), each tag separated with colon character (``:``) |
| 311 |
- If an abbreviation is defined for a tag and one want it to be reported by itself not rendered over module name |
| 312 |
|
| 313 |
- This abbreviation should be set in ``MODULES_TAG_COLOR_NAME`` |
| 314 |
- Not the full tag name this abbreviation refers to |
| 315 |
|
| 316 |
Querying |
| 317 |
^^^^^^^^ |
| 318 |
|
| 319 |
- The ``tags`` sub-command of :mfcmd:`module-info` modulefile command enables modulefile to know what tags apply to itself |
| 320 |
|
| 321 |
- ``module-info tags`` returns a list of all the tags applying to currently evaluated module |
| 322 |
- an empty list is returned when called from a modulerc evaluation context or if no tag applies to current modulefile |
| 323 |
|
| 324 |
- Tags cannot be queried to select modules |
| 325 |
|
| 326 |
- Symbolic versions or variants can be used to select modules |
| 327 |
|
| 328 |
Updating tags on already loaded modules |
| 329 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 330 |
|
| 331 |
- An attempt to load an already loaded module with a ``--tag`` option set will |
| 332 |
update the list of extra tags set for this loaded module |
| 333 |
|
| 334 |
- Works for every sub-command and modulefile commands accepting the |
| 335 |
``--tag`` option |
| 336 |
- Does not imply the reload of the loaded module |
| 337 |
- Add tags to the tag list already set, no removal |
| 338 |
- As tags defined with ``module-tag`` cannot be unset |
| 339 |
|
| 340 |
- A ``tag`` sub-command may seem useful to update tag list of already loaded |
| 341 |
modules |
| 342 |
|
| 343 |
- But it is simpler to use the loading/enabling sub-command to set these |
| 344 |
extra tags, especially to distinguish between tagging modules or |
| 345 |
modulepaths |
| 346 |
- So no need for a dedicated sub-command, use loading or enabled |
| 347 |
sub-commands instead |
| 348 |
|
| 349 |
- If extra tags specified are already set as non-extra tags on already loaded |
| 350 |
module, the tags are not updated (extra tag list is not updated) |
| 351 |
|
| 352 |
- With ``prereq``-like commands: |
| 353 |
|
| 354 |
- all loaded requirement in specified list get their tag list updated |
| 355 |
- loading requirement does not get its tag list updated (no real use case |
| 356 |
foreseen for cyclic dependencies) |
| 357 |
|
| 358 |
- When restoring collection, extra tags of modules are unset to only keep the |
| 359 |
extra tags defined in collection. |
| 360 |
|
| 361 |
- Extra tags are cleared either when module is unloaded or specifically |
| 362 |
if module is already loaded at the correct position |
| 363 |
|
| 364 |
- When unloading a module, the ``auto-loaded``, ``keep-loaded`` and all |
| 365 |
extra tags are unset from in-memory knowledge, not to reapply automatically |
| 366 |
these tags if the module is loaded again: only the extra and state tags |
| 367 |
from this new load will be set. |
| 368 |
|
| 369 |
Tags set over full path module designation |
| 370 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 371 |
|
| 372 |
Sometimes a tag should be applied on a specific modulefile whose name and |
| 373 |
version is available in several modulepaths. For that need, tag has to be set |
| 374 |
over full path module designation. |
| 375 |
|
| 376 |
Tags set over module full path designation cannot be mixed with tags set over |
| 377 |
regular module name and version as they only apply to the one modulefile in |
| 378 |
one modulepath and not to every module using the same short name and version |
| 379 |
designation. |
| 380 |
|
| 381 |
Forbidden tag set over module full path designation and its properties get |
| 382 |
precedence over same tag's properties set over short module name and version. |
| 383 |
|
| 384 |
It makes code more complex as full path designation has to be passed as |
| 385 |
argument along short name to get all tags applying to module. |
| 386 |
|
| 387 |
When checking tag definition for stickiness, if tag is set over full path |
| 388 |
module then it means stickiness applies to fully qualified module. Thus it |
| 389 |
cannot be swapped by another version of this module. Defining stickiness over |
| 390 |
full path module directory is not possible as full path designation should |
| 391 |
match a modulefile. |
| 392 |
|
| 393 |
.. vim:set tabstop=2 shiftwidth=2 expandtab autoindent: |