Paludis, the Other Package Mangler



This document describes the Paludis hooks interface. A hook is a piece of code that is executed when a particular well defined action occurs.

There are currently four categories of hook:

There are currently three categories of hook execution code:

Not all hook execution code methods are available for all hook categories. The following table indicates availability:

.bash .hook Repository
General yes yes yes
Ebuild Phase yes
Ebuild Message yes
Merger yes yes yes

Where there is a choice, .hook hooks should be favoured over .bash hooks.

Available Hooks

General Hooks

The following general normal hooks are available:

In general, certain special environment variables will be set. HOOK will contain the name of the hook. For all hooks, TARGETS will contain the targets for the operation. For non-all hooks, TARGET will contain the current target. The PALUDIS_CMDLINE variables described below are also available. For the install_pretend_display_item hooks, the KIND variable will also be of interest.

Ebuild Hooks

The following ebuild hooks are available:

As well as the full ebuild environment, the HOOK environment variable will contain the name of the hook being called. The PALUDIS_CMDLINE variables described below are also available.

Ebuild Message Hooks

The following ebuild message hooks are available:

The HOOK environment variable will contain the name of the hook being called, and the MESSAGE environment variable will contain the message being passed to the function. The PALUDIS_CMDLINE variables described below are also available.

Merger / Unmerger Hooks

The merger runs in two stages, for safety. First it checks that it can probably install safely, then it does the actual install. Note that calculating the md5, timestamp etc for VDB CONTENTS is done after the install_post hooks are called.

In each of the following subcategories, the hooks that do not name a specific type of object are called before or after the entire process; those that do are called once for each relevant item.

The following merger check hooks are available:

The INSTALL_SOURCE and INSTALL_DESTINATION environment variables contain the target source and destination. The ROOT variable contains the filesystem root. The IMAGE variable contains the image root.

The following merger hooks are available:

Again, ROOT and IMAGE are available. For install hooks, INSTALL_SOURCE, INSTALL_DESTINATION are set, and for uninstall hooks, UNLINK_TARGET.

The unmerger hooks are used for uninstalling a package, but not when existing things have to be removed for an install (the merger does that). The following unmerger hooks are available:

The UNLINK_TARGET environment variable specifies the file about to be unlinked, and ROOT is the filesystem root.

User Defined Hooks

User defined hooks should be executable (chmod a+x) scripts named *.bash or *.hook. They can live in two locations (or be symlinked there, to allow a single script to be shared between hooks):

Bash Hooks

A .bash hook is merely executed when the associated action is triggered. There is no guarantee as to execution order.

Hook Hooks

A .hook hook is more powerful. It must not run anything in global scope, but instead defines all its actions in functions. It must, at minimum, define a function called hook_run_$HOOK for each hook that it can handle. It may also define functions called hook_depend_$HOOK, which should output names of any other hooks upon which it depends, and hook_after_$HOOK, which is similar but indicates an ordering rather than hard dependency (the named hooks not existing is not an error). For example:


    # ensure that einfo etc are available
    export PATH="$(${PALUDIS_EBUILD_DIR}/utils/canonicalise ${PALUDIS_EBUILD_DIR}/utils/ ):${PATH}"
    source ${PALUDIS_EBUILD_DIR}/echo_functions.bash

    einfo "Checking for monkeys..."

    if [[ -d "${ROOT}/var/lib/monkeys" ]] ; then
        for m in "${ROOT}"/var/lib/monkeys/* ; do
            ewarn "Found monkey $(basename ${m} )"
        einfo "No monkeys found"

    # we need to run after the Paludis standard eselect_env_update hook
    echo eselect_env_update

    # if checking for rabbits or squirrels, do those first
    echo check_for_rabbits check_for_squirrels

Note that the hook_depend_ and hook_after_ functions are cached, and are generally only called once per session, so the output should not vary based upon outside parameters.

Package Manager Defined Hooks

Paludis places some of its own hooks in LIBEXECDIR/hooks/hookname. These directories are not for end user use.

Example Hooks

Paludis ships certain example hooks that many users would find useful, but that are not suitably general to be enabled by default -- these live in DATADIR/paludis/hooks/demos/. You may also find the default hooks useful -- these live in various places in LIBEXECDIR/paludis/hooks/.


Sometimes hooks need access to the commandline used to invoke paludis. However, manual parsing of the commandline by hooks will lead to bugs when people forget to emulate certain behaviour (say, short options, aliases or -- support). To work around this issue, Paludis provides environment variables prefixed PALUDIS_CMDLINE_ that specify the parsed command line: