The following sections provide basic instructions on using the ports collection to install or remove programs from your system.
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 files directory. The files directory contains a file named md5. This file is named after the MD5 algorithm used to determine ports checksums. A checksum is a number generated by adding up all the data in the file you want to check. If any characters change, the checksum will differ from the original and an error message will be displayed so you are able to investigate the changes.
The files directory can also contain other files that are required by the port but do not belong elsewhere in the directory structure.
A patches 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.
A pkg directory. This directory normally contains three files. Occasionally, there will be more than three, but it depends on the port. Most only require three. The files are:
COMMENT. This is a one-line description of the program.
DESCR. This is a more detailed, often multiple-line, description of the program.
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.
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.
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).
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.
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>.