-.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
supplied) in the top level directory of the built source tree, on the
host. The package should be installed on the testbed.
-.SH OPTIONS
+.SH PROCESSING INSTRUCTIONS
.TP
-.BR --tests-tree [ -tb ] " " \fIdirectory\fR
-Specifies that the built source tree can be found in
-.IR directory .
-(Default: adt-run's current directory, on the host.)
+.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
+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 [ -tb ] " " \fIdsc\fR
-Builds \fIdsc\fR, and then uses the tests in that tree, as well as
-testing the packages from this build and using them to satisfy
-dependencies. Equivalent to \fB--source-tests\fI and
-\fB--source-binaries\fI (except that it only does the build once).
+.BR --source " " \fIdsc\fR
+Builds \fIdsc\fR. The resulting binaries will (by default) be used to
+satisfy dependencies. The tests from that built tree will also be run
+(by default). The ordering is significant: each \fB--source\fR option
+should precede options whose dependencies are to be satisfied by the
+binaries it produces.
.TP
-.BR --source-tests [ -tb ] " " \fIdsc\fR
-Builds \fIdsc\fR (installing dependencies as appropriate), and then
-uses the tests in that tree. The packages tested will be those
-installed on the testbed, not the ones from this build.
+.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 --source-testsinstall [ -tb ] " " \fIdsc\fR
-Builds \fIdsc\fR (installing dependencies as appropriate), and then
-installs the packages which result (subject to
-\fB--package-filter-source-install\fR). The packages tested will be
-those installed on the testbed, not the ones from this build. This is
-like \fB--source-tests\fR except that the packages from the build are
-installed even if they are not required as a dependency for any test.
+.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
+necessarily installed. The ordering is significant, as for
+\fB--source\fR.
.TP
-.BR --source-binaries [ -tb ] " " \fIdsc\fR
-Builds \fIdsc\fR (installing dependencies as appropriate), and then
-use the resulting binary packages to satisfy dependencies (instead of
-packages from the default archive).
-
-
-Only dependencies mentioned by
-tests, or binary packages built by or provided directly to
-\fBadt-run\fR, are affected: dependencies mentioned by binary packages
-installed implicitly
-
- The dependencies affected are
-
-
-which are themselves installed deliberately by the test
-. Binary packages
-installed implicitly by
-
-
-direct \Test-Depends lines,
-
-installs the packages which result (subject to
-\fB--package-filter-source-install\fR). The packages tested will be
-those installed on the testbed, not the ones from this build.
-
-
-
-
-Equivalent to \fB--source-tests\fR but
-
-; also uses the tests in the
-resulting build tree.
-
-
-and then
-uses the tests in that tree. The packages tested will be those
-installed on the testbed, not the ones from this build.
+.I filename
+Bare filename arguments are processed as if
+.BR --built-tree ", " --source ", " --unbuilt-tree " or " --binary
+was specified; the nature of the argument is guessed from the form of
+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.
.TP
-
-
-
-, as well as
-testing the packages from this build and using them to satisfy
-dependencies. Equivalent to \fB--source-tests\fI and
-\fB--source-binaries\fI (except that it only does the build once).
-
-
-
-Specifies that the source to use for the tests can be found in
-.IR filename
-(which should be a \fB.dsc\fR). The source will be unpacked
-and built, and the tests from this build tree will be run.
+.BR --paths-testbed | --paths-host
+Specifies that subsequent pathnames in command-line arguments refer to
+files on the testbed, or on the host, respectively. The default is
+\fB--paths-host\fR.
.TP
-.BR --use-source [ -tb ] " " \fIfilename\fR
-Specifies that the source to use for the tests can be found in
-.IR filename
-(which should be a \fB.dsc\fR), and that the packages from this
-build should be the ones tested, and used to satisfy any dependencies;
-this option is like \fB--build-source\fR and \fB--from-source\fR combined.
+.BR --sources-tests | --sources-no-tests
+Specifies that the tests in subsequent \fB--source\fR and
+\fB--unbuilt-tree\fR arguments should (or should not) be run.
.TP
-.BR --user " " \fIusername\fR
-Specifies that commands on the testbed should generally be run as
-\fIusername\fR; this option does not make much sense unless the
-virtualisation environment provides root on the testbed. Commands are
-run via \fBsu -c\fR; affected commands are tests (other than those
-which declare that they need root), source package builds and source
-package binary generation (via fakeroot). If the testbed advertises
-the \fBroot-on-testbed\fR and \fBsuggest-normal-user=\fR capabilities,
-the suggested normal is used as the default; otherwise the default is
-to run commands as the testbed's default user (this can be explicitly
-requested by specifying the empty string for \fIusername\fR).
+.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 and \fB--unbuilt-tree\fR arguments.
.TP
-.BR --fakeroot " " \fIfakeroot-command\fR
-Specifies that \fBdebian/rules binary\fR should be run via
-\fIfakeroot-command\fR. The default is \fBfakeroot\fR if the testbed
-doesn't offer us root or if we are running \fBdebian/rules build\fR as
-a normal user according to a specified or default value of
-\fB--user\fR, and no wrapper otherwise.
-
-The default is to run without any special
-measures if the test
-
-Specifies that commands on the testbed should generally be run as
-\fIusername\fR; this option does not make much sense unless the
-virtualisation environment provides root on the testbed. Commands
-are run via \fBsu -c\fR; affected commands are tests (other than those
-which declare that they need root), source package builds and source
-package binary generation (except if \fB--fakeroot\fR is specified -
-see below).
-
-Specifies that \fIfilename\fR (which should be a \fB.deb\fR) should be
-unconditionally installed on the testbed before any tests are run (but
-after any necessary building). This can be used to test a specific
-binary package.
-.TP
-.BR --install-binary [ -tb ] " " \fIfilename\fR
-Specifies that \fIfilename\fR (which should be a \fB.deb\fR) should be
-unconditionally installed on the testbed before any tests are run (but
-after any necessary building). This can be used to test a specific
-binary package.
+.BR --no-built-binaries
+Specifies that all built binaries should be ignored completely;
+equivalent to
+.BR --built-binaries-filter=_
+(since no package name ever contains \fB_\fR).
.TP
-.BR --from-source [ -tb ] " " \fIsource\fR
-Specifies that \fIsource\fR (which should be a \fB.dsc\fR) should be
-built on the testbed and then the resulting \fB.deb\fR's
-used to satisfy dependencies where necessary.
+.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 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 .
.TP
-.BR --install-from-source [ -tb ] " " \fIsource\fR
-Specifies that \fIsource\fR (which should be a \fB.dsc\fR) should be
-built on the testbed and then (some subset of) the \fB.deb\fR's which
-result should be installed.
-;.TP
-;.BR --without-depends | --with-depends-only | --with-depends | --with-recommends
-;Specifies dependency handling: These options control whether
-;dependencies necessary for building and installing the packages as
-;requested will be installed (and possibly deinstalled, if there are
-;conflicts).
-;.IP
-;Each option controls installation of the dependencies for
-;all subsequent
-;.BR --build-source ", " --install-package " and " --install-from-source
-;options, until the next dependency handling option; the last
-;dependency handling option controls whether dependencies specified in
-;the actual test control file are installed.
-;.IP
-;The four handling modes are to honour, respectively: no dependencies, only
-;\fBDepends\fR, everything except \fBRecommends\fR and \fBSuggests\fR,
-;and everything except \fBSuggests\fR.
-;The default is \fB--without-depends\fR (it is as if this was
-;specified at the start of the command line).
-;.TP
-;.BR --package-filter-dependency " [!]\fIpattern\fR[,[!]\fIpattern\fR...]"
-;Limits the packages installed (or removed) due to dependencies to
-;those matching the specified filter. The filter is a comma-separated
-;list of glob patterns (which must match the whole package name); each
-;optionally preceded by \fB!\fR (which indicates that matching packages
-;should not be installed). The first pattern found determines; if no
-;pattern matches, then the package is taken to match the filter iff the
-;last pattern had a \fB!\fR.
+.BI --binaries-forbuilds= ...
+Like \fB--binaries=\fR but only changes the handling during package
+building: packages will be ignored, used for dependencies, or
+unconditionally installed, when a source package is built.
.TP
-.BR --package-filter-from-source " [!]\fIpattern\fR[,[!]\fIpattern\fR...]"
-Limits the packages installed directly due to
-.B --install-from-source
-directives; the patterns are interpreted as for
-.BR --package-filter-dependency .
+.BI --binaries-fortests= ...
+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 \fB--source\fR, \fB--built-tree\fR or \fB--unbuilt-tree\fR).
+.SH OTHER OPTIONS
.TP
-.BR --control [ -tb ] " " \fIcontrol\fR
-Specifies that
-.I control
-should be used as the test control file instead of
-.B debian/tests/control
-in the build tree. Note that it is not an error for this file not to
-exist; that just means that there are no tests.
-.TP
-.BR --output-dir [ -tb ] " " \fIoutput-dir\fR
+.BI --output-dir " " \fIoutput-dir\fR
Specifies that stderr and stdout from the tests should be placed in
.IR output-dir .
-The files are 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)".
+.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
+the testbed; if root on the testbed is not available then builds and
+tests run as whatever user is provided.
+.TP
+.BI --gain-root= gain-root
+Prefixes
+.B debian/rules binary
+with
+.RB gain-root .
+The default is not to use anything, except that if
+\fB--user\fR is supplied or root on the testbed is not available the
+default is \fBfakeroot\fR.
+.TP
+.BI --tmp-dir= tmpdir
+Specifies that \fItmpdir\fR should be used instead of a fresh
+temporary directory on the host. \fItmpdir\fR will be created if
+necessary, and emptied of all of its contents before \fBadt-run\fR
+starts, and it will not be cleaned out afterwards. \fItmpdir\fR is
+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 -d " | " --debug
-Enables debugging output. Probably not hugely interesting.
+.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
+unrelated keys, since \fBadt-run\fR does not specify to \fBgpg\fR
+which keys to use. The default is
+.BR $HOME/.autopkgtest .
+\fB--paths-testbed\fR has no effect on this option.
+.TP
+.B --gnupg-home=fresh
+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 -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.
-
-.SS NOTES
-Some options which come in variants with and without
-.BR -tb .
-These specify paths on the testbed and the host, respectively. The
-data will be copied by
-.B adt-run
-to where it is needed.
+.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
-consists of the name of the test, some horizontal whitespace, and
-either
+consists of a short string identifying the test, some horizontal
+whitespace, and either
.B PASS
or
.BR FAIL " reason"
where the pass/fail indication is separated by any reason by some
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, the \fIargid\fR, followed by a hyphen and the test name.
+
Sometimes a
.B SKIP
will be reported when the name of the test is not known or not
.B *
will appear where the name of the test should be.
+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. 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-2007 Canonical Ltd and
+others.
See \fB/usr/share/doc/autopkgtest/CREDITS\fR for the list of
contributors and full copying conditions.
~ianmdlvl / autopkgtest.git / blobdiff