BSD Ports and Packages Collection pt. 1, A Walkthrough of the Port System

by Nicolás Baldi, <openbsd@softhome.net>

First of all, you need to get the Ports & Packages Collection tarball. For this, you can check either on the official CD, or fetch the file ports.tar.gz from any of the mirrors. You should place this file under /usr since the directory /usr/ports will be created with all the Collection's directory structure inside. Remember to untar the Ports file as root or using sudo. I strongly recommend running OpenBSD 3.4 since it comes with lots of bug fixes and is totally different from its previous version. You must take care not to use a OpenBSD-current ports tree with OpenBSD-3.4 or earlier.

(I am assuming you placed ports.tar.gz under /usr)

% cd /usr
% sudo tar -zxvf ports.tar.gz

This will take a while, especially on an old machine. You will need around 250MB. If you don't have enough space on your hard drive for this, please take a look at pkg_add. This command will allow you to install a precompiled package on your machine.

After all the directories and files are extracted, you will see that /usr/ports was created, and inside you will see something like this:

% cd /usr/ports
% ls
.cvsignore     books          emulators      mbone          russian
CVS            cad            games          misc           security
INDEX          chinese        graphics       net            shells
Makefile       comms          infrastructure news           sysutils
Makefile.bak   converters     japanese       packages       textproc
README         databases      java           palm           www
archivers      devel          korean         parallel       x11
astro          distfiles      lang           plan9
audio          editors        mail           print
benchmarks     education      math           productivity

If you are interested in installing mpg123 - a mp3 player ,

% cd /usr/ports/audio/mpg123
% sudo make

Here's where the real magic begins. Let's review in detail what make install clean will do. First, it will get the tarball for mpg123 (in this case) from ftp.openbsd.org since this is the default (it is possible to change this to your nearest mirror.) All the tarballs are downloaded into /usr/ports/distfiles. The script will check the integrity of the file by verifying the file's SHA1 checksum, then it will extract all the files into the ./w-mpg123 directory. The script will patch the source files for the application (if needed) with the files under ./patches. Then it will proceed to execute the "configure" script inside the application. So far you will see something like this.

>> Checksum OK for mpg123-0.59r.tar.gz. (SHA1)
>> Checksum OK for mpg123-059r-v6-20000713b.diff.gz. (SHA1)
>> Checksum OK for l3.diff.gz. (SHA1)
===>  Extracting for mpg123-0.59rp2
===>  Patching for mpg123-0.59rp2
===>  Applying distribution patches for mpg123-0.59rp2
===>  Configuring for mpg123-0.59rp2
===>  Building for mpg123-0.59rp2

After all this the compilation starts (notice the Building statement.) You will see the compilation process going on in your standard output. Once this process is finished a new binary package file will be placed at /usr/ports/packages/i386/All (in case you are using an i386 machine.)

% ls -la /usr/ports/packages/i386/All
-rw-r--r--  2 root  wheel     60669 Aug 20 17:59 mpg123-0.59rp1.tgz

The application was compiled and it is ready to be installed.

% sudo make install
===>  Installing mpg123-0.59rp2 from /usr/ports/packages/i386/all/mpg123-0.59rp2.tgz

This will install your application under /usr/local/bin since this is the default for OpenBSD. If you check with the command pkg_info you will see the name of the application on the left and a small description on the right.

% pkg_info
mpg123-0.59rp2     mpeg audio 1/2 layer 1, 2 and 3 player

This is extremely helpful to check which applications you have already installed in your system, and it is also a great way to uninstall them using the pkg_delete command.

% sudo pkg_delete mpg123-0.59rp2

Another feature from the Collection is that when you try to install an application, it will automatically check if a dependency (e.g. libraries, another application, etc) is needed for the Port to work. The procedure for the dependencies is exactly the same as for a regular port, since they are also ports inside the Collection. Lets say that you want to install an application that requires GTK in order to work. make install will take care not only of your application itself, but also GTK, and all the dependencies that GTK needs to work. After you're finished with the compilation and installation, you no longer need the source files plus the object files inside ./w-w-mpg123-0.59rp2. So you can get rid of them just by typing:

% sudo make clean

Remember that this only deletes the ./w-mpg123-0.59rp2 directory and its contents. It does not delete the tarball under /usr/ports/distfiles nor any of the dependencies' tarballs, nor any of the dependencies' source and object files. In case you are low on hard drive space you can delete everything inside /usr/ports/distfiles by hand. And if you want to delete the dependencies' source and object files you can do a "make clean" under /usr/ports. That will take care of cleaning all the ports' directory tree.

Now your application is ready to run.

After seeing the "hard" path, it is also helpful to know that all this can be done just by simply using:

% sudo tar -zxvf ports.tar.gz
% cd /usr/ports/audio/mpg123
% sudo make install clean

In the next article I will explain in detail what each of the directories and files inside a Port are and for what they are used. I will go through the contents of each of the files that are needed to create a Port and get it to work. This will be helpful in case you decide to create your own Port or if you have to troubleshoot one.

Bibliography: