[Modules] Hook API

[Xavier D. v. lists.hpsf.i. <xav...@li...>]

Hi all,

With the upcoming Modules 5.7 release, sites will get a new, stable way to
run their own code around modulefile and modulerc evaluation, without
having to reach into modulecmd.tcl internals.

Until now, running site-specific code before or after an evaluation meant
either using the Tcl trace command on an internal procedure like
execute-modulefile, or renaming and wrapping an internal procedure
outright. Both techniques work, but they bind site configuration to
implementation details that can change from one Modules version to the next
— meaning sites relying on them have had to re-check their siteconfig
against the internal code on every upgrade.

5.7 will introduce a new add-hook <event> <procedure> siteconfig command
instead. It lets you register one or more procedures on a fixed, documented
set of events, each with a stable, versioned argument contract:
  - before-modulefile-eval / after-modulefile-eval
  - before-modulerc-eval / after-modulerc-eval

Multiple procedures can be registered on the same event and will run in
registration order. A hook procedure that raises an error gets reported,
but won't abort the running module command or block the other procedures
registered on that event — these hooks fire on nearly every invocation, so
a mistake in one shouldn't lock out the tool site-wide.

The existing trace/rename techniques aren't going away — they remain
available as a lower-level fallback for anything not (yet) covered by a
hook event, and we expect to add further events over time as real use cases
come up.

A couple of things worth looking at once 5.7 is out:

  - The Hooks section of the module(1) man page documents add-hook and all
four events, with examples.
  - The MIGRATING guide has a short write-up of the feature:
https://modules.readthedocs.io/en/latest/MIGRATING.html#hook-api
  - A new cookbook recipe shows a realistic use case: syncing an
application directory from a network share to local disk on a module's
first load, using a before-modulefile-eval hook:
https://modules.readthedocs.io/en/latest/cookbook/sync-remote-appdir.html
  - If you'd like to contribute a new hook event yourself, there's now a
dedicated contributor guide walking through what needs to change (core
code, docs, testsuite):
https://modules.readthedocs.io/en/latest/devel/add-new-hook-event.html

As always, feedback and questions are welcome here on the list.

Cheers,
Xavier


-=-=-=-=-=-=-=-=-=-=-=-
Links: You receive all messages sent to this group.
View/Reply Online (#45): https://lists.hpsf.io/g/modules-interest/message/45
Mute This Topic: https://lists.hpsf.io/mt/120640069/10150481
Group Owner: mod...@li...
Unsubscribe: https://lists.hpsf.io/g/modules-interest/unsub [mod...@li...]
-=-=-=-=-=-=-=-=-=-=-=-