From b8ce141a401c502407ab3e076ccfc3b428c8ac61 Mon Sep 17 00:00:00 2001 From: jmmv Date: Sat, 28 Dec 2013 20:05:31 +0000 Subject: 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. --- tests/README | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 tests/README (limited to 'tests/README') 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$ -- cgit v1.1