hooks.conf.example

# 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):
#   HOOKS_DIR/post_install/10-logger
#   HOOKS_DIR/post_install/20-notify
#
# 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:
#
#   HOOKS_DIR/post_install/hooks.conf:
#       20-notify:
#           AFTER=10-logger
#       30-extra-check:
#           IF_USE=debug
#
# 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
#
# 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.
#
# which phase directories exist: every built-in pre_/post_<phase> 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):
#   # from a port's build: phase --
#   $MP_HOOK post-configure
# 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=<name> in mp.conf) gets its own,
# fully independent hooks tree at $WD/sysroots/<name>/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.