.TH adt\-testreport\-runloop 1 2007 autopkgtest "Linux Programmer's Manual"
.SH NAME
adt\-testreport\-runloop \- repeatedly choose and test packages
.SH SYNOPSYS
.B adt\-testreport\-runloop
.RI [[\fB!@\fR] variable \fB=\fR value |[\fB!@\fR] settings\-file ]...
.br
.SH DESCRIPTION
.B adt\-testreport\-runloop
is a rather ad-hoc script which repeatedly invokes
.BR adt\-testreport\-onepackage ;
it is designed to be invoked from cron.

\fBWARNING\fR - it is essential to reconfigure this program before
use, as the supplied examples will \fBsend emails\fR to people who
will become \fBvery upset\fR with you!
.SH CONFIGURATION
Command-line arguments containing \fB=\fR are interpreted
with \fBeval\fR; other arguments are sourced using \fB.\fR,
in each case interpreted as bash script.

Supplied arguments are both executed by a-t-r and passed through to
the invocation of a-t-o.  You may prefix an argument with \fB@\fR to
indicate that it is for a-t-onepackage only, or with \fB!\fR to
indicate that it is for a-t-runloop only.

Thus the set of variables which can be set is the union of those for
a-t-runloop itself and those for a-t-onepackage.  See the a-t-o
manpage for such information about its configuration as is available.
Configuration fragment authors should bear in mind that both programs
use \fBset -e\fR.

It is quite permissible to set PATH and other needed environmnet
variables in the configuration file.

The following variables may be set:
.TP
.B distro
distribution (`suite') to be tested.  There is no default.  This
variable is used only for the default values of
.B testbed_check_path
and
.BR test_classes .
However, it is probably a convenient way of specifying the intended
effect particularly as attempting to do cross-distribution testing in a
single installation does not work properly right now (see a-t-o's BUGS).
.TP
.B max_test_count
the maximum number of times to invoke a-t-o.  This counts both passed
and failed tests, but it doesn't count possible runs which were
suppressed.  Default: 10.
.TP
.B go_anway
Run even though the file \fBgo\fR does not exist.  See SUPPRESSION,
below.  Default: \fBfalse\fR.
.TP
.B architecture
Used in combination with \fBdistro\fR when calculating the right
default for test_classes.  The default is the result from
.BR "dpkg --print-architecture" .
.TP
.B testbed_check_path
If the file named by this variable doesn't exist, a-t-r will exit.
This avoids it spinning and reporting many immediate failures due to a
broken testbed.  The default is
.BI /var/lib/autopkgtest/xenlvm/adt_ distro /good
if distro is set, which assumes that the Xen-based virtualisation
system is being used; if distro is not set then default is /dev/null
which nullifies this feature.
.TP
.B test_classes
Specifies the set of test classes to try, with the details of each
test class separated by a colon \fB:\fR from the next.  a-t-r will run
a-t-o once for each listed test class and then return to the beginning
of the list.

Tests in each class are thus selected approximately equally often.
(If max_test_count is not a multiple of the number of actual test
classes then early classes are used slightly more.)

Each test class consists of a set of suppression checks, a comma
\fB,\fR, and some configuration arguments for a-t-o.  The suppression
checks are whitespace-separated words; see SUPPRESSION.  The
configuration arguments are likewise whitespace-separated.  There is
no provision for passing configuration arguments containing spaces to
a-t-o.  a-t-o arguments in test classes override other configuration
settings.

The default is
.BI "source " distro ", target=source : binary " distro ,
.BI target=binary- architecture
which tests binary packages and source packages from the same
distribution in alternation
.SH SUPPRESSION
a-t-r is designed to be enabled and disabled by sentinel files.

Firstly, if the file \fBgo\fR does not exist in its working directory,
it will stop at the first sensible opportunity.  (See also the
go_anyway configuration variable.)

Secondly, test classes may specify suppression checks.  For each such
check \fIclasscheck\fR, a-t-r will test for the existence of
.BI stop- classcheck
in its current directory.  If that file exists, it will suppress that
class of test.  Do not suppress all of the tests without removing
\fBgo\fR.
.SH FILES
.TP
.BI /var/lib/autopkgtest/xenlvm/adt_ distro /good
default sentinel file for testbed_check_path.
.TP
.B ./go
Sentinel file indicating that operation should be enabled.
.TP
.BI ./stop- classcheck
Sentinel file indicating that test classes mentioning \fIclasscheck\fR
should be suppressed.
.LP
adt-testreport-runloop does not use any other files directly, but it
will probably need a configuration file as an argument, and it will
invoke adt-testreport-onepackage which uses many files in the current
directory and which invokes an autopkgtest virtualisation server.
.SH BUGS AND WARNINGS
\fBIt is essential not to use the example configuration!\fR
This configuration is likely to send inappropriate emails!

There is no locking.  Whatever invokes a-t-r should take out a lock of
some kind.  See the example cronjobs provided in
.B hosts/*/cronjob
in the source package.

If all of the test classes are suppressed, a-t-r will spin in a tight
loop looking for something to do.

The
.B testbed_check_path
feature is rather ad-hoc.  It would be better to query the
virtualisation server to be used directly and then suppress the test
class if relevant.  (But the infinite loop bug would need to be fixed
too.)

The design precludes detecting attempts to set incorrectly
named configuration options.
.SH AUTHORS AND COPYRIGHT
This manpage is part of autopkgtest, a tool for testing Debian binary
packages.  autopkgtest is Copyright (C) 2006-2007 Canonical Ltd and
others.

See \fB/usr/share/doc/autopkgtest/CREDITS\fR for the list of
contributors and full copying conditions.