1 .TH adt\-testreport\-onepackage 1 2007 autopkgtest "Linux Programmer's Manual"
3 adt\-testreport\-onepackage \- choose one package and test it with adt-run
5 .B adt\-testreport\-onepackage
6 .RI [ variable \fB=\fR value | settings\-file ]...
9 .B adt\-testreport\-onepackage
10 is a rather ad-hoc script which chooses a package to test, calls
11 adt-run, and reports the results. In a service installation
12 a-t-o is usually called from
13 .BR adt\-testreport\-runloop .
15 a-t-o has the following functionality:
17 a-t-o downloads the Sources or Packages file, chooses a package to
18 test (see below), downloads its source, invokes \fBadt\-run\fR, writes a
19 report describing the outcome, and emails the report to some
22 \fBWARNING\fR - it is essential to reconfigure this program before
23 use, as the supplied examples will \fBsend emails\fR to people who
24 will become \fBvery upset\fR with you!
26 Command-line arguments containing \fB=\fR are interpreted by a-t-o
27 with \fBeval\fR; other arguments are sourced using \fB.\fR,
28 in each case interpreted as bash script. Configuration fragment
29 authors should bear in mind that a-t-o uses \fBset -e\fR.
31 Various variables can be set for useful effect. A selection of the
32 most usual ones, with default values, can be seen at the top of the
33 a-t-o script itself. Certain others are mentioned in this manpage.
34 There is no exhaustive list and no documentation of the semantics.
35 .SH PACKAGE AND TEST SELECTION
36 The configuration variable \fBtarget\fR specifies whether a source
37 package, or a binary package, is to be tested. It should be set to
38 \fBsource\fR or \fBbinary\-\fR\fIarch\fR.
40 a-t-o maintains a record of when each package was last tested, what
41 version was tested, and whether the package had any tests.
43 This record is used to choose which package should be tested next:
44 packages which have changed since the last test are preferred, as are
45 packages which didn't lack tests last time they were examined.
47 If the configuration sets \fBpkg\fR to a package name (for example if
48 \fBpkg=\fR\fIpackage\fR is passed as an argument), this overrides
49 a-t-o's package selection algorithm.
51 If \fBinteractive\fR is set to \fBtrue\fR (the default), a-t-o will
52 not redirect the output from adt-run and will not email anyone,
53 although the start of the email which would have been sent is sent to
54 stdout. If \fBinteractive\fR is \fBfalse\fR, a-t-o sends an email to
55 its administrator (if a-t-o considers that the testing machinery is
56 broken, or if \fBmaintainer_email_override\fR is set), or otherwise to
57 the package maintainer.
59 No email is sent if there were no tests, or all the tests skipped or
62 The emailed report contains a summary of the outcome of the tests, and
63 the output from adt-run. Additionally, if an email is sent, the build
64 trees, test results, and so forth, will be uploaded to the location
65 specified with the \fBdest\fR* options (see the
66 \fBonepackage-config\fR example configuration file).
68 Some vague progress information is printed to a-t-o's stdout.
69 .SH AUTOMATIC BUG REPORTING
70 With suitable configuration, a-t-o can be made to automatically file
71 bugs when it detects a problem with a package.
73 It is necessary to avoid the submission of multiple reports for the
74 same problem. This is done by fetching somehow a list of the open bug
75 reports from the relevant bug system and extracting a list of the
76 source package names. These are to be listed in the file named by the
78 configuration variable. Testing frequency of these source packages is
79 reduced, and when a problem is found the email is not sent.
81 When the system does decide to send an email about a package it will
82 normally email the maintainer as determined from the package's control
83 file. To submit bugs instead, set
84 .B maintainer_email_override
85 to the submission email address for the bug system. You must also set
86 .BR email_sourcepackage_header and email_binarypackage_header
87 to appropriate templates. These templates specify what information
88 should be prepended at the top of the body (not the RFC822 header) of
89 the mail to be sent. In these templates
91 stands for the package name being tested (the source package name for
92 source packages or the binary package name for binary package tests),
94 stands for the version being tested,
96 stands for the source package name (even if a binary package generated
97 by that source is being tested) and
99 stands for a single at sign \fB@\fR.
101 If you an appropriately useable GPG signing key is available, you may
104 which is passed to gpg's \fB-u\fR option. Otherwise the email is not
107 The \fBtmp=\fR\fItmp\fR and \fBvar=\fR\fIvar\fR configuration
108 variables name two directories which must belong solely to this
111 \fItmp\fR will be erased by a-t-o at startup and then used for
112 temporary files. It is not cleaned up afterwards; it is assumed that
113 the next run of a-t-o will do that. \fItmp\fR should not be made to
114 refer to a symlink or mountpoint as a-t-o would break the link or
115 attempt to remove the mountpoint; specify a subdirectory instead.
117 \fIvar\fR is used to record the state, including the information about
118 each package used for package selection. \fIvar\fR\fB/log\fR contains
119 a one-line record of each test run and may need to be rotated.
121 \fItmp\fR and \fIvar\fR default to \fBtmp\fR and \fBvar\fR in a-t-o's
124 0 a package was apparently tested
126 20 adt-run reported an unexpected failure
128 other other unexpected failures including bad usage, disk full, etc.
130 When a-t-o is run in a loop, the loop should stop pending
131 administrator intervention if a-t-o exits nonzero.
134 .IR tmp " (default: \fB./tmp\fR)"
135 Temporary directory for working files. Do not specify /tmp.
137 .IR var " (default: \fB./var\fR)"
138 Storage directory for package testing history, score reports,
141 .IB var /lastinfo- target
142 Information about the last test and outcome for each package. This is
143 used for package scoring and selection.
145 .IB var /scores- target
146 Report giving the score for each package, and the factors which
147 influenced that score.
149 .IB var /emailed/last- pkg , emailaddress
150 The summary of the last message sent to emailaddress about pkg.
151 If the configuration variable \fBsuppressrepeatedemails\fR is
152 \fBtrue\fR then this is used to ensure that a maintainer (or the
153 test installation operator) is only emailed when the situation for a
154 particular package changes.
156 .IB var /emailed/diff- pkg
157 Changes to the summary for the last email sent regarding pkg.
158 This can be used to find out why an email was sent.
161 Logfile from a-t-o. If a-t-runloop is being used its stdout output
162 often makes a better logfile.
164 .IB destrsynchead / destdirfin / pkg
165 Full logfile and other information is rsync'd here. It is assumed
166 that this area will be published via a webserver.
170 \fBIt is essential not to use the example configuration!\fR
171 This configuration is likely to send inappropriate emails!
173 There is no documentation for the variable settings, and no error
174 handling for detecting attempts to set incorrectly named variables.
176 The tuning parameters for the package selection algorithm cannot be
177 adjusted. This algorithm is not hugely sophisticated. There should
178 be a facility for explicitly requesting retests (other than setting
179 \fBpkg\fR); there should be some kind of manual prioritisation queue.
181 Distributions whose management systems permit archive skew (that is,
182 distributions whose contents sometimes contains unsatisfiable
183 dependencies) cause pathological behaviour. a-t-o will prefer to test
184 the newly-changed packages and immediately detect and report the
185 archive skew as test failures. It would be better if it would detect
186 this situation and not report a failure unless the problem persisted.
187 And there ought to be an option to have it not try to test a package
188 until its version has been stable for a nominated period.
190 If multiple distributions (multiple values of \fBdistro\fR) are used,
191 a-t-o will conflate their last-tested versions. It should use
194 Cross-architecture testing (where host and target have differing
195 Debian architectures) has not been tested and is likely to have
196 bugs both in interfaces and implementation.
198 a-t-o should be capable of automatically closing bug reports if it
199 retests a package and finds that the bug is fixed.
201 The script lacks flexibility in many respects; many additional
202 configuration settings and hooks are needed.
204 There is no facility for sharing test queues across multiple
205 machines. This means that it is difficult to share the testing load.
206 .SH AUTHORS AND COPYRIGHT
207 This manpage is part of autopkgtest, a tool for testing Debian binary
208 packages. autopkgtest is Copyright (C) 2006-2007 Canonical Ltd and
211 See \fB/usr/share/doc/autopkgtest/CREDITS\fR for the list of
212 contributors and full copying conditions.