Debian Codegraph @

doc/source/design/hide-or-forbid-modulefile.rst

raw
1 .. _hide-or-forbid-modulefile:
2
3 Hide or forbid modulefile
4 =========================
5
6 Configuration
7 -------------
8
9 - No specific configuration
10
11
12 Use cases
13 ---------
14
15 - Restrict usage of particular software to a limited set of user (RestrictUsage)
16
17 - Included in module specification result for a not granted user: no
18 - Visible for a not granted user on a full ``avail`` or ``spider``: no
19 - Visible for a not granted user on a targeted ``avail`` or ``spider``: no
20 - Visible for a not granted user once loaded on a ``list``: yes
21 - Load tentative for a not granted user: error
22
23 - Allow usage of particular software once clearance has been obtained (AllowOnceCleared)
24
25 - Included in module specification result for a not granted user: yes
26 - Visible for a not granted user on a full ``avail`` or ``spider``: yes
27 - Visible for a not granted user on a targeted ``avail`` or ``spider``: yes
28 - Visible for a not granted user once loaded on a ``list``: yes
29 - Load tentative for a not granted user: error
30
31 - Expire a software after a given date (Expire)
32
33 - Included in module specification result for a not granted user: no after expiration date
34 - Visible for a not granted user on a full ``avail`` or ``spider``: no after expiration date
35 - Visible for a not granted user on a targeted ``avail`` or ``spider``: no after expiration date
36 - Visible for a not granted user once loaded on a ``list``: yes, even after expiration date
37 - Load tentative for a not granted user: error after expiration date
38
39 - Disclose a software after a given date (Disclose)
40
41 - Included in module specification result for a not granted user: no prior disclosure date
42 - Visible for a not granted user on a full ``avail`` or ``spider``: no prior disclosure date
43 - Visible for a not granted user on a targeted ``avail`` or ``spider``: no prior disclosure date
44 - Visible for a not granted user once loaded on a ``list``: yes, even prior disclosure date
45 - Load tentative for a not granted user: error prior disclosure date
46
47 - Hide software not of interest for current user (HideNotOfInt)
48
49 - Included in module specification result for a not granted user: yes
50 - Visible for a not granted user on a full ``avail`` or ``spider``: no, unless specific option set
51 - Visible for a not granted user on a targeted ``avail`` or ``spider``: yes
52 - Visible for a not granted user once loaded on a ``list``: yes
53 - Load tentative for a not granted user: success
54
55 - Hide software only useful for other software as dependency (HideDep)
56
57 - Included in module specification result for a not granted user: yes
58 - Visible for a not granted user on a full ``avail`` or ``spider``: no, unless specific option set
59 - Visible for a not granted user on a targeted ``avail`` or ``spider``: yes
60 - Visible for a not granted user once loaded on a ``list``: yes
61 - Load tentative for a not granted user: success
62
63 - Hide dependency software once loaded (HideDepOnceLoaded)
64
65 - Included in module specification result for a not granted user: see HideDep
66 - Visible for a not granted user on a full ``avail`` or ``spider``: see HideDep
67 - Visible for a not granted user on a targeted ``avail`` or ``spider``: see HideDep
68 - Visible for a not granted user once loaded on a ``list``: no, unless specific option set
69 - Load tentative for a not granted user: see HideDep
70
71
72 Specification
73 -------------
74
75 - 2 new modulefile commands are introduced for the needs described above: :mfcmd:`module-hide` and :mfcmd:`module-forbid`
76
77 - ``module-hide`` removes visibility of specified modules
78
79 - ``module-hide`` acts when modules are searched (``avail``, ``spider``, ``whatis`` and ``search`` sub-commands) or selected (``load``, ``unload``, ``display``, etc sub-commands)
80
81 - Visibility is however enabled if hidden module is specifically searched
82
83 - On all context hidden module *mod/1.0* is included in result for instance if *mod/1.0* or *[email protected],2.0* are specified
84 - But hidden module *mod/1.0* is excluded from result if *mod@:2.0* or *mod@1:* are specified
85 - And is also excluded from result if *mod* or *mod/** are specified when *mod/1.0* is set default
86 - Unless if search is made to select one module since in this context a *mod* search query is equivalent to *mod/default*
87 - Hard-hidden modules are not disclosed even if specifically searched
88
89 - Excluded from module resolution result
90
91 - Unless precisely specified on the following selection contexts:
92
93 - :ref:`module_version_specification_to_select_one_module`
94 - :ref:`module_version_specification_to_check_compatibility`
95 - :ref:`module_version_specification_to_return_all_matching_modules`
96
97 - For example, the hidden module *mod/1.0*
98
99 - is included in ``module load mod/1.0`` result
100 - is excluded from ``module load mod/1`` result, even if default symbol targets it
101 - is excluded from ``module load mod`` result, unless if default symbol targets it (as query is equivalent to *mod/default*)
102 - is excluded from ``module load mod@:2`` result, even if default symbol targets it
103 - is included in ``module load [email protected],2.0`` result
104 - is included/excluded the same way for ``prereq`` and ``conflict`` sub-commands than ``load`` sub-command
105 - is matched by ``is-loaded`` and ``info-loaded`` sub-commands querying it once loaded
106 - is excluded from ``module whatis`` result
107 - is included/excluded the same way for ``whatis``, ``spider`` sub-commands than ``avail`` sub-command
108 - is excluded from ``module avail`` result
109 - is excluded from ``module avail m*`` result
110 - is included in ``module avail mod/1.0`` result
111 - is excluded from ``module avail mod/1`` result, even if default symbol targets it
112 - is excluded from ``module avail mod`` result, even if default symbol targets it (as query is NOT equivalent to *mod/default* in this context)
113 - is excluded from ``module avail mod@:2`` result, even if default symbol targets it
114 - is included in ``module avail [email protected],2.0`` result
115
116 - Included in module resolution result if :option:`--all` option of ``avail``, ``whatis``, ``search``, ``aliases`` and ``spider`` sub-commands is set
117
118 - ``--all`` option does not apply to ``is-avail`` sub-command to make it coherent with ``load`` sub-command (e.g., a ``is-avail mod`` returning true implies ``load mod`` effectively loading a module)
119
120 - Visibility of a module targeted by a ``module-hide`` command, with regular hiding level defined, acts similarly than for a file whose name is prefixed by a dot character on Unix platform
121
122 - If ``--soft`` option is set on ``module-hide`` command, module hiding is weakened
123
124 - Module is always included in resolution result for the following contexts
125
126 - :ref:`module_version_specification_to_select_one_module`
127 - :ref:`module_version_specification_to_check_compatibility`
128
129 - For example, the hidden module *mod/1.0*
130
131 - is included in ``module load mod/1.0`` result
132 - is included in ``module load mod/1`` result
133 - is included in ``module load mod`` result
134 - is included in ``module load mod@:2`` result
135 - is included in ``module load [email protected],2.0`` result
136 - is included/excluded the same way for ``prereq`` and ``conflict`` sub-commands than ``load`` sub-command
137 - is matched by ``is-loaded`` and ``info-loaded`` sub-commands querying it once loaded
138 - is excluded from ``module whatis`` result
139 - is included/excluded the same way for ``whatis``, ``spider`` sub-commands than ``avail`` sub-command
140 - is excluded from ``module avail`` result
141 - is excluded from ``module avail m*`` result
142 - is included in ``module avail mod/1.0`` result
143 - is included in ``module avail mod/1`` result
144 - is included in ``module avail mod`` result
145 - is included in ``module avail mod@:2`` result
146 - is included in ``module avail [email protected],2.0`` result
147
148 - If ``--hard`` option is set on ``module-hide`` command, hiding is hardened and designated modules are never unveiled
149
150 - Designated modules are strictly hidden, also referred as *hard-hidden*
151
152 - ``--all`` option of ``avail`` and ``spider`` sub-commands cannot unveil them
153
154 - Excluded from module resolution result, which means it is always excluded from resolution on following context:
155
156 - :ref:`module_version_specification_to_select_one_module`
157 - :ref:`module_version_specification_to_check_compatibility`
158 - :ref:`module_version_specification_to_return_all_matching_modules`
159
160 - For example, the hard-hidden module *mod/1.0*
161
162 - is excluded from ``module load mod/1.0`` result
163 - is excluded from ``module load mod`` result, even if default symbol targets it
164 - is excluded from ``module load mod/1`` result, even if default symbol targets it
165 - is excluded from ``module load mod@:2`` result, even if default symbol targets it
166 - is excluded from ``module load [email protected],2.0`` result
167 - is included/excluded the same way for ``prereq`` and ``conflict`` sub-commands than ``load`` sub-command
168 - is matched by ``is-loaded`` and ``info-loaded`` sub-commands querying it once loaded
169 - is excluded from any ``avail`` query result
170 - is included/excluded the same way for ``whatis``, ``spider`` sub-commands than ``avail`` sub-command
171
172 - Visibility of a module targeted by a ``module-hide --hard`` command acts like if no modulefile exists on filesystem
173
174 - If ``--hidden-loaded`` option is set on ``module-hide``, hiding also applies to specified modules once they are loaded
175
176 - Hidden once loaded modules do not appear on ``module list``
177
178 - Unless ``--all`` option is set on ``list`` sub-command
179
180 - Hidden once loaded modules load, unload or tag is not reported
181
182 - If this evaluation has been triggered automatically
183
184 - By an *automated module handling mechanism* for instance
185 - Which means user has not explicitly asked the module load or unload
186
187 - And was automatically loaded, in case of an automatic unload
188
189 - Which means the automatic unload of an hidden loaded module will be reported if it was manually loaded
190
191 - And if ``verbosity`` level is lower than ``verbose2`` level
192 - And if no issue occurs during hidden module evaluation
193 - Switch of hidden modules is not reported
194
195 - If both switched-off and switched-on modules are set hidden
196 - If switched-off module were automatically loaded
197 - And if the switch evaluation has been automatically triggered
198
199 - When those modules are loaded, a ``hidden-loaded`` tag is applied to them and recorded in :envvar:`__MODULES_LMTAG` environment variable to keep track of their hidden status
200 - Hidden once loaded status does not affect ``is-loaded``: these modules will always be reported if they match ``is-loaded`` queries
201
202 - ``module-forbid`` disallow evaluation of specified modules
203
204 - It does not imply hiding, but can be of course coupled with ``module-hide`` calls
205 - Evaluation of targeted modules is forbidden
206
207 - Error is rendered prior evaluation when trying to *load*, *display*, *help*, *test*, *path*, *whatis* them
208 - Note that for *whatis* evaluation mode, an error is reported only if a module is referred by its exact name which is not the case on ``search`` sub-command as no module is specified, just a keyword to search
209 - No error occurs when unloading a module that were set forbidden after it was loaded by user
210
211 - As it impacts module evaluation, ``module-forbid`` is only effective when it targets modulefiles or virtual modules
212
213 - Module alias or symbolic version are not impacted by ``module-forbid`` directives
214 - Even if they match some ``module-forbid`` statements, they are still resolved to their target and these targets do not inherit the *forbidden* tag set on their alias, symbol.
215 - When a ``module-forbid`` command targets a directory, this directory is still resolved to its target, but the target inherits the *forbidden* tag as it matches the name specified on ``module-forbid`` command
216
217 - When combined with a ``module-hide --hard`` command, designated modules is unveiled if referred by its exact name and set in error
218
219 - Thus an error is obtained when trying to reach module instead of not finding it (which is the regular behavior for hard-hidden modules)
220
221 - ``module-hide`` accepts options that change its behavior:
222
223 - ``--hidden-loaded``: hides module from loaded module list
224 - ``--soft``: lightweight module hide
225 - ``--hard``: highest hiding level
226 - ``--not-user``: specify a list of users unaffected by hide mechanism
227 - ``--not-group``: specify a list of groups whose member are unaffected by hide mechanism
228 - ``--user``: specify a list of users specifically affected by hide mechanism
229 - ``--group``: specify a list of groups whose member are specifically affected by hide mechanism
230 - ``--before``: enables hide mechanism until a given date
231 - ``--after``: enables hide mechanism after a given date
232
233 - ``module-forbid`` accepts options that change its behavior:
234
235 - ``--not-user``: specify a list of users unaffected by forbid mechanism
236 - ``--not-group``: specify a list of groups whose member are unaffected by forbid mechanism
237 - ``--user``: specify a list of users specifically affected by forbid mechanism
238 - ``--group``: specify a list of groups whose member are specifically affected by forbid mechanism
239 - ``--before``: enables forbid mechanism until a given date
240 - ``--after``: enables forbid mechanism after a given date
241 - ``--message``: supplements error message obtained when trying to evaluate a forbidden module with given text message
242 - ``--nearly-message``: supplements warning message obtained when evaluating a nearly forbidden module with given text message
243
244 - Each use case expressed above are covered by following command:
245
246 - RestrictUsage: ``module-hide --hard``
247 - AllowOnceCleared: ``module-forbid``
248 - Expire: ``module-forbid --after`` + ``module-hide --hard --after``
249 - Disclose: ``module-hide --hard --before``
250 - HideNotOfInt: ``module-hide --soft``
251 - HideDep: ``module-hide --soft``
252 - HideDepOnceLoaded: ``module-hide --soft --hidden-loaded``
253
254 - ``module-hide`` and ``module-forbid`` accept the specification of several modules
255
256 - For instance ``module-hide mod1 mod2...``
257 - :ref:`advanced-module-version-specifiers` are supported if relative module option is enabled
258 - Full path specification are not supported, as modulerc are not evaluated when reaching a modulefile specified as full path
259
260 - For instance, ``/path/to/modulefiles/.modulerc`` is not evaluated when loading ``/path/to/modulefiles/mod/1.0``
261 - Thus ``module-hide`` and ``module-forbid`` commands set in this modulerc files are not evaluated
262 - If module is specified as full path, no error is returned, but it will have no effect as demonstrated above
263
264 - Unless on very specific cases, where a global rc file defines these hidden/forbidden commands for the full path modules
265
266 - ``--user``, ``--group``, ``--not-user`` and ``--not-group`` specification is only supported on Unix platform
267
268 - These options raise an error when used on Windows platform
269 - In which case relative ``module-hide`` or ``module-forbid`` command is made ineffective as well as remaining content of the modulerc script hosting them
270 - Error message is clearly seen when trying to load related modules and indicate where to find the erroneous command
271
272 - ``--user`` and ``--group`` options prevail over ``--not-user`` and ``--not-group`` options
273
274 - When ``--user`` or ``--group`` is set, exclusion list from ``--not-user`` and ``--not-group`` are ignored
275
276 - ``--before`` and ``--after`` are also supported by ``module-hide`` to phase-out modules prior to forbid their evaluation
277
278 - ``--before`` and ``--after`` accept a date time as value
279
280 - Accepted date time format is ``YYYY-MM-DD[THH:MM]``
281 - If no time value is specified (just a date like ``2020-08-01``), *00:00* is assumed
282
283 - So ``2020-08-01`` is translated into ``2020-08-01T00:00``
284
285 - An error is raised if submitted date time value does not match accepted date time format
286
287 - if both ``--before`` and ``--after`` options are set and *before* date is greater than *after* date
288
289 - targeted module is always hidden/forbidden
290 - no error is returned
291
292 - ``--before`` and ``--after`` options are not supported on Tcl version below 8.5
293
294 - Prior 8.5, ``clock scan`` command does not have a ``-format`` option
295 - This option is required to support defined date time format
296 - An error is raised when ``--before`` or ``--after`` options are used over a Tcl version below 8.5
297
298 - ``--message`` option adds additional text to the *access denied* error message
299
300 - Newline set in text message are preserved, which could help to control text output format
301 - Message content is set along forbidden module specification
302
303 - Message recorded for matching module specification will be printed
304 - Message recorded on other matching specification will be ignored, only message from retained matching specification is printed
305 - Firstly evaluated ``module-forbid`` command that matches module specification is retained with its message property
306
307 - a module matching a ``module-forbid`` statement whose ``--after`` limit is close is considered *nearly forbidden*
308
309 - ``nearly-forbidden`` tag applies to such module
310 - matched ``module-forbid`` statement should of course not be disabled for current user or group due to ``--not-user`` or ``--not-group`` option values
311 - the *near* range is defined by the :mconfig:`nearly_forbidden_days` configuration, which equals to ``14`` (14 days) by default
312 - this configuration accepts an integer value which represents a number of days prior forbidding starts to be effective for module
313 - ``nearly_forbidden_days`` configuration can be set at configure time with :instopt:`--with-nearly-forbidden-days` option or afterward with the ``config`` sub-command (which sets the :envvar:`MODULES_NEARLY_FORBIDDEN_DAYS` environment variable)
314 - when evaluating a *nearly-forbidden* module, a warning message is reported to indicate that module access will soon be denied
315
316 - ``--nearly-message`` option adds additional text to the *access will be denied* warning message
317
318 - Newline set in text message are preserved, which could help to control text output format
319 - Message content is set along nearly-forbidden module specification
320
321 - Message recorded for matching module specification will be printed
322 - Message recorded on other matching specification will be ignored, only message from retained matching specification is printed
323 - Firstly evaluated ``module-forbid`` command that matches module specification is retained with its message property
324
325 - ``module-hide`` and ``module-forbid`` are intended to be used in modulerc files
326
327 - as they impact modulefile resolution
328 - they also need to be enabled in modulefile context as global/user rc files are evaluated as modulefile, not modulerc
329
330 - several ``module-hide`` calls for the same module will supersede each other
331
332 - definition with the highest hiding level wins
333 - which means the most restrictive call wins
334 - a ``--hidden-loaded`` status set is kept even if corresponding ``module-hide`` call is not the highest one
335 - the multiple definitions can come across different modulerc files (global, modulepath or modulefile rc levels)
336
337 - Module specification passed as argument to ``module-hide`` and ``module-forbid`` are matched exactly against available modules
338
339 - Exception made when *extended_default* or *icase* mechanisms are enabled
340 - Which means wildcard characters like *\** or *?* are treated literally
341
342 - Auto symbols (*@default* and *@latest*) are adapted when a *latest* version is hidden
343
344 - Auto symbols are applied to this version if it is selected specifically (for instance loaded by its full name)
345 - Auto symbols are applied to another version when hidden latest is not selected specifically, even if specified with *@latest* auto symbol
346
347 - Auto-symbols cannot be set hidden
348
349 - When a defined ``default`` or ``latest`` symbol is set hidden, it is replaced by a ``default`` or ``latest`` auto-symbol targeting highest available module version
350 - Targeting an auto-symbol with a ``module-hide`` command, will have no effect
351
352 - When module specification of ``module-hide`` targets:
353
354 - A symbolic version
355
356 - This symbol only is hidden
357 - Modulefile targeted by hidden symbolic version stays visible
358
359 - An alias
360
361 - This alias only is hidden
362 - Modulefile targeted by hidden alias stays visible
363
364 - A modulefile targeted by either symbolic version or alias
365
366 - This modulefile is hidden and all symbolic versions targeting it
367 - Aliases targeting modulefile stays visible (thus resolving alias in *load* or *whatis* contexts make hidden modulefile target visible unless if set hard-hidden)
368
369 - Hidden alias or symbolic version should not appear in the list of alternative names of loaded modules
370
371 - Unless this alias or symbolic version is not hard-hidden and is used to designate the module to load
372 - When ``default`` symbolic version is set hidden
373
374 - also remove parent module name from the list of alternative names
375 - if resolution query corresponds to parent module name, unhide ``default`` symbol unless if hard-hidden
376
377 - On ``avail``/``spider`` sub-commands
378
379 - Hidden symbolic versions are not reported along module they target
380
381 - Unless for non-hard-hidden symbols specifically designated in search query
382
383 - A :option:`--default` filtered search considers search query matches ``default`` symbol
384
385 - So ``default`` symbolic version will appear in result unless if hard-hidden
386
387 - Different hiding level are considered
388
389 - *-1*: module is not hidden
390 - *0*: soft hiding (applied with ``module-hide --soft``)
391 - *1*: regular hiding (applied with dot name module or default ``module-hide`` command)
392 - *2*: hard hiding (applied with ``module-hide --hard``)
393
394 - Hiding threshold
395
396 - is *0* by default, which means module is considered hidden if its hiding level is greater or equal to *0*
397 - is raised to *2* when ``--all`` option is applied, which means module is considered hidden if its hiding level is greater or equal to *2*
398
399 .. vim:set tabstop=2 shiftwidth=2 expandtab autoindent: