svn commit: r359386 - head/contrib/kyua/doc
Enji Cooper
ngie at FreeBSD.org
Sat Mar 28 03:02:29 UTC 2020
Author: ngie
Date: Sat Mar 28 01:14:37 2020
New Revision: 359386
URL: https://svnweb.freebsd.org/changeset/base/359386
Log:
Follow up to r359385
Actually add the generated manpages to unbreak the build.
MFC with: r359385
Added:
head/contrib/kyua/doc/kyua-about.1 (contents, props changed)
head/contrib/kyua/doc/kyua-config.1 (contents, props changed)
head/contrib/kyua/doc/kyua-db-exec.1 (contents, props changed)
head/contrib/kyua/doc/kyua-db-migrate.1 (contents, props changed)
head/contrib/kyua/doc/kyua-debug.1 (contents, props changed)
head/contrib/kyua/doc/kyua-help.1 (contents, props changed)
head/contrib/kyua/doc/kyua-list.1 (contents, props changed)
head/contrib/kyua/doc/kyua-report-html.1 (contents, props changed)
head/contrib/kyua/doc/kyua-report-junit.1 (contents, props changed)
head/contrib/kyua/doc/kyua-report.1 (contents, props changed)
head/contrib/kyua/doc/kyua-test.1 (contents, props changed)
head/contrib/kyua/doc/kyua.1 (contents, props changed)
head/contrib/kyua/doc/kyua.conf.5 (contents, props changed)
head/contrib/kyua/doc/kyuafile.5 (contents, props changed)
Added: head/contrib/kyua/doc/kyua-about.1
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ head/contrib/kyua/doc/kyua-about.1 Sat Mar 28 01:14:37 2020 (r359386)
@@ -0,0 +1,95 @@
+.\" 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 May 20, 2015
+.Dt KYUA-ABOUT 1
+.Os
+.Sh NAME
+.Nm "kyua about"
+.Nd Shows detailed authors, license, and version information
+.Sh SYNOPSIS
+.Nm
+.Op Ar authors | license | version
+.Sh DESCRIPTION
+The
+.Sq about
+command provides generic information about the
+.Xr kyua 1
+tool.
+In the default synopsis form (no arguments), the information printed
+includes:
+.Bl -enum
+.It
+The name of the package, which is
+.Sq kyua .
+.It
+The version number, which is
+.Sq 0.13 .
+.It
+License information.
+.It
+Authors information.
+.It
+A link to the project web site.
+.El
+.Pp
+You can customize the information printed by this command by specifying
+the desired topic as the single argument to the command.
+This can be one of:
+.Bl -tag -width authorsXX
+.It Ar authors
+Displays the list of authors and contributors only.
+.It Ar license
+Displays the license information and the list of copyrights.
+.It Ar version
+Displays the package name and the version number in a format that is
+compatible with the output of GNU tools that support a
+.Fl -version
+flag.
+Use this whenever you have to query the version number of the package.
+.El
+.Sh FILES
+The following files are read by the
+.Nm
+command:
+.Bl -tag -width XX
+.It Pa /usr/share/doc/kyua/AUTHORS
+List of authors (aka copyright holders).
+.It Pa /usr/share/doc/kyua/CONTRIBUTORS
+List of contributors (aka individuals that have contributed to the project).
+.It Pa /usr/share/doc/kyua/LICENSE
+License information.
+.El
+.Sh EXIT STATUS
+The
+.Nm
+command always returns 0.
+.Pp
+Additional exit codes may be returned as described in
+.Xr kyua 1 .
+.Sh SEE ALSO
+.Xr kyua 1
Added: head/contrib/kyua/doc/kyua-config.1
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ head/contrib/kyua/doc/kyua-config.1 Sat Mar 28 01:14:37 2020 (r359386)
@@ -0,0 +1,59 @@
+.\" 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 September 9, 2012
+.Dt KYUA-CONFIG 1
+.Os
+.Sh NAME
+.Nm "kyua config"
+.Nd Inspects the values of the loaded configuration
+.Sh SYNOPSIS
+.Nm
+.Op Ar variable1 .. variableN
+.Sh DESCRIPTION
+The
+.Nm
+command provides a way to list all defined configuration variables and
+their current values.
+.Pp
+This command is intended to help you in resolving the values of the
+configuration variables without having to scan over configuration files.
+.Pp
+In the default synopsis form (no arguments), the command prints all
+configuration variables.
+If any arguments are provided, the command will only print the
+requested variables.
+.Sh EXIT STATUS
+The
+.Nm
+command returns 0 on success or 1 if any of the specified configuration
+variables does not exist.
+.Pp
+Additional exit codes may be returned as described in
+.Xr kyua 1 .
+.Sh SEE ALSO
+.Xr kyua 1
Added: head/contrib/kyua/doc/kyua-db-exec.1
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ head/contrib/kyua/doc/kyua-db-exec.1 Sat Mar 28 01:14:37 2020 (r359386)
@@ -0,0 +1,199 @@
+.\" 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-DB-EXEC 1
+.Os
+.Sh NAME
+.Nm "kyua db-exec"
+.Nd Executes a SQL statement in a results file
+.Sh SYNOPSIS
+.Nm
+.Op Fl -no-headers
+.Op Fl -results-file Ar file
+.Ar statement
+.Sh DESCRIPTION
+The
+.Nm
+command provides a way to execute an arbitrary SQL statement within the
+database.
+This command is mostly intended to aid in debugging, but can also be used to
+extract information from the database when the current interfaces do not
+provide the desired functionality.
+.Pp
+The input database must exist.
+It makes no sense to use
+.Nm
+on a nonexistent or empty database.
+.Pp
+The
+.Nm
+command takes one or more arguments, all of which are concatenated to form
+a single SQL statement.
+Once the statement is executed,
+.Nm
+prints the resulting table on the screen, if any.
+.Pp
+The following subcommand options are recognized:
+.Bl -tag -width XX
+.It Fl -no-headers
+Avoids printing the headers of the table in the output of the command.
+.It Fl -results-file Ar path , Fl s Ar path
+.\" Copyright 2014 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.
+Specifies the results file to operate on.
+Defaults to
+.Sq LATEST ,
+which causes
+.Nm
+to automatically load the latest results file from the current test suite.
+.Pp
+The following values are accepted:
+.Bl -tag -width XX
+.It Sq LATEST
+Requests the load of the latest results file available for the test suite rooted
+at the current directory.
+.It Directory
+Requests the load of the latest results file available for the test suite rooted
+at the given directory.
+.It Test suite name
+Requests the load of the latest results file available for the given test suite.
+.It Results identifier
+Requests the load of a specific results file.
+.It Explicit file name (aka everything else)
+Load the specified results file.
+.El
+.Pp
+See
+.Sx Results files
+for more details.
+.El
+.Ss Results files
+.\" Copyright 2014 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.
+Results files contain, as their name implies, the results of the execution of a
+test suite.
+Each test suite executed by
+.Xr kyua-test 1
+generates a new results file, and such results files can be loaded later on by
+inspection commands such as
+.Xr kyua-report 1
+to analyze their contents.
+.Pp
+Results files support identifier-based lookups and also path name lookups.
+The differences between the two are described below.
+.Pp
+The default naming scheme for the results files provides simple support for
+identifier-based lookups and historical recording of test suite runs.
+Each results file is given an identifier derived from the test suite that
+generated it and the time the test suite was run.
+Kyua can later look up results files by these fields.
+.Pp
+The identifier follows this pattern:
+.Bd -literal -offset indent
+\*(Lttest_suite\*(Gt.\*(LtYYYYMMDD\*(Gt-\*(LtHHMMSS\*(Gt-\*(Ltuuuuuu\*(Gt
+.Ed
+.Pp
+where
+.Sq test_suite
+is the path to the root of the test suite that was run with all slashes replaced
+by underscores and
+.Sq YYYYMMDD-HHMMSS-uuuuuu
+is a timestamp with microsecond resolution.
+.Pp
+When using the default naming scheme, results files are stored in the
+.Pa ~/.kyua/store/
+subdirectory and each file holds a name of the form:
+.Bd -literal -offset indent
+~/.kyua/store/results.\*(Ltidentifier\*(Gt.db
+.Ed
+.Pp
+Results files are simple SQLite databases with the schema described in the
+.Pa /usr/share/kyua/store/schema_v?.sql
+files.
+For details on the schema, please refer to the heavily commented SQL file.
+.Sh EXIT STATUS
+The
+.Nm
+command returns 0 on success or 1 if the SQL statement is invalid or fails
+to run.
+.Pp
+Additional exit codes may be returned as described in
+.Xr kyua 1 .
+.Sh SEE ALSO
+.Xr kyua 1 ,
+.Xr kyua-test 1
Added: head/contrib/kyua/doc/kyua-db-migrate.1
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ head/contrib/kyua/doc/kyua-db-migrate.1 Sat Mar 28 01:14:37 2020 (r359386)
@@ -0,0 +1,182 @@
+.\" Copyright 2013 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-DB-MIGRATE 1
+.Os
+.Sh NAME
+.Nm "kyua db-migrate"
+.Nd Upgrades the schema of an existing results file
+.Sh SYNOPSIS
+.Nm
+.Op Fl -results-file Ar file
+.Sh DESCRIPTION
+The
+.Nm
+command migrates the schema of an existing database to the latest
+version implemented in
+.Xr kyua 1 .
+.Pp
+This operation is not reversible.
+However, a backup of the database is created in the same directory where the
+database lives.
+.Pp
+The following subcommand options are recognized:
+.Bl -tag -width XX
+.It Fl -results-file Ar path , Fl s Ar path
+.\" Copyright 2014 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.
+Specifies the results file to operate on.
+Defaults to
+.Sq LATEST ,
+which causes
+.Nm
+to automatically load the latest results file from the current test suite.
+.Pp
+The following values are accepted:
+.Bl -tag -width XX
+.It Sq LATEST
+Requests the load of the latest results file available for the test suite rooted
+at the current directory.
+.It Directory
+Requests the load of the latest results file available for the test suite rooted
+at the given directory.
+.It Test suite name
+Requests the load of the latest results file available for the given test suite.
+.It Results identifier
+Requests the load of a specific results file.
+.It Explicit file name (aka everything else)
+Load the specified results file.
+.El
+.Pp
+See
+.Sx Results files
+for more details.
+.El
+.Ss Results files
+.\" Copyright 2014 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.
+Results files contain, as their name implies, the results of the execution of a
+test suite.
+Each test suite executed by
+.Xr kyua-test 1
+generates a new results file, and such results files can be loaded later on by
+inspection commands such as
+.Xr kyua-report 1
+to analyze their contents.
+.Pp
+Results files support identifier-based lookups and also path name lookups.
+The differences between the two are described below.
+.Pp
+The default naming scheme for the results files provides simple support for
+identifier-based lookups and historical recording of test suite runs.
+Each results file is given an identifier derived from the test suite that
+generated it and the time the test suite was run.
+Kyua can later look up results files by these fields.
+.Pp
+The identifier follows this pattern:
+.Bd -literal -offset indent
+\*(Lttest_suite\*(Gt.\*(LtYYYYMMDD\*(Gt-\*(LtHHMMSS\*(Gt-\*(Ltuuuuuu\*(Gt
+.Ed
+.Pp
+where
+.Sq test_suite
+is the path to the root of the test suite that was run with all slashes replaced
+by underscores and
+.Sq YYYYMMDD-HHMMSS-uuuuuu
+is a timestamp with microsecond resolution.
+.Pp
+When using the default naming scheme, results files are stored in the
+.Pa ~/.kyua/store/
+subdirectory and each file holds a name of the form:
+.Bd -literal -offset indent
+~/.kyua/store/results.\*(Ltidentifier\*(Gt.db
+.Ed
+.Pp
+Results files are simple SQLite databases with the schema described in the
+.Pa /usr/share/kyua/store/schema_v?.sql
+files.
+For details on the schema, please refer to the heavily commented SQL file.
+.Sh EXIT STATUS
+The
+.Nm
+command returns 0 on success or 1 if the migration fails.
+.Pp
+Additional exit codes may be returned as described in
+.Xr kyua 1 .
+.Sh SEE ALSO
+.Xr kyua 1
Added: head/contrib/kyua/doc/kyua-debug.1
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ head/contrib/kyua/doc/kyua-debug.1 Sat Mar 28 01:14:37 2020 (r359386)
@@ -0,0 +1,398 @@
+.\" 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
+.\" 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.
+.Em Build directories
+(or object directories, target directories, product directories, etc.) is
+the concept that allows a developer to keep the source tree clean from
+build products by asking the build system to place such build products
+under a separate subtree.
+.Pp
+Most build systems today support build directories.
+For example, the GNU Automake/Autoconf build system exposes such concept when
+invoked as follows:
+.Bd -literal -offset indent
+$ cd my-project-1.0
+$ mkdir build
+$ cd build
+$ ../configure
+$ make
+.Ed
+.Pp
+Under such invocation, all the results of the build are left in the
+.Pa my-project-1.0/build/
+subdirectory while maintaining the contents of
+.Pa my-project-1.0/
+intact.
+.Pp
+Because build directories are an integral part of most build systems, and
+because they are a tool that developers use frequently,
+.Nm
+supports build directories too.
+This manifests in the form of
+.Nm
+being able to run tests from build directories while reading the (often
+immutable) test suite definition from the source tree.
+.Pp
+One important property of build directories is that they follow (or need to
+follow) the exact same layout as the source tree.
+For example, consider the following directory listings:
+.Bd -literal -offset indent
+src/Kyuafile
+src/bin/ls/
+src/bin/ls/Kyuafile
+src/bin/ls/ls.c
+src/bin/ls/ls_test.c
+src/sbin/su/
+src/sbin/su/Kyuafile
+src/sbin/su/su.c
+src/sbin/su/su_test.c
+
+obj/bin/ls/
+obj/bin/ls/ls*
+obj/bin/ls/ls_test*
+obj/sbin/su/
+obj/sbin/su/su*
+obj/sbin/su/su_test*
+.Ed
+.Pp
+Note how the directory layout within
+.Pa src/
+matches that of
+.Pa obj/ .
+The
+.Pa src/
+directory contains only source files and the definition of the test suite
+(the Kyuafiles), while the
+.Pa obj/
+directory contains only the binaries generated during a build.
+.Pp
+All commands that deal with the workspace support the
+.Fl -build-root Ar path
+option.
+When this option is provided, the directory specified by the
+option is considered to be the root of the build directory.
+For example, considering our previous fake tree layout, we could invoke
+.Nm
+as any of the following:
+.Bd -literal -offset indent
+$ kyua debug --kyuafile=src/Kyuafile --build-root=obj
+$ cd src && kyua debug --build-root=../obj
+.Ed
+.Ss Test filters
+.\" 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.
+A
+.Em test filter
+is a string that is used to match test cases or test programs in a test suite.
+Filters have the following form:
+.Bd -literal -offset indent
+test_program_name[:test_case_name]
+.Ed
+.Pp
+Where
+.Sq test_program_name
+is the name of a test program or a subdirectory in the test suite, and
+.Sq test_case_name
+is the name of a test case.
+.Ss Test isolation
+.\" Copyright 2014 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.
+The test programs and test cases run by
+.Nm
+are all executed in a deterministic environment.
+This known, clean environment serves to make the test execution as
+reproducible as possible and also to prevent clashes between tests that may,
+for example, create auxiliary files with overlapping names.
+.Pp
+For plain test programs and for TAP test programs, the whole test program
+is run under a single instance of the environment described in this page.
+For ATF test programs (see
+.Xr atf 7 ) ,
+each individual test case
+.Em and
+test cleanup routine are executed in separate environments.
+.Bl -tag -width XX
+.It Process space
+Each test is executed in an independent processes.
+Corollary: the test can do whatever it wants to the current process (such
+as modify global variables) without having to undo such changes.
+.It Session and process group
+The test is executed in its own session and its own process group.
+There is no controlling terminal attached to the session.
+.Pp
+Should the test spawn any children, the children should maintain the same
+session and process group.
+Modifying any of these settings prevents
+.Nm
+from being able to kill any stray subprocess as part of the cleanup phase.
+If modifying these settings is necessary, or if any subprocess started by
+the test decides to use a different process group or session, it is the
+responsibility of the test to ensure those subprocesses are forcibly
+terminated during cleanup.
+.It Work directory
+The test is executed in a temporary directory automatically created by the
+runtime engine.
+Corollary: the test can write to its current directory
+without needing to clean any files and/or directories it creates.
+The runtime engine takes care to recursively delete the temporary directories
+after the execution of a test case.
+Any file systems mounted within the temporary directory are also unmounted.
+.It Home directory
+The
+.Va HOME
+environment variable is set to the absolute path of the work directory.
+.It Umask
+The value of the umask is set to 0022.
+.It Environment
+The
+.Va LANG ,
+.Va LC_ALL ,
+.Va LC_COLLATE ,
+.Va LC_CTYPE ,
+.Va LC_MESSAGES ,
+.Va LC_MONETARY ,
+.Va LC_NUMERIC
+and
+.Va LC_TIME
+variables are unset.
+.Pp
+The
+.Va TZ
+variable is set to
+.Sq UTC .
+.Pp
+The
+.Va TMPDIR
+variable is set to the absolute path of the work directory.
+This is to prevent the test from mistakenly using a temporary directory
+outside of the automatically-managed work directory, should the test use the
+.Xr mktemp 3
+familiy of functions.
+.It Process limits
+The maximum soft core size limit is raised to its corresponding hard limit.
+This is a simple, best-effort attempt at allowing tests to dump core for
+further diagnostic purposes.
+.It Configuration varibles
+The test engine may pass run-time configuration variables to the test program
+via the environment.
+The name of the configuration variable is prefixed with
+.Sq TEST_ENV_
+so that a configuration variable of the form
+.Sq foo=bar
+becomes accessible in the environment as
+.Sq TEST_ENV_foo=bar .
+.El
+.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
Added: head/contrib/kyua/doc/kyua-help.1
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ head/contrib/kyua/doc/kyua-help.1 Sat Mar 28 01:14:37 2020 (r359386)
@@ -0,0 +1,64 @@
+.\" 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 September 9, 2012
+.Dt KYUA-HELP 1
+.Os
+.Sh NAME
+.Nm "kyua help"
+.Nd Shows usage information
+.Sh SYNOPSIS
+.Nm
+.Op Ar command
+.Sh DESCRIPTION
+The
+.Nm
+command provides interactive help on all supported commands and options.
+If, for some reason, you happen to spot a discrepancy in the output of this
+command and this document, the command is the authoritative source of
+information.
+.Pp
+If no arguments are provided, the command prints the list of common options
+and the list of supported subcommands.
+.Pp
+If the
+.Ar command
*** DIFF OUTPUT TRUNCATED AT 1000 LINES ***
More information about the svn-src-head
mailing list