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.

4.5.1 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 are needed for a program to compile and install cleanly on FreeBSD. 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 checksums, to ensure that those 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 program.

This directory may also contain other files used in building the port.
A pkg-comment file. This is a one-line description of the program.
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.

Now that you have enough background information to know what the ports collection is used for, you are ready to install your first port. There are two ways this can be done, and each is explained below.

Before we get into that however, you will need to choose a port to install. There are a few ways to do this, with the easiest method being the ports listing on the FreeBSD web site. You can browse through the ports listed there or use the search function on the site. Each port also includes a description so you can read a bit about each port before deciding to install it.

Another method is to use the whereis command. To use whereis, simply type ``whereis <program you want to install>'' at the prompt, and if it is found on your system, you will be told where it is, like so:

    # whereis lsof
    lsof: /usr/ports/sysutils/lsof

This tells us that lsof (a system utility) can be found in the /usr/ports/sysutils/lsof directory.

Yet another way of finding a particular port is by using the ports collection's built-in search mechanism. To use the search feature, you will need to be in the /usr/ports directory. Once in that directory, run make search key=program-name where ``program-name'' is the name of the program you want to find. For example, if you were looking for lsof:

    # cd /usr/ports
    # make search key=lsof
    Port:   lsof-4.56.4
    Path:   /usr/ports/sysutils/lsof
    Info:   Lists information about open files (similar to fstat(1))
    Maint:  obrien@FreeBSD.org
    Index:  sysutils
    B-deps: 
    R-deps:

The part of the output you want to pay particular attention to is the ``Path:'' line, since that tells you where to find it. The other information provided is not needed in order to install the port directly, so it will not be covered here.

Note: You must be the root user to install ports.

Now that you have found a port you would like to install, you are ready to do the actual installation.

4.5.1.1 Installing Ports from a CDROM

As you may have guessed from the title, everything described in this section assumes you have a FreeBSD CDROM set. If you do not, you can order one from the FreeBSD Mall.

Assuming that your FreeBSD CDROM is in the drive and is mounted on /cdrom (and the mount point must be /cdrom), you are ready to install the port. To begin, change to the directory where the port you want to install lives:

    # cd /usr/ports/sysutils/lsof

Once inside the lsof directory, you will see the port skeleton. The next step is to compile (also called 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 file:/cdrom/ports/distfiles/.
    ===>  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 snipped]
    ...
    #

Take 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
    ...
    [install routines 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.

Note: You can save an extra step by just running make install instead of make and make install as two separate steps.

Note: Please be aware that the licenses of a few ports do not allow for inclusion on the CDROM. This could be because a registration form needs to be filled out before downloading, redistribution is not allowed, and so on. If you wish to install a port not included on the CDROM, you will need to be online in order to do so (see the next section).

4.5.1.2 Installing Ports from the Internet

As with the last section, this section makes an assumption that you have a working Internet connection. If you do not, you will need to perform the CDROM installation.

Installing a port from the Internet is done exactly the same way as it would be if you were installing from a CDROM. The only difference between the two is that the program's source code is downloaded from the Internet instead of pulled from the CDROM.

The steps involved are identical:

    # make install
    >> lsof_4.57D.freebsd.tar.gz doesn't seem to exist in /usr/ports/distfiles/.
    >> Attempting to fetch from ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/.
    Receiving lsof_4.57D.freebsd.tar.gz (439860 bytes): 100%
    439860 bytes transferred in 18.0 seconds (23.90 kBps)
    ===>  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 snipped]
    ...
    ===>  Installing for lsof-4.57
    ...
    [install routines 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.
    #

As you can see, the only difference is the line that tells you where the system is fetching the port from.

That about does it for installing ports onto your system. In the next section you will learn how to remove a port from your system.

4.5.2 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 you decide that you installed the wrong port. The next few paragraphs will cover just that.

Now we will remove our previous example (which was lsof for those of you not paying attention). As with installing ports, the first thing you must do is change to the port directory, which if you remember was /usr/ports/irc/lsof. After you change directories, you are ready to uninstall lsof. This is done with the make deinstall command:

    # cd /usr/ports/irc/lsof
    # make deinstall
    ===>  Deinstalling for lsof-4.57

That was easy enough. You have now managed to remove lsof from your system. If you would like to reinstall it, you can do so by running make reinstall from the /usr/ports/irc/lsof directory.

Prev	Home	Next
Using the Packages System	Up	Troubleshooting