Debian Codegraph @

doc/source/devel/add-new-hook-event.rst

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