Add more regress guidelines to bsd.regress.mk(5) man page.

input schwarze@ jmc@; OK henning@ benno@

diff --git a/share/man/man5/bsd.regress.mk.5 b/share/man/man5/bsd.regress.mk.5
index 917c82a..37d9c5c 100644 (file)
--- a/share/man/man5/bsd.regress.mk.5
+++ b/share/man/man5/bsd.regress.mk.5
@@ -1,4 +1,4 @@
-.\" $OpenBSD: bsd.regress.mk.5,v 1.11 2017/01/16 07:00:03 jmc Exp $
+.\" $OpenBSD: bsd.regress.mk.5,v 1.12 2017/05/29 20:35:47 bluhm Exp $
 .\"
 .\" Copyright (c) 2002 Anil Madhavapeddy
 .\" Copyright (c) 2000 Marc Espie
@@ -25,7 +25,7 @@
 .\" (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 $Mdocdate: January 16 2017 $
+.Dd $Mdocdate: May 29 2017 $
 .Dt BSD.REGRESS.MK 5
 .Os
 .Sh NAME
@@ -72,10 +72,6 @@ If this variable is set to anything but
 the
 .Cm regress
 target will abort as soon as a test fails.
-This variable is intended to be set at runtime in the environment
-or in
-.Pa /etc/mk.conf ,
-but not in the test's Makefile itself.
 .It Ev REGRESS_LOG
 Points to the fully-qualified path of a file to which regression
 results are appended.
@@ -112,6 +108,11 @@ test targets which require it.
 See
 .Xr doas 1 .
 .El
+.Pp
+Some variables are intended to be set at runtime in the environment
+or in
+.Xr mk.conf 5 ,
+but not in the regress Makefile itself.
 .Sh GUIDELINES
 If an individual test passes,
 .Sy make Ar testname
@@ -129,6 +130,16 @@ To skip everything, implement the
 target with a command that prints
 .Qq SKIPPED .
 .Pp
+Some tests may require a special setup on the test machine that has
+to be done manually before testing.
+This requirement has to be documented in the Makefile or in a
+.Pa README
+file.
+The test should find out whether the setup exists before running
+and print
+.Qq SKIPPED
+and exit if it is missing.
+.Pp
 Tests should not fail because an intended feature has not been
 implemented yet.
 To avoid such false failures, a test should show the reason, print
@@ -151,6 +162,12 @@ but running
 or
 .Sy make
 should have the same effect.
+Tests must be runnable by root, and may also succeed when run as a
+regular user.
+To run tests automatically with
+.Xr cron 8
+they must not assume to have a controlling tty.
+An individual regress test may create a pseudo tty if it needs one.
 .Pp
 Tests should use the binaries installed and the kernel running on
 the local system.