Chapter 13. Dos and Don'ts

Here is a list of common dos and don’ts that are encountered during the porting process. Check the port against this list, but also check ports in the PR database that others have submitted. Submit any comments on ports as described in Bug Reports and General Commentary. Checking ports in the PR database will both make it faster for us to commit them, and prove that you know what you are doing.

Do not write anything to files outside WRKDIR. WRKDIR is the only place that is guaranteed to be writable during the port build (see installing ports from a CDROM for an example of building ports from a read-only tree). The pkg-* files can be modified by redefining a variable rather than overwriting the file.

Make sure the port honors WRKDIRPREFIX. Most ports do not have to worry about this. In particular, when referring to a WRKDIR of another port, note that the correct location is ${WRKDIRPREFIX}${PORTSDIR}/subdir/name/work not ${PORTSDIR}/subdir/name/work or ${.CURDIR}/../../subdir/name/work or some such.

Some code needs modifications or conditional compilation based upon what version of FreeBSD Unix it is running under. The preferred way to tell FreeBSD versions apart are the __FreeBSD_version and __FreeBSD__ macros defined in sys/param.h. If this file is not included add the code,

to the proper place in the .c file.

__FreeBSD__ is defined in all versions of FreeBSD as their major version number. For example, in FreeBSD 9.x, __FreeBSD__ is defined to be 9.

A complete list of __FreeBSD_version values is available in __FreeBSD_version Values.

Do not write anything after the .include <bsd.port.mk> line. It usually can be avoided by including bsd.port.pre.mk somewhere in the middle of the Makefile and bsd.port.post.mk at the end.

bsd.port.pre.mk only defines a few variables, which can be used in tests in the Makefile, bsd.port.post.mk defines the rest.

Here are some important variables defined in bsd.port.pre.mk (this is not the complete list, please read bsd.port.mk for the complete list).

Here are some examples of things that can be added after bsd.port.pre.mk:

Always use tab instead of spaces after BROKEN=.

If the port installs a shell script whose purpose is to launch another program, and if launching that program is the last action performed by the script, make sure to launch the program using the exec statement, for instance:

The exec statement replaces the shell process with the specified program. If exec is omitted, the shell process remains in memory while the program is executing, and needlessly consumes system resources.

The Makefile should do things in a simple and reasonable manner. Making it a couple of lines shorter or more readable is always better. Examples include using a make .if construct instead of a shell if construct, not redefining do-extract if redefining EXTRACT* is enough, and using GNU_CONFIGURE instead of CONFIGURE_ARGS += --prefix=${PREFIX}.

If a lot of new code is needed to do something, there may already be an implementation of it in bsd.port.mk. While hard to read, there are a great many seemingly-hard problems for which bsd.port.mk already provides a shorthand solution.

The port must respect both CC and CXX. What we mean by this is that the port must not set the values of these variables absolutely, overriding existing values; instead, it may append whatever values it needs to the existing values. This is so that build options that affect all ports can be set globally.

If the port does not respect these variables, please add NO_PACKAGE=ignores either cc or cxx to the Makefile.

Here is an example of a Makefile respecting both CC and CXX. Note the ?=:

Here is an example which respects neither CC nor CXX:

Both CC and CXX can be defined on FreeBSD systems in /etc/make.conf. The first example defines a value if it was not previously set in /etc/make.conf, preserving any system-wide definitions. The second example clobbers anything previously defined.

The port must respect CFLAGS. What we mean by this is that the port must not set the value of this variable absolutely, overriding the existing value. Instead, it may append whatever values it needs to the existing value. This is so that build options that affect all ports can be set globally.

If it does not, please add NO_PACKAGE=ignores cflags to the Makefile.

Here is an example of a Makefile respecting CFLAGS. Note the +=:

Here is an example which does not respect CFLAGS:

CFLAGS is defined on FreeBSD systems in /etc/make.conf. The first example appends additional flags to CFLAGS, preserving any system-wide definitions. The second example clobbers anything previously defined.

Remove optimization flags from the third party Makefiles. The system CFLAGS contains system-wide optimization flags. An example from an unmodified Makefile:

Using system optimization flags, the Makefile would look similar to this example:

Make the port build system display all commands executed during the build stage. Complete build logs are crucial to debugging port problems.

Non-informative build log example (bad):

Verbose build log example (good):

Some build systems such as CMake, ninja, and GNU configure are set up for verbose logging by the ports framework. In other cases, ports might need individual tweaks.

Do send applicable changes and patches to the upstream maintainer for inclusion in the next release of the code. This makes updating to the next release that much easier.

README.html is not part of the port, but generated by make readme. Do not include this file in patches or commits.

In certain cases, users must be prevented from installing a port. There are several variables that can be used in a port’s Makefile to tell the user that the port cannot be installed. The value of these make variables will be the reason that is shown to users for why the port refuses to install itself. Please use the correct make variable. Each variable conveys radically different meanings, both to users and to automated systems that depend on Makefiles, such as the ports build cluster, and FreshPorts.

Do remember that BROKEN and FORBIDDEN are to be used as a temporary resort if a port is not working. Permanently broken ports will be removed from the tree entirely.

When it makes sense to do so, users can be warned about a pending port removal with DEPRECATED and EXPIRATION_DATE. The former is a string stating why the port is scheduled for removal; the latter is a string in ISO 8601 format (YYYY-MM-DD). Both will be shown to the user.

It is possible to set DEPRECATED without an EXPIRATION_DATE (for instance, recommending a newer version of the port), but the converse does not make any sense.

There is no set policy on how much notice to give. Current practice seems to be one month for security-related issues and two months for build issues. This also gives any interested committers a little time to fix the problems.

The correct way for a Makefile to signal that the port cannot be installed due to some external factor (for instance, the user has specified an illegal combination of build options) is to set a non-blank value to IGNORE. This value will be formatted and shown to the user by make install.

It is a common mistake to use .error for this purpose. The problem with this is that many automated tools that work with the ports tree will fail in this situation. The most common occurrence of this is seen when trying to build /usr/ports/INDEX (see Running make describe). However, even more trivial commands such as make maintainer also fail in this scenario. This is not acceptable.

The usage of sysctl is discouraged except in targets. This is because the evaluation of any makevars, such as used during make index, then has to run the command, further slowing down that process.

Only use sysctl(8) through SYSCTL, as it contains the fully qualified path and can be overridden, if one has such a special need.

Sometimes the authors of software change the content of released distfiles without changing the file’s name. Verify that the changes are official and have been performed by the author. It has happened in the past that the distfile was silently altered on the download servers with the intent to cause harm or compromise end user security.

Put the old distfile aside, download the new one, unpack them and compare the content with diff(1). If there is nothing suspicious, update distinfo.

Contact the authors of the software and confirm the changes with them.

FreeBSD ports generally expect POSIX compliance. Some software and build systems make assumptions based on a particular operating system or environment that can cause problems when used in a port.

Do not use /proc if there are any other ways of getting the information. For example, setprogname(argv[0]) in main() and then getprogname(3) to know the executable name.

Do not rely on behavior that is undocumented by POSIX.

Do not record timestamps in the critical path of the application if it also works without. Getting timestamps may be slow, depending on the accuracy of timestamps in the OS. If timestamps are really needed, determine how precise they have to be and use an API which is documented to just deliver the needed precision.

A number of simple syscalls (for example gettimeofday(2), getpid(2)) are much faster on Linux® than on any other operating system due to caching and the vsyscall performance optimizations. Do not rely on them being cheap in performance-critical applications. In general, try hard to avoid syscalls if possible.

Do not rely on Linux®-specific socket behavior. In particular, default socket buffer sizes are different (call setsockopt(2) with SO_SNDBUF and SO_RCVBUF, and while Linux®'s send(2) blocks when the socket buffer is full, FreeBSD’s will fail and set ENOBUFS in errno.

If relying on non-standard behavior is required, encapsulate it properly into a generic API, do a check for the behavior in the configure stage, and stop if it is missing.

Check the man pages to see if the function used is a POSIX interface (in the "STANDARDS" section of the man page).

Do not assume that /bin/sh is bash. Ensure that a command line passed to system(3) will work with a POSIX compliant shell.

A list of common bashisms is available here.

Check that headers are included in the POSIX or man page recommended way. For example, sys/types.h is often forgotten, which is not as much of a problem for Linux® as it is for FreeBSD.

Always double-check pkg-descr and pkg-plist. If reviewing a port and a better wording can be achieved, do so.

Please be careful to note any legal issues! Do not let us illegally distribute software!