[[!tag ubuntu debian presentation piuparts]]

The following is the text on which I based my Ubuntu Developer Week session on piuparts. The actual session transcript can be found at https://wiki.ubuntu.com/MeetingLogs/devweek0901/PackageTesting.

What is piuparts?

Piuparts is a tool to test that a .deb package can be installed and removed, and installed, upgraded, and removed.

It is primarily meant for people who maintain and upload packages.

It works by constructing a chroot with a minimal Debian or Ubuntu installation, and then installing the package being tested into the chroot. It also installs the dependencies.

After this is done, it removes and then purges the package, and any other packages that got installed.

Finally, it compares the state of the chroot before the package and its dependencies were installed, and after they got purged. It checks that all files are still there, and haven't been changed, and that there are no new files.

Obviously, some things will always change, such as log files. Piuparts ignores those.

Basic usage

The very basic way of using piuparts is as follows:

piuparts foo.deb

Note that this can take a long time, and can produce quite a lot of output. You probably don't want to run the command just now.

Because piuparts builds a chroot, it must run as root. Prefix the command with sudo. To avoid people accidentally copypasting commands when they shouldn't, I'm not prefixing it in examples.

This will run the install/remove/purge test. If the package is already in the archive, it will also test that the package can be upgraded from the archive to the .deb you give.

The other way of running piuparts is as follows:

piuparts -a foo

Here foo is the name of a package. Piuparts will fetch it from the archive and test it. This will, obviously, not test upgrades since there is no newer package.

You can also test upgrading from release to release:

piuparts -a -d dapper -d hardy -d intrepid -d jaunty foo

This will take even longer.

Interpreting the results

Piuparts outputs quite a lot of text when it runs. This is because when I was developing it, it was quite useful to me to see what was going on and figure out when things broke. I never got around to fixing things so that it was nice to use for other people.

Since the output can be pretty large, up to several hundred kilobytes, it is best to capture it in a file:

piuparts -l foo.log foo.deb

The output will go to the named file, and also to the screen.

Every line of output piuparts outputs is prefixed with a relative timestamp (minutes and seconds since piuparts started), and a log level: DUMP, DEBUG, INFO, WARNING, ERROR, FATAL. DUMP and DEBUG you can mostly ignore; unfortunately there is no switch to let you do that at the moment.

The useful stuff is in INFO, and in ERROR if it is there. Therefore, the way to read a piuparts log file is to grep for INFO and ERROR. Then, if those don't make any sense, read DUMP and DEBUG as well.

When piuparts finishes, it outputs one of two things: either a PASS or a FAIL message. They look like these:

2m11.0s INFO: PASS: All tests.
5m33.8s ERROR: Broken symlinks:

Obviously these were from different runs.

Speeding it up

It can take a long time to construct the chroot. Since most package maintainers use pbuilder, and it constructs a chroot too, piuparts provides the --pbuilder (-p) option to use the pbuiler tarball to create the chroot. This makes things much faster.

On the server I used to use to run piuparts on all packages in Debian, a couple of years ago, piuparts took only a few seconds per typical small package.

Testing packages for newer releases

Piuparts can test packages for newer releases, if you use the debootstrap package from backports.

Gotchas

Piuparts works on a chroot. This means that it does not properly protect the host system. A malicious package, or a really unfortunately buggy package, may ruin the host system. In the three years since I wrote piuparts, I have had that happen, but it's possible. The solution, of course, is to fix piuparts to use KVM.

Piuparts can use a lot of CPU, RAM, disk I/O, and network bandwidth. Be prepared for that.

Some of the checks piuparts does often fail, but they don't matter much in real life. The manual page has lists all options, so you can look there if something annoys you. For example, piuparts checks that all symlinks point somewhere that actually exists. For some reason, this is triggered fairly often, so you can disable it with the --no-symlinks (-N) option.

For some reason piuparts in Ubuntu defaults to gutsy, since it hasn't been updated since the hardy release. You can blame me for that. Actually, don't blame me, file a bug in Launchpad, and subscribe me to it (liw on Launchpad). You can work around this by specifying the distribution manually with the -d option:

piuparts -d jaunty foo

Summary

Do this:

sudo piuparts -d jaunty -p -l foo.log foo.deb

and grep foo.log for INFO and ERROR, and read surrounding text.