4.2.2. How does the Ports collection work?

Programs are typically distributed on the Internet as a tarball consisting of a Makefile and the source code for the program and usually some instructions (which are unfortunately not always as instructive as they could be), with perhaps a configuration script.

The standard scenario is that you FTP down the tarball, extract it somewhere, glance through the instructions, make any changes that seem necessary, run the configure script to set things up and use the standard `make' program to compile and install the program from the source.

FreeBSD ports still use the tarball mechanism, but use a skeleton to hold the "knowledge" of how to get the program working on FreeBSD, rather than expecting the user to be able to work it out. They also supply their own customised Makefile, so that almost every port can be built in the same way.

If you look at a port skeleton (either on your FreeBSD system or the FTP site) and expect to find all sorts of pointy-headed rocket science lurking there, you may be disappointed by the one or two rather unexciting-looking files and directories you find there. (We will discuss in a minute how to go about Getting a port).

``How on earth can this do anything?'' I hear you cry. ``There is not even any source code there!''

Fear not, gentle reader, all will become clear (hopefully). Let's see what happens if we try and install a port. I have chosen `bash', also known as the Bourne-Again Shell, as that seems fairly typical.

Note if you are trying this at home, you will need to be root.

 # cd /usr/ports/shells/bash
 # make install
 Checksums OK.
 ===>  Extracting for bash-1.14.5
 ===>  Patching for bash-1.14.5
 ===>  Applying FreeBSD patches for bash-1.14.5
 ===>  Configuring for bash-1.14.5
 ===>  Building for bash-1.14.5
 [lots and lots of compiler output here...]
 ===>  Installing for bash-1.14.5
 make -f bash-Makefile    bindir=/usr/local/bin  prefix=/usr/local install
 (cd ./documentation/; make  )
 rm -f builtins.txt
 nroff -man builtins.1 > builtins.txt
 install -c -o bin -g bin -m 555 bash /usr/local/bin/bash
 install -c -o bin -g bin -m 555 bashbug /usr/local/bin/bashbug
 ( cd ./documentation/ ; make   mandir=/usr/local/man/man1 man3dir=/usr/local/man/man3 infodir=/usr/local/info install )
 [ -d /usr/local/man/man1 ] || mkdir /usr/local/man/man1
 [ -d /usr/local/info ] || mkdir /usr/local/info
 ../support/install.sh -c -m 644 bash.1 /usr/local/man/man1
 ../support/install.sh -c -m 644 builtins.1 /usr/local/man/man1/bash_builtins.1
 ../support/install.sh -c -m 644 features.info /usr/local/info/bash.info
 gzip -9nf /usr/local/man/man1/bash.1 /usr/local/man/man1/bash_builtins.1
 ===>  Registering installation for bash-1.14.5

To avoid confusing the issue, I have slightly pruned the install output, as well as completely removing the build output. If you tried this yourself, you may well have got something like this at the start:-

 >> bash-1.14.5.tar.gz doesn't seem to exist on this system.
 >> Attempting to fetch from ftp://slc2.ins.cwru.edu/pub/dist/.

The `make' program has noticed that you did not have a local copy of the source code and tried to FTP it down so it could get the job done (are you starting to feel impressed? 8-)). I already had the source handy in my example, so it did not need to fetch it.

Let's go through this and see what the `make' program was doing.

1. Locate the source code tarball. If it is not available locally, try to grab it from an FTP site.
2. Run a checksum test on the tarball to make sure it has not been tampered with, accidentally truncated, struck by neutrinos while in transit, etc.
3. Extract the tarball into a temporary work directory.
4. Apply any patches needed to get the source to compile and run under FreeBSD.
5. Run any configuration script required by the build process and correctly answer any questions it asks.
6. (Finally!) Compile the code.
7. Install the program executable and other supporting files, man pages, etc. under the /usr/local hierarchy, where they will not get mixed up with system programs. This also makes sure that all the ports you install will go in the same place, instead of being flung all over your system.
8. Register the installation in a database. This means that, if you do not like the program, you can cleanly remove all traces of it from your system.

See if you can match these steps to the make output. And if you were not impressed before, you should be by now!