nsz Git - libc-test/blob - README

   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/run 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 as well, run reruns the dynamically
  72 linked executables)
  73
  74 for each directory under src there are targets like src/directory/all,
  75 src/directory/run and src/directory/clean to make only the contents
  76 of that directory, each directory has its own Makefile set up so it
  77 invokes the top level make with src/directory/foo for the foo target,
  78 so it is possible to work only under a specific test directory
  79
  80 the build and runtime errors of each target are accumulated into a
  81 target.err file and in the end they are concatenated into a REPORT
  82
  83 each .c file in src/functional and src/regression are built into a
  84 dynamic linked and a static linked executable test binary by default,
  85 this behaviour can be changed by a similarly named .mk file changing
  86 make variables and specifying additional rules:
  87
  88 $(N) is the name of the binary target (the file name without the .c)
  89 $(N)-static is the name of the static binary target
  90 $(D) is the directory
  91 $(N).CFLAGS are added to the CFLAGS at compilation
  92 $(N).LDFLAGS are added to the LDFLAGS at linking
  93 $(N).LDLIBS are added to the LDLIBS at linking
  94 $(N).BINS are the targets (if empty no binaries are built)
  95 $(N).LIBS are the non-executable targets (shared objects may use it)
  96
  97 if a binary is linked together from several .o files then they
  98 have to be specified as prerequisits for the binary targets and
  99 added to the $(N).LDLIBS as well
 100
 101 if a binary depends on a file at runtime (eg. a .so opened by dlopen)
 102 then the $(N).err target should depend on that file