runner/adt-testreport-runloop.1

   1 .TH adt\-testreport\-runloop 1 2007 autopkgtest "Linux Programmer's Manual"
   2 .SH NAME
   3 adt\-testreport\-runloop \- repeatedly choose and test packages
   4 .SH SYNOPSYS
   5 .B adt\-testreport\-runloop
   6 .RI [[\fB!@\fR] variable \fB=\fR value |[\fB!@\fR] settings\-file ]...
   7 .br
   8 .SH DESCRIPTION
   9 .B adt\-testreport\-runloop
  10 is a rather ad-hoc script which repeatedly invokes
  11 .BR adt\-testreport\-onepackage ;
  12 it is designed to be invoked from cron.
  13
  14 \fBWARNING\fR - it is essential to reconfigure this program before
  15 use, as the supplied examples will \fBsend emails\fR to people who
  16 will become \fBvery upset\fR with you!
  17 .SH CONFIGURATION
  18 Command-line arguments containing \fB=\fR are interpreted
  19 with \fBeval\fR; other arguments are sourced using \fB.\fR,
  20 in each case interpreted as bash script.
  21
  22 Supplied arguments are both executed by a-t-r and passed through to
  23 the invocation of a-t-o.  You may prefix an argument with \fB@\fR to
  24 indicate that it is for a-t-onepackage only, or with \fB!\fR to
  25 indicate that it is for a-t-runloop only.
  26
  27 Thus the set of variables which can be set is the union of those for
  28 a-t-runloop itself and those for a-t-onepackage.  See the a-t-o
  29 manpage for such information about its configuration as is available.
  30 Configuration fragment authors should bear in mind that both programs
  31 use \fBset -e\fR.
  32
  33 It is quite permissible to set PATH and other needed environmnet
  34 variables in the configuration file.
  35
  36 The following variables may be set:
  37 .TP
  38 .B distro
  39 distribution (`suite') to be tested.  There is no default.  This
  40 variable is used only for the default values of
  41 .B testbed_check_path
  42 and
  43 .BR test_classes .
  44 However, it is probably a convenient way of specifying the intended
  45 effect particularly as attempting to do cross-distribution testing in a
  46 single installation does not work properly right now (see a-t-o's BUGS).
  47 .TP
  48 .B max_test_count
  49 the maximum number of times to invoke a-t-o.  This counts both passed
  50 and failed tests, but it doesn't count possible runs which were
  51 suppressed.  Default: 10.
  52 .TP
  53 .B go_anway
  54 Run even though the file \fBgo\fR does not exist.  See SUPPRESSION,
  55 below.  Default: \fBfalse\fR.
  56 .TP
  57 .B architecture
  58 Used in combination with \fBdistro\fR when calculating the right
  59 default for test_classes.  The default is the result from
  60 .BR "dpkg --print-architecture" .
  61 .TP
  62 .B testbed_check_path
  63 If the file named by this variable doesn't exist, a-t-r will exit.
  64 This avoids it spinning and reporting many immediate failures due to a
  65 broken testbed.  The default is
  66 .BI /var/lib/autopkgtest/xenlvm/adt_ distro /good
  67 if distro is set, which assumes that the Xen-based virtualisation
  68 system is being used; if distro is not set then default is /dev/null
  69 which nullifies this feature.
  70 .TP
  71 .B test_classes
  72 Specifies the set of test classes to try, with the details of each
  73 test class separated by a colon \fB:\fR from the next.  a-t-r will run
  74 a-t-o once for each listed test class and then return to the beginning
  75 of the list.
  76
  77 Tests in each class are thus selected approximately equally often.
  78 (If max_test_count is not a multiple of the number of actual test
  79 classes then early classes are used slightly more.)
  80
  81 Each test class consists of a set of suppression checks, a comma
  82 \fB,\fR, and some configuration arguments for a-t-o.  The suppression
  83 checks are whitespace-separated words; see SUPPRESSION.  The
  84 configuration arguments are likewise whitespace-separated.  There is
  85 no provision for passing configuration arguments containing spaces to
  86 a-t-o.  a-t-o arguments in test classes override other configuration
  87 settings.
  88
  89 The default is
  90 .BI "source " distro ", target=source : binary " distro ,
  91 .BI target=binary- architecture
  92 which tests binary packages and source packages from the same
  93 distribution in alternation
  94 .SH SUPPRESSION
  95 a-t-r is designed to be enabled and disabled by sentinel files.
  96
  97 Firstly, if the file \fBgo\fR does not exist in its working directory,
  98 it will stop at the first sensible opportunity.  (See also the
  99 go_anyway configuration variable.)
 100
 101 Secondly, test classes may specify suppression checks.  For each such
 102 check \fIclasscheck\fR, a-t-r will test for the existence of
 103 .BI stop- classcheck
 104 in its current directory.  If that file exists, it will suppress that
 105 class of test.  Do not suppress all of the tests without removing
 106 \fBgo\fR.
 107 .SH FILES
 108 .TP
 109 .BI /var/lib/autopkgtest/xenlvm/adt_ distro /good
 110 default sentinel file for testbed_check_path.
 111 .TP
 112 .B ./go
 113 Sentinel file indicating that operation should be enabled.
 114 .TP
 115 .BI ./stop- classcheck
 116 Sentinel file indicating that test classes mentioning \fIclasscheck\fR
 117 should be suppressed.
 118 .LP
 119 adt-testreport-runloop does not use any other files directly, but it
 120 will probably need a configuration file as an argument, and it will
 121 invoke adt-testreport-onepackage which uses many files in the current
 122 directory and which invokes an autopkgtest virtualisation server.
 123 .SH BUGS AND WARNINGS
 124 \fBIt is essential not to use the example configuration!\fR
 125 This configuration is likely to send inappropriate emails!
 126
 127 There is no locking.  Whatever invokes a-t-r should take out a lock of
 128 some kind.  See the example cronjobs provided in
 129 .B hosts/*/cronjob
 130 in the source package.
 131
 132 If all of the test classes are suppressed, a-t-r will spin in a tight
 133 loop looking for something to do.
 134
 135 The
 136 .B testbed_check_path
 137 feature is rather ad-hoc.  It would be better to query the
 138 virtualisation server to be used directly and then suppress the test
 139 class if relevant.  (But the infinite loop bug would need to be fixed
 140 too.)
 141
 142 The design precludes detecting attempts to set incorrectly
 143 named configuration options.
 144 .SH AUTHORS AND COPYRIGHT
 145 This manpage is part of autopkgtest, a tool for testing Debian binary
 146 packages.  autopkgtest is Copyright (C) 2006-2007 Canonical Ltd and
 147 others.
 148
 149 See \fB/usr/share/doc/autopkgtest/CREDITS\fR for the list of
 150 contributors and full copying conditions.