|
| 1 | +libc-test is developed as part of the musl project |
| 2 | +http://www.musl-libc.org/ |
| 3 | + |
| 4 | +configuring: |
| 5 | + cp config.mak.def config.mak |
| 6 | + edit config.mak |
| 7 | +build and run tests: |
| 8 | + make |
| 9 | +clean up: |
| 10 | + make clean |
| 11 | + |
| 12 | +make builds all test binaries and runs them to create |
| 13 | +a REPORT file that contains all build and runtime errors |
| 14 | +(this means that make does not stop at build failures) |
| 15 | + |
| 16 | +contributing tests: |
| 17 | + |
| 18 | +design goals: |
| 19 | + |
| 20 | +- tests should be easy to run and build even a single test in isolation |
| 21 | +(so test should be self contained if possible) |
| 22 | +- failure of one test should not interfere with others |
| 23 | +(build failure, crash or unexpected results are all failures) |
| 24 | +- test output should point to the cause of the failure |
| 25 | +- test results should be robust |
| 26 | +- the test system should have minimal dependency |
| 27 | +(libc, posix sh, gnu make) |
| 28 | +- the test system should run on all archs and libcs |
| 29 | +- tests should leave the system in a clean state |
| 30 | + |
| 31 | +conventions: |
| 32 | + |
| 33 | +each test is in a separate file at a path like src/directory/file.c with |
| 34 | +its own main |
| 35 | + |
| 36 | +the test should return 0 on success and non-0 on failure, on failure it |
| 37 | +should print error messages to standard out if possible, on success no |
| 38 | +message should be printed |
| 39 | + |
| 40 | +to help with the above test protocol use t_error function for printing |
| 41 | +errors and return t_status from main, see src/common/test.h |
| 42 | +(t_error allows standard printf formatting, outputs at most 512bytes |
| 43 | +in a single write call to fd 1, so there is no buffering, long outputs |
| 44 | +are truncated, it sets the global t_status to 1) |
| 45 | + |
| 46 | +it is common to do many similar checks in a test, in such cases macros |
| 47 | +may be used to simplify the code like |
| 48 | +#define T1(a,b) (check(a,b) || (t_error("check(%s,%s) failed\n", a, b),0)) |
| 49 | +#define T2(f,w) (result=(f), result==(w) || (t_error("%s failed: got %s, want %s\n", #f, result, w),0)) |
| 50 | + |
| 51 | +binaries should be possible to run from arbitrary directory. |
| 52 | +the build system runs the tests using the src/common/runtest tool which |
| 53 | +kills the test process after a timeout and reports the exit status |
| 54 | +in case of failure |
| 55 | + |
| 56 | +directories: |
| 57 | + |
| 58 | +src/api: interface tests, build time include header tests |
| 59 | +src/common: common utilities compiled into libtest.a |
| 60 | +src/functional: functional tests aiming for large coverage of libc |
| 61 | +src/math: tests for each math function with input-output test vectors |
| 62 | +src/regression: regression tests aiming for testing particular bugs |
| 63 | + |
| 64 | +initial set of functional tests are derived from the libc-testsuit of |
| 65 | +Rich Felker, regression tests should contain reference of the bug |
| 66 | +(musl commit hash, glibc bug tracker url, etc) |
| 67 | + |
| 68 | +build system: |
| 69 | + |
| 70 | +the main non-file make targets are all, run, clean and cleanall. |
| 71 | +(cleanall removes the reports unlike clean, run reruns the dynamically |
| 72 | +linked executables) |
| 73 | + |
| 74 | +make variable can be overridden from config.mak or the make command line, |
| 75 | +the variable B sets the build directory which is src by default |
| 76 | + |
| 77 | +for each directory under src there are targets like $(B)/directory/all, |
| 78 | +$(B)/directory/run and $(B)/directory/clean to make only the contents |
| 79 | +of that directory, each directory has its own Makefile set up so it |
| 80 | +invokes the top level make with B=src src/directory/foo for the foo |
| 81 | +target, so it is possible to work only under a specific test directory |
| 82 | + |
| 83 | +the build and runtime errors of each target are accumulated into a |
| 84 | +target.err file and in the end they are concatenated into a REPORT |
| 85 | + |
| 86 | +each .c file in src/functional and src/regression are built into a |
| 87 | +dynamic linked and a static linked executable test binary by default, |
| 88 | +this behaviour can be changed by a similarly named .mk file changing |
| 89 | +make variables and specifying additional rules: |
| 90 | + |
| 91 | +$(B)/$(N) is the name of the binary target (the file name without the .c) |
| 92 | +$(B)/$(N)-static is the name of the static binary target |
| 93 | +$(B)/$(D) is the build directory |
| 94 | +$(N).CFLAGS are added to the CFLAGS at compilation |
| 95 | +$(N).LDFLAGS are added to the LDFLAGS at linking |
| 96 | +$(N).LDLIBS are added to the LDLIBS at linking |
| 97 | +$(N).BINS are the targets (if empty no binaries are built) |
| 98 | +$(N).LIBS are the non-executable targets (shared objects may use it) |
| 99 | + |
| 100 | +if a binary is linked together from several .o files then they |
| 101 | +have to be specified as prerequisits for the binary targets and |
| 102 | +added to the $(N).LDLIBS as well |
| 103 | + |
| 104 | +if a binary depends on a file at runtime (eg. a .so opened by dlopen) |
| 105 | +then the $(N).err target should depend on that file |
0 commit comments