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.  a-t-o has the following
  12 functionality:
  13
  14 a-t-o downloads the Sources file, chooses a package to test (see
  15 below), downloads its source, invokes adt-run, writes a report
  16 describing the outcome, and emails the report to some appropriate
  17 address.
  18
  19 \fBWARNING\fR - it is essential to reconfigure this program before
  20 use, as the supplied examples will \fBsend emails\fR to people who
  21 will become \fBvery upset\fR with you!
  22 .SH CONFIGURATION
  23 Command-line arguments containing \fB=\fR are interpreted by a-t-o
  24 with \fBeval\fR; other arguments are sourced using \fB.\fR,
  25 in each case interpreted as bash script.  Configuration fragment
  26 authors should bear in mind that a-t-o uses \fBset -e\fR.
  27
  28 Various variables can be set for useful effect.  A selection of the
  29 most usual ones, with default values, can be seen at the top of the
  30 a-t-o script itself.  Certain others are mentioned in this manpage.
  31 There is no exhaustive list and no documentation of the semantics.
  32 .SH PACKAGE SELECTION
  33 a-t-o maintains a record of when each package was last tested, what
  34 version was tested, and whether the package had any tests.
  35
  36 This record is used to choose which package should be tested next:
  37 packages which have changed since the last test are preferred, as are
  38 packages which didn't lack tests last time they were examined.
  39
  40 If the configuration sets \fBpkg\fR to a package name (for example by
  41 passing \fBpkg=\fR\fIpackage-name\fR), this overrides
  42 a-t-o's package selection algorithm.
  43 .SH REPORTING
  44 If \fBinteractive\fR is set to \fBtrue\fR (the default), a-t-o will
  45 not redirect the output from adt-run and will not email anyone,
  46 although the start of the email which would have been sent is sent to
  47 stdout.  If \fBinteractive\fR is \fBfalse\fR, a-t-o sends an email to
  48 its administrator (if a-t-o considers that the testing machinery is
  49 broken, or if \fBmaintainer_email_override\fR is set), or otherwise to
  50 the package maintainer.
  51
  52 No email is sent if there were no tests, or all the tests skipped or
  53 passed.
  54
  55 The emailed report contains a summary of the outcome of the tests, and
  56 the output from adt-run.  Additionally, if an email is sent, the build
  57 trees, test results, and so forth, will be uploaded to the location
  58 specified with the \fBdest\fR* options (see the
  59 \fBonepackage-config\fR example configuration file).
  60
  61 Some vague progress information is printed to a-t-o's stdout.
  62 .SH FILES
  63 The \fBtmp=\fR\fItmp\fR and \fBvar=\fR\fIvar\fR configuration
  64 variables name two directories which must belong solely to this
  65 instance of a-t-o.
  66
  67 \fItmp\fR will be erased by a-t-o at startup and then used for
  68 temporary files.  It is not cleaned up afterwards; it is assumed that
  69 the next run of a-t-o will do that.
  70
  71 \fIvar\fR is used to record the state, including the information about
  72 each package used for package selection.  \fIvar\fR\fB/log\fR contains
  73 a one-line record of each test run and may need to be rotated.
  74
  75 \fItmp\fR and \fIvar\fR default to \fBtmp\fR and \fBvar\fR in a-t-o's
  76 starting directory.
  77 .SH EXIT STATUS
  78 0       a package was apparently tested
  79 .br
  80 20      adt-run reported an unexpected failure
  81 .br
  82 other   other unexpected failures including bad usage, disk full, etc.
  83
  84 When a-t-o is run in a loop, the loop should stop pending
  85 administrator intervention if a-t-o exits nonzero.
  86 .SH SEE ALSO
  87 \fBadt-run\fR(1).
  88 .SH BUGS
  89 \fBIt is essential not to use the example configuration!\fR
  90 This configuration is likely to send inappropriate emails!
  91
  92 There is no documentation for the variable settings, and no error
  93 handling for detecting attempts to set incorrectly named variables.
  94
  95 The tuning parameters for the package selection algorithm cannot be
  96 adjusted.  This algorithm is not hugely sophisticated.  There should
  97 be a facility for explicitly requesting retests (other than setting
  98 \fBpkg\fR); there should be some kind of manual prioritisation queue.
  99
 100 a-t-o cannot choose a distrorelease (eg, dapper, feisty, etch, sid) or
 101 suite (eg main, non-free, universe); the caller must do that.
 102
 103 Configuration by the use of bash fragments is rather unsophisticated.
 104
 105 The script lacks flexibility in many respects; many additional
 106 configuration settings and hooks are needed.
 107 .SH AUTHORS AND COPYRIGHT
 108 This manpage is part of autopkgtest, a tool for testing Debian binary
 109 packages.  autopkgtest is Copyright (C) 2006-2007 Canonical Ltd and
 110 others.
 111
 112 See \fB/usr/share/doc/autopkgtest/CREDITS\fR for the list of
 113 contributors and full copying conditions.