document current behaviour

diff --git a/runner/adt-run.1 b/runner/adt-run.1
index 437476421c46ca18b59062610f019e486dbe9b60..9dc4b27e49c99595c937dcaf0bb353343a7452de 100644 (file)
--- a/runner/adt-run.1
+++ b/runner/adt-run.1
@@ -1,4 +1,4 @@
-.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
@@ -102,20 +102,21 @@ package under test), or unconditionally installed, when tests are run
 .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
@@ -139,6 +140,11 @@ not affected by \fB--paths-testbed\fR.
 .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
@@ -153,10 +159,10 @@ This can be very slow and depends on the availability of sufficient
 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
@@ -178,7 +184,7 @@ horizontal whitespace.
 
 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
@@ -191,24 +197,28 @@ In this case
 .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
@@ -224,14 +234,16 @@ cause of a problem are listed last.
 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.