X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=runner%2Fadt-run.1;h=ff1a661efae13e3d9ad96d00445b62dfa225d06a;hb=aa43f2a81adb120c1da99919c5b3523ea952d170;hp=3140dc4740336fba1495976e0df46622b024c4b6;hpb=98b000316242c08ebd8147a616e4e35f8c8fd837;p=autopkgtest.git diff --git a/runner/adt-run.1 b/runner/adt-run.1 index 3140dc4..ff1a661 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 @@ -27,10 +27,14 @@ host. The package should be installed on the testbed. .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. +should be run. Note that the packages that would normally be +installed as a result of \fB*\fR in the tests' \fBDepends\fR field +(which includes the case where the \fBDepends\fR field is not +specified) are \fInot\fR installed. The caller must explicitly +instruct \fBadt-run\fR to install any relevant packages. .TP .BR --source " " \fIdsc\fR Builds \fIdsc\fR. The resulting binaries will (by default) be used to @@ -39,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 +.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 @@ -47,10 +58,11 @@ necessarily installed. The ordering is significant, as for .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 -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. @@ -61,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 -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 -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; @@ -78,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 -\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 . @@ -92,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 -(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 . -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 @@ -135,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 +.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 @@ -148,14 +199,27 @@ Use a fresh temporary directory and generate fresh keys each run. This can be very slow and depends on the availability of sufficient quantities of high-quality entropy. .TP -.BR -d " | " --debug -Enables debugging output. Probably not hugely interesting. +.BR -q " | " --quiet +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 +.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 @@ -171,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 -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 @@ -184,24 +248,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 @@ -217,14 +285,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-2007 Canonical Ltd and +others. See \fB/usr/share/doc/autopkgtest/CREDITS\fR for the list of contributors and full copying conditions.