README revision 257097
1257097Srpaulosrc/tests: The FreeBSD test suite 2257097Srpaulo================================= 3257097Srpaulo 4257097SrpauloThis file describes the build infrastructure of the FreeBSD test suite. 5257097SrpauloIf you are only interested in using the test suite itself, please refer 6257097Srpauloto tests(7) instead. 7257097Srpaulo 8257097SrpauloThe build of the test suite is organized in the following manner: 9257097Srpaulo 10257097Srpaulo* The build of all test artifacts is protected by the MK_TESTS knob. 11257097Srpaulo The user can disable these with the WITHOUT_TESTS setting in 12257097Srpaulo src.conf(5). 13257097Srpaulo 14257097Srpaulo* The goal for /usr/tests/ (the installed test programs) is to follow 15257097Srpaulo the same hierarchy as /usr/src/ wherever possible, which in turn drives 16257097Srpaulo several of the design decisions described below. This simplifies the 17257097Srpaulo discoverability of tests. We want a mapping such as: 18257097Srpaulo 19257097Srpaulo /usr/src/bin/cp/ -> /usr/tests/bin/cp/ 20257097Srpaulo /usr/src/lib/libc/ -> /usr/tests/lib/libc/ 21257097Srpaulo /usr/src/usr.bin/cut/ -> /usr/tests/usr.bin/cut/ 22257097Srpaulo ... and many more ... 23257097Srpaulo 24257097Srpaulo* Test programs for specific utilities and libraries are located next 25257097Srpaulo to the source code of such programs. For example, the tests for the 26257097Srpaulo src/lib/libcrypt/ library live in src/lib/libcrypt/tests/. The tests/ 27257097Srpaulo subdirectory is optional and should, in general, be avoided. 28257097Srpaulo 29257097Srpaulo* The src/tests/ hierarchy (this directory) provides generic test 30257097Srpaulo infrastructure and glue code to join all test programs together into 31257097Srpaulo a single test suite definition. 32257097Srpaulo 33257097Srpaulo* The src/tests/ hierarchy also includes cross-functional test programs: 34257097Srpaulo i.e. test programs that cover more than a single utility or library 35257097Srpaulo and thus don't fit anywhere else in the tree. Consider this to follow 36257097Srpaulo the same rationale as src/share/man/: this directory contains generic 37257097Srpaulo manual pages while the manual pages that are specific to individual 38257097Srpaulo tools or libraries live next to the source code. 39257097Srpaulo 40257097SrpauloIn order to keep the src/tests/ hierarchy decoupled from the actual test 41257097Srpauloprograms being installed --which is a worthy goal because it simplifies 42257097Srpaulothe addition of new test programs and simplifies the maintenance of the 43257097Srpaulotree-- the top-level Kyuafile does not know which subdirectories may 44257097Srpauloexist upfront. Instead, such Kyuafile automatically detects, at 45257097Srpaulorun-time, which */Kyuafile files exist and uses those directly. 46257097Srpaulo 47257097SrpauloSimilarly, every category subdirectory within src/tests/ provides the 48257097Srpaulosame Kyuafile with auto-discovery features. For example: src/tests/lib/ 49257097Srpauloholds a generic Makefile to install test-suite related material but such 50257097Srpaulodirectory does not know upfront which libraries within src/lib/ will 51257097Srpauloinstall tests. For this reason, the Kyuafile in src/tests/lib/ has to 52257097Srpauloalso use the auto-discovery features. The same applies for any other 53257097Srpaulocategory subdirectory (e.g. bin, usr.sbin, etc.). 54257097Srpaulo 55257097Srpaulo-- 56257097Srpaulo$FreeBSD: head/tests/README 257097 2013-10-25 05:25:19Z rpaulo $ 57