Add some documentation for bsd.test.mk.

1 files changed, 84 insertions, 0 deletions

diff --git a/share/mk/bsd.README b/share/mk/bsd.README
index a9adc1f2201f..0dcfb2ccadd1 100644
--- a/share/mk/bsd.README
+++ b/share/mk/bsd.README
@@ -39,6 +39,7 @@ bsd.prog.mk		- building programs from source files
 bsd.snmpmod.mk		- building modules for the SNMP daemon bsnmpd
 bsd.subdir.mk		- targets for building subdirectories
 bsd.sys.mk		- common settings used for building FreeBSD sources
+bsd.test.mk		- building test programs from source files
 sys.mk			- default rules for all makes
 
 This file does not document bsd.port*.mk.  They are documented in ports(7).
@@ -365,3 +366,86 @@ It has rules for building profiled objects; profiled libraries are
 built by default.
 
 Libraries are ranlib'd before installation.
+
+=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
+
+The include file <bsd.test.mk> handles building one or more test programs
+intended to be used in the FreeBSD Test Suite under /usr/tests/.
+
+It has seven targets:
+
+	all:
+		build the test programs.
+	clean:
+		remove the test programs and any object files.
+	cleandir:
+		remove all of the files removed by the target clean, as
+		well as .depend and tags.
+	depend:
+		make the dependencies for the source files, and store
+		them in the file .depend.
+	install:
+                install the test programs and their data files; if the
+                Makefile does not itself define the target install, the
+                targets beforeinstall and afterinstall may also be used
+                to cause actions immediately before and after the
+                install target is executed.
+	lint:
+		run lint on the source files.
+	tags:
+		create a tags file for the source files.
+	test:
+		runs the test programs from the object directory; if the
+		Makefile does not itself define the target test, the
+		targets beforetest and aftertest may also be used to
+		cause actions immediately before and after the test
+		target is executed.
+
+It sets/uses the following variables, among many others:
+
+TESTDIR		Path to the installed tests.  Must be a subdirectory of
+		TESTSBASE and the subpath should match the relative
+		location of the tests within the src tree.
+
+KYUAFILE	If 'auto' (the default), generate a Kyuafile out of the
+		test programs defined in the Makefile.  If 'yes', then a
+		manually-crafted Kyuafile must be supplied with the
+		sources.  If 'no', no Kyuafile is installed (useful for
+		subdirectories providing helper programs or data files
+		only).
+
+ATF_TESTS_C	The names of the ATF C test programs to build.
+
+ATF_TESTS_CXX	The names of the ATF C++ test programs to build.
+
+ATF_TESTS_SH	The names of the ATF sh test programs to build.
+
+PLAIN_TESTS_C	The names of the plain (legacy) programs to build.
+
+PLAIN_TESTS_CXX	The names of the plain (legacy) test programs to build.
+
+PLAIN_TESTS_SH	The names of the plain (legacy) test programs to build.
+
+TAP_TESTS_C	The names of the TAP-compliant C test programs to build.
+
+TAP_TESTS_CXX	The names of the TAP-compliant C++ test programs to
+		build.
+
+TAP_TESTS_SH	The names of the TAP-compliant sh test programs to
+		build.
+
+TESTS_SUBDIRS	List of subdirectories containing tests into which to
+		recurse.  Differs from SUBDIR in that these directories
+		get registered into the automatically-generated
+		Kyuafile (if any).
+
+NOT_FOR_TEST_SUITE
+		If defined, none of the built test programs get
+		installed under /usr/tests/ and no Kyuafile is
+		automatically generated.  Should not be used within the
+		FreeBSD source tree but is provided for the benefit of
+		third-parties.
+
+The actual building of the test programs is performed by <bsd.prog.mk>.
+Please see the documentation above for this other file for additional
+details on the behavior of <bsd.test.mk>.