File: README.txt

package info (click to toggle)
piuparts 1.0.0
  • links: PTS, VCS
  • area: main
  • in suites: buster, sid
  • size: 2,108 kB
  • sloc: python: 7,409; sh: 3,989; makefile: 167
file content (291 lines) | stat: -rw-r--r-- 9,382 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
piuparts README
---------------

Author: Lars Wirzenius
Email: <liw@iki.fi>

After reading this README you probably also want to have a look
at the piuparts manpage, to learn about the available options.
But read this document first!

== Introduction

piuparts is a tool for testing that .deb packages can be
installed, upgraded, and removed without problems. The
name, a variant of something suggested by Tollef Fog
Heen, is short for "package installation, upgrading, and
removal testing suite".

piuparts is licensed under the GNU General Public License,
version 2, or (at your option) any later version.

https://piuparts.debian.org has been testing the Debian archive
since the Lenny release in 2009, though responsible maintainers
run piuparts locally before uploading packages to the archive.


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

----
# piuparts ./sm_0.6-1_i386.deb -d testing
----

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

It's possible to use -d more than once. For example, to do a first
installation in stable, then upgrade to testing, then upgrade to
unstable and then upgrade to the local package use this:

----
# piuparts -d stable -d testing -d unstable ./sm_0.6-1_i386.deb
----


=== Some tips

piuparts also has a manpage, where all available options are explained.

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

While pbuilder itself supports using cdebootstrap, this is not
fully supported by piuparts: You will need to use debootstrap
or use the '--warn-on-debsums-errors' option for piuparts and then
you will still see spurious warnings in the log.

=== Piuparts tests

By default, piuparts does two tests:

. Installation and purging test.
. 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'

=== Testing packages in the config-files-remaining state

The --install-remove-install option modifies the three piuparts
tests in order to test package installation while config files
from a previous installation are remaining, but the package itself
was removed inbetween.
This exercises different code paths in the maintainer scripts.

. Installation and purging test: install, remove, install again
 and purge.
. Installation, upgrade and purging test: install the old version,
 remove, install the new version and purge.
. Distupgrade test: install the version from the first
 distribution, remove, distupgrade to the last distribution,
 install the new version.

=== 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.

== Custom scripts with piuparts

You can specify several custom scripts to be run inside piuparts.
You have to store them in a directory and give it as argument to
piuparts: '--scriptsdir=/dir/with/the/scripts'
This option can be given multiple times. The scripts from all
directories will be merged together (and later ones may overwrite
earlier scripts with the same filename).

By default this is *not* set to anything. Have a look at
'/etc/piuparts/scripts*' to learn which scripts and script
directories are shipped by the package.

The script prefix determines in which step it is executed. You
can run several scripts in every step, they are run in
alphabetical order.

The scripts need to be executable and are run *inside* the piuparts
chroot and can only be shell scripts. If you want to run Python or
Perl scripts, you have to install Python or Perl. The chroot where
piuparts is run is minimized and does not include Perl.

The variable PIUPARTS_OBJECTS is set to the packages currently
being tested (seperated by spaces, if applicable) or the .changes
file(s) being used.  So when running in master-slave mode, it
will be set to the (one) package being tested at a time.

Depending on the current test, the variable PIUPARTS_TEST is set
to

. 'install' (installation and purging test),
. 'upgrade' (installation, upgrade and purging tests) or
. 'distupgrade'.

During the 'upgrade' and 'distupgrade' tests, the variable
PIUPARTS_PHASE is set to one of the following values:

. 'install' while initially installing the packages from the
 repository,
. 'upgrade' when upgrading to the .debs,
. 'distupgrade' while reinstalling the packages after
 'apt-get dist-upgrade' to ensure they were not removed accidently
During the 'install' test, the PIUPARTS_PHASE variable is set to
'install'.

The current distribution is available in the variable
PIUPARTS_DISTRIBUTION.

The following prefixes for scripts are recognized:

'post_chroot_unpack' - after the chroot has been unpacked/debootrapped.
Before the chroot gets updated/dist-upgraded initially.

'post_setup_' - after the *setup* of the chroot is finished.
Before metadata of the chroot is recorded for later comparison.

'pre_test_' - at the beginning of each test. After metadata of
the chroot was recorded for later comparison.

'is_testable_' - before *installing* your package. If this script
returns a non-zero return value, the installation of the package
will be skipped. With a return value of 1 the test will be reported
as successful, but with a return value if 2 it will be reported as
failed.
Use this to flag packages that cannot be be tested with piuparts
by design (e.g. usrmerge), require not publicly available external
ressources (e.g. some downloader packages) or are broken beyond
repair (e.g. buggy packages in archived releases). Use the return
value of 2 for seriously broken packages that can break piuparts.

'pre_install_' - before *installing* your package. Depending on
the test, this may be run multiple times. The PIUPARTS_TEST and
PIUPARTS_PHASE variables can be used to distinguish the cases.

'post_install_' - after *installing* your package and its
dependencies.  Depending on the test, this may be run multiple
times. The PIUPARTS_TEST and PIUPARTS_PHASE variables can be used
to distinguish the cases.

'pre_remove_' - before *removing* your package.
Depending on the test, this may be run multiple times.

'post_remove_' - after *removing* your package.
Depending on the test, this may be run multiple times.

'post_purge_' - after *purging* your package.
Depending on the test, this may be run multiple times.

'post_test_' - at the end of each test. Right before performing
final checks and comparing the chroot with the reference chroot
metadata.

'pre_distupgrade_' - before *upgrading* the chroot to the *next
distribution*. The next distribution is available in the variable
PIUPARTS_DISTRIBUTION_NEXT.

'post_distupgrade_' - after *upgrading* the chroot to the *next
distribution*. The previous distribution is available in the
variable PIUPARTS_DISTRIBUTION_PREV.


=== Example custom scripts:

'$ 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_OBJECTS will now get tested."
exit 0
----


== Distributed testing

This is described in README_server.txt.

// vim: set filetype=asciidoc: