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