| 1 |
.. _add-new-hook-event: |
| 2 |
|
| 3 |
Add new hook event |
| 4 |
================== |
| 5 |
|
| 6 |
This document is a guide for Modules developers that wish to introduce a new |
| 7 |
hook event for the ``add-hook`` siteconfig command. See the :ref:`hook-api` |
| 8 |
design notes for the rationale behind this mechanism, and the *Hooks* |
| 9 |
section of :manpage:`module(1)` man page for the events already available. |
| 10 |
|
| 11 |
Core code |
| 12 |
--------- |
| 13 |
|
| 14 |
A hook event is a name registered in ``g_hookEvents``, plus a ``runHooks`` |
| 15 |
call placed at the exact point in the internal code where site procedures |
| 16 |
registered on that event should run. |
| 17 |
|
| 18 |
#. Declare the new event name in the ``g_hookEvents`` list. |
| 19 |
|
| 20 |
- File to edit: :file:`tcl/init.tcl.in` |
| 21 |
|
| 22 |
Event names are lower-case, dash-separated, and usually paired as |
| 23 |
``before-<something>``/``after-<something>`` when they bracket an |
| 24 |
operation, following the existing ``before-modulefile-eval``/ |
| 25 |
``after-modulefile-eval`` and ``before-modulerc-eval``/ |
| 26 |
``after-modulerc-eval`` events. |
| 27 |
|
| 28 |
#. Add a ``runHooks <event-name> <arg> ...`` call at the point in the |
| 29 |
internal code where the event should fire. |
| 30 |
|
| 31 |
- File to edit: depends on the touch point the event relates to. The |
| 32 |
four existing events all fire from :file:`tcl/interp.tcl.in`, around |
| 33 |
the ``evaluateModulefile``/``evaluateModulerc`` calls inside |
| 34 |
``execute-modulefile``/``execute-modulerc``. A hook event covering a |
| 35 |
different touch point (for instance module load/unload completion, or |
| 36 |
collection save/restore, both mentioned as future candidates in the |
| 37 |
:ref:`hook-api` design notes) would instead be added next to the |
| 38 |
internal code implementing that operation. |
| 39 |
|
| 40 |
Decide on a fixed, positional argument list for the event: this argument |
| 41 |
contract *is* the stable API a hook procedure relies on, so it should be |
| 42 |
descriptive enough on its own (an absolute file path rather than a |
| 43 |
relative one, a resolved value rather than an internal handle, etc.) and |
| 44 |
should not change once released. Look at the argument list of the |
| 45 |
existing events for the kind of information usually passed: paths, |
| 46 |
resolved names, current mode, and a trailing ``status`` argument on |
| 47 |
``after-*`` events reporting whether the wrapped operation succeeded. |
| 48 |
|
| 49 |
``runHooks`` catches an error raised by a hook procedure, reports it, and |
| 50 |
keeps going: neither the other procedures registered on the same event |
| 51 |
nor the operation the hook wraps are interrupted. This is the right |
| 52 |
default for an event that is purely informational, like the four |
| 53 |
existing ones, since a buggy hook procedure must not be able to lock |
| 54 |
site-wide command usage. If the new event is deliberately designed to let |
| 55 |
a hook procedure influence the operation it wraps -- aborting it, or |
| 56 |
altering a value used afterward -- that is a different contract that |
| 57 |
``runHooks`` does not provide as-is; the call site needs its own code to |
| 58 |
read back a value or catch a raised error and act on it, and this |
| 59 |
divergence from the informational-only default should be spelled out |
| 60 |
clearly in the event's documentation. |
| 61 |
|
| 62 |
Documentation |
| 63 |
------------- |
| 64 |
|
| 65 |
Man page and other user documentation have to be updated to describe the |
| 66 |
introduced event. |
| 67 |
|
| 68 |
Files that should be edited: |
| 69 |
|
| 70 |
- :file:`doc/source/module.rst` (module manpage) |
| 71 |
|
| 72 |
- add event description with ``mhook`` anchor under the *Hooks* |
| 73 |
subsection, following the pattern of the existing four events: argument |
| 74 |
list in the directive signature, prose describing each argument, and a |
| 75 |
note on whether the value a registered procedure returns is used or |
| 76 |
ignored |
| 77 |
|
| 78 |
- :file:`doc/source/changes.rst` |
| 79 |
|
| 80 |
- add the event to the table under the *Siteconfig hooks* subsection of |
| 81 |
the current Modules major version, next to the version it is introduced |
| 82 |
in |
| 83 |
|
| 84 |
- :file:`NEWS.rst` |
| 85 |
|
| 86 |
- add an entry under the in-development version's bullet list, at the end |
| 87 |
of it |
| 88 |
|
| 89 |
- :file:`MIGRATING.rst` |
| 90 |
|
| 91 |
- the *Hook API* entry already announces that more hook events will be |
| 92 |
added over time, so a single new event usually does not need its own |
| 93 |
highlight there; consider adding or extending an entry if the new event |
| 94 |
opens up a use case significant enough to be worth a dedicated |
| 95 |
highlight (a new category of touch point, for instance, rather than |
| 96 |
another modulefile/modulerc-evaluation event) |
| 97 |
|
| 98 |
- :file:`doc/source/design/hook-api.rst` |
| 99 |
|
| 100 |
- a new event covering the same kind of touch point as the existing ones |
| 101 |
(modulefile/modulerc evaluation) can usually just be documented in |
| 102 |
:file:`module.rst` as above; a new event opening up a different touch |
| 103 |
point (see the *Open questions and future work* section of this design |
| 104 |
document) is significant enough to warrant its own design notes first, |
| 105 |
following this document as a template |
| 106 |
|
| 107 |
Testsuite |
| 108 |
--------- |
| 109 |
|
| 110 |
Non-regression testsuite must be adapted to check the behavior of the added |
| 111 |
event and ensure overall code coverage does not drop. |
| 112 |
|
| 113 |
#. Register a procedure on the new event, following the existing |
| 114 |
``switch --`` cases already used to select which hook scenario a test |
| 115 |
run exercises. |
| 116 |
|
| 117 |
- File to edit: :file:`testsuite/example/siteconfig.tcl-1` |
| 118 |
|
| 119 |
#. Craft tests that validate the event fires at the right point with the |
| 120 |
correct arguments, on both a successful and a failing operation if |
| 121 |
applicable. |
| 122 |
|
| 123 |
- File to edit: :file:`testsuite/modules.50-cmds/740-hook.exp` if the |
| 124 |
new event relates to modulefile/modulerc evaluation like the existing |
| 125 |
ones, a new dedicated ``.exp`` file otherwise, following the existing |
| 126 |
naming and numbering pattern of the directory the new touch point |
| 127 |
belongs to |
| 128 |
|
| 129 |
The generic ``add-hook`` behaviors (unknown event name, several |
| 130 |
procedures registered on the same event, a hook procedure error not |
| 131 |
interrupting the wrapped operation, wrong argument count) are already |
| 132 |
covered for the existing events and do not need to be duplicated; focus |
| 133 |
new tests on what is specific to the new event: its firing point and its |
| 134 |
argument values. |
| 135 |
|
| 136 |
.. vim:set tabstop=2 shiftwidth=2 expandtab autoindent: |