docs/reference/hooks-conf-example.btft

[table class="topnav"]
[tr]
[td class="logotab"]mp[e]
[td][see name="index"]index[e][e]
[td][see name="guide/index"]guide[e][e]
[td][see name="reference/index"]reference[e][e]
[e]
[e]
 
[h1]hooks.conf.example[e]
 
[quote class="note"]
generated from hooks.conf.example -- do not edit this page directly, edit that file and regenerate ("mk . d" / "sh mk/d.sh") instead. see [see name="reference/config"]reference/config[e] for the narrative tour this page doesn't replace.
[e]
 
hooks.conf -- an OPTIONAL, per-phase file for advanced hook management. lives at HOOKS_DIR/<phase>/hooks.conf (HOOKS_DIR defaults to $WD/hooks, e.g. /usr/mp/hooks -- see mp.conf.example, this file's sibling, for the whole hook system this builds on, and its own patches.conf.example for the closely-related grammar for patches instead of hooks). nothing here is required: a HOOKS_DIR/<phase>/ directory with no hooks.conf just runs every executable file in it, in filename order -- exactly as before this file existed. hooks.conf only ADDS conditions and reordering on top of that, for the hooks that actually need them.
 
a hook is named by its plain filename under HOOKS_DIR/<phase>/ (not a path -- unlike patches.conf, there's no subdirectory convention here):
 
[code]
  HOOKS_DIR/post_install/10-logger
  HOOKS_DIR/post_install/20-notify
[e]
 
same "<name>:" section grammar as mp.conf/patches.conf -- an indented key under a hook's own header applies to just that one hook file:
 
[code]
  HOOKS_DIR/post_install/hooks.conf:
      20-notify:
          AFTER=10-logger
      30-extra-check:
          IF_USE=debug
[e]
 
[code]
IF_USE=<flag> <flag> ...
  the current package's USE flag(s) gate whether this hook file runs
  at all (same enabled_use() as everywhere else -- for a canon-less
  hook like pre_sync/post_sync, which has no one package, this checks
  the global USE= instead). a leading '!' requires the flag's ABSENCE:
    IF_USE=debug               only runs if USE=debug is enabled
    IF_USE=!minimal            only runs if USE=minimal is NOT enabled
[e]
 
[code]
AFTER=<hookfile> <hookfile> ...
  ordering prerequisite(s) among the hook files actually running in
  this phase, topologically sorted. filename order is still the
  default/tiebreak for anything with no AFTER (and the whole
  directory's default when there's no hooks.conf at all):
    30-final:
        AFTER=10-logger 20-notify
  an AFTER edge to a hook IF_USE filtered out (or that isn't in this
  phase's directory at all) is silently ignored -- AFTER only orders
  among what's actually running. a genuine ordering cycle is a hard
  error, not a hang or a silently-wrong order.
[e]
 
which phase directories exist: every built-in pre_/post_&lt;phase&gt; pair (pre_fetch, post_fetch, pre_patch, post_patch, pre_build, post_build, pre_check, post_check -- RUN_TESTS=yes only --, pre_install, post_install, pre_remove, post_remove, pre_sync, post_sync), plus on_fail (fires, best-effort, when an install is rejected for a file conflict), plus any CUSTOM name a port author's phase script fires via $MP_HOOK (exported to every phase script):
 
[code]
  # from a port's build: phase --
  $MP_HOOK post-configure
[e]
 
reuses this exact same hooks.conf pipeline: HOOKS_DIR/post-configure/* and HOOKS_DIR/post-configure/hooks.conf work identically to any built-in phase's. the one thing $MP_HOOK refuses is a name that collides with a real built-in lifecycle phase (pre_install, on_fail, etc.) -- that's almost always a typo, not something a port author actually wants, since it would silently re-fire that hook a second time mid-build instead of running your own custom one.
 
a sysroot-scoped package (SYSROOT=&lt;name&gt; in mp.conf) gets its own, fully independent hooks tree at $WD/sysroots/&lt;name&gt;/hooks -- a hook configured for the default root's HOOKS_DIR never fires for a sysroot-scoped install, and vice versa; hooks.conf works the same way in either location.
 
combining a USE-gated hook with a USE-gated patch (and the dependency that patch itself needs) is a common pattern -- see patches.conf.example (this file's sibling)'s closing worked example for a full "one USE flag drives a patch, a dependency, and a hook together" walkthrough.