Debian Codegraph @

doc/source/design/hook-api.rst

raw
1 .. _hook-api:
2
3 Hook API
4 ========
5
6 It is sometimes desired to execute specific site procedures at the beginning
7 or at the end of a modulefile or modulerc evaluation.
8
9 This is currently possible with either the ``trace`` Tcl command or by
10 superseding one of the internal Tcl procedures (like ``execute-modulefile``),
11 as described in the *Hooks* section of :manpage:`module(1)` man page. Both
12 techniques bind site code to internal implementation details: procedure
13 names and call signatures that may change from one Modules version to the
14 next. Sites relying on them have to re-review this internal code on every
15 upgrade to determine whether their hook code or its connection point still
16 applies.
17
18 This document defines a stable, documented ``add-hook`` API to replace this
19 need for most cases, without removing the lower-level ``trace``/rename
20 techniques, which remain available for anything not covered by a hook
21 event. This first change introduces 4 events; the API is designed so more
22 can be added later without changing how existing ones behave.
23
24 The ``add-hook`` command
25 ------------------------
26
27 A new ``add-hook`` command is introduced, usable from :file:`siteconfig.tcl`
28 (and any script it sources). Like ``trace`` or ``rename``, it is only
29 meaningful in the main Tcl interpreter: :file:`siteconfig.tcl` is sourced
30 once at startup, before any modulefile or modulerc sub-interpreter is
31 created, so hook procedures execute in that same main-interpreter context —
32 exactly like ``trace``-based hooks do today. A hook procedure that needs to
33 act on the modulefile or modulerc currently being evaluated reaches it the
34 same way an existing ``trace``-based hook would: through
35 ``getCurrentModfileInterpName`` and ``interp eval``, as already documented
36 for the current hook technique.
37
38 Syntax::
39
40 add-hook <event> <procedure>
41
42 * ``event`` must be one of the event names defined below. An unknown event
43 name is a configuration mistake, so it raises an error immediately, at the
44 time ``add-hook`` is called — the same treatment already given to other
45 siteconfig configuration mistakes (for instance an odd-length
46 :sitevar:`modulefile_extra_vars` list).
47 * ``procedure`` is the name of a Tcl procedure, defined in
48 :file:`siteconfig.tcl` or a script it sources, that will be called when
49 the event occurs. It is looked up by name at call time, not validated at
50 registration time.
51
52 Several procedures can be registered on the same event. They are called in
53 their registration order. This lets independent site concerns (say,
54 logging and environment tuning) each register their own procedure on the
55 same event rather than being forced to share a single procedure body — a
56 constraint the existing ``ModulesHelp``/``ModulesDisplay``/``ModulesTest``
57 fixed-proc-name convention would have imposed if reused here.
58
59 First hook events and their argument contract
60 ---------------------------------------------
61
62 The first 4 events introduced cover the beginning and the end of
63 modulefile and modulerc evaluation. Each one calls the registered
64 procedure with a fixed, positional argument list — this argument contract
65 *is* the stable API: it is what lets a hook procedure survive a Modules
66 upgrade unchanged.
67
68 ``before-modulefile-eval``
69 Called immediately before a modulefile is evaluated.
70
71 ``proc {modfile modname modnamevr modspec mode requested} {...}``
72
73 ``after-modulefile-eval``
74 Called immediately after a modulefile has been evaluated.
75
76 ``proc {modfile modname modnamevr modspec mode requested status} {...}``
77
78 ``before-modulerc-eval``
79 Called immediately before a modulerc (or ``.version`` file) is evaluated.
80
81 ``proc {modfile modname} {...}``
82
83 ``after-modulerc-eval``
84 Called immediately after a modulerc (or ``.version`` file) has been
85 evaluated.
86
87 ``proc {modfile modname status} {...}``
88
89 Argument meaning, common to these events:
90
91 * ``modfile`` — absolute path of the modulefile or modulerc being evaluated.
92 * ``modname`` — module name and version being evaluated, without its variant
93 specification.
94 * ``modnamevr`` (``*-modulefile-eval`` events only) — module name, version
95 and variant currently resolved for this evaluation. Modulerc evaluation
96 is not tied to one resolved module the way modulefile evaluation is, so
97 this argument is omitted for the two modulerc events, which only get the
98 bare ``modname``.
99 * ``modspec`` (``*-modulefile-eval`` events only) — module specification as
100 it was passed to the internal evaluation call, prior to any resolution:
101 typically what the user typed on the command line (or the raw entry read
102 from a collection or loaded-modules list), which may still differ from
103 ``modnamevr`` (for instance a partial version, or a variant specification
104 merged in as a separate list element). Modulerc evaluation has no
105 equivalent notion, so this argument is also omitted for the two modulerc
106 events.
107 * ``mode`` — current evaluation mode (``load``, ``unload``, ``display``,
108 ``help``, ``test``, ``whatis``, ``refresh``, ``scan`` or ``dep``).
109 Modulerc evaluation is not mode-specific the way modulefile evaluation is,
110 so this argument is omitted for the two modulerc events.
111 * ``requested`` — boolean, true if this module was directly requested by the
112 user, false if it is being evaluated as a side effect (for instance an
113 auto-loaded dependency). Modulerc evaluation has no equivalent notion, so
114 this argument is also omitted for the two modulerc events.
115 * ``status`` (``after-*`` events only) — ``0`` if evaluation succeeded,
116 ``1`` if it raised an error, mirroring the return-code convention already
117 used internally around modulefile/modulerc evaluation.
118
119 The before/after events fire around the actual evaluation step, skipped
120 whenever interpretation itself is skipped (for instance when interpretation
121 is inhibited during a dependency-resolution pass) — so a hook only fires for
122 evaluations that really read and interpret the target file.
123 ``before-modulefile-eval`` and ``before-modulerc-eval`` fire after the
124 target modulefile's or modulerc's dedicated Tcl sub-interpreter has been
125 created and reset to its initial state, so a hook procedure can already
126 reach it (see ``getCurrentModfileInterpName`` in :manpage:`module(1)` man
127 page) to run modulefile commands there.
128
129 These hooks are informational for this first iteration: the value a hook
130 procedure returns is ignored, and it cannot cancel or otherwise alter the
131 evaluation it wraps — unlike :mfcmd:`module-forbid` or :mfcmd:`module-warn`,
132 which are dedicated mechanisms for that purpose. See `Open questions and
133 future work`_ below.
134
135 Error handling
136 --------------
137
138 If a hook procedure raises a Tcl error, that error is caught and reported,
139 but does not abort the ``module`` command being run. In particular:
140
141 * when several procedures are registered on the same event, one procedure
142 raising an error does not prevent the other procedures registered on that
143 event from running: each remaining procedure in the list is still called,
144 in its registration order;
145 * the modulefile or modulerc evaluation being wrapped by the hook still
146 proceeds normally.
147
148 This differs from how a load-time error in :file:`siteconfig.tcl` itself is
149 handled today (which is fatal). The distinction is deliberate: a
150 ``before-``/``after-*-eval`` hook fires on essentially every modulefile or
151 modulerc evaluation, so letting a single buggy hook procedure abort every
152 ``module`` invocation site-wide would be far more disruptive than letting a
153 malformed :file:`siteconfig.tcl` fail once, loudly, at startup.
154
155 Relation to existing trace/rename-based hooks
156 ---------------------------------------------
157
158 The ``trace``/rename techniques described in :manpage:`module(1)` man page
159 keep working unchanged — nothing is removed. The *Hooks* section of that man
160 page is restructured to present ``add-hook`` as the primary, recommended
161 mechanism for the events it supports, and the ``trace``/rename techniques
162 as an advanced, lower-level fallback for connection points ``add-hook``
163 does not (yet) cover.
164
165 Documentation
166 -------------
167
168 Hook events are documented with a new Sphinx object type, ``mhook``
169 (``.. mhook::``/``:mhook:``), defined the same way existing ``mfcmd``,
170 ``mfvar`` and ``sitevar`` object types are in ``doc/source/conf.py``. A
171 distinct name from the generic "hook" is used to avoid ambiguity with the
172 other unrelated uses of that word already in the docs (git commit hooks in
173 ``CONTRIBUTING.rst``, and the existing ``trace``-based hook technique
174 described in ``module.rst``).
175
176 Touch points for implementation
177 -------------------------------
178
179 This section lists the files a future implementation is expected to touch;
180 it is not itself an implementation plan.
181
182 * ``tcl/interp.tcl.in`` — hook registry (populated by ``add-hook``), a small
183 dispatch helper, and the four call sites added around the existing
184 ``evaluateModulefile``/``evaluateModulerc`` calls inside
185 ``execute-modulefile``/``execute-modulerc``.
186 * ``siteconfig.tcl`` (root template, and its installed copy) — a new
187 commented example of how to register a hook with ``add-hook``, pointing
188 at :manpage:`module(1)` man page for the current list of events, next to
189 the existing commented-out
190 :sitevar:`modulefile_extra_vars`/:sitevar:`modulefile_extra_cmds`/
191 :sitevar:`modulerc_extra_vars`/:sitevar:`modulerc_extra_cmds` examples.
192 * ``doc/source/conf.py`` — register the new ``mhook`` object type.
193 * ``doc/source/module.rst`` — restructure the *Hooks* section: document
194 ``add-hook`` and the four ``mhook`` entries, demote the ``trace``/rename
195 description to the advanced fallback case.
196 * ``doc/source/changes.rst`` and ``NEWS.rst`` — new entry under the
197 in-development ``Modules 5.7.0`` section (appended at the end of its
198 bullet list, per project convention).
199 * Nagelfar syntax db (``share/``) — check whether ``make testlint`` requires
200 it to be regenerated for the new ``add-hook`` command to lint cleanly in
201 :file:`siteconfig.tcl` examples.
202 * Testsuite — a new, dedicated ``.exp`` file (kept separate from
203 ``testsuite/modules.50-cmds/560-siteconfig-interp.exp``, which already
204 covers the older extra_vars/extra_cmds mechanism), with a matching new
205 ``testsuite/example/siteconfig.tcl-N`` fixture, following the existing
206 naming and numbering pattern in that directory.
207
208 Open questions and future work
209 ------------------------------
210
211 * A ``remove-hook`` command, and/or a way to introspect which procedures are
212 currently registered on a given event, is not part of this first pass.
213 The registry design should not preclude adding one later.
214 * Future hook events (for instance around module load/unload completion, or
215 collection save/restore) will be exposed through this same ``add-hook``
216 mechanism, once real use cases for them emerge.
217 * Future hook events may be designed to influence the evaluation they wrap --
218 altering argument values, changing the execution flow, or raising an error
219 that aborts it -- but only where the event is purposely built for that and
220 the calling code is written to expect it, unlike the events introduced
221 here.
222
223 .. vim:set tabstop=2 shiftwidth=2 expandtab autoindent: