Debian – What does dh_usrlocal actually do

debianpackaging

The dh_usrlocal manpage sounds a bit cryptic to me:

It finds subdirectories of usr/local in the package build directory, and
removes them, replacing them with maintainer script snippets (unless -n is
used) to create the directories at install time, and remove them when the
package is removed, in a manner compliant with Debian policy. These
snippets are inserted into the maintainer scripts by dh_installdeb. See
dh_installdeb(1) for an explanation of debhelper maintainer script
snippets.

Mainainer scripts, snippets, -n… OK, but what is the purpose? Does it really just create (empty?) directories?

Can a kind soul explain it to me in a more practical way? Which part of policy I should read? Should I care if my app installs with PREFIX=/usr?

Best Answer

The purpose is to aid with policy compliance by that package. According to Debian policy (and, IIRC, the Filesystem Hierarchy Standard or FHS), official Debian packages are not permitted to own files or directories under /usr/local - that directory tree belongs to the local system administrator.

From https://www.debian.org/doc/debian-policy/ch-opersys.html#s9.1.2 :

(bold emphasis added by me)

9.1.2. Site-specific programs

As mandated by the FHS, packages must not place any files in /usr/local, either by putting them in the file system archive to be unpacked by dpkg or by manipulating them in their maintainer scripts.

However, the package may create empty directories below /usr/local so that the system administrator knows where to place site-specific files. These are not directories in /usr/local, but are children of directories in /usr/local. These directories (/usr/local/*/dir/) should be removed on package removal if they are empty.

Note that this applies only to directories below /usr/local, not in /usr/local. Packages must not create sub-directories in the directory /usr/local itself, except those listed in FHS, section 4.5. However, you may create directories below them as you wish. You must not remove any of the directories listed in 4.5, even if you created them.

Since /usr/local can be mounted read-only from a remote server, these directories must be created and removed by the postinst and prerm maintainer scripts and not be included in the .deb archive. These scripts must not fail if either of these operations fail.

For example, the emacsen-common package could contain something like

if [ ! -e /usr/local/share/emacs ]; then
    if mkdir /usr/local/share/emacs 2>/dev/null; then
        if chown root:staff /usr/local/share/emacs; then
            chmod 2775 /usr/local/share/emacs || true
        fi
    fi
fi

in its postinst script, and

rmdir /usr/local/share/emacs/site-lisp 2>/dev/null || true
rmdir /usr/local/share/emacs 2>/dev/null || true

in the prerm script. (Note that this form is used to ensure that if the script is interrupted, the directory /usr/local/share/emacs will still be removed.)

If you do create a directory in /usr/local for local additions to a package, you should ensure that settings in /usr/local take precedence over the equivalents in /usr.

However, because /usr/local and its contents are for exclusive use of the local administrator, a package must not rely on the presence or absence of files or directories in /usr/local for normal operation.

The /usr/local directory itself and all the subdirectories created by the package should (by default) have permissions 2775 (group-writable and set-group-id) and be owned by root:staff.

See also https://wiki.debian.org/FilesystemHierarchyStandard

dh_usrlocal removes any such directories from the package and replaces them with code in the package scripts (the .postinst and .prerm scripts) to create/delete them at install/uninstall time, following the example given in the policy.

This may seem to make little practical difference because the directories are still created on install and deleted on uninstall, but Debian considers the failure of a package to comply with policy to be as serious a bug as any other - consistent and scrupulous adherence to policy is a major factor in quality assurance for Debian packages.

Related Question