FreeBSD Handbook
Prev | Chapter 5 Installing Applications: Packages and Ports | Next

# 5.6 Using the Ports Collection

This section provides basic instructions on using the Ports Collection to install or remove software. The detailed description of available `make` targets and environment variables is available in ports(7).

> Warning: As of mid 2012, the FreeBSD Ports Project has migrated revision control systems from CVS to Subversion. The preferred method for obtaining and maintaining the ports tree is Portsnap. Users requiring local customization of ports (that is, maintaining additional local patches) will probably prefer to use Subversion directly. The CVSup service was phased out as of February 28, 2013.

## 5.6.1 Obtaining the Ports Collection

The Ports Collection is a set of `Makefiles`, patches, and description files stored in `/usr/ports`. This set of files is used to compile and install applications on FreeBSD. The instructions below show several methods of obtaining the Ports Collection if it was not installed during initial FreeBSD setup.

Portsnap Method

Portsnap is a fast and user-friendly tool for retrieving the Ports Collection, the preferred choice for most users. See Using Portsnap for a detailed description of Portsnap.

1. Download a compressed snapshot of the Ports Collection into `/var/db/portsnap`.

       # portsnap fetch

2. When running Portsnap for the first time, extract the snapshot into `/usr/ports`:

       # portsnap extract

3. After the first use of Portsnap has been completed as shown above, `/usr/ports` can be updated with:

       # portsnap fetch
       # portsnap update

Subversion Method

If more control over the ports tree is needed (for example, for maintaining local changes), Subversion can be used to obtain the Ports Collection. Refer to the Subversion Primer for a detailed description of Subversion.

1. Subversion must be installed before it can be used to check out the ports tree. If a copy of the ports tree is already present, install Subversion like this:

       # cd /usr/ports/devel/subversion
       # make install clean

   If the ports tree is not available, Subversion can be installed as a package:

       # pkg_add -r subversion

   If pkgng is being used to manage packages, Subversion can be installed with it instead:

       # pkg install subversion

2. Check out a copy of the ports tree. Use a specific Subversion mirror close to your geographic location instead of `svn0.us-east.FreeBSD.org` in the command below for better performance. Committers should read the Subversion Primer first to be sure the correct protocol is chosen.

       # svn checkout https://svn0.us-east.FreeBSD.org/ports/head /usr/ports

3. To update `/usr/ports` after the initial Subversion checkout:

       # svn update /usr/ports

Sysinstall Method

This method involves using sysinstall to install the Ports Collection from the installation media. Note that the old copy of Ports Collection from the date of the release will be installed. If you have Internet access, you should always use one of the methods mentioned above.

1. As `root`, run `sysinstall` as shown below:

       # sysinstall

2. Scroll down and select Configure, press Enter.

3. Scroll down and select Distributions, press Enter.

4. Scroll down to ports, press Space.

5. Scroll up to Exit, press Enter.

6. Select your desired installation media, such as CDROM, FTP, and so on.

7. Scroll up to Exit and press Enter.

8. Press X to exit sysinstall.

## 5.6.2 Migrating from CVSup/csup to portsnap

> Warning: By February 28, 2013, the ports tree will no longer be exported to CVS and therefore CVSup and csup will no longer provide updates for the ports tree.

Migration to Portsnap

The migration will require about 1 GB of disk space on `/usr`, plus Portsnap requires about 150 MB disk space on `/var`.

1. Disable any automated ports updates you may use, such as a cron(8) job calling CVSup or csup.

2. Move the existing ports tree to a temporary location:

       # mv /usr/ports /usr/ports.old

3. Fetch the new ports tree with Portsnap and extract it to `/usr/ports`:

       # portsnap fetch extract

4. Move distfiles and saved packages to the new ports tree:

       # mv /usr/ports.old/distfiles /usr/ports
       # mv /usr/ports.old/packages /usr/ports

5. Delete the old ports tree:

       # rm -rf /usr/ports.old

6. If CVSup was used before, it can now be uninstalled:

       # pkg_delete -r -v cvsup-without-gui-\*

   Users of pkgng can use the following command:

       # pkg delete cvsup-without-gui

See Using Portsnap for a detailed description of Portsnap and how to update the ports tree with Portsnap.

## 5.6.3 Installing Ports

A port skeleton is a set of files that tell FreeBSD system how to compile and install a program. Each port skeleton includes:

- `Makefile`: The `Makefile` contains statements that specify how the application should be compiled and where its components should be installed.

- `distinfo`: This file contains information about the files that must be downloaded to build the port, and their checksums (using sha256(1)), to verify that files have not been corrupted during the download.

- `files/`: This directory contains any patches needed for the program to compile and install on FreeBSD. This directory may also contain other files used to build the port.

- `pkg-descr`: This file provides a more detailed description of the program.

- `pkg-plist`: This is a list of all the files that will be installed by the port. It also tells the ports system what files to remove upon deinstallation.

Some ports include other files, such as `pkg-message`. The ports system uses these files to handle special situations. If you want more details on these files, and on ports in general, refer to the FreeBSD Porter's Handbook.

The port does not include the actual source code, also known as a “distfile”. Source code is distributed in whatever manner the software author desires. The two methods for installing a FreeBSD port are described below.

> Note: You must be logged in as `root` to install ports.

> Warning: Before compiling any port, be sure to have an up-to-date Ports Collection and check http://vuxml.freebsd.org/ for security issues related to your port. If `ports-mgmt/portaudit`) is installed, run `portaudit -F` before installing a new port, to fetch the current vulnerabilities database. A security audit and an update of the database will be performed during the daily security system check. For more information read the portaudit(1) and periodic(8) manual pages.

Using the Ports Collection assumes a working Internet connection. Otherwise, manually obtain and place a copy of the distfile into `/usr/ports/distfiles`.

To begin, change to the directory of the port to be installed:

    # cd /usr/ports/sysutils/lsof

To compile, or “build”, the port, type `make` at the prompt. You should see messages similar to the ones in this example:

    # make
    >> lsof_4.57D.freebsd.tar.gz doesn't seem to exist in /usr/ports/distfiles/.
    >> Attempting to fetch from ftp://lsof.itap.purdue.edu/pub/tools/unix/lsof/.
    ===>  Extracting for lsof-4.57
    ...
    [extraction output snipped]
    ...
    >> Checksum OK for lsof_4.57D.freebsd.tar.gz.
    ===>  Patching for lsof-4.57
    ===>  Applying FreeBSD patches for lsof-4.57
    ===>  Configuring for lsof-4.57
    ...
    [configure output snipped]
    ...
    ===>  Building for lsof-4.57
    ...
    [compilation output snipped]
    ...
    #

Once the compile is complete, you are returned to the prompt. The next step is to install the port using `make install`:

    # make install
    ===>  Installing for lsof-4.57
    ...
    [installation output snipped]
    ...
    ===>   Generating temporary packing list
    ===>   Compressing manual pages for lsof-4.57
    ===>   Registering installation for lsof-4.57
    ===>  SECURITY NOTE:
          This port has installed the following binaries which execute with
          increased privileges.
    #

Once you are returned to the prompt, you should be able to run the installed application. Since `lsof` is a program that runs with increased privileges, a security warning is shown. During the building and installation of ports, take heed of any other warnings that may appear.

It is a good idea to delete the working subdirectory, which contains all the temporary files used during compilation. Doing so saves disk space and minimizes the chance of problems later when upgrading to the newer version of the port.

    # make clean
    ===>  Cleaning for lsof-4.57
    #

> Note: You can save two extra steps by just running `make `install clean`` instead of `make`, `make `install`` and `make `clean`` as three separate steps.

> Note: Using only `make `install`` means there will potentially be many waiting periods between user interaction as the default behaviour is to prompt the user for options. To avoid this when there are many dependencies, first run `make `config-recursive`` to do the configuration in one batch. Then run `make `install [clean]`` afterwards.

> Tip: When using `config-recursive`, the list of ports to configure are gathered by the `all-depends-list` make(1) target. It is often recommended to run `make `config-recursive`` until all dependent ports options have been defined, and ports options dialog(1) screens no longer appear, to be certain all ports options have been configured as intended.

> Note: Some shells keep a cache of the commands that are available in the directories listed in the `PATH` environment variable, to speed up lookup operations for the executable file of these commands. If you are using `tcsh`, you might have to type `rehash` so that a newly installed command can be used without specifying its full path. Use `hash -r` instead for the `sh` shell. Refer to the documentation for the shell for more information.

Some third-party DVD products such as the FreeBSD Toolkit from the FreeBSD Mall contain distfiles. They can be used with the Ports Collection. Mount the DVD on `/cdrom`. If you use a different mount point, set `CD_MOUNTPTS` make variable. The needed distfiles will be automatically used if they are present on the disk.

> Note: The licenses of a few ports do not allow their inclusion on the DVD. This could be because a registration form needs to be filled out before downloading or redistribution is not allowed. If you wish to install a port not included on the DVD, you will need to be connected to the Internet.

The ports system uses fetch(1) to download the files, which honors various environment variables, including `FTP_PASSIVE_MODE`, `FTP_PROXY`, and `FTP_PASSWORD`. You may need to set one or more of these if you are behind a firewall, or need to use an FTP/HTTP proxy. See fetch(3) for the complete list.

For users which cannot be connected all the time, the `make `fetch`` option is provided. Run this command within `/usr/ports` and the required files will be downloaded. This command also works in the lower level categories, such as `/usr/ports/net`. Note that if a port depends on libraries or other ports, this will not fetch the distfiles of ports from another category. Use `make `fetch-recursive`` to fetch all the dependencies of a port.

> Note: You can build all the ports in a category or as a whole by running `make` in the top level directory. This is dangerous, however, as some ports cannot co-exist. In other cases, some ports can install two different files with the same filename.

In some rare cases, users may need to acquire the tarballs from a site other than the default `MASTER_SITES`. You can override the `MASTER_SITES` option with the following command:

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

In this example, `MASTER_SITES` is changed to `ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/`.

> Note: Some ports provide build options which can be used to enable/disable parts of the application which are unneeded, provide security options, or allow for other customizations. Examples include `www/firefox`, `security/gpgme`, and `mail/sylpheed-claws`. A menu will be displayed at the beginning of a port compile when compile options are available.

### 5.6.3.1 Overriding the Default Ports Directories

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.

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

### 5.6.3.2 Reconfiguring Ports

Certain ports provide an ncurses-based menu containing build options. There are several ways to revisit this 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 the manual page for ports(7).

## 5.6.4 Removing Installed Ports

Installed ports and packages are uninstalled using the pkg_delete(1) command:

    # pkg_delete lsof-4.57

## 5.6.5 Upgrading Ports

First, list outdated ports that have a newer version available in the Ports Collection with the pkg_version(1) command:

    # pkg_version -v

### 5.6.5.1 Read `/usr/ports/UPDATING`

Once you have updated your Ports Collection, before attempting a port upgrade, you should check `/usr/ports/UPDATING`. This file describes various issues and additional steps users may encounter and need to perform when updating a port, including such things as file format changes, changes in locations of configuration files, or other such incompatibilities with previous versions.

If `UPDATING` contradicts something you read here, `UPDATING` takes precedence.

### 5.6.5.2 Upgrading Ports Using Portupgrade

The portupgrade utility is designed to easily upgrade installed ports. It is available from the `ports-mgmt/portupgrade` port. Install it like any other port, using `make `install clean``:

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

Scan the list of installed ports using `pkgdb -F` and fix all the inconsistencies it reports. It is a good idea to do this regularly, before every upgrade.

Use `portupgrade -a` to upgrade all the outdated ports installed on the system. 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``. Include `-R` to first upgrade all the ports required by the given application.

    # portupgrade -R firefox

To use packages instead of ports, include the `-P` flag. With this option, portupgrade searches the local directories listed in `PKG_PATH`, then fetches packages from a remote site if not found locally. If packages can not be found locally or fetched remotely, portupgrade will use ports. To avoid using ports, specify `-PP`.

    # portupgrade -PP gnome2

To just fetch distfiles (or packages, if `-P` is specified) without building or installing anything, use `-F`. For further information see portupgrade(1).

### 5.6.5.3 Upgrading Ports Using portmaster

`ports-mgmt/portmaster` is another utility for upgrading installed ports. portmaster was designed to use the tools found in the “base” system without depending upon other ports. It uses the information in `/var/db/pkg/` to determine which ports to upgrade. To install the port:

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

Portmaster groups ports into four categories:

- Root ports: no dependencies and is not depended on by other ports

- Trunk ports: no dependencies, but other ports depend upon it

- Branch ports: have dependencies and are depended upon by other ports

- Leaf ports: have dependencies but are not depended upon by other ports

To list all installed software and search for updates, use `-L`:

    # 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)
    ===>>> apache-2.2.3
            ===>>> New version available: apache-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

All the installed ports can be upgraded using this command:

    # portmaster -a

> Note: By default, portmaster will make a backup package before deleting the existing port. If the installation of the new version is successful, portmaster will delete the backup. Using `-b` will instruct portmaster not to automatically delete the backup. Adding `-i` will start portmaster in interactive mode, prompting for confirmation before upgrading each port.

If you encounter errors during the upgrade process, use `-f` to upgrade/rebuild all ports:

    # portmaster -af

You can also use portmaster to install new ports on the system, upgrading all dependencies before building and installing the new port:

    # portmaster shells/bash

Refer to portmaster(8) for more information.

## 5.6.6 Ports and Disk Space

Using the Ports Collection will use up disk space over time. After building and installing a port, `make `clean`` will clean up the temporary `work` directory. To sweep the whole Ports Collection:

    # portsclean -C

A lot of out-dated source distribution files will collect in `distfiles` over time. The following command will delete all the distfiles that are no longer referenced by any ports:

    # portsclean -D

To remove all distfiles not referenced by any port currently installed on the system:

    # portsclean -DD

> Note: The `portsclean` utility is part of the portupgrade suite.

`ports-mgmt/pkg_cutleaves` automates the task of removing installed ports that are no longer needed.

Prev | Home | Next
Using pkgng for Binary Package Management | Up | Post-installation Activities