testsuite/README

   1                      README for ltrace testsuite
   2               18, October, 2005 by Yao Qi  <qiyao@cn.ibm.com>
   3
   4 This is the README file for ltrace testsuite.
   5
   6 Quick Overview
   7 ==============
   8
   9    This testsuite is based on the dejagnu framework, which is again
  10 dependent on Expect and Tcl.  So all these three package (tcl, expect
  11 and dejagnu) should be installed on your system before running these
  12 tests.
  13
  14    After unpacking file ltrace-0.3.36.tar.gz:
  15
  16         tar -zxvfm ltrace-0.3.36.tar.gz
  17
  18    you'll find a directory named ltrace-0.3.36, which contains:
  19
  20  debian etc testsuite sysdeps
  21
  22 you can first build this package, then run the testsuite in the
  23 following steps:
  24
  25         1 cd ltrace-0.3.36
  26
  27         2 Confiugre ltrace for 32-bit mode or 64-bit mode.
  28         ./configure
  29          OR CC='gcc -m64' ./configure
  30
  31         3 Build ltace
  32         make
  33
  34         4 Run all the test in default mode.
  35         make check
  36
  37         The default is to test the ltrace just built, using the default
  38 compiler options.  You can control this by adding a symbol to 'make check':
  39
  40         To test the shipped ltrace tool (as opposed to the just built by "make")
  41
  42            --tool_exec=/usr/bin/ltrace
  43
  44         To change compiler switches for the target test cases
  45
  46            CFLAGS_FOR_TARGET=-m64
  47
  48         To change the target compiler (instead of shipped gcc)
  49
  50            CC_FOR_TARGET=/opt/gcc-4.0/bin/gcc
  51
  52
  53         You can run all the tests in different mode respectively as follows,
  54
  55         (1) ./run-my-tests.sh -m32
  56         OR make check
  57
  58         (test ltrace in build tree and compile test cases in 32-bit mode)
  59
  60         (2) ./run-my-tests.sh -m64
  61         OR make check RUNTESTFLAGS="CFLAGS_FOR_TARGET=-m64"
  62
  63         (test ltrace in build tree and compile test cases in 64-bit mode)
  64
  65         (3) ./run-my-tests.sh -m32 /usr/bin/ltrace
  66         OR make check RUNTESTFLAGS="--tool_exec=/usr/bin/ltrace"
  67
  68         (test shipped ltrace and compile test cases in 32-bit mode)
  69
  70         (4) ./run-my-tests.sh -m64 /usr/bin/ltrace
  71         OR make check RUNTESTFLAGS="--tool_exec=/usr/bin/ltrace CFLAGS_FOR_TARGET=-m64"
  72
  73         (run shipped ltrace and compile test cases in 64-bit mode)
  74
  75         (5) cd testsuite; make test
  76
  77         (run ltrace in build tree and compile test cases same as ltrace itself)
  78
  79
  80         (6) make check RUNTESTFLAGS="--tool_exec=/usr/bin/ltrace CFLAGS_FOR_TARGET=-m64 CC_FOR_TARGET=/opt/gcc-4.0/bin/gcc"
  81
  82         (run shipped ltrace and compile test cases in 64 bit mode by /opt/gcc-4.0/bin/gcc)
  83 Ltrace Testsuite
  84 ================
  85
  86    This testsuite for ltrace is a DejaGNU based testsuite that can
  87 either be used to test your newly built ltrace, or for regression
  88 testing a ltrace with local modifications.
  89
  90    Running the testsuite requires the prior installation of DejaGNU.
  91 The directory ftp://sources.redhat.com/pub/dejagnu/ will contain a
  92 recent snapshot.  Once DejaGNU is installed or built and add the
  93 location of runtest into $PATH, you can run the tests in one of the
  94 four ways it mentioned in Quick Overview.  The DejaGNU framework could
  95 be built in following steps:
  96
  97     1 Uppack these three packages.
  98     tar zxvf dejagnu-1.4.4.tar.gz
  99     tar zxvf tcl8.4.9-src.tar.gz
 100     tar zxvf expect-5.43.0.tar.gz
 101
 102     2 Build them and install.
 103     cd dejagnu-1.4.4
 104     ./configure
 105     make
 106     make install
 107     cd ..
 108
 109     cd tcl8.4.9/unix
 110     ./configure
 111     make
 112     make install
 113     cd ..
 114
 115     cd expect-5.43
 116     ./configure
 117     make
 118     make install
 119     cd ..
 120
 121    See the DejaGNU documentation and dejagnu-1.4.4/README for further
 122 details.
 123
 124
 125 Componets in ltrace testsuite
 126 =============================
 127
 128    This testsuite include all the source code you need for ltrace
 129 test in a single directory, which is "ltrace-0.3.36/testsuite".
 130 This directory includes the following files and sub-directories:
 131
 132 `config/unix.exp`
 133    configuration file for dejagnu-based test.
 134
 135 `lib/ltrace.exp`
 136    some basic functions used in all the test cases.
 137
 138 `ltrace.main/`
 139    some basic tests for major fetures of ltrace.
 140
 141    (1) ltrace.main/main.exp does tests on tracing a function
 142 implemented in a shared library.
 143
 144    (2) ltrace.main/main-internal.exp does tests on tracing a function
 145 implemented in main executable.
 146
 147    (3) ltrace.main/signals.exp do test on tracing user-defined signals
 148 sent by program to itself.
 149
 150    (4) ltrace.main/system_calls.exp do test on tracing all the system
 151 calls in program.
 152
 153 `ltrace.minor/`
 154    some tests for minor fetures of ltrace.
 155
 156    (1) ltrace.minor/attach-process.exp do test on attching a process.
 157
 158    (2) ltrace.minor/count-record.exp do test on counting time and
 159 calls.
 160
 161    (3) ltrace.minor/demangle.exp do test on demangling the C++ symbols.
 162
 163    (4) ltrace.minor/time-record-T.exp do test on showing the time spent
 164 inside each call.
 165
 166    (5) ltrace.minor/time-record-tt.exp
 167    (6) ltrace.minor/time-record-ttt.exp  do test on printing absolute
 168 timestamps in different format.
 169
 170    (7) ltrace.minor/trace-clone.exp do test on following clone to child
 171 process.
 172
 173    (8) ltrace.minor/trace-fork.exp do test on following fork to child
 174 process.
 175
 176 `ltrace.torture/`
 177    some tests in extreme condations.
 178
 179    (1) ltrace.torture/signals.exp do test on tracing flooded signals
 180 send to program itself.
 181
 182 Trouble shootings
 183 =================
 184
 185    (1) Running ltrace with -u option requires the superuser privilege.
 186 You must make sure you are root or have already got root's password.
 187
 188    (2) Check the *.ltrace files in each ltrace.* directories if there are
 189 some FAILs in the output.  They are informative.
 190
 191     (3) Add --verbose option in RUNTESTFLAGS when 'make check' if you want
 192 to see more details of these tests.
 193
 194 Test case extension
 195 ===================
 196
 197    Current testsuite is quite basic.  The framework of testsuite is
 198 extendable and scalealbe, so you can add new testcases into it easily.
 199 I will describe how to do that in different ways.
 200
 201    (1) Add new test case in an existed testcase directory.
 202
 203     It is simple.  Just add a foo.exp script and a relevant foo.c if
 204 necessary.  The dejagnu framework can run that script automatically when
 205 you run "make check".  The executable and object file would be generate
 206 in the test, please add them in 'clean' entry in Makefile.in to ensure
 207 that they could be cleaned up automatically when run 'make clean'.
 208
 209    (2) Add new test case in a new testcase directory.
 210
 211    It is a little complicated.  Fisrt create a new directory in
 212 testsuite/ with the same pattern as others, for example ltrace.bar,
 213 and then create a Makefile.in, an Expect script foo.exp, and relative
 214 foo.c if necessary.  Then modify the configure.ac in ltrace-0.3.36/,
 215 and add "testsuite/ltrace.bar/Makefile" into macro AC_OUTPUT,
 216 testsuite/ltrace.bar/Makefile will be generated when you configure
 217 this package.
 218
 219    Adding Makefile.in in the new directroy is just to remove
 220 intermediate files and log files automatically later, such as foo.ltrace,
 221 object files and executables.  For example, if you want to remove A.ltrace,
 222 B.ltrace, A and B at the time of cleanup, you can write Makefile.in
 223 like this:
 224
 225    clean:
 226         -rm -f A B
 227         -rm -f *.o
 228         -rm -f *.ltrace
 229    distclean: clean
 230         -rm -f Makefile
 231
 232    At last add the new directory 'ltrace.bar' into the macro SUBDIRS
 233 in testsuite/Makefile.in.
 234
 235    Rerun the autoconf and ./configure in ./ltrace-0.3.36, the Makefile
 236 will be updated.
 237
 238
 239
 240 ^L
 241 (this is for editing this file with GNU emacs)
 242 Local Variables:
 243 mode: text
 244 End: