* adt-xenlvm-with-testbed: sleep 1 after xm destroy, which is racy.

[autopkgtest.git] / runner / adt-run.1

diff --git a/runner/adt-run.1 b/runner/adt-run.1
index 437476421c46ca18b59062610f019e486dbe9b60..ff1a661efae13e3d9ad96d00445b62dfa225d06a 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
 .SH NAME
 adt\-run \- test an installed binary package using the package's tests
 .SH SYNOPSYS


@@ -27,7 +27,7 @@ host.  The package should be installed on the testbed.
 
 .SH PROCESSING INSTRUCTIONS
 .TP
 
 .SH PROCESSING INSTRUCTIONS
 .TP

-.BR --tests-tree " " \fIdirectory\fR
+.BR --built-tree " " \fIdirectory\fR

 Specifies that tests from the built source tree
 .IR directory
 should be run.  Note that the packages that would normally be
 Specifies that tests from the built source tree
 .IR directory
 should be run.  Note that the packages that would normally be


@@ -43,6 +43,13 @@ satisfy dependencies.  The tests from that built tree will also be run
 should precede options whose dependencies are to be satisfied by the
 binaries it produces.
 .TP
 should precede options whose dependencies are to be satisfied by the
 binaries it produces.
 .TP

+.BR --unbuilt-tree " " \fIdirectory\fR
+Specifies that tests from the unbuilt source tree
+.IR directory
+should be run.  This is very similar to specifing \fB--source\fR
+except that a directory tree (which should be pristine) is supplied,
+instead of a source package.
+.TP

 .BR --binary " " \fIdeb\fR
 Specifies that \fIdeb\fR should be used.  By default it will be used
 to satisfy dependencies, both during building and testing, but not
 .BR --binary " " \fIdeb\fR
 Specifies that \fIdeb\fR should be used.  By default it will be used
 to satisfy dependencies, both during building and testing, but not


@@ -51,10 +58,11 @@ necessarily installed.  The ordering is significant, as for
 .TP
 .I filename
 Bare filename arguments are processed as if
 .TP
 .I filename
 Bare filename arguments are processed as if

-.BR --tests-tree ", " --source " or " --binary
+.BR --built-tree ", " --source ", " --unbuilt-tree " or " --binary

 was specified; the nature of the argument is guessed from the form of
 was specified; the nature of the argument is guessed from the form of

-the filename.  (So in the case of \fB--tests-tree\fR, either the
-option must be specified, or the filename must end in a slash.)
+the filename.  In the case of \fB--built-tree\fR, either the
+option must be specified, or the filename must end in a slash; two
+slashes at the end are taken to mean \fB--unbuilt-tree\fR.

 .SH PROCESSING OPTIONS
 These affect modify processing instructions.  Unless stated
 otherwise, they affect all subsequent options.
 .SH PROCESSING OPTIONS
 These affect modify processing instructions.  Unless stated
 otherwise, they affect all subsequent options.


@@ -65,13 +73,13 @@ files on the testbed, or on the host, respectively.  The default is
 \fB--paths-host\fR.
 .TP
 .BR --sources-tests | --sources-no-tests
 \fB--paths-host\fR.
 .TP
 .BR --sources-tests | --sources-no-tests

-Specifies that the tests in subsequent \fB--source\fR arguments should
-(or should not) be run.
+Specifies that the tests in subsequent \fB--source\fR and
+\fB--unbuilt-tree\fR arguments should (or should not) be run.

 .TP
 .BR --built-binaries-filter= \fIpattern\fB,\fIpattern\fB,\fR...
 Specifies that only binaries whose package names match one of the
 specified patterns should be used; others will be ignored.  This
 .TP
 .BR --built-binaries-filter= \fIpattern\fB,\fIpattern\fB,\fR...
 Specifies that only binaries whose package names match one of the
 specified patterns should be used; others will be ignored.  This

-option applies to subsequent \fB--source\fR arguments.
+option applies to subsequent \fB--source\fR and \fB--unbuilt-tree\fR arguments.

 .TP
 .BR --no-built-binaries
 Specifies that all built binaries should be ignored completely;
 .TP
 .BR --no-built-binaries
 Specifies that all built binaries should be ignored completely;


@@ -82,7 +90,7 @@ equivalent to
 .B --binaries=ignore | --binaries=auto | --binaries=install
 Specifies that binary package (in subsequently specified
 \fB--binary\fR arguments, or resulting from subsequently specified
 .B --binaries=ignore | --binaries=auto | --binaries=install
 Specifies that binary package (in subsequently specified
 \fB--binary\fR arguments, or resulting from subsequently specified

-\fB--source\fR arguments and not filtered out) should be ignored, used
+\fB--source\fR or \fB--unbuilt-tree\fR arguments and not filtered out) should be ignored, used

 only to satisfy dependencies, or installed unconditionally,
 respectively.  Equivalent to specifying both
 .BR --binaries-forbuilds " and " --binaries-fortests .
 only to satisfy dependencies, or installed unconditionally,
 respectively.  Equivalent to specifying both
 .BR --binaries-forbuilds " and " --binaries-fortests .


@@ -96,26 +104,27 @@ unconditionally installed, when a source package is built.
 Like \fB--binaries=\fR but only changes the handling during testing:
 packages will be ignored, used for dependencies (including as the
 package under test), or unconditionally installed, when tests are run
 Like \fB--binaries=\fR but only changes the handling during testing:
 packages will be ignored, used for dependencies (including as the
 package under test), or unconditionally installed, when tests are run

-(as a result of either \fB--source\fR or \fB--build-tree\fR).
+(as a result of \fB--source\fR, \fB--built-tree\fR or \fB--unbuilt-tree\fR).

 .SH OTHER OPTIONS
 .TP
 .BI --output-dir " " \fIoutput-dir\fR
 Specifies that stderr and stdout from the tests should be placed in
 .IR output-dir .
 .SH OTHER OPTIONS
 .TP
 .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
 and

-.BI stdout- test
+.BI argid- test -stdout

 for each test
 .IR test ,
 and
 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
 .TP
 .BI --user= user
 Run builds and tests as \fIuser\fR on the testbed.  This needs root on


@@ -139,6 +148,44 @@ not affected by \fB--paths-testbed\fR.
 .B NOTE
 again that all of the contents of \fItmpdir\fR will be \fBdeleted\fR.
 .TP
 .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 --summary= summary
+Specifies that a summary of the outcome should be written to
+\fIsummary\fR.  The events in the summary are written to the log
+in any case.
+\fIsummary\fR is not affected by \fB--paths-testbed\fR.
+.TP
+.BR --timeout- \fIwhich\fR = \fIseconds\fR
+Use a different timeout for operations on or with the testbed.  There
+are four timeouts affected by four values of \fIwhich\fR:
+.BR short :
+supposedly
+short operations like setting up the testbed's apt and checking the
+state (default: 100s);
+.BR install :
+installation of packages including dependencies
+(default: 3ks);
+.BR test :
+test runs (default: 10ks); and
+.BR build :
+builds (default:
+100ks).  The value must be specified as an integer number of seconds.
+.TP
+.BR --timeout-factor =\fIdouble\fR
+Multiply all of the default timeouts by the specified factor (see
+\fB--timeout-\fR\fIwhich\fR above).  Only the defaults are affected;
+explicit timeout settings are used exactly as specified.
+.TP
+.BR --debug | -d
+Include additional debugging information in the trace log.  Each
+additional \fB-d\fR increases the debugging level; the current maximum
+is \fB-ddd\fR.  If you like to see what's going on, \fR-d\fB or
+\fR-dd\fB is recommended.
+.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
 .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,16 +200,26 @@ This can be very slow and depends on the availability of sufficient
 quantities of high-quality entropy.
 .TP
 .BR -q " | " --quiet
 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
 to invoke.  All the remaining arguments and options after
 .B ---
 are passed to the virtualisation server program.
 .TP
 \fB---\fR \fIvirt-server virt-server-arg\fR...
 Specifies the virtualisation regime server, as a command and arguments
 to invoke.  All the remaining arguments and options after
 .B ---
 are passed to the virtualisation server program.

+.TP
+.BI --set-lang= langval
+When running commands on the testbed, sets the \fBLANG\fR environment
+variable to \fIlangval\fR.  The default in \fBadt-run\fR is to set it
+to \fBC\fR.
+.TP
+.BI --leave-lang
+Suppresses the setting by \fBadt-run\fR of \fBLANG\fR on the testbed.
+This results in tests and builds using the testbed's own normal
+\fBLANG\fR value setting.

 
 .SH OUTPUT FORMAT
 During a normal test run, one line is printed for each test.  This
 
 .SH OUTPUT FORMAT
 During a normal test run, one line is printed for each test.  This


@@ -178,7 +235,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
 
 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
 
 Sometimes a
 .B SKIP


@@ -191,24 +248,28 @@ In this case
 .B *
 will appear where the name of the test should be.
 
 .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)
 .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
 
 .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
 2      at least one test skipped
 .br
 4      at least one test failed


@@ -224,14 +285,16 @@ cause of a problem are listed last.
 20     other unexpected failures including bad usage
 
 .SH SEE ALSO
 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
 
 .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
 
 .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-2007 Canonical Ltd and
+others.

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