Set up the /usr/tests hierarchy.

This is a MFC of the following into stable/10:
- r257097 Set up the /usr/tests hierarchy.
- r257098 Add missing WITHOUTTESTS file.
- r257100 Add a tests(7) manual page.
- r257105 Disable WITHTESTS= for now.
- r257848 Fix buildworld when WITHTESTS is enabled.
- r257850 Subsume the functionality of MKATF into MKTESTS.
- r257851 Handle the removal of the test suite when WITHOUTTESTS=yes.
- r257852 Install category Kyuafiles from their category directories.
- r258232 Install BSD.tests.mtree when MKTESTS is yes.

Note that building with WITH_TESTS is still broken at this point (and
hence why WITHOUT_TESTS is the set as the default).  Subsequent pullups
will fix the remaining issues.

1 files changed, 55 insertions, 0 deletions

diff --git a/tests/README b/tests/README
new file mode 100644
index 0000000..416cea7
--- /dev/null
+++ b/tests/README
@@ -0,0 +1,55 @@
+src/tests: The FreeBSD test suite
+=================================
+
+This file describes the build infrastructure of the FreeBSD test suite.
+If you are only interested in using the test suite itself, please refer
+to tests(7) instead.
+
+The build of the test suite is organized in the following manner:
+
+* The build of all test artifacts is protected by the MK_TESTS knob.
+  The user can disable these with the WITHOUT_TESTS setting in
+  src.conf(5).
+
+* The goal for /usr/tests/ (the installed test programs) is to follow
+  the same hierarchy as /usr/src/ wherever possible, which in turn drives
+  several of the design decisions described below.  This simplifies the
+  discoverability of tests.  We want a mapping such as:
+
+    /usr/src/bin/cp/      -> /usr/tests/bin/cp/
+    /usr/src/lib/libc/    -> /usr/tests/lib/libc/
+    /usr/src/usr.bin/cut/ -> /usr/tests/usr.bin/cut/
+    ... and many more ...
+
+* Test programs for specific utilities and libraries are located next
+  to the source code of such programs.  For example, the tests for the
+  src/lib/libcrypt/ library live in src/lib/libcrypt/tests/.  The tests/
+  subdirectory is optional and should, in general, be avoided.
+
+* The src/tests/ hierarchy (this directory) provides generic test
+  infrastructure and glue code to join all test programs together into
+  a single test suite definition.
+
+* The src/tests/ hierarchy also includes cross-functional test programs:
+  i.e. test programs that cover more than a single utility or library
+  and thus don't fit anywhere else in the tree.  Consider this to follow
+  the same rationale as src/share/man/: this directory contains generic
+  manual pages while the manual pages that are specific to individual
+  tools or libraries live next to the source code.
+
+In order to keep the src/tests/ hierarchy decoupled from the actual test
+programs being installed --which is a worthy goal because it simplifies
+the addition of new test programs and simplifies the maintenance of the
+tree-- the top-level Kyuafile does not know which subdirectories may
+exist upfront.  Instead, such Kyuafile automatically detects, at
+run-time, which */Kyuafile files exist and uses those directly.
+
+Similarly, every directory in src/ that wants to install a Kyuafile to
+just recurse into other subdirectories reuses this Kyuafile with
+auto-discovery features.  As an example, take a look at src/lib/tests/
+whose sole purpose is to install a Kyuafile into /usr/tests/lib/.
+The goal in this specific case is for /usr/tests/lib/ to be generated
+entirely from src/lib/.
+
+-- 
+$FreeBSD$