9.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. Your 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), you do not need any 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 simply 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 your 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.

This test 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` should be tested for proper operation to make sure there are no problems with paths.

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

Refer to programs and files from other ports with the variables mentioned above, not explicit pathnames. For instance, if your 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.

For questions about the FreeBSD ports system, e-mail <ports@FreeBSD.org>.
For questions about this documentation, e-mail <doc@FreeBSD.org>.