10.4. PREFIX and DESTDIR

PREFIX determines where the port will be installed. It defaults to /usr/local, but can be set by the user to a custom path like /opt. The port must respect the value of this variable.

DESTDIR, if set by the user, determines the complete alternative environment, usually a jail or an installed system mounted somewhere other than /. A port will actually install into DESTDIR/PREFIX, and register with the package database in DESTDIR/var/db/pkg. As DESTDIR is handled automatically by the ports infrastructure with chroot(8). There is no need for modifications or any extra care to write DESTDIR-compliant ports.

The value of PREFIX will be set to LOCALBASE (defaulting to /usr/local). If USE_LINUX_PREFIX is set, PREFIX will be LINUXBASE (defaulting to /compat/linux).

Avoiding hard-coded /usr/local paths in the source makes the port much more flexible and able to cater to the needs of other sites. Often, this can be accomplished by replacing occurrences of /usr/local in the port's various Makefiles with ${PREFIX}. This variable is automatically passed down to every stage of the build and install processes.

Make sure the application is not installing things in /usr/local instead of PREFIX. A quick test for such hard-coded paths is:

% make clean; make package PREFIX=/var/tmp/`make -V PORTNAME`

If anything is installed outside of PREFIX, the package creation process will complain that it cannot find the files.

In addition, it is worth checking the same with the stage directory support (see Section 6.1, “Staging”):

% make stage && make check-plist && make stage-qa && make package

These tests will not find hard-coded paths inside the port's files, nor will it verify that LOCALBASE is being used to correctly refer to files from other ports. The temporarily-installed port in /var/tmp/`make -V PORTNAME` must be tested for proper operation to make sure there are no problems with paths.

PREFIX must not be set explicitly in a port's Makefile. Users installing the port may have set PREFIX to a custom location, and the port must respect that setting.

Refer to programs and files from other ports with the variables mentioned above, not explicit pathnames. For instance, if the port requires a macro PAGER to have the full pathname of less, do not use a literal path of /usr/local/bin/less. Instead, use ${LOCALBASE}:

-DPAGER=\"${LOCALBASE}/bin/less\"

The path with LOCALBASE is more likely to still work if the system administrator has moved the whole /usr/local tree somewhere else.

Tip:

All these tests are done automatically when running poudriere testport or poudriere bulk -t. It is highly recommended that every ports contributor install and test their ports with it. See Section 10.5, “Poudriere for more information.

All FreeBSD documents are available for download at https://download.freebsd.org/ftp/doc/

Questions that are not answered by the documentation may be sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.