1 files changed, 145 insertions, 0 deletions
diff --git a/doc/kyua-debug.1.in b/doc/kyua-debug.1.in
new file mode 100644
index 000000000000..9e962a465421
--- /dev/null
+++ b/doc/kyua-debug.1.in
@@ -0,0 +1,145 @@
+.\" Copyright 2012 The Kyua Authors.
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions are
+.\" met:
+.\"
+.\" * Redistributions of source code must retain the above copyright
+.\"   notice, this list of conditions and the following disclaimer.
+.\" * Redistributions in binary form must reproduce the above copyright
+.\"   notice, this list of conditions and the following disclaimer in the
+.\"   documentation and/or other materials provided with the distribution.
+.\" * Neither the name of Google Inc. nor the names of its contributors
+.\"   may be used to endorse or promote products derived from this software
+.\"   without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+.\" OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+.Dd October 13, 2014
+.Dt KYUA-DEBUG 1
+.Os
+.Sh NAME
+.Nm "kyua debug"
+.Nd Executes a single test case with facilities for debugging
+.Sh SYNOPSIS
+.Nm
+.Op Fl -build-root Ar path
+.Op Fl -kyuafile Ar file
+.Op Fl -stdout Ar path
+.Op Fl -stderr Ar path
+.Ar test_case
+.Sh DESCRIPTION
+The
+.Nm
+command provides a mechanism to execute a single test case bypassing some
+of the Kyua infrastructure and allowing the user to poke into the execution
+behavior of the test.
+.Pp
+The test case to run is selected by providing a test filter, described below in
+.Sx Test filters ,
+that matches a single test case.
+The test case is executed and its result is printed as the last line of the
+output of the tool.
+.Pp
+The test executed by
+.Nm
+is run under a controlled environment as described in
+.Sx Test isolation .
+.Pp
+At the moment, the
+.Nm
+command allows the following aspects of a test case execution to be
+tweaked:
+.Bl -bullet
+.It
+Redirection of the test case's stdout and stderr to the console (the
+default) or to arbitrary files.
+See the
+.Fl -stdout
+and
+.Fl -stderr
+options below.
+.El
+.Pp
+The following subcommand options are recognized:
+.Bl -tag -width XX
+.It Fl -build-root Ar path
+Specifies the build root in which to find the test programs referenced
+by the Kyuafile, if different from the Kyuafile's directory.
+See
+.Sx Build directories
+below for more information.
+.It Fl -kyuafile Ar file , Fl k Ar file
+Specifies the Kyuafile to process.
+Defaults to
+.Pa Kyuafile
+file in the current directory.
+.It Fl -stderr Ar path
+Specifies the file to which to send the standard error of the test
+program's body.
+The default is
+.Pa /dev/stderr ,
+which is a special character device that redirects the output to
+standard error on the console.
+.It Fl -stdout Ar path
+Specifies the file to which to send the standard output of the test
+program's body.
+The default is
+.Pa /dev/stdout ,
+which is a special character device that redirects the output to
+standard output on the console.
+.El
+.Pp
+For example, consider the following Kyua session:
+.Bd -literal -offset indent
+$ kyua test
+kernel/fs:mkdir  ->  passed
+kernel/fs:rmdir  ->  failed: Invalid argument
+
+1/2 passed (1 failed)
+.Ed
+.Pp
+At this point, we do not have a lot of information regarding the
+failure of the
+.Sq kernel/fs:rmdir
+test.
+We can run this test through the
+.Nm
+command to inspect its output a bit closer, hoping that the test case is
+kind enough to log its progress:
+.Bd -literal -offset indent
+$ kyua debug kernel/fs:rmdir
+Trying rmdir('foo')
+Trying rmdir(NULL)
+kernel/fs:rmdir  ->  failed: Invalid argument
+.Ed
+.Pp
+Luckily, the offending test case was printing status lines as it
+progressed, so we could see the last attempted call and we can know match
+the failure message to the problem.
+.Ss Build directories
+__include__ build-root.mdoc COMMAND=debug
+.Ss Test filters
+__include__ test-filters.mdoc
+.Ss Test isolation
+__include__ test-isolation.mdoc
+.Sh EXIT STATUS
+The
+.Nm
+command returns 0 if the test case passes or 1 if the test case fails.
+.Pp
+Additional exit codes may be returned as described in
+.Xr kyua 1 .
+.Sh SEE ALSO
+.Xr kyua 1 ,
+.Xr kyuafile 5