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

# 4.5 Using the Ports Collection

The following sections provide basic instructions on using the Ports Collection to install or remove programs from your system. The detailed description of available `make` targets and environment variables is available in ports(7).

## 4.5.1 Obtaining the Ports Collection

Before you can install ports, you must first obtain the Ports Collection--which is essentially a set of `Makefiles`, patches, and description files placed in `/usr/ports`.

When installing your FreeBSD system, sysinstall asked if you would like to install the Ports Collection. If you chose no, you can follow these instructions to obtain the ports collection:

CVSup Method

This is a quick method for getting and keeping your copy of the Ports Collection up to date using CVSup protocol. If you want to learn more about CVSup, see Using CVSup.

> Note: The implementation of CVSup protocol included with the FreeBSD system is called csup.

Make sure `/usr/ports` is empty before you run csup for the first time! If you already have the Ports Collection present, obtained from another source, csup will not prune removed patch files.

1. Run `csup`:

       # csup -L 2 -h cvsup.FreeBSD.org /usr/share/examples/cvsup/ports-supfile

   Change `cvsup.FreeBSD.org` to a CVSup server near you. See CVSup Mirrors (Section A.6.7) for a complete listing of mirror sites.

   > Note: One may want to use his own `ports-supfile`, for example to avoid the need of passing the CVSup server on the command line.

   > 1. In this case, as `root`, copy `/usr/share/examples/cvsup/ports-supfile` to a new location, such as `/root` or your home directory.

   > 2. Edit `ports-supfile`.

   > 3. Change `CHANGE_THIS.FreeBSD.org` to a CVSup server near you. See CVSup Mirrors (Section A.6.7) for a complete listing of mirror sites.

   > 4. And now to run `csup`, use the following:

   >        # csup -L 2 /root/ports-supfile

2. Running the csup(1) command later will download and apply all the recent changes to your Ports Collection, except actually rebuilding the ports for your own system.

Portsnap Method

Portsnap is an alternative system for distributing the Ports Collection. Please refer to Using Portsnap for a detailed description of all Portsnap features.

1. Download a compressed snapshot of the Ports Collection into `/var/db/portsnap`. You can disconnect from the Internet after this step, if you wish.

       # portsnap fetch

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

       # portsnap extract

   If you already have a populated `/usr/ports` and you are just updating, run the following command instead:

       # portsnap update

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.

## 4.5.2 Installing Ports

The first thing that should be explained when it comes to the Ports Collection is what is actually meant by a “skeleton”. In a nutshell, a port skeleton is a minimal set of files that tell your FreeBSD system how to cleanly compile and install a program. Each port skeleton includes:

- A `Makefile`. The `Makefile` contains various statements that specify how the application should be compiled and where it should be installed on your system.

- A `distinfo` file. 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.

- A `files` directory. This directory contains patches to make the program compile and install on your FreeBSD system. Patches are basically small files that specify changes to particular files. They are in plain text format, and basically say “Remove line 10” or “Change line 26 to this ...”. Patches are also known as “diffs” because they are generated by the diff(1) program.

  This directory may also contain other files used to build the port.

- A `pkg-descr` file. This is a more detailed, often multiple-line, description of the program.

- A `pkg-plist` file. 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 have 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, check out the FreeBSD Porter's Handbook.

The port includes instructions on how to build source code, but does not include the actual source code. You can get the source code from a CD-ROM or from the Internet. Source code is distributed in whatever manner the software author desires. Frequently this is a tarred and gzipped file, but it might be compressed with some other tool or even uncompressed. The program source code, whatever form it comes in, is called a “distfile”. The two methods for installing a FreeBSD port are described below.

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

> Warning: Before installing any port, you should be sure to have an up-to-date Ports Collection and you should check http://vuxml.freebsd.org/ for security issues related to your port.

> A security vulnerabilities check can be automatically done by portaudit before any new application installation. This tool can be found in the Ports Collection (`ports-mgmt/portaudit`). Consider running `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.

The Ports Collection makes an assumption that you have a working Internet connection. If you do not, you will need to put a copy of the distfile into `/usr/ports/distfiles` manually.

To begin, change to the directory for the port you want to install:

    # cd /usr/ports/sysutils/lsof

Once inside the `lsof` directory, you will see the port skeleton. The next step is to compile, or “build”, the port. This is done by simply typing `make` at the prompt. Once you have done so, you should see something like this:

    # 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]
    ...
    #

Notice that once the compile is complete you are returned to your prompt. The next step is to install the port. In order to install it, you simply need to tack one word onto the `make` command, and that word is `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 your prompt, you should be able to run the application you just installed. Since `lsof` is a program that runs with increased privileges, a security warning is shown. During the building and installation of ports, you should 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. Not only does it consume valuable disk space, but it would also cause 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: 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 one of these shells, you might have to use the `rehash` command after installing a port, before the newly installed commands can be used. This command will work for shells like `tcsh`. Use the `hash -r` command for shells like `sh`. Look at the documentation for your shell for more information.

Some third-party DVD-ROM products such as the FreeBSD Toolkit from the FreeBSD Mall contain distfiles. They can be used with the Ports Collection. Mount the DVD-ROM 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: Please be aware that the licenses of a few ports do not allow for inclusion on the CD-ROM. This could be because a registration form needs to be filled out before downloading or redistribution is not allowed, or for another reason. If you wish to install a port not included on the CD-ROM, you will need to be online in order to do so.

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. Just run this command at the top level directory (`/usr/ports`) and the required files will be downloaded for you. This command will also work in the lower level categories, for example: `/usr/ports/net`. Note that if a port depends on libraries or other ports this will not fetch the distfiles of those ports too. Replace `fetch` with `fetch-recursive` if you want to fetch all the dependencies of a port too.

> Note: You can build all the ports in a category or as a whole by running `make` in the top level directory, just like the aforementioned `make `fetch`` method. 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 `MASTER_SITES` (the location where files are downloaded from). 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 we change the `MASTER_SITES` option to `ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/`.

> Note: Some ports allow (or even require) you to provide build options which can enable/disable parts of the application which are unneeded, certain security options, and other customizations. A few which come to mind are `www/mozilla`, `security/gpgme`, and `mail/sylpheed-claws`. A message will be displayed when options such as these are available.

### 4.5.2.1 Overriding the Default Ports Directories

Sometimes it is useful (or mandatory) to use a different working and target directory. The `WRKDIRPREFIX` and `PREFIX` variables can override the default 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 it in `/usr/ports` and install it in `/usr/home/example/local`.

And of course,

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

will combine the two (it is too long to completely write on this page, but it should give you the general idea).

Alternatively, these variables can also be set as part of your environment. Read the manual page for your shell for instructions on doing so.

### 4.5.2.2 Dealing with `imake`

Some ports that use `imake` (a part of the X Window System) do not work well with `PREFIX`, and will insist on installing under `/usr/X11R6`. Similarly, some Perl ports ignore `PREFIX` and install in the Perl tree. Making these ports respect `PREFIX` is a difficult or impossible job.

### 4.5.2.3 Reconfiguring Ports

When building certain ports, you may be presented with a ncurses-based menu from which you can select certain build options. It is not uncommon for users to wish to revisit this menu to add, remove, or change these options after a port has been built. There are many ways to do this. One option is to go into the directory containing the port and type `make `config``, which will simply present the menu again with the same options selected. Another option is to use `make `showconfig``, which will show you all the configuration options for the port. Yet 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).

## 4.5.3 Removing Installed Ports

Now that you know how to install ports, you are probably wondering how to remove them, just in case you install one and later on decide that you installed the wrong port. We will remove our previous example (which was `lsof` for those of you not paying attention). Ports are being removed exactly the same as the packages (discussed in the Packages section), using the pkg_delete(1) command:

    # pkg_delete lsof-4.57

## 4.5.4 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

### 4.5.4.1 `/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.

### 4.5.4.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 the `make `install clean`` command:

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

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

When you run `portupgrade -a`, portupgrade will begin to upgrade all the outdated ports installed on your system. Use the `-i` flag if you want to be asked for confirmation of every individual upgrade.

    # portupgrade -ai

If you want to upgrade only a certain application, not all available ports, use `portupgrade `pkgname``. Include the `-R` flag if portupgrade should first upgrade all the ports required by the given application.

    # portupgrade -R firefox

To use packages instead of ports for installation, provide `-P` flag. With this option portupgrade searches the local directories listed in `PKG_PATH`, or fetches packages from remote site if it is 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).

### 4.5.4.3 Upgrading Ports using Portmanager

Portmanager is another utility for easy upgrading of installed ports. It is available from the `ports-mgmt/portmanager` port:

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

All the installed ports can be upgraded using this simple command:

    # portmanager -u

You can add the `-ui` flag to get asked for confirmation of every step Portmanager will perform. Portmanager can also be used to install new ports on the system. Unlike the usual `make `install clean`` command, it will upgrade all the dependencies prior to building and installing the selected port.

    # portmanager x11/gnome2

If there are any problems regarding the dependencies for the selected port, you can use Portmanager to rebuild all of them in the correct order. Once finished, the problematic port will be rebuilt too.

    # portmanager graphics/gimp -f

For further information see portmanager(1).

### 4.5.4.4 Upgrading Ports using Portmaster

Portmaster is another utility for upgrading installed ports. Portmaster was designed make use of the tools found in the “base” system (it does not depend upon other ports) and uses the information in `/var/db/pkg/` to determine which ports to upgrade. It is available from the `ports-mgmt/portmaster` port:

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

Portmaster groups ports into four categories:

- Root ports (no dependencies, not depended on)

- Trunk ports (no dependencies, are depended on)

- Branch ports (have dependencies, are depended on)

- Leaf ports (have dependencies, not depended on)

You can list all the installed ports and search for updates using the `-L` option:

    # 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 simple 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 the `-b` will instruct Portmaster not to automatically delete the backup. Adding the `-i` option will start Portmaster in interactive mode, prompting you before upgrading each port.

If you encounter errors during the upgrade process, you can use the `-f` option 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

Please see portmaster(8) for more information.

## 4.5.5 Ports and Disk Space

Using the Ports Collection will use up disk space over time. After building and installing software from the ports, you should always remember to clean up the temporary `work` directories using the `make `clean`` command. You can sweep the whole Ports Collection with the following command:

    # portsclean -C

You will accumulate a lot of old source distribution files in the `distfiles` directory over time. You can remove them by hand, or you can use the following command to delete all the distfiles that are no longer referenced by any ports:

    # portsclean -D

Or to remove all distfiles not referenced by any port currently installed on your system:

    # portsclean -DD

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

Do not forget to remove the installed ports once you no longer need them. A nice tool to help automate this task is available from the `ports-mgmt/pkg_cutleaves` port.

Prev | Home | Next
Using the Packages System | Up | Post-installation Activities