From: Ian Jackson Date: Wed, 21 Feb 2007 13:54:35 +0000 (+0000) Subject: document current behaviour X-Git-Tag: converted-from-bzr~32^3~34 X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=commitdiff_plain;h=e3ef7cbb4d99f83310b864118b942a776dba8e2b;p=autopkgtest.git document current behaviour --- diff --git a/runner/adt-run.1 b/runner/adt-run.1 index 4374764..9dc4b27 100644 --- 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.