4.2. Using the Ports Collection

The following sections provide basic instructions on using the ports collection to install or remove programs from your system.

4.2.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:

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 xchat
    xchat: /usr/ports/irc/xchat
    #

This tells us that xchat (an irc client) can be found in the /usr/ports/irc/xchat 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 xchat:

    # cd /usr/ports
    # make search key=xchat
    Port:   xchat-1.3.8
    Path:   /usr/ports/irc/xchat
    Info:   An X11 IRC client using the GTK+ toolkit, and optionally, GNOME
    Maint:  jim@FreeBSD.org
    Index:  irc
    B-deps: XFree86-3.3.5 bzip2-0.9.5d gettext-0.10.35 giflib-4.1.0 glib-1.2.6 gmake-3.77 gtk-1.2.6
            imlib-1.9.8 jpeg-6b png-1.0.3 tiff-3.5.1
    R-deps: XFree86-3.3.5 gettext-0.10.35 giflib-4.1.0 glib-1.2.6 gtk-1.2.6 imlib-1.9.8 jpeg-6b
            png-1.0.3 tiff-3.5.1

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.2.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 directories to the directory where the port you want to install lives:

    # cd /usr/ports/irc/xchat

Once inside the xchat 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
    >> xchat-1.3.8.tar.bz2 doesn't seem to exist on this system.
    >> Attempting to fetch from file:/cdrom/ports/distfiles/.
    ===>  Extracting for xchat-1.3.8
    >> Checksum OK for xchat-1.3.8.tar.bz2.
    ===>   xchat-1.3.8 depends on executable: bzip2 - found
    ===>   xchat-1.3.8 depends on executable: gmake - found
    ===>   xchat-1.3.8 depends on shared library: gtk12.2 - found
    ===>   xchat-1.3.8 depends on shared library: Imlib.5 - found
    ===>   xchat-1.3.8 depends on shared library: X11.6 - found
    ===>  Patching for xchat-1.3.8
    ===>  Applying FreeBSD patches for xchat-1.3.8
    ===>  Configuring for xchat-1.3.8
    ...
    [configure output snipped]
    ...
    ===>  Building for xchat-1.3.8
    ...
    [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 xchat-1.3.8
    ===>   xchat-1.3.8 depends on shared library: gtk12.2 - found
    ===>   xchat-1.3.8 depends on shared library: Imlib.5 - found
    ===>   xchat-1.3.8 depends on shared library: X11.6 - found
    ...
    [install routines snipped]
    ...
    ===>   Generating temporary packing list
    ===>   Installing xchat docs in /usr/X11R6/share/doc/xchat
    ===>   Registering installation for xchat-1.3.8
    #

Once you are returned to your prompt, you should be able to run the application you just installed.

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 for various reasons, including things such as as registration form needs to be filled out before downloading, if 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.2.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 do 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
    >> xchat-1.3.8.tar.bz2 doesn't seem to exist on this system.
    >> Attempting to fetch from http://xchat.org/files/v1.3/.
    Receiving xchat-1.3.8.tar.bz2 (305543 bytes): 100%
    305543 bytes transferred in 2.9 seconds  (102.81 Kbytes/s)
    ===>  Extracting for xchat-1.3.8
    >> Checksum OK for xchat-1.3.8.tar.bz2.
    ===>   xchat-1.3.8 depends on executable: bzip2 - found
    ===>   xchat-1.3.8 depends on executable: gmake - found
    ===>   xchat-1.3.8 depends on shared library: gtk12.2 - found
    ===>   xchat-1.3.8 depends on shared library: Imlib.5 - found
    ===>   xchat-1.3.8 depends on shared library: X11.6 - found
    ===>  Patching for xchat-1.3.8
    ===>  Applying FreeBSD patches for xchat-1.3.8
    ===>  Configuring for xchat-1.3.8
    ...
    [configure output snipped]
    ...
    ===>  Building for xchat-1.3.8
    ...
    [compilation snipped]
    ...
    ===>  Installing for xchat-1.3.8
    ===>   xchat-1.3.8 depends on shared library: gtk12.2 - found
    ===>   xchat-1.3.8 depends on shared library: Imlib.5 - found
    ===>   xchat-1.3.8 depends on shared library: X11.6 - found
    ...
    [install routines snipped]
    ...
    ===>   Generating temporary packing list
    ===>   Installing xchat docs in /usr/X11R6/share/doc/xchat
    ===>   Registering installation for xchat-1.3.8
    #

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 section you will learn how to remove a port from your system.

4.2.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 xchat 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/xchat. After you change directories, you are ready to uninstall xchat. This is done with the make deinstall command (makes sense right?):

    # cd /usr/ports/irc/xchat
    # make deinstall
    ===>  Deinstalling for xchat-1.3.8
    #

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

For questions about FreeBSD, e-mail <questions@FreeBSD.org>.
For questions about this documentation, e-mail <doc@FreeBSD.org>.