|author||Rui Paulo <rpaulo@FreeBSD.org>||2013-10-25 05:25:19 +0000|
|committer||Rui Paulo <rpaulo@FreeBSD.org>||2013-10-25 05:25:19 +0000|
Set up the /usr/tests hierarchy.
Populate /usr/tests with the only test programs that currently live in the tree (those in lib/libcrypt/tests/) and add all the build machinery to accompany this change. In particular: - Add a WITHOUT_TESTS variable that users can define to request that no tests be put in /usr/tests. - Add a top-level Kyuafile for /usr/tests and a way to create similar Kyuafiles in top-level subdirectories. - Add a BSD.tests.dist file to define the directory layout of /usr/tests. Submitted by: Julio Merino jmmv google.com Reviewed by: sjg MFC after: 2 weeks
Notes: svn path=/head/; revision=257097
Diffstat (limited to 'tests/README')
1 files changed, 56 insertions, 0 deletions
diff --git a/tests/README b/tests/README
new file mode 100644
@@ -0,0 +1,56 @@
+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
+* 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 category subdirectory within src/tests/ provides the
+same Kyuafile with auto-discovery features. For example: src/tests/lib/
+holds a generic Makefile to install test-suite related material but such
+directory does not know upfront which libraries within src/lib/ will
+install tests. For this reason, the Kyuafile in src/tests/lib/ has to
+also use the auto-discovery features. The same applies for any other
+category subdirectory (e.g. bin, usr.sbin, etc.).