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 directories:
  52
  53 src/api: interface tests, build time include header tests
  54 src/common: common utilities compiled into libtest.a
  55 src/functional: functional tests aiming for large coverage of libc
  56 src/math: tests for each math function with input-output test vectors
  57 src/regression: regression tests aiming for testing particular bugs
  58
  59 initial set of functional tests are derived from the libc-testsuit of
  60 Rich Felker, regression tests should contain reference of the bug
  61 (musl commit hash, glibc bug tracker url, etc)
  62
  63 build system:
  64
  65 the targets src/directory/all and src/directory/clean build and clean
  66 only the specified directory, each directory has its own Makefile that
  67 invokes the top level make with src/directory/foo for the foo target,
  68 so it is possible to work only under a specific test directory
  69
  70 the build and runtime errors of each target are accumulated into a
  71 target.err file and in the end they are concatenated into a REPORT
  72
  73 each .c file in src/functional and src/regression are built into a
  74 dynamic linked and a static linked executable test binary by default,
  75 this behaviour can be changed by a similarly named .mk file changing
  76 make variables and specifying additional rules:
  77
  78 $(N) is the name of the binary target (the file name without the .c)
  79 $(N)-static is the name of the static binary target
  80 $(D) is the directory
  81 $(N).CFLAGS are added to the CFLAGS at compilation
  82 $(N).LDFLAGS are added to the LDFLAGS at linking
  83 $(N).LDLIBS are added to the LDLIBS at linking
  84 $(N).BINS are the targets (if empty no binaries are built)
  85 $(N).LIBS are the non-executable targets (shared objects may use it)
  86
  87 if a binary is linked together from several .o files then they
  88 have to be specified as prerequisits for the binary targets and
  89 added to the $(N).LDLIBS as well
  90
  91 if a binary depends on a file at runtime (eg. a .so opened by dlopen)
  92 then the $(N).err target should depend on that file