Testing your packages with piuparts is as easy as typing at the console prompt:

# piuparts sm_0.6-1_i386.deb

Note that in order to work, piuparts has to be executed as user root, so you need to be logged as root or use sudo.

This will create a sid chroot with debootstrap, where it’ll test your package.

If you want to test your package in another release, for example, lenny, you can do so with:

# piuparts sm_0.6-1_i386.deb -d lenny

By default, this will read the first mirror from your /etc/apt/sources.list ' file. If you want to specify a different mirror you can do it with the option '-m:

# piuparts sm_0.6-1_i386.deb -m http://ftp.de.debian.org/debian

If you use piuparts on a regular basis, waiting for it to create a chroot every time takes too much time, even if you are using a local mirror or a caching tool such as approx.

Piuparts has the option of using a tarball as the contents of the initial chroot, instead of building a new one with debootstrap. A easy way to use this option is use a tarball created with pbuilder. If you are not a pbuilder user, you can create this tarball with the command (again, as root):

# pbuilder create

then you only have to remember to update this tarball with:

# pbuilder update

To run piuparts using this tarball:

# piuparts -p sm_0.6-1_i386.deb

If you want to use your own pre-made tarball:

# piuparts --basetgz=/path/to/my/tarball.tgz sm_0.6-1_i386.deb

Piuparts also has the option of using a tarball as the contents of the initial chroot, instead of building a new one with pbuilder. You can save a tarball for later use with the -s (--save) piuparts option. Some people like this, others prefer to only have to maintain one tarball. Read the piuparts manpage about the -p, -b and -s options

piuparts has a manpage too.

By default, piuparts does two tests:

The first test installs the package in a minimal chroot, removes it and purges it. The second test installs the current version in the archive of the given packages, then upgrades to the new version (deb files given to piuparts in the input), removes and purges.

If you only want to perfom the first test, you can use the option: --no-upgrade-test

When piuparts finishes all the tests satisfactorily, you will get these lines as final output:

0m39.5s INFO: PASS: All tests.
0m39.5s INFO: piuparts run ends.

Anyway, it is a good idea to read the whole log in order to discover possible problems that did not stop the piuparts execution.

If you do not get those lines, piuparts has failed during a test. The latest lines should give you a pointer to the problem with your package.

$ cat post_install_numbers

#!/bin/bash

number=`dpkg -l | wc -l`
echo "There are $number packages installed."
exit 0

$ cat post_setup_package

#!/bin/sh

echo "$PIUPARTS_OBJECT will now get tested."
exit 0

The slave machine and the piuparts-master program communicate using a simplistic line based protocol. SSH takes care of authentication, so there is nothing in the protocol for that. The protocol is transaction based: the slave gives a command, the master program responds. Commands and responses can be simple (a single line) or long (a status line plus additional data lines). Simple commands and responses are of the following format:

'keyword arg1 arg2 arg3 ... argN'

The keyword is a command or status code ("ok"), and it and the arguments are separated by spaces. An argument may not contain a space.

A long command or response is deduced from the context: certain commands always include additional data, and certain commands always get a long response, if successful (error responses are always simple). The first line of a long command or response is the same as for a simple one, the additional lines are prefixed with a space, and followed by a line containing only a period.

A sample session (">>" indicates what the slave sends, "<<" what the master responds with):

<< hello
>> pass liwc 1.2.3-4
>>  The piuparts
>>  log file comes
>>  here
>> .
<< ok
>> reserve
<< ok vorbisgain 2.3-4

Here the slave first reports a successful test of package liwc, version 1.2.3-4, and sends the piuparts log file for it. Then it reserves a new package to test and the master gives it vorbisgain, version 2.3-4.

The communication always starts with the master saying "hello". The slave shall not speak until the master has spoken.

Commands and responses in this protocol:

Command: reserve
Success: ok <packagename> <packageversion>
Failure: error

Slave asks master to reserve a package (a particular version of it) for the slave to test. The slave may reserve any number of packages to test. If the transaction fails, there are no more packages to test, and the slave should disconnect, wait some time and try again.

Command: unreserve <packagename> <packageversion>
Success: ok

Slave informs master it cannot test the desired version of a package (perhaps it went away from the mirror?).

Command: pass <packagename> <packageversion>
          log file contents
         .
Success: ok

Slave reports that it has tested a particular version of a package and that the package passed all tests. Master records this and stores the log file somewhere suitable.

Command: fail <packagename> <packageversion>
          log file contents
         .
Success: ok

Same as "pass", but package failed one or more tests.

Command: untestable <packagename> <packageversion>
          log file contents
         .
Success: ok

Slave reports that a particular package is untestable, possibly because it insists on interacting with the user.

In all cases, if the master cannot respond with "ok" (e.g., because of a disk error storing a log file), it aborts and the connection fails. The slave may only assume the command has succeeded if the master responds with "ok".

The master may likewise abort, without an error message, if the slave sends garbage, or sends too much data.

piuparts-master, piuparts-slave and piuparts-report share the configuration file /etc/piuparts/piuparts.conf. The syntax is defined by the Python ConfigParser class, and is, briefly, like this:

    [master]
    foo = bar

If you want to run piuparts-report (which is only+very useful if you run piuparts in master-slave mode), you need to apt-get install python-rpy r-recommended r-base-dev. For more information see svn://svn.debian.org/svn/piuparts/piatti/README.txt.