bsd.port.mk expects ports to work with a so-called “stage directory”. This means that a port should not install files directly to the regular destination directories (that is, under PREFIX, for example) but instead into a separate directory from which the package is then built. In many cases, this does not require root privileges, therefore it enables building packages as an unprivileged user. With staging, the package is first built, installed into the stage directory, referenced as STAGEDIR, packaged, and then installed from the package. Automake tools refers to this concept as DESTDIR, but in FreeBSD, DESTDIR has a different meaning (see Section 9.4, “PREFIX and DESTDIR”).

When a port still requires system-wide privileges in order to run the package target, the following line has to be added to its Makefile:

For meta ports, add the following line, otherwise they would needlessly extract the mtree(8), the basic directory layout of the package, to the stage directory, and will be counted as orphans. Meta ports are the ports that do not install files themselves but depend on other ports, hence this distinction.

To enable staging for a port, the STAGEDIR variable has to prepended before the uses of PREFIX, ETCDIR, DATADIR, EXAMPLESDIR, MANPREFIX, DOCSDIR, etc. at the pre-install, do-install, and post-install targets (see the examples through the book). Directories should be created as part of the post-install target. Try to avoid using absolute paths whenever possible.

When creating a symlink, STAGEDIR should be prepended to the target path only. For example:

Note that the source path, ${PREFIX}/lib/libfoo.so.42, while looks fine, could be in fact incorrect, since absolute paths can potentially point to a wrong location, e.g. when remote filesystem is mounted via NFS under a non-root mount point. Relative paths are less fragile, and often much shorter.

For ports that install kernel modules, the STAGEDIR variable has to be prepended to their default destination, /boot/modules. Then the pre-install target may be used to take care of the creation of this directory:

Furthermore, one should pay attention to disallow running kldxref(8) on install. This can be usually disabled via defining the NO_XREF variable and adding it to MAKE_ENV in the port's Makefile.

Instead, the hints files for the kernel loader should be only generated when the package is installed or deinstalled. This can be achieved by invoking kldxref(8) in the pkg-plist file.