Chapter 6. Special Considerations

Table of Contents
6.1. Staging
6.2. Shared Libraries
6.3. Ports with Distribution Restrictions or Legal Concerns
6.4. Building Mechanisms
6.5. Using GNU Autotools
6.6. Using GNU gettext
6.7. Using Perl
6.8. Using X11
6.9. Using GNOME
6.10. Using Qt
6.11. Using KDE
6.12. Using Java
6.13. Web Applications, Apache and PHP
6.14. Using Python
6.15. Using Tcl/Tk
6.16. Using Emacs
6.17. Using Ruby
6.18. Using SDL
6.19. Using wxWidgets
6.20. Using Lua
6.21. Using iconv
6.22. Using Xfce
6.23. Using Mozilla
6.24. Using Databases
6.25. Starting and Stopping Services (rc Scripts)
6.26. Adding Users and Groups
6.27. Ports That Rely on Kernel Sources

There are some more things you have to take into account when you create a port. This section explains the most common of those.

6.1. Staging

bsd.port.mk expects ports to work with a 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, making it possible to build packages as an unprivileged user. With staging, the port is built and installed into the stage directory, STAGEDIR. A package is created from the stage directory and then installed on the system. Automake tools refer 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 stage and package targets, this line must be added to the Makefile:

NEED_ROOT=	yes

Note:

The vast majority of ports do not really need to be root. You can mostly avoid it by using USES=uidfix, and from time to time by slightly patching the port's Makefiles.

Meta ports, or ports that do not install files themselves but only depend on other ports, should avoid needlessly extracting the mtree(8) to the stage directory. This is the basic directory layout of the package, and these empty directories will be seens as orphans. To prevent mtree(8) extraction, add this line:

NO_MTREE=	yes

Staging is enabled by prepending the STAGEDIR variable to paths used in the pre-install, do-install, and post-install targets (see the examples through the book). Typically, this includes PREFIX, ETCDIR, DATADIR, EXAMPLESDIR, MANPREFIX, DOCSDIR, and so on. Directories should be created as part of the post-install target. Avoid using absolute paths whenever possible.

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

${LN} -sf libfoo.so.42 ${STAGEDIR}${PREFIX}/lib/libfoo.so

The source path ${PREFIX}/lib/libfoo.so.42 looks fine but could, in fact, be incorrect. Absolute paths can point to a wrong location, like when a remote file system has been mounted with NFS under a non-root mount point. Relative paths are less fragile, and often much shorter.

Ports that install kernel modules must prepend the STAGEDIR variable to their destination, by default /boot/modules.

All FreeBSD documents are available for download at http://ftp.FreeBSD.org/pub/FreeBSD/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>.