Time to make the donuts… ports…

One of the things I enjoy doing as I learn more about OpenBSD and the community around it is to help with the effort to port software to the platform that I personally find useful and think others will.  The ports system is where all of this third party software lives (/usr/ports) and you can read about it more here:

http://www.openbsd.org/faq/ports/ports.html

Keep in mind that the ports tree isn’t just an archaic way of building software from source, it is also where all of the binary packages come from. This is worth repeating – if you want a binary package, someone first had to create a port of it. 

The capabilities of the ports and packages system are pretty daunting when you first start to look at them.  Since I’ve muddled through a few ports successfully so far (with a lot of help from the community), I thought I would outline the general process I have followed here as a guide to others.

Step 1 – Figure out what you want to port

This may sound obvious, but you probably want to give some thought to what software that you find useful with an eye towards software that other people will find useful.  Sometimes, searching around on Google for folks complaining that X or Y isn’t available on OpenBSD can be helpful if you don’t have any solid ideas here.  The community wants the ports and packages for OpenBSD to be useful and will frequently prune things that don’t make sense or are hopelessly out of date.

Step 2 – Be ready to make a commitment

If you list yourself as the port maintainer, then you are taking on a serious responsibility to keep up with the upstream work on this piece of software and keep it current in the OpenBSD ports tree.  This can be time-consuming and will require you to work some to a lot with the “upstream” folks who actually author the software in the first place.

Step 3 – Be friendly to upstream

This is critically important.  A really poor OpenBSD port is one that has a bunch of patches in the ports subdirectory and more or less hacks the software together into some semblance of usefulness.  A truly good port is one where you have worked with the upstream authors and have contributed patches back to them that allow the OpenBSD version to build cleanly with no extra patching necessary.  By investing the time up-front, you not only help the upstream project but you also help yourself in the future as you maintain the port going forward.

Step 4 – Be polite to the kind folks at ports@

Since you are not likely an OpenBSD committer, you will need to get help from the people on the ports@openbsd.org mailing list to get your changes committed to the source tree.  Sometimes people can be in a hurry or focused on other things and maybe you won’t get a quick response to your port.  Be patient and polite and you will eventually get where you are.  If you don’t, it might be an indication that this particular piece of software isn’t terribly interesting to the community.

Step 5 – Read the documentation

There is a tremendous amount of very good documentation available online as part of the OpenBSD website.  Read it.  Then read it a second time.  Then when you hit problems, read it a third time.  If you are still stuck, politely request some help on either IRC or the ports@ mailing list and tell them what you have tried so far.  If you genuinely show an effort was made and you are just stuck, you are far more likely to find someone who will help you out.

How does a port work?

This was interesting for me to learn.  The /usr/ports directory tree doesn’t actually contain any source code (outside of patch files and some scripts).  The ports system (when building from source) pulls the source code from the upstream repository, deposits it into a /usr/ports/distfiles/PORT-v.v.v subdirectory and works on it in a subdirectory called /usr/ports/pobj/PORT-v.v.v.  This allows OpenBSD to have a light footprint and not pull down tons of source code that may or may not be of interest to the person building the machine.

The ports directory is subdivided based on the type of software.  For example, developer tools go in “devel”, database tools go in “database”, etc.  Not too tricky is it?  Each port then lives in a subdirectory under its category name.

The directory for a given port contains several standard files.  There is a “Makefile” which contains a very abbreviated set of build instructions that heavily leverages the ports infrastructure kindly provided by the OpenBSD developers.  There is a “distinfo” file that contains a manifest of data that validates the source file downloaded from upstream is the one the port maintainer was expecting.  Finally there is a pkg subdirectory with two files – “DESCR” and “PLIST”.  The “DESCR” file contains a brief description of what the port is and the “PLIST” file contains a package manifest of where the various components of the port are installed in a working system.

Most ports include a file at the bottom of their Makefile called “bsd.port.mk”.  Read the manpage for this file as it really does an excellent job of describing how the ports infrastructure works.  Given everything that you can build on OpenBSD from the ports tree, it is astonishing how well thought-out the infrastructure is.

That’s all for this posting.  Next time, we’ll get into the meat of how you actually port something with a real-world example of something I just finished porting.