portupgrade

In the previous article, we took a look at the built-in utilities that can be used to manage the FreeBSD ports collection. In this article, I'd like to continue in that vein. Let's take a look at portupgrade, a feature-rich port designed to help you get the most out of the ports collection.

Installing portupgrade

Like any other port, you install portupgrade by cding into its directory and issuing a make command:

% cd /usr/ports/sysutils/portupgrade
% make install clean

The build will install over a dozen useful utilities. Let's take a trick from the last article and see which manpages, and hence, which utilities, were installed:

% pkg_info -xL portupgrade | grep man
/usr/local/man/man1/pkg_deinstall.1.gz
/usr/local/man/man1/pkg_fetch.1.gz
/usr/local/man/man1/pkg_glob.1.gz
/usr/local/man/man1/pkg_sort.1.gz
/usr/local/man/man1/pkgdb.1.gz
/usr/local/man/man1/portcvsweb.1.gz
/usr/local/man/man1/portsclean.1.gz
/usr/local/man/man1/portsdb.1.gz
/usr/local/man/man1/portupgrade.1.gz
/usr/local/man/man1/portversion.1.gz
/usr/local/man/man5/pkgtools.conf.5.gz
/usr/local/man//man1/pkg_which.1.gz
/usr/local/man//man1/portinstall.1.gz
/usr/local/man//man1/ports_glob.1.gz

It is time well spent to skim through those manpages. You'll get an idea of the power and the flexibility of the ports collection and will uncover tips and tricks you've never thought of. However, don't be dismayed if you feel a bit overwhelmed by the amount of available information. In the next few articles, I'll walk you through some concrete examples to get you started in using these utilities effectively.

First, let's review the ports structure, where it's installed on your system, and how you can keep it up to date.

When you installed FreeBSD and chose to install the ports collection, /usr/ports and its files and subdirectories were created for you. If you ls /usr/ports, you'll see that it contains subdirectories that logically divide the ports collection. For example, there are subdirectories for mail, www, and databases. Each subdirectory contains subdirectories for applicable applications, so www has subdirectories for mozilla and lynx. Each of those subdirectories contains the information needed in order to install that particular application. For example:

$ ls -F /usr/ports/www/mozilla
./	Makefile	distinfo	pkg-descr	pkg-message
../	README.html	files/		pkg-descr.gtk2

We were actually gathering information from the Makefile, pkg-descr, and pkg-message files with some of the utilities and switches we covered in the last article.

The ports collection is constantly being updated. New ports are added regularly, usually on a daily basis. If you're the curious type and like to see a layout of which ports were added when, you'll find FreshPorts an invaluable resource.

It's great to have such a dynamic ports collection, but it does mean that your ports tree, the /usr/ports directory structure, can quickly become out of date. To keep in sync with the changes and ensure that you always have the ability to build any available port, use cvsup.

Syncing Your Ports Tree

I've mentioned cvsup often. If you're not using cvsup yet, you really do want to read through Using CVSup before giving it a go. The handbook is definitely the best place to get the proper understanding of the entire cvsup process. Once you're ready:

% cd /usr/ports/net/cvsup-without-gui
% make install clean

cvsup can be used to keep both your operating system and your ports collection up to date. If you're only interested in keeping your ports tree in sync, a file similar to this will do it:

% more /root/cvs-supfile
*default host=cvsup.ca.freebsd.org
*default base=/usr/local/etc/cvsup
*default prefix=/usr
*default release=cvs delete use-rel-suffix compress
ports-all tag=.

The file can be invoked with this command as the superuser:

% cvsup -g -L 2 ~/cvs-supfile

If that file or that command doesn't make sense to you, read the section of the handbook I referred to above. Also note that the =. in the ports-all line is important, so double-check that your file has it.

That cvsup command will download all of the latest bits of the ports collection and add them to your ports tree. This is the type of command that benefits from being run on a daily basis, so you might wish to add it as a cron job.

The cvsup process also updates a file called /usr/ports/INDEX. This file contains a list of all of the ports in your ports tree. To see how up to date your ports tree is, use this command:

$ ls -l /usr/ports/INDEX
-rw-r--r--  1 root  wheel  3678738 May 17 17:04 INDEX

That particular machine was installed on May 17 and I haven't kept its ports tree up to date. If I compare that system to my main machine, which is cvsuped daily:

$ ls -l /usr/ports/INDEX
-rw-r--r--  1 root  wheel  3912366 Aug 17 08:50 INDEX

you'll see that the size of the file, and thus the number of port entries, has grown considerably in that three-month period.

Updating the Ports Database

Okay, we're finally ready for portupgrade and its suite of utilities. After each cvsup, run this command:

% portsdb -Uu

The first time you use this command, a database called INDEX.db will be created in /usr/ports. This database will be updated every time you repeat that portsdb command after a fresh cvsup. If you use the file utility, you'll see that you won't be able to access the contents of INDEX.db, since it is not an ASCII text file:

$ file /usr/ports/INDEX.db
/usr/ports/INDEX.db: Berkeley DB 1.85/1.86 (Btree, version 3, native byte-order)

However, several of the portupgrade utilities will use this database. The Btree refers to a type of database algorithm that is designed to quickly search through a large amount of data. This is ideal for the ports collection — we'll find that some of the portupgrade utilities are faster and more efficient than the built-in utilities we saw in the last article, because of that Btree.

You'll have to be patient, as portsdb takes a while to run. Once it is finished, you're ready to use portversion to see if any of your installed ports need upgrading. Remember this command?

% portversion -l "<"

If you receive any output, your next step is to upgrade those out-of-date ports. Not surprisingly, we'll use portupgrade, which is also called portinstall.