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 47260013SjmmvSimilarly, every directory in src/ that wants to install a Kyuafile to 48260013Sjmmvjust recurse into other subdirectories reuses this Kyuafile with 49260013Sjmmvauto-discovery features. As an example, take a look at src/lib/tests/ 50260013Sjmmvwhose sole purpose is to install a Kyuafile into /usr/tests/lib/. 51260013SjmmvThe goal in this specific case is for /usr/tests/lib/ to be generated 52260013Sjmmventirely from src/lib/. 53257097Srpaulo 54257097Srpaulo-- 55257097Srpaulo$FreeBSD$ 56