Debian Codegraph @

doc/source/design/module-tags.rst

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