Chapter 6. Special Considerations
Prev		Next

Chapter 6. Special Considerations

This section explains the most common things to consider when creating a port.

6.1. Staging

bsd.port.mk expects ports to work with a “stage directory”. This means that a port must 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 10.4, “PREFIX and DESTDIR”).

Note:

No port really needs to be root. It can mostly be avoided by using USES=uidfix. If the port still runs commands like chown(8), chgrp(1), or forces owner or group with install(1) then use USES=fakeroot to fake those calls. Some patching of the port's Makefiles will be needed.

Meta ports, or ports that do not install files themselves but only depend on other ports, must 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 seen as orphans. To prevent mtree(8) extraction, add this line:

NO_MTREE=	yes

Tip:

Metaports should use USES=metaport. It sets up defaults for ports that do not fetch, build, or install anything.

Staging is enabled by prepending STAGEDIR 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.

Tip:

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

6.1.1. Handling Symbolic Links

When creating a symlink, there are two cases, either the source and target are both within ${PREFIX}. In that case, use ${RLN}. In the other case, if one or both of the paths are outside of ${PREFIX} use ${LN} -s and only prepend ${STAGEDIR} to the target's path.

Example 6.1. Inside ${PREFIX}, Create Relative Symbolic Links

${RLN} uses install(1)'s relative symbolic feature which frees the porter of computing the relative path.

${RLN} ${STAGEDIR}${PREFIX}/lib/libfoo.so.42 ${STAGEDIR}${PREFIX}/lib/libfoo.so

Will generate:

% ls -lF ${STAGEDIR}${PREFIX}/lib
  lrwxr-xr-x  1 nobody  nobody    181 Aug  3 11:27 libfoo.so@ -> libfoo.so.42
  -rwxr-xr-x  1 nobody  nobody     15 Aug  3 11:24 libfoo.so.42*

When used with paths not in the same directory:

${RLN} ${STAGEDIR}${PREFIX}/libexec/foo/bar ${STAGEDIR}${PREFIX}/bin/bar

Will automatically generate the relative symbolic links:

% ls -lF ${STAGEDIR}${PREFIX}/bin
  lrwxr-xr-x  1 nobody  nobody    181 Aug  3 11:27 bar@ -> ../libexec/foo/bar

Example 6.2. Outside ${PREFIX}, Create Absolute Symbolic Links

When creating a symbolic link outside of ${PREFIX}, the source must not contain ${STAGEDIR}, the target, however, must:

${LN} -sf /var/cache/${PORTNAME} ${STAGEDIR}${PREFIX}/share/${PORTNAME}

Will generate:

% ls -lF ${STAGEDIRDIR}${PREFIX}/share
  lrwxr-xr-x  1 nobody  nobody    181 Aug  3 11:27 foo@ -> /var/cache/foo

Prev		Next
5.16. Installing Files	Home	6.2. Bundled Libraries