The Ports Tree

A port is a set of instructions on how to apply fixes to, or patch, a set of source code files. By combining patches with installation instructions, OpenBSD can maintain a complete record of everything the software-install process has done. This frees you from struggling to install a program and allows you to concentrate instead on making the program work properly.

If you followed the post-installation hints in Chapter 5, you installed the ports tree, and should have something like the following under /usr/ports.

 # ls /usr/ports 1 CVS          chinese        games          mbone          russian 2 INDEX        comms          graphics       misc           security 3 Makefile     converters   4 infrastructure net            shells 5 README       databases      japanese       news           sysutils  archivers     devel          java           packages       textproc  astro       6 distfiles      korean         palm           www  audio         editors        lang           plan9          x11  benchmarks    education      mail           print  cad           emulators      math           productivity  # 

Note

If you don't see something like this in /usr/ports, you need to install the ports tree to continue. See "Installing the Ports Collection" in Chapter 5.

The directory 1 CVS contains information for the revision control system used by OpenBSD, Concurrent Versions System. (See Chapter 16.) This has no impact on the day-to-day operations of your ports tree.

The 2 INDEX file contains a list of all the ports. See "Finding Software" for instructions on how to use this effectively.

The 3 Makefile contains instructions for building or managing the entire ports collection. This is mostly useful when building packages for an OpenBSD release, but we'll discuss occasional bits of functionality useful to sysadmins.

The 4 infrastructure directory contains related tools for building the ports tree. Global ports settings appear here, as well as machine instructions for everything else we'll look at.

The file 5 README contains a brief introduction to the ports collection and pointers to various man pages that describe its functionality.

Finally, the 6 distfiles directory contains source code for the various ports. It starts off empty; when you install a port, OpenBSD will populate this directory.

The remainders of these directories are software categories. Each category contains a further layer of directories, and each directory under a category is a port of a piece of software. OpenBSD has over 2,000 ports, so this directory tree is vital to keeping them in any sort of manageable order!

The following directory listing shows the contents of the "benchmarks" folder, where benchmarking software that is known to run on OpenBSD is kept. This is one of the smaller categories; some categories, such as "x11," have hundreds of entries!

 # ls /usr/ports/benchmarks/ CVS       bonnie    iozone    netperf   tcpblast Makefile  bytebench lmbench   netpipe   xengine # 

Just like the CVS directory in the main ports tree, the category's CVS directory contains CVS information that doesn't matter in day-to-day operations.

The Makefile contains a list of valid ports within the category. You could build all of the ports in this category at once using this Makefile. This function is mostly only useful when building packages for redistribution, as the OpenBSD project does during a release.

Ports Subcategories

Some ports have subcategories, where many different but related pieces of software are included in one port directory. For example, here are the contents of the directory for /usr/ports/www/netscape, the port for the Netscape Web browser.

 # ls /usr/ports/www/netscape CVS                 1 communicator        2 navigator Makefile            3 communicator-linux  4 navigator-linux Makefile.inc        5 communicator-old    6 navigator-old # 

This contains six subcategories. They contain the latest 1 Netscape Communicator and 2 Netscape Navigator releases for BSD/OS, the latest 3 Netscape Communicator and 4 Netscape Navigator for Linux releases, and older 5 Netscape Communicator and 6 Netscape Navigator releases. These packages are closely related, and there's no point in cluttering the already-busy /usr/ports/www directory with six almost-identical pieces of software. ^[1]

You'll find similar subcategories for some of the popular window manager suites, such as KDE and Gnome.

Finding Software

With over 2,000 ports, how could you possibly find anything? The file /usr/ ports/INDEX contains a complete list of all ports in the tree, in alphabetical order. Each port is described on a single line, with pipe-delimited fields (|), much like this:

 fastjar-0.93|archivers/fastjar||Sun JDK's jar command written entirely in C| archivers/fastjar/pkg/DESCR|Dan Harnett<[e-mail]>|archivers||:devel/gmake|| any|y|y|y|y 

While this is a convenience format for system tools to access, it's not particularly friendly for human beings. The INDEX file is convenient to find out if a particular piece of software has been ported to OpenBSD, but that's about it. OpenBSD provides a variety of tools to more easily access this information.

If you're interested in an easier-to-read index of all the available packages, you can get a nicely formatted INDEX file by running "make print-index" in /usr/ports. Here's a snippet of the make print-index output for the same port.

 # cd /usr/ports # make print-index ... 1 Port:   fastjar-0.93 2 Path:   archivers/fastjar 3 Info:   Sun JDK's jar command written entirely in C 4 Maint:  Dan Harnett <[e-mail]> 5 Index:  archivers 6 L-deps: 7 B-deps: :devel/gmake 8 R-deps: 

The 1 port line gives the official name of the port and the version number of the ported software. The 2 path gives the category and directory where the port can be found. For example, this piece of software can be found in /usr/ports/ archivers/fastjar. The 3 info line gives a one-line description of the software. A 4 maintainer is the person responsible for porting this software to OpenBSD and for maintaining the software's entry in the ports collection. The 5 index line contains a list of all the categories that this software is assigned to. Some pieces of software could be considered part of multiple categories, and they are listed here.

The final three entries describe other software that this software depends upon. The 6 L-deps line lists ports that contain libraries that this software uses. This particular software cannot be used if these libraries are not present. The 7 B-deps line lists software that is required to build this port. In this example, the port is built with the "gmake" program available in /usr/ports/devel/gmake. Gmake does not need to be present to run the software, merely to build it. Finally, the 8 R-deps entry lists other non-library software that must be present to actually run this port.

Finding Software by Name

While the index can be helpful, how can you find a piece of software if you know its name?

If you know the exact name of the software package, you can use a simple grep command to pick it out. This is quick and easy, if you know the exact name of the software. For example, to find the "lsof" system-monitoring tool you might enter this command:

 # grep -i ^lsof INDEX lsof-4.63| 1 sysutils/lsof||list information about open files|sysutils/lsof/pkg/ DESCR|Peter Valchev <[e-mail]>|sysutils||||any|y|y|y|y # 

OpenBSD has a port for lsof, and you can find it in the 1 sysutils/lsof directory.

Finding by Keyword

If you don't know the software's exact name, try the ports collection's search feature. The "make search" command scans the ports index, searching either for the name of a port or a port where the word appears. For example, if you're interested in software to support Java Servlet Pages, you might try to search on the keyword "jserv."

 # make search key=jserv Port:   jserv-3.2.4 Path:   www/jserv Info:   Tomcat (Servlet/JSP) - Apache Connector Maint:   Reinhard J. Sammer <[e-mail]> Index:   www L-deps: B-deps:  unzip-*:archivers/unzip R-deps:  jakarta-tomcat-3.*:www/jakarta-tomcat/v3 1 Archs:   i386 # 

This looks exactly like an index display, with the addition of an 1 architecture category. This particular program only runs on the i386 architecture.

You may have to try several possible keywords for a particular package, as some keywords may have no hits and others may generate too many. For a good example of too many hits, try "make search key=java".

Browsing the Ports Tree

If you prefer to just poke through the ports collection and see what's available, you can build an HTML index and package description tree. Just go to /usr/ports and type "make readmes" to generate an HTML file for every port in the tree. This isn't quick, but you only have to generate the HTML files once to browse them forevermore. (If you upgrade your ports tree, however, you'll need to regenerate these HTML files.)

When you're finished, point your browser at /usr/ports/README.html, which contains links and a description for every category. Each category has its own HTML index, with a brief description of each port in the category, which in turn links to a more detailed description of the port. With nothing but a web browser, you can spend hours clicking through the ports to find both the software you need for your job and software you can waste your time with. ^[2]

Now that you know how to find software, let's look at actually installing some.

^[1]If you're paying attention, you might wonder why OpenBSD includes Linux and BSD/OS software. OpenBSD can run software from these operating systems with a minimum of work. See "Running Foreign Software" later in this chapter.

^[2]If you want to keep your spare time, avoid /usr/ports/games/falconseye and /usr/ports/ games/freeciv at all costs!