Debian Codegraph @

doc/source/design/evaluation-errors.rst

raw
1 .. _evaluation-errors:
2
3 Evaluation errors
4 =================
5
6 This document describes the different evaluation errors, depending on the
7 evaluation modes. The obtained behaviors when these errors raise and the
8 configuration options or command-line switches that change these behaviors.
9
10 Error kinds
11 -----------
12
13 The following list describes the different kind of evaluation error:
14
15 * *bad code*: modulefile has some code error (e.g., bad Tcl syntax, using
16 undefined commands)
17 * *break*: use of ``break`` Tcl command in modulefile
18 * *exit*: use of ``exit`` Tcl command in modulefile
19 * *error*: use of ``error`` Tcl command in modulefile
20 * *not found*: designated modulefile cannot be found
21 * *hard hidden*: designated modulefile is hidden in ``--hard`` mode and cannot
22 be found
23 * *not loaded*: when unloading a module, designated modulefile is not found
24 loaded
25 * *already loaded*: when loading a module, designated modulefile is already
26 loaded
27 * *conflict*: dependency issue where loading modulefile conflicts with at
28 least one loaded module
29 * *missing requirement*: dependency issue where a loading modulefile has at
30 least one requirement module not loaded
31 * *dependent reload*: dependency issue where a loading or unloading modulefile
32 has at least one dependent module that fails to reload (either during the
33 unload or load phase)
34 * *unloading dependent*: dependency issue where an unloading modulefile has at
35 least one loaded module requiring it
36 * *forbidden*: evaluated modulefile is tagged forbidden
37 * *sticky unload*: when unloading a module tagged sticky
38 * *super-sticky unload*: when unloading a module tagged super-sticky
39 * *dependent sticky reload*: *dependent reload* special case where a sticky
40 dependent module fails to reload (during the load phase)
41 * *dependent super-sticky reload*: *dependent reload* special case where a
42 super-sticky dependent module fails to reload (during the load phase)
43
44 .. note:: Use of ``continue`` Tcl command in modulefile shortens evaluation
45 but it is not considered an error.
46
47 .. note:: When a *dependent reload* issue occurs during the load or unload of
48 a modulefile, the dependent module failing to reload has raised one of the
49 following error kind: bad code, break, exit, error, conflict, missing
50 requirement, forbidden or hard hidden.
51
52 Behavior when error raises
53 --------------------------
54
55 This section describes the behaviors generally obtained when the different
56 error kinds raise.
57
58 Other specific behavior depending on evaluation mode or configuration options
59 are described in the following parts of the document.
60
61 .. _default:
62
63 Default
64 ^^^^^^^
65
66 Default behavior when an error raises:
67
68 * current modulefile evaluation is aborted
69 * an error message is reported
70 * exit code is set to 1
71
72 Ignored errors
73 ^^^^^^^^^^^^^^
74
75 The following error kinds are *ignored errors*:
76
77 * not loaded
78 * already loaded
79
80 These errors lead to a different behavior:
81
82 * current modulefile evaluation is skipped
83 * no message reported
84 * no error exit code set
85
86 Errors raised during modulefile evaluation
87 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
88
89 Following errors are raised during the Tcl evaluation of a modulefile:
90
91 * bad code
92 * break
93 * exit
94 * error
95 * conflict (also raised outside modulefile evaluation)
96 * missing requirement
97
98 Evaluation mode or options specific behaviors
99 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
100
101 Some error kinds only occur during specific evaluation mode or when
102 configuration options are set to a given value.
103
104 +---------------------+------------+-------------------------------+
105 | Error kind | Evaluation | Configuration option |
106 | | mode | |
107 +=====================+============+===============================+
108 | conflict | load | |
109 +---------------------+------------+-------------------------------+
110 | missing requirement | load | |
111 +---------------------+------------+-------------------------------+
112 | dependent reload | load, | |
113 | | unload | |
114 +---------------------+------------+-------------------------------+
115 | unloading dependent | unload | when :mconfig:`auto_handling` |
116 | | | is disabled |
117 +---------------------+------------+-------------------------------+
118 | forbidden | load | |
119 +---------------------+------------+-------------------------------+
120 | hard hidden | load | |
121 +---------------------+------------+-------------------------------+
122 | already loaded | load | |
123 +---------------------+------------+-------------------------------+
124 | not loaded | unload | |
125 +---------------------+------------+-------------------------------+
126 | sticky unload | unload | |
127 +---------------------+------------+-------------------------------+
128 | super-sticky unload | unload | |
129 +---------------------+------------+-------------------------------+
130 | dependent sticky | load | |
131 | reload | | |
132 +---------------------+------------+-------------------------------+
133 | dependent | load | |
134 | super-sticky reload | | |
135 +---------------------+------------+-------------------------------+
136
137 When evaluation mode and/or configuration option matches for these error kinds
138 to raise, a :ref:`default error behavior<default>` error behavior is applied.
139
140 Load sub-command
141 ----------------
142
143 Specific error behavior for modulefile load evaluation by :subcmd:`load`
144 sub-command.
145
146 Force mode
147 ^^^^^^^^^^
148
149 When :option:`--force` command-line switch is used, load evaluation by-pass
150 following errors:
151
152 * conflict
153 * missing requirement
154 * dependent reload
155 * dependent sticky reload
156
157 Following behavior is observed:
158
159 * evaluation continues (error is by-passed)
160 * warning message reported (instead of an error message)
161 * no error exit code set
162
163 .. warning:: *Missing requirement* and *dependent reload* errors currently
164 returns an error exit code. This behavior might be aligned with the above
165 one in the future. Or the above behavior may be adapted the other way
166 around.
167
168 No effect on other error kinds as it is not useful to mark loaded a broken or
169 nonexistent modulefile.
170
171 ``abort_on_error`` configuration option is ignored when ``--force`` option is
172 in use. Which means *continue on error* behavior is applied.
173
174 *Abort on error* behavior is applied whatever the value of
175 :mconfig:`abort_on_error` if following kind of error occurs:
176
177 * dependent sticky reload and force mode is disabled.
178 * dependent super-sticky reload
179
180 Multiple modulefiles passed as argument
181 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
182
183 When multiple modulefiles are passed to the ``load`` sub-command for
184 evaluation. If the evaluation of one modulefile raises an error, behavior for
185 this error is applied and if:
186
187 * :mconfig:`abort_on_error` configuration option does not contain ``load`` or
188 ``--force`` is set:
189
190 * already evaluated modulefiles from the argument list are kept loaded
191 * in case of an *exit* error, evaluation stops
192 * for other kind of error, evaluation continues with next modulefile in
193 argument list
194
195 * :mconfig:`abort_on_error` configuration option contains ``load`` and
196 ``--force`` is not set:
197
198 * already evaluated modulefiles from the argument list are withdrawn (they
199 will not appear loaded and their environment changes are flushed)
200 * evaluation stops
201
202 The above description only applies to ``load`` sub-command executed from the
203 top level context and not from a modulefile evaluation. Multiple arguments on
204 a ``module load`` command in modulefile are evaluated independently as an
205 *AND* requirement list.
206
207 .. warning:: :command:`ml` command applies the ``abort_on_error`` behavior by
208 default, whatever behavior is configured for ``load``. Default behavior for
209 ``load`` may be changed in next major version to align ``ml`` command
210 behavior.
211
212 Load-any sub-command
213 --------------------
214
215 Specific error behavior for modulefile load evaluation by :subcmd:`load-any`
216 sub-command.
217
218 Following errors are ignored:
219
220 * not found
221 * forbidden
222 * hard hidden
223
224 However if no module is loaded after evaluating all ``load-any`` modulefile
225 arguments:
226
227 * an error message is reported
228 * an error exit code is set
229
230 For other kind of error, relative error message is reported and error exit
231 code is set. Even if a module is loaded after evaluating all modulefile
232 arguments.
233
234 Force mode
235 ^^^^^^^^^^
236
237 Same force behavior observed than for `Load sub-command`_.
238
239 Multiple modulefiles passed as argument
240 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
241
242 :subcmd:`load-any` stops evaluation process as soon as a modulefile argument
243 is successfully loaded.
244
245 ``load-any`` is not a valid value element for :mconfig:`abort_on_error`
246 configuration option.
247
248 *exit* error stops evaluation of remaining modulefiles in the argument list.
249
250 When ``module load-any`` is evaluated as a modulefile command:
251
252 * if one modulefile in the list is loaded
253
254 * no error message is reported whatever the error kind
255
256 * if no modulefile in the list is loaded
257
258 * an error message is reported for errors other than *not found*,
259 *forbidden* and *hard hidden*
260 * modulefile declaring the ``module load-any`` command raises a *missing
261 requirement* error
262
263 .. warning:: An error message may also be reported for *not found*,
264 *forbidden* and *hard hidden* error in the future when no modulefile in the
265 list is loaded.
266
267 .. warning:: Error messages may be transformed into warnings and exit code may
268 be untouched in the future if one modulefile in the list is loaded.
269
270 Try-load sub-command
271 --------------------
272
273 Specific error behavior for modulefile load evaluation by :subcmd:`try-load`
274 sub-command.
275
276 Following errors are ignored:
277
278 * not found
279 * forbidden
280 * hard hidden
281
282 Even if no module is loaded after evaluating all ``try-load`` modulefile
283 arguments.
284
285 Force mode
286 ^^^^^^^^^^
287
288 Same force behavior observed than for `Load sub-command`_.
289
290 Multiple modulefiles passed as argument
291 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
292
293 Same multiple modulefile arguments behavior is observed than for `Load
294 sub-command`_.
295
296 Except *not found*, *forbidden* and *hard hidden* errors are ignored even if
297 :mconfig:`abort_on_error` configuration option contains ``try-load``.
298
299 Mod-to-sh sub-command
300 ---------------------
301
302 Specific error behavior for modulefile load evaluation by :subcmd:`mod-to-sh`
303 sub-command.
304
305 Same behavior is observed than for `Load sub-command`_.
306
307 Reload sub-command
308 ------------------
309
310 Specific error behavior for modulefile load evaluation by :subcmd:`reload`
311 sub-command.
312
313 In case of any error (either during unload or load phase) evaluation stops and
314 environment changes of already unloaded/loaded modules are flushed. Unless if
315 force mode is enabled or if reload is removed from :mconfig:`abort_on_error`
316 configuration option (where it is enabled by default). In this case, a
317 *continue on error* behavior is applied.
318
319 *Abort on error* behavior is applied whatever the value of
320 :mconfig:`abort_on_error` if:
321
322 * a sticky module is not able to reload and force mode is disabled.
323 * a super-sticky module is not able to reload
324
325 Prior running evaluations, dependencies of loaded modules are checked. If at
326 least one dependency (requirement or conflict) is not satisfied, an error is
327 raised.
328
329 Purge sub-command
330 ------------------
331
332 Specific error behavior for modulefile load evaluation by :subcmd:`purge`
333 sub-command.
334
335 In case of error, *continue on error* behavior is applied. If purge is added
336 in the value list of :mconfig:`abort_on_error` configuration option and if
337 force mode is not set, *abort on error* behavior applies.
338
339 Unload sub-command
340 ------------------
341
342 Specific error behavior for modulefile unload evaluation by :subcmd:`unload`
343 sub-command.
344
345 Force mode
346 ^^^^^^^^^^
347
348 When :option:`--force` command-line switch is used, unload evaluation by-pass
349 following errors:
350
351 * bad code
352 * break
353 * exit
354 * error
355 * dependent reload
356 * unloading dependent
357 * sticky unload
358 * dependent sticky reload
359
360 Following behavior is observed:
361
362 * evaluation continues (error is by-passed)
363 * warning message reported (instead of an error message)
364 * no error exit code set
365
366 When facing an erroneous modulefile, it seems useful to be able to get rid of
367 it from user's loaded environment.
368
369 ``abort_on_error`` configuration option is ignored when ``--force`` option is
370 in use. Which means *continue on error* behavior is applied.
371
372 *Abort on error* behavior is applied whatever the value of
373 :mconfig:`abort_on_error` if following kind of error occurs:
374
375 * dependent sticky reload and force mode is disabled.
376 * dependent super-sticky reload
377
378 Multiple modulefiles passed as argument
379 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
380
381 When multiple modulefiles are passed to the ``unload`` sub-command for
382 evaluation. If the evaluation of one modulefile raises an error, behavior for
383 this error is applied and if:
384
385 * :mconfig:`abort_on_error` configuration option does not contain ``unload``
386 or ``--force`` is set:
387
388 * already evaluated modulefiles from the argument list are kept unloaded
389 * for other kind of error, evaluation continues with next modulefile in
390 argument list
391
392 * :mconfig:`abort_on_error` configuration option contains ``load`` and
393 ``--force`` is not set:
394
395 * already evaluated modulefiles from the argument list are withdrawn (they
396 will appear loaded again and their environment changes are untouched)
397 * evaluation stops
398
399 The above description only applies to ``unload`` sub-command executed from the
400 top level context and not from a modulefile evaluation. Multiple arguments on
401 a ``module unload`` command in modulefile are evaluated independently as an
402 *AND* conflict list.
403
404 .. warning:: :command:`ml` command applies an abort behavior when facing an
405 error. Evaluation stops and already unloaded modulefiles are restored in
406 loaded environment. It may be changed in the next major version to align
407 unload phase of ``ml`` command on ``unload`` sub-command behavior.
408
409 .. note:: *exit* error does not lead to an evaluation inhibit of remaining
410 modulefiles when evaluation is made in unload mode. Unless if an exit error
411 was previously raised in a load evaluation mode prior an unload phase.
412
413 .. vim:set tabstop=2 shiftwidth=2 expandtab autoindent: