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