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
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
|
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN"
"file:///usr/share/xml/docbook/schema/dtd/4.1.2/docbookx.dtd"
[]>
<refentry>
<refentryinfo>
<title>piuparts(1)</title>
<address>
<email>liw@iki.fi</email>
</address>
<author>
<firstname>Lars</firstname>
<surname>Wirzenius</surname>
</author>
<date>2005-07-10</date>
</refentryinfo>
<refmeta>
<refentrytitle>piuparts</refentrytitle>
<manvolnum>1</manvolnum>
</refmeta>
<refnamediv>
<refname>piuparts</refname>
<refpurpose>.deb installation, upgrade, and removal
testing suite</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>piuparts</command>
<arg><option>-apvV</option></arg>
<arg><option>-d</option> <replaceable>distro</replaceable></arg>
<arg><option>-i</option> <replaceable>filename</replaceable></arg>
<arg><option>-I</option> <replaceable>regexp</replaceable></arg>
<arg><option>-l</option> <replaceable>logfile</replaceable></arg>
<arg><option>-m</option> <replaceable>url</replaceable></arg>
<arg><option>--bindmount</option> <replaceable>dir</replaceable></arg>
<arg><replaceable>package</replaceable></arg>
<arg><replaceable>changes_file</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>DESCRIPTION</title>
<para><command>piuparts</command> tests that Debian packages
handle installation, upgrading, and removal correctly. It does
this by creating a minimal Debian installation in a chroot, and
installing, upgrading, and removing packages in that
environment, and comparing the state of the directory tree
before and after. <command>piuparts</command> reports any files
that have been added, removed, or modified during this
process.</para>
<para><command>piuparts</command> is meant as a quality
assurance tool for people who create Debian packages to test
them before they upload them to the Debian package
archive.</para>
<para>By default, piuparts can do three different tests:</para>
<orderedlist>
<listitem><para>A simple install-purge test within one
Debian distribution (chosen with the <option>-d</option>
option, <literal>unstable</literal> by default). It sets up
the chroot with the desired distribution, then installs and
purges the packages, and reports problems.</para></listitem>
<listitem><para>A simple install-upgrade-purge test within
one Debian distribution. This test is like the install-purge
test, but install the packages first via
<command>apt-get</command> and then from the package files
given on the command line. If the command line has package
names (option <option>-a</option> used), or the packages are
not known to <command>apt-get</command> (new packages), this
test is skipped, otherwise it is performed
automatically.</para></listitem>
<listitem><para>An upgrade test between Debian releases.
This test is enabled by using the <option>-d</option> option
multiple times and disables the other two tests. It sets up
the chroot with the first distribution named, then upgrades
it to each successive one, and then remembers the directory
tree state at the end. After this, it starts over with the
chroot of the first distribution, installs the desired
packages (via <command>apt-get</command>), and does the
successive upgrading (via <command>apt-get
dist-upgrade</command>). Then, if package files (and not
just package names) were given on the command line, it
installs them. Finally, it reports problems against the
state of the directory tree at the last distribution
compared with the state without the packages having been
installed. This test can be quite slow to
execute.</para>
<para>Note that this does not work with experimental,
because apt-get does not automatically upgrade to packages in
experimental. To test a particular package or group of packages
in experimental, use the second test.</para></listitem>
</orderedlist>
<para>Command line arguments are the paths to package files
(e.g., <filename>piuparts_1.0-1_all.deb</filename>), paths to
changes files (e.g.,
<filename>piuparts_1.0-1_i386.changes</filename>),
or names of packages, if the <option>--apt</option> option is
given. </para>
<para>When processing changes files, by default, every package in a
changes file will be processed together with all individual packages
given on the command line. Then each package given on the command line
is processed in a single group. If the
<option>--single-changes-list</option> is used, the packages in every
changes file are processed together along with any individual packages
that were given on the command line.</para>
<para><command>piuparts</command> outputs to the standard output
some log messages to show what is going on. If a
log file is used, the messages go there as well.</para>
<para><command>piuparts</command> needs to be run as root.</para>
</refsect1>
<refsect1>
<title>OPTIONS</title>
<para>Options must come before the other command line
arguments.</para>
<variablelist>
<varlistentry>
<term><option>-a</option></term>
<term><option>--apt</option></term>
<listitem>
<para>The <replaceable>package</replaceable> arguments
on the command line are to be treated as package names
and installed via <command>apt-get</command> instead
of being names of package files, to be installed
via <command>dpkg -i</command>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-b</option> <replaceable>tarball</replaceable></term>
<term><option>--basetgz=</option><replaceable>tarball</replaceable></term>
<listitem>
<para>Use <replaceable>tarball</replaceable> as the
contents of the initial chroot, instead of building
a new one with <command>debootstrap</command>.</para>
<para>The tarball can be created with the
<option>-s</option> option, or you can use one that
pbuilder has created (see <option>-p</option>). If
you create one manually, make sure the root of the
chroot is the root of the tarball.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-d</option> <replaceable>name</replaceable></term>
<term><option>--distribution=</option><replaceable>name</replaceable></term>
<listitem>
<para>Which Debian distribution to use: a code name
(etch, lenny, sid) or experimental. The default is
sid (i.e, unstable).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-D</option> <replaceable>flavor</replaceable></term>
<term><option>--defaults</option> <replaceable>flavor</replaceable></term>
<listitem>
<para>Use default settings suitable for a particular
<replaceable>flavor</replaceable> of Debian: either
<literal>debian</literal> or <literal>ubuntu</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-i</option> <replaceable>filename</replaceable></term>
<term><option>--ignore=</option><replaceable>filename</replaceable></term>
<listitem>
<para>Add a filename to the list of filenames to be
ignored when comparing changes before and after
installation. By default,
<command>piuparts</command> ignores files that
always change during a package installation and
uninstallation, such as <command>dpkg</command>
status files. The filename should be relative to the
root of the chroot (e.g.,
<filename>var/lib/dpkg/status</filename>). This
option can be used as many times as
necessary.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-I</option> <replaceable>regexp</replaceable></term>
<term><option>--ignore-regexp=</option><replaceable>regexp</replaceable></term>
<listitem>
<para>Add a regular expression pattern to the list
of patterns for filenames to be ignored when
comparing changes before and after installation.
This option can be used as many times as
necessary.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-k</option></term>
<term><option>--keep-tmpdir</option></term>
<listitem>
<para>Don't remove the temporary directory for
the chroot when the program ends.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--keep-sources-list</option></term>
<listitem>
<para>Don't modify the chroot's etc/apt/sources.list (only
makes sense with <option>--basetgz</option>).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--warn-on-others</option></term>
<listitem>
<para>Print a warning rather than failing if files are
left behind, modified, or removed by a package that was
not given on the command-line.</para>
<para>This way, you can basically isolate the purge test
to your own packages. If a package that is brought in as
a dependency doesn't purge cleanly, the test will not
fail because of it (but a warning message will be
printed).</para>
<para>Behavior with multple packages given on the
command-line could be problematic, particularly if the
dependency tree of one package in the list includes
another in the list. Therefore, it is recommended to
use this option with one package at a time.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--skip-minimize</option></term>
<listitem>
<para>Allow skip minimize chroot step. This is useful when
you want to test several packages with piuparts. You can
prepare a tarball already minimized and skip this step in all the
tests.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--list-installed-files</option></term>
<listitem>
<para>List the files added to the chroot after the installation
of the package and after the installation of the package
dependencies.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--no-upgrade-test</option></term>
<listitem>
<para>Skip testing upgrade from an existing version in the
archive.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--skip-cronfiles-test</option></term>
<listitem>
<para>Skip testing the output from the cron files left in the
system after remove a package.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>---scriptsdir=<replaceable>DIR</replaceable></option></term>
<listitem>
<para>Directory where are placed the custom scripts. For more information
about this, read custom-scripts.txt</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-l</option> <replaceable>filename</replaceable></term>
<term><option>--log-file=</option><replaceable>filename</replaceable></term>
<listitem>
<para>Write log file to
<replaceable>filename</replaceable> in addition to
the standard output.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-m</option> <replaceable>url</replaceable></term>
<term><option>--mirror=</option><replaceable>url</replaceable></term>
<listitem>
<para>Which Debian mirror to use. The default is the
first mirror named in
<filename>/etc/apt/sources.list</filename> or
<filename>http://ftp.debian.org/</filename> if none is
found. This option may be used multiple times to use
multiple mirrors. Only the first mirror is used with
<command>debootstrap</command>.</para>
<para>The 'components' that are used for a mirror
can also be set with this option: a space separated
list within the same argument (so you need to quote
the entire argument in the shell). If no components
are given explicitly, the usual Debian components
are used (<literal>main</literal>,
<literal>contrib</literal>, and
<literal>non-free</literal>). For the mirrors read from
<filename>/etc/apt/sources.list</filename>, the
components are read from the same place.</para>
<para>Note that <literal>file:</literal> addresses
works if the directories are made accessible from within
the chroot with <option>--bindmount</option>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--bindmount=</option><replaceable>dir</replaceable></term>
<listitem>
<para>Bind-mount a directory inside the chroot.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-n</option></term>
<term><option>--no-ignores</option></term>
<listitem>
<para>Forget all built-in and other ignores that
have been set so far. Any <option>-i</option> or
<option>-I</option> arguments that come after
this one will be obeyed, but none of the ones
that come before.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-N</option></term>
<term><option>--no-symlinks</option></term>
<listitem>
<para>Don't check for broken symlinks.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-p</option></term>
<term><option>--pbuilder</option></term>
<listitem>
<para>Use
<filename>/var/cache/pbuilder/base.tgz</filename> as
the base tarball. This is a shorthand so that you
don't need to use <option>-b</option> for it.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-s</option> <replaceable>filename</replaceable></term>
<term><option>--save=</option><replaceable>filename</replaceable></term>
<listitem>
<para>Save the chroot, after it has been set up, as
a tarball into <replaceable>filename</replaceable>.
It can then be used with <option>-b</option>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-t</option> <replaceable>directory</replaceable></term>
<term><option>--tmpdir=</option><replaceable>directory</replaceable></term>
<listitem>
<para>Use <replaceable>directory</replaceable> as the place
where temporary files and directories are created. The
default is the environment variable <envar>TMPDIR</envar>,
or <filename>/tmp</filename> if not set.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--single-changes-list</option></term>
<listitem>
<para>When processing changes files, piuparts will process
the packages in each individual changes file seperately.
This option will set piuparts to scan the packages of all
changes files together along with any individual package
files that may have been given on the command line.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-v</option></term>
<term><option>--verbose</option></term>
<listitem>
<para>This option no longer has any meaning, but it
is still accepted for backwards compatibility.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-V</option></term>
<term><option>--version</option></term>
<listitem>
<para>Write out the version number of the
program.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>EXAMPLES</title>
<para>Assume that you have just built a new version of your
Debian package, to be uploaded to Debian unstable. It is in
<filename>../foo_1.0-2_i386.deb</filename> and you would
like to know whether it installs and uninstalls properly.
Here's what you would do:</para>
<programlisting>piuparts ../foo_1.0-2_i386.deb</programlisting>
<para>If the package exists in the Debian archive already,
the above command also tests that it upgrades properly.</para>
<para>To do the same test, but using a particular mirror,
and only the <literal>main</literal> component, you would
do this:</para>
<programlisting
>piuparts -m 'http://gytha/debian main' ../foo_1.0-2_i386.deb</programlisting>
<para>If you want to do the same as above but for your changes
files, pass in your changes files when running piuparts, and
piuparts will process each package in the changes files as though
you had passed all those packages on the command line to piuparts
yourself. For example:</para>
<programlisting>piuparts ../foo_1.0-2_i386.changes</programlisting>
<programlisting
>piuparts -m 'http://gytha/debian main' ../foo_1.0-2_i386.changes</programlisting>
<para>If you want to test that a package installs properly
in the stable (etch) Debian release, then can be upgraded
to the testing (lenny) and unstable (sid) versions, and then
uninstalled without problems, you would give the following
command:</para>
<programlisting
>piuparts -a -d etch -d lenny -d sid foo</programlisting>
</refsect1>
<refsect1>
<title>ENVIRONMENT</title>
<variablelist>
<varlistentry>
<term><envar>TMPDIR</envar></term>
<listitem>
<para>Location for temporary files and directories.
If not set, use <filename>/tmp</filename>. See
also the <option>-t</option> (<option>--tmpdir</option>)
option.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>NOTES</title>
<para>Outputs of commands run by <command>piuparts</command>
are limited to the last megabyte. To change this limit, the
source code needs to be edited.</para>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>pbuilder</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>debootstrap</refentrytitle>
<manvolnum>8</manvolnum>
</citerefentry>
</para>
</refsect1>
<refsect1>
<title>AUTHOR</title>
<para>Lars Wirzenius (liw@iki.fi).</para>
</refsect1>
</refentry>
|