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