The FreeBSD Ports Collection

The freebsd ports collection uses a set of makefiles that automate the download, extraction, patching, compilation and installation of software applications. This is how the system provides binary backward compatibility between major releases.

The pkg package management tool tracks quarterly branch-releases of the ports tree but not HEAD. This can cause dependencies between the port tree and pkg to be inconsistent.

How to install

Generally speaking, a port is a set of Makefiles, patches, and description files used to compile software applications for the FreeBSD operating system. The actual application being compiled is called the target. The ports system allows users to install a large number of third party applications.

Ports are maintained in a hierarchy under the /usr/ports/ tree. There are several ways to obtain the ports collection if it was not installed during the initial setup of FreeBSD. The recommended method is to use Portsnap, which connects to a secure FreeBSD site and retrieves a copy of the ports collection.

Once the ports have been installed, the ports system can be used to install and update them. Before doing this, it is a good idea to read /usr/ports/UPDATING. This file describes various issues and additional steps users may encounter when upgrading ports, such as possible changes to file formats or the location of configuration files. In addition, it discusses how the ports system updates dependencies.

How to update

The Ports Collection is a collection of Makefiles, patches and description files needed to build and install a unique piece of software on FreeBSD. These are kept under a subdirectory of /usr/ports by default.

The resulting binary programs (and libraries) are usually installed by the pkg utility. Using the Ports Collection in combination with pkg may lead to conflicts between dependencies installed by pkg and those downloaded from the ports tree. Therefore it is typically not recommended to use the Ports Collection and pkg together.

Keeping up to date with the Ports Collection is done with the freebsd-update command. A basic setup of the update tool will download a compressed snapshot of the ports tree from a remote location and extract it into /usr/ports.

A configuration option can be set to leave specified directories, such as /usr/bin or /sbin, untouched during the updating process. This is useful for preventing freebsd-update from overwriting local changes with those from the snapshot.

How to remove

A port’s source code does not include the actual software program (otherwise known as a distfile) itself. Instead it contains instructions on how to build the program, along with other information about the port like build options, configure flags etc. The distfile can be a tarred or gzipped file or a directory. The ports system manages this information in a few different ways and is described in detail in the FreeBSD Porter’s Handbook.

The command pkg_delete(8) removes installed ports that are no longer needed. It is interactive by default and asks the user to confirm before deleting any distfile. There is also a more automated tool called ports-mgmt/pkg_cutleaves.

Portupgrade discovers stale dependencies, that is a dependency cycle that has broken because the original port has disappeared (like portindex) or changed its origin in the ports tree. It then reassociates the dependencies to the correct new location by checking a MOVED file. This can be a very time consuming operation.

How to configure

The FreeBSD ports system offers two complementary technologies for installing third party software: the Ports Collection, for installing applications from source code, and packages, which provide pre-compiled binaries. Each has advantages and disadvantages depending on the software installation requirements of a given system.

The Ports Collection consists of Makefiles, patches and description files that automate the process of downloading, extracting, patching, building, and installing an application/software program on FreeBSD. The collection is kept under a subdirectory of the /usr/ports directory and is referred to as a port.

The ports system provides a way to quickly search for a specific application and to keep track of changes made to a particular port. In addition to a centralized search tool available through the ports web site Dan Langille maintains FreshPorts, a free and open source utility that tracks the latest ports changes. In order to use this tool you need to have a copy of the ports CVSup file, which is located in /usr/share/examples/cvsup/ports-supfile.

Head back to the root page