1 README for ltrace testsuite 2 18, October, 2005 by Yao Qi <qiyao (a] 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: 245
