-.TH adt\-run 1 2006 autopkgtest "Linux Programmer's Manual"
+.TH adt\-run 1 2007 autopkgtest "Linux Programmer's Manual"
.SH NAME
adt\-run \- test an installed binary package using the package's tests
.SH SYNOPSYS
.BI --output-dir " " \fIoutput-dir\fR
Specifies that stderr and stdout from the tests should be placed in
.IR output-dir .
-The files were previously named
-.BI stderr- test
+These files are named
+.BI argid- test -stderr
and
-.BI stdout- test
+.BI argid- test -stdout
for each test
.IR test ,
and
-.BR log-buildt " (for the build logs from " --build-source ),
-.BI log-buildi- i
-.RI "(for the build logs from the " i th
-.BR --install-from-source ),
-.BI log-install- j
-.RI "(for the installation logs from the " j "th installation or removal)".
-Names have probably changed since this manual was written.
+.BR log
+for the log transcript. If no \fIoutput-dir\fR is specified, or the
+path is specified to be on the testbed (ie, if \fB--output-dir\fR
+follows \fB--paths-testbed\fR), then the \fBlog\fR file is instead
+written to the temporary directory \fItmpdir\fR if one was specified,
+or otherwise no separate copy is made. Note that the log transcript
+output will also be sent to \fBadt-run\fR's stderr unless
+\fB--quiet\fR is specified.
.TP
.BI --user= user
Run builds and tests as \fIuser\fR on the testbed. This needs root on
.B NOTE
again that all of the contents of \fItmpdir\fR will be \fBdeleted\fR.
.TP
+.BI --log-file= logfile
+Specifies that the trace log should be written to \fIlogfile\fR
+instead of to \fBlog\fR in \fIoutput-dir\fR or \fItmpdir\fR.
+\fIlog-file\fR is not affected by \fB--paths-testbed\fR.
+.TP
.BI --gnupg-home= dir
Uses \fIdir\fR as the \fBGNUPGHOME\fR for local apt archive signing.
The specified directory should not contain keyrings containing other
quantities of high-quality entropy.
.TP
.BR -q " | " --quiet
-Do not send a copy of \fBadt-run\fR's trace logstream to stderr;
-instead, store it in the \fItmpdir\fR if one was specified, or discard
-it otherwise. Note that without the trace logstream it can be very
-hard to diagnose problems.
+Do not send a copy of \fBadt-run\fR's trace logstream to stderr. This
+option does not affect the copy sent to \fIlogfile\fR,
+\fIoutput-dir\fR or \fItmpdir\fR. Note that without the trace
+logstream it can be very hard to diagnose problems.
.TP
\fB---\fR \fIvirt-server virt-server-arg\fR...
Specifies the virtualisation regime server, as a command and arguments
The string to identify the test consists of a short alphanumeric
string invented by \fBadt-run\fR to distinguish different command-line
-arguments, followed by a hyphen and the test name.
+arguments, the \fIargid\fR, followed by a hyphen and the test name.
Sometimes a
.B SKIP
.B *
will appear where the name of the test should be.
-Also, the output:
-.BR blame: ...
-may be produced, where the right hand side is
+If \fBadt-run\fR detects that erroneous package(s) are involved, it
+will print the two lines
+.BR "blame: " \fIblamed-thing\fR ...
+and
+.BR "badpkg: " \fImessage\fR.
+Here each whitespace-separated \fIblamed-thing\fR is one of
.BI arg: argument
(representing a pathname found in a command line argument),
.BI dsc: package
(a source package name),
.BI deb: package
(a binary package name)
-or possibly other strings to be determined. In case of an erroneous
-package (see \fBEXIT STATUS\fR) this indicates which arguments and/or
-packages might have contributed to the problem; the ones which were
-processed most recently and which are therefore most likely to be the
-cause of a problem are listed last.
+or possibly other strings to be determined. This indicates which
+arguments and/or packages might have contributed to the problem; the
+ones which were processed most recently and which are therefore most
+likely to be the cause of a problem are listed last.
.SH EXIT STATUS
0 all tests passed
.br
+1 unexpected failure (the python interpreter invents this exit status)
+.br
2 at least one test skipped
.br
4 at least one test failed
20 other unexpected failures including bad usage
.SH SEE ALSO
-\fBadt-virt-chroot\fR(1)
+\fBadt-virt-chroot\fR(1), \fBadt-virt-xenlvm\fR(1)
.SH BUGS
-This tool still lacks many important features.
+This tool still lacks some important features and is not very
+well-tested.
.SH AUTHORS AND COPYRIGHT
This manpage is part of autopkgtest, a tool for testing Debian binary
-packages. autopkgtest is Copyright (C) 2006 Canonical Ltd and others.
+packages. autopkgtest is Copyright (C) 2006-1007 Canonical Ltd and
+others.
See \fB/usr/share/doc/autopkgtest/CREDITS\fR for the list of
contributors and full copying conditions.