version 1.2, 2017/03/05 19:57:39 |
version 1.5, 2020/03/13 15:32:31 |
|
|
.\" $Id$ |
.\" $Id$ |
.\" |
.\" |
.\" Copyright (c) 2017 Ingo Schwarze <schwarze@openbsd.org> |
.\" Copyright (c) 2017, 2019, 2020 Ingo Schwarze <schwarze@openbsd.org> |
.\" |
.\" |
.\" Permission to use, copy, modify, and distribute this software for any |
.\" Permission to use, copy, modify, and distribute this software for any |
.\" purpose with or without fee is hereby granted, provided that the above |
.\" purpose with or without fee is hereby granted, provided that the above |
|
|
.Sh SYNOPSIS |
.Sh SYNOPSIS |
.Nm ./regress.pl |
.Nm ./regress.pl |
.Oo |
.Oo |
.Ar directory Ns Op Pf : Ar test |
.Ar directory Ns Op Pf / Ar test |
.Op Ar modifier ... |
.Op Ar modifier ... |
.Oc |
.Oc |
.Sh DESCRIPTION |
.Sh DESCRIPTION |
|
|
steering script allows running the |
steering script allows running the |
.Xr mandoc 1 |
.Xr mandoc 1 |
regression suite on arbitrary operating systems, |
regression suite on arbitrary operating systems, |
even though the suite was designed for OpenBSD only. |
even though the suite was originally designed for OpenBSD only. |
.Pp |
.Pp |
When run without an argument, |
When run without an argument, |
.Nm |
.Nm |
runs the complete regression suite. |
runs the complete regression suite. |
.Pp |
.Pp |
When run with one argument, that argument can be: |
The first argument is a Perl regular expression to match test names, |
.Bl -enum |
automatically anchored at the beginning of the names. |
.It |
Test names are names of test input files without the file name extension |
A single dot to run the complete suite. |
.Pa .in , |
.It |
for example |
One of the top level directories, for example |
.Pa char/unicode/named . |
.Pa mdoc , |
|
to run the test suite for a complete language or feature group. |
|
.It |
|
A subdirectory, for example |
|
.Pa man/IP , |
|
to run the tests for a specific macro or an individual feature. |
|
.It |
|
A subdirectory with a test name appended with a colon, for example |
|
.Pa char/unicode : Ns Pa named , |
|
to run the tests for one particular input file. |
|
.El |
|
.Pp |
.Pp |
Any additional arguments modify the way the tests are run. |
Any additional arguments modify the way the tests are run. |
The default is |
The default is |
|
|
Run subtests for |
Run subtests for |
.Fl T Cm markdown |
.Fl T Cm markdown |
output mode. |
output mode. |
|
.It Cm tag |
|
Run subtests for automatic and manual tagging. |
.It Cm utf8 |
.It Cm utf8 |
Run subtests for |
Run subtests for |
.Fl T Cm utf8 |
.Fl T Cm utf8 |
|
|
.It Cm verbose |
.It Cm verbose |
Display approximate indications of what is being done. |
Display approximate indications of what is being done. |
.El |
.El |
.Pp |
|
The amount of summary lines shown can be modified by giving an |
|
argument consisting of a single digit: |
|
.Bl -tag -width verbose |
|
.It Cm 3 |
|
Show all summary lines for all directories entered. |
|
Even without |
|
.Cm verbose , |
|
this generates more than hundred lines of output when running the |
|
complete regression suite. |
|
.It Cm 2 |
|
This is the default. |
|
It shows the summary lines for the |
|
.Ar directory |
|
given on the command line and its immediate children. |
|
Except for |
|
.Pa mdoc , |
|
the output usually fits on one screen. |
|
.It Cm 1 |
|
Only show a single summary line for the whole run. |
|
.It Cm 0 |
|
Do not show any summary lines. |
|
No output means success. |
|
Success or failure can also be seen from the exit status. |
|
.El |
|
.Pp |
|
All failed tests are always reported, even when the |
|
.Cm 0 |
|
modifier is given. |
|
.Sh EXIT STATUS |
.Sh EXIT STATUS |
.Ex -std |
.Ex -std |
.Sh EXAMPLES |
.Sh EXAMPLES |
Line 140 Complete check, but keep the tree clean: |
|
Line 102 Complete check, but keep the tree clean: |
|
.Pp |
.Pp |
.Dl ./regress.pl \&. all clean |
.Dl ./regress.pl \&. all clean |
.Pp |
.Pp |
Test all of |
|
.Pa mdoc , |
|
but don't print the usual 65 lines of output: |
|
.Pp |
|
.Dl ./regress.pl mdoc 1 |
|
.Pp |
|
Investigate a specific failure: |
Investigate a specific failure: |
.Pp |
.Pp |
.Dl ./regress.pl mdoc/Bd:broken man verbose |
.Dl ./regress.pl mdoc/Bd/broken man verbose |
.Sh HISTORY |
.Sh HISTORY |
The |
The |
.Nm |
.Nm |
|
|
subdirectory of the regression suite is not included. |
subdirectory of the regression suite is not included. |
It uses a Makefile structure that differs vastly from the |
It uses a Makefile structure that differs vastly from the |
rest of the suite. |
rest of the suite. |
|
.Sh BUGS |
|
The C library function |
|
.Xr wcwidth 3 |
|
is known to be buggy on Solaris, which may cause failures in the |
|
regression suite, usually because output lines containing affected |
|
Unicode characters wrap too early. |
|
.Pp |
|
The regression suite does not work at all on Solaris 10 or earlier |
|
because the Perl interpreter provided with those systems is too old. |