Cleaning and Customizing Your Ports

We've spent the last few articles discussing how to use the built-in ports utilities and portupgrade to keep your installed applications up to date. Today, I'd like to finish the series by demonstrating how to keep your system clean of uninstalled applications and how to customize your ports tree with pkgtools.conf.

Anyone who installs or uninstalls software soon realizes what a messy business this can be. Installations can clutter the hard drive with temporary files, unread READMEs, and unnoticed directories. Sometimes a program uninstall will leave behind souvenirs: files that are no longer required but still take up disk space. Worse, an install might overwrite, or an uninstall might remove, libraries that were being used by other applications. These frustrations seemingly transcend operating-system boundaries and often result in a user reinstalling the operating system from scratch just to start over with a clean slate.

Keeping Your Ports Clean

Fortunately, there are tools available to help you intelligently manage software installation and keep your FreeBSD system happily humming along for years. For example, when you install a port, remember to include the word clean:

% make install clean

This will tell make to clean out its working directory once the port has successfully installed. If you forget to clean, you'll soon find that working directories can consume a lot of disk space.

Depending upon your needs and the amount of disk space you have to work with, you might consider using this command instead:

% make install distclean

When you install a port, the required source files are downloaded from the Internet and copied into /usr/ports/distfiles. If you ever want to reinstall that port, the necessary source files are already on disk. distclean tells make to erase those files once the port is successfully installed. When deciding whether or not to use distclean, balance your available disk space with the speed and reliability of your Internet connection. Also, for license reasons, some ports require you to fetch the source manually and save it to /usr/ports/distfiles. I find it more convenient to save those files on disk, so I don't use distclean when building those ports.

Related Reading The Complete FreeBSD Documentation from the Source By Greg Lehey

Those two switches can go a long way in conserving disk space. However, if you've installed portupgrade, check out the portsclean utility that came with it. As the name suggests, this utility is designed to clean out what may have been left behind from using the ports collection.

I have a system that I use to test applications, meaning I've used it to install and uninstall hundreds of ports. I usually remember to use clean and sometimes remember to use distclean. Let's take a look at its current condition and see if portsclean will make a difference. First, I'll check how much disk space is free on /usr:

% df /usr
Filesystem  1K-blocks    Used   Avail Capacity  Mounted on
/dev/ad0s1f  13360662 6189648 6102162    50%    /usr

Next, I'll look for disk hogs in /usr/ports. This command will show the disk usage, sorted by largest usages first and piped to head so I can see the top ten disk wasters:

% du /usr/ports |sort -rn|head
3110862	/usr/ports
1848846	/usr/ports/distfiles
822278	/usr/ports/editors
816710	/usr/ports/editors/openoffice-devel
816592	/usr/ports/editors/openoffice-devel/work
604784	/usr/ports/editors/openoffice-devel/work/oo_644_src
362536	/usr/ports/distfiles/KDE
295404  /usr/ports/distfiles/openoffice
211718  /usr/ports/editors/openoffice-devel/work/mozilla
211654  /usr/ports/editors/openoffice-devel/work/mozilla/work

Hmmm. Looks like I haven't used distclean as much as I thought, and I still have working files left behind from the OpenOffice build.

I'll start by cleaning out all of those missed working directories:

% portsclean -C

Did it make a difference in disk space?

% df /usr
Filesystem  1K-blocks    Used   Avail Capacity  Mounted on
/dev/ad0s1f  13360662 5160664 7131146    42%    /usr

Oh yeah. I just increased my disk capacity by 8%. Remember, cleaning out working directories is a good thing, as they are only used during the build process. They aren't needed once the port successfully installs.

The next portsclean switch is pretty cool. Let's say you've decided to keep /usr/ports/distfiles intact. For the past few years. And you've uninstalled a few applications along the way, and upgraded others to the latest versions. There's a very good chance that some outdated and unneeded source files are collecting dust in /usr/ports/distfiles. To find and remove those relics:

% portsclean -DD
Detecting unreferenced distfiles...
<output varies>

and to check out the impact:

% df /usr
Filesystem  1K-blocks    Used   Avail Capacity  Mounted on
/dev/ad0s1f  13360662 4092490 8199320    33%    /usr

Whoa. Another 9% in disk savings. I should also see a major difference in the du command:

% du /usr/ports | sort -rn | head
1011998	/usr/ports
780760	/usr/ports/distfiles
161724	/usr/ports/distfiles/openoffice
137010	/usr/ports/distfiles/staroffice52
122648	/usr/ports/distfiles/KDE
55478	/usr/ports/distfiles/xc
24936	/usr/ports/distfiles/rpm
20536	/usr/ports/devel
18194	/usr/ports/distfiles/AbiWord
17704	/usr/ports/distfiles/ghostscript

Notice that while disk usage has decreased considerably, my system still holds the distfiles referenced by my currently installed applications.

Customizing Available Ports

Let's move on to customizing how you interact with the ports collection. When you installed portupgrade, the files /usr/local/etc/pkgtools.conf and /usr/local/etc/pkgtools.conf.sample were installed for you. By default, both files are the same. Make any changes to /usr/local/etc/pkgtools.conf and keep /usr/local/etc/pkgtools.conf.sample as is, to remind you of the original settings.

If you take the time to read this file, you'll find that it is well commented and chock full of neat and useful advice designed to help you get the most out of your ports. I'll highlight some of the more useful options, but do take the time to check out the full file yourself.

For starters, this file allows you to set the environment variables used by the portupgrade suite of utilities. For example, the default temporary directory is /var/tmp. This default can cause problems on small hard drives where disk space is limited on /var. To change this default, search for this line in /usr/local/etc/pkgtools.conf:

#   ENV['PKG_TMPDIR'] ||= '/var/tmp'

and change it to something like this:

ENV['PKG_TMPDIR'] ||= '/usr/tmp'

Remember to remove the comment (#) and to ensure the new temporary directory exists.

Another useful setting is the ignore categories section:

# IGNORE_CATEGORIES: array
#
# This is a list of port categories you want the pkgtools to ignore.
# Typically you want to list language specific categories of the
# languages you don't use.
#
# After configuring this list, you need to rebuild the ports
# database to reflect the changes. (run 'portsdb -Ufu')
#
# e.g.:
#   IGNORE_CATEGORIES = [
#     'chinese',
#     'french',
#     'german',
#     'hebrew',
#     'japanese',
#     'korean',
#     'russian',
#     'ukrainian',
#     'vietnamese',
#   ]

IGNORE_CATEGORIES = [
]

Here, the comments are quite clear. If you decide to take advantage of this option, remove the # from categories you wish to ignore. While the language categories are suggested, you can ignore any category. For example, if you never plan on installing applications from the astro or irc categories, you can include those. Here is a sample edit:

IGNORE_CATEGORIES = [
    'chinese',
    'german',
    'hebrew',
    'japanese',
    'korean',
    'russian',
    'ukrainian',
    'vietnamese',
    'astro',
]

#	  IGNORE_CATEGORIES = [
# 	]

Notice that I remarked the default empty IGNORE_CATEGORIES section. I then removed the remarks from the section listing the categories I'd like to be ignored. I also used the same format to add the astro category. Don't forget to follow the directions in the comments and:

% portsdb -Ufu

once you've saved your edits to this section.

Customizing Individual Port Build Options

One of the handiest settings in this file is the MAKE_ARGS section. Some ports allow you to customize how they build by specifying certain arguments. These arguments are found in the port's Makefile and are usually invoked like this:

% cd /usr/ports/multimedia/mplayer
% make WITH_GUI=yes WITH_FREETYPE=yes install clean

The above make command is equivalent to this invocation:

% make -DWITH_GUI -DWITH_FREETYPE install clean

If you ever plan on using portupgrade to upgrade mplayer and wish to use the same arguments, you have a choice. Either count on your ability to remember to use the m switch to specify your make arguments with portupgrade:

% portupgrade -rRm '-DWITH_GUI' '-DWITH_FREETYPE' mplayer

or spend a moment and add those switches to /usr/local/etc/pkgtools.conf:

MAKE_ARGS = {
    'multimedia/mplayer-*' => 'WITH_GUI=1 WITH_FREETYPE=1',
}

Let's pick that apart, as it looks a bit complicated and the syntax is rather picky. Notice that the entire MAKE_ARGS section is enclosed within curly brackets ({ and }). Within those brackets are the particular ports and their make arguments. This means you can keep adding ports to this section, each on their own line, ensuring that all of the ports are between those brackets.

The name of the port itself must be quoted in single quotes (') and includes the name of its subdirectory in the ports collection. The name is followed by the wildcard -*.

The make arguments themselves are also enclosed between single quotes located after the =>. Note that the number 1 is used instead of the word yes and that the arguments are separated by a space.

It's worth your while to spend the few minutes it takes to add your arguments to this section whenever you first build a port that uses arguments. You'll eventually upgrade that port, and it is highly unlikely that you'll even remember that it used arguments, let alone what those actual arguments were.

Ports Tools

Let's finish this series by peeking at the tools section of the ports tree. If you haven't discovered it on your own yet, take a look at:

% more /usr/ports/Tools/scripts/README

Gee, just when you thought you knew everything there was to know about ports, you find there's a whole new stash of useful utilities. Since these are all scripts, don't forget to put a ./ in front of the name as you try out each of the scripts:

% cd /usr/ports/Tools/scripts
% ./consistency-check

I'd suggest trying out each script that piques your interest as you read its description in the README file. If you find some new favorites, consider either copying them or symlinking them to ~/bin so they will be in your path.

I hope you've enjoyed the past few articles on the ports collection. I'll be taking a break from the series over the next few months in order to write a book. Stay tuned for more details.

Dru Lavigne is a network and systems administrator, IT instructor, author and international speaker. She has over a decade of experience administering and teaching Netware, Microsoft, Cisco, Checkpoint, SCO, Solaris, Linux, and BSD systems. A prolific author, she pens the popular FreeBSD Basics column for O'Reilly and is author of BSD Hacks and The Best of FreeBSD Basics.

Read more FreeBSD Basics columns.

Return to the BSD DevCenter.

Copyright © 2009 O'Reilly Media, Inc.