runner/adt-testreport-onepackage.1

   1 .TH adt\-testreport\-onepackage 1 2007 autopkgtest "Linux Programmer's Manual"
   2 .SH NAME
   3 adt\-testreport\-onepackage \- choose one package and test it with adt-run
   4 .SH SYNOPSYS
   5 .B adt\-testreport\-onepackage
   6 .RI [ variable \fB=\fR value | settings\-file ]...
   7 .br
   8 .SH DESCRIPTION
   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 .
  14
  15 a-t-o has the following functionality:
  16
  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
  20 appropriate address.
  21
  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!
  25 .SH CONFIGURATION
  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.
  30
  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.
  39
  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.
  42
  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.
  46
  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.
  50 .SH REPORTING
  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.
  58
  59 No email is sent if there were no tests, or all the tests skipped or
  60 passed.
  61
  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).
  67
  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.
  72
  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
  77 .B suppresspackages
  78 configuration variable.  Testing frequency of these source packages is
  79 reduced, and when a problem is found the email is not sent.
  80
  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
  90 .B @p
  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),
  93 .B @v
  94 stands for the version being tested,
  95 .B @s
  96 stands for the source package name (even if a binary package generated
  97 by that source is being tested) and
  98 .B @a
  99 stands for a single at sign \fB@\fR.
 100
 101 If you an appropriately useable GPG signing key is available, you may
 102 specify
 103 .B email_signing_key
 104 which is passed to gpg's \fB-u\fR option.  Otherwise the email is not
 105 signed.
 106 .SH FILES
 107 The \fBtmp=\fR\fItmp\fR and \fBvar=\fR\fIvar\fR configuration
 108 variables name two directories which must belong solely to this
 109 instance of a-t-o.
 110
 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.
 116
 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.
 120
 121 \fItmp\fR and \fIvar\fR default to \fBtmp\fR and \fBvar\fR in a-t-o's
 122 starting directory.
 123 .SH EXIT STATUS
 124 0       a package was apparently tested
 125 .br
 126 20      adt-run reported an unexpected failure
 127 .br
 128 other   other unexpected failures including bad usage, disk full, etc.
 129
 130 When a-t-o is run in a loop, the loop should stop pending
 131 administrator intervention if a-t-o exits nonzero.
 132 .SH FILES
 133 .TP
 134 .IR tmp " (default: \fB./tmp\fR)"
 135 Temporary directory for working files.  Do not specify /tmp.
 136 .TP
 137 .IR var " (default: \fB./var\fR)"
 138 Storage directory for package testing history, score reports,
 139 logfiles, etc.
 140 .TP
 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.
 144 .TP
 145 .IB var /scores- target
 146 Report giving the score for each package, and the factors which
 147 influenced that score.
 148 .TP
 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.
 155 .TP
 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.
 159 .TP
 160 .IB var /log
 161 Logfile from a-t-o.  If a-t-runloop is being used its stdout output
 162 often makes a better logfile.
 163 .TP
 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.
 167 .SH SEE ALSO
 168 \fBadt-run\fR(1).
 169 .SH BUGS
 170 \fBIt is essential not to use the example configuration!\fR
 171 This configuration is likely to send inappropriate emails!
 172
 173 There is no documentation for the variable settings, and no error
 174 handling for detecting attempts to set incorrectly named variables.
 175
 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.
 180
 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.
 189
 190 If multiple distributions (multiple values of \fBdistro\fR) are used,
 191 a-t-o will conflate their last-tested versions.  It should use
 192 separate files.
 193
 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.
 197
 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.
 200
 201 The script lacks flexibility in many respects; many additional
 202 configuration settings and hooks are needed.
 203
 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
 209 others.
 210
 211 See \fB/usr/share/doc/autopkgtest/CREDITS\fR for the list of
 212 contributors and full copying conditions.