How to use piuparts in 5 minutes
================================

* Basic Usage
-------------

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, etch, you can
do so with:

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

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


* Some tips
-----------

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 tarbal 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 tests
----------------

By default, piuparts does 2 test:
1 - Installation and purging test.
2 - Installation, upgrade and purging 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  


* Analyzing piuparts results
----------------------------

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.







