Some ports provide build options which can be used to enable or disable application components, provide security options, or allow for other customizations. Examples include www/firefox, security/gpgme, and mail/sylpheed-claws. If the port depends upon other ports which have configurable options, it may pause several times for user interaction as the default behavior is to prompt the user to select options from a menu. To avoid this and do all of the configuration in one batch, run make config-recursive within the port skeleton. Then, run make install [clean] to compile and install the port.

There are several ways to revisit a port's build options menu in order to add, remove, or change these options after a port has been built. One method is to cd into the directory containing the port and type make config. Another option is to use make showconfig. Another option is to execute make rmconfig which will remove all selected options and allow you to start over. All of these options, and others, are explained in great detail in ports(7).

The ports system uses fetch(1) to download the source files, which supports various environment variables. The FTP_PASSIVE_MODE, FTP_PROXY, and FTP_PASSWORD variables may need to be set if the FreeBSD system is behind a firewall or FTP/HTTP proxy. See fetch(3) for the complete list of supported variables.

For users who cannot be connected to the Internet all the time, make fetch can be run within /usr/ports, to fetch all distfiles, or within a category, such as /usr/ports/net, or within the specific port skeleton. Note that if a port has any dependencies, running this command in a category or ports skeleton will not fetch the distfiles of ports from another category. Instead, use make fetch-recursive to also fetch the distfiles for all the dependencies of a port.

In rare cases, such as when an organization has a local distfiles repository, the MASTER_SITES variable can be used to override the download locations specified in the Makefile. When using, specify the alternate location:

# cd /usr/ports/directory
# make MASTER_SITE_OVERRIDE= \
ftp://ftp.organization.org/pub/FreeBSD/ports/distfiles/ fetch

The WRKDIRPREFIX and PREFIX variables can override the default working and target directories. For example:

# make WRKDIRPREFIX=/usr/home/example/ports install

will compile the port in /usr/home/example/ports and install everything under /usr/local.

# make PREFIX=/usr/home/example/local install

will compile the port in /usr/ports and install it in /usr/home/example/local. And:

# make WRKDIRPREFIX=../ports PREFIX=../local install

will combine the two.

These can also be set as environmental variables. Refer to the manual page for your shell for instructions on how to set an environmental variable.

The Ports Collection contains several utilities to perform the actual upgrade. Each has its strengths and weaknesses.

Historically, most installations used either Portmaster or Portupgrade. Synth is a newer alternative.

ports-mgmt/portmaster is a very small utility for upgrading installed ports. It is designed to use the tools installed with the FreeBSD base system without depending on other ports or databases. To install this utility as a port:

# cd /usr/ports/ports-mgmt/portmaster
# make install clean

Portmaster defines four categories of ports:

To list these categories and search for updates:

# portmaster -L
===>>> Root ports (No dependencies, not depended on)
===>>> ispell-3.2.06_18
===>>> screen-4.0.3
        ===>>> New version available: screen-4.0.3_1
===>>> tcpflow-0.21_1
===>>> 7 root ports
...
===>>> Branch ports (Have dependencies, are depended on)
===>>> apache22-2.2.3
        ===>>> New version available: apache22-2.2.8
...
===>>> Leaf ports (Have dependencies, not depended on)
===>>> automake-1.9.6_2
===>>> bash-3.1.17
        ===>>> New version available: bash-3.2.33
...
===>>> 32 leaf ports

===>>> 137 total installed ports
        ===>>> 83 have new versions available

This command is used to upgrade all outdated ports:

# portmaster -a

If errors are encountered during the upgrade process, add -f to upgrade and rebuild all ports:

# portmaster -af

Portmaster can also be used to install new ports on the system, upgrading all dependencies before building and installing the new port. To use this function, specify the location of the port in the Ports Collection:

# portmaster shells/bash

More information about ports-mgmt/portmaster may be found in its pkg-descr.

ports-mgmt/portupgrade is another utility that can be used to upgrade ports. It installs a suite of applications which can be used to manage ports. However, it is dependent upon Ruby. To install the port:

# cd /usr/ports/ports-mgmt/portupgrade
# make install clean

Before performing an upgrade using this utility, it is recommended to scan the list of installed ports using pkgdb -F and to fix all the inconsistencies it reports.

To upgrade all the outdated ports installed on the system, use portupgrade -a. Alternately, include -i to be asked for confirmation of every individual upgrade:

# portupgrade -ai

To upgrade only a specified application instead of all available ports, use portupgrade pkgname. It is very important to include -R to first upgrade all the ports required by the given application:

# portupgrade -R firefox

If -P is included, Portupgrade searches for available packages in the local directories listed in PKG_PATH. If none are available locally, it then fetches packages from a remote site. If packages can not be found locally or fetched remotely, Portupgrade will use ports. To avoid using ports entirely, specify -PP. This last set of options tells Portupgrade to abort if no packages are available:

# portupgrade -PP gnome3

To just fetch the port distfiles, or packages, if -P is specified, without building or installing anything, use -F. For further information on all of the available switches, refer to the manual page for portupgrade.

More information about ports-mgmt/portupgrade may be found in its pkg-descr.