How to Use the FreeBSD Port Patch System

The FreeBSD ports collection provides software that can be downloaded, configured, compiled, and installed. Each piece of software has a port description file called pkg-descr.

This file should contain a brief description of the port, preferably in an easily readable format such as a man page or README. It is also used as a basis for displaying information to users via make -v options and to automated systems like poudriere and FreshPorts.

1. Update the INDEX

In order to use the port management system, one needs to have an up to date INDEX. This is used by tools like portupgrade and the pkg-info command.

The INDEX is a database of rows, one for each port in the FreeBSD ports system, and lives directly under the portsdir /usr/ports. The INDEX records dependencies between the ports and the pkg-info data which describes packages (or pkgs).

To update the INDEX, the program first determines all installed ports. Then it follows the MOVED file to discover if any of them have taken a new origin. It then recomputes the dependency information using “make build-depend-list” and similar tools for the ports requiring attention. It also updates VALID_CATEGORIES if the port has been moved to a new category.

2. Update the CONFIGURATION

Keeping ports updated with security patches in a timely fashion and upgrading to a newer release of FreeBSD are important tasks for system administrators. These can be done with a utility called freebsd-update.

The pkg-descr provides a more detailed description of the program, and a more accurate picture of how it should work on your site (for example, whether it should have a hard-coded /usr/local path or not). The pkg-plist is used to list the files installed by the port, and tells the ports system which files to remove upon deinstallation.

The EXTRA_PATCHES section can contain conditional patches, which specify which shell to use for line-ending conversion and other processing. The pkg-config section defines which options are available for the port, including security options.

3. Update the PACKAGE

For some ports there may be patches that need to be applied when a specific FreeBSD version is used or when the pkg_config option is enabled. These conditional patches should be placed in the EXTRA_PATCHES directory, if not already present. The patch program accepts the difference listing produced by diff and applies it to one or more original files, producing patched versions of those files.

This process can be automated by using poudriere, part of the ports-mgmt/poudriere package. It maintains jails where these steps can be tested and run without affecting the host system. For more information see the poudriere manual page. This method also supports upgrading to new minor and major releases. It can be used to update the core operating system and to upgrade ports tree installed software packages with a single command.

4. Update the PATCHFILES

The first part of a ports Makefile sets its PORTNAME. This is a unique name that distinguishes the software from all other FreeBSD packages. It is used in a variety of ways, such as for PKGBASE and DISTDIR.

The second part of a ports Makefile sets its MASTER_SITES and PATCH_SITES variables. These are used when a new port is created to specify where the tarball will be downloaded and how it will be placed on the local system.

Some ports require specific architectures, such as x86 or amd64. The read-only makevar TARGET_ARCH sets these constraints, and ports that do not have them set are marked with the value NO_ARCH. The port patch program uses a special diff utility to record the differences between original files and their modified versions.

5. Update the PORT

Some ports require patch files that are not applied automatically by the framework. This can be done by placing them in EXTRA_PATCHES. This variable can also be used to set the base directory for the line-ending conversion, which is useful if the distfiles include many tarballs.

The PORTS_UPDATING file in /usr/ports provides instructions for upgrading the ports on your system. It can be a good idea to read this before upgrading, as it often indicates any extra steps that need to be taken to upgrade the software.

There are several utilities in the Ports Collection that perform the actual upgrade process, such as portmaster, poudriere and Synth. It is recommended to use poudriere, which maintains jails where each of the above steps can be tested without affecting the host system.

Go Home