README
1 README for ltrace testsuite
2 18, October, 2005 by Yao Qi <qiyao@cn.ibm.com>
3
4This is the README file for ltrace testsuite.
5
6Quick Overview
7==============
8
9 This testsuite is based on the dejagnu framework, which is again
10dependent on Expect and Tcl. So all these three package (tcl, expect
11and dejagnu) should be installed on your system before running these
12tests.
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
22you can first build this package, then run the testsuite in the
23following 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
38compiler 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)
83Ltrace Testsuite
84================
85
86 This testsuite for ltrace is a DejaGNU based testsuite that can
87either be used to test your newly built ltrace, or for regression
88testing a ltrace with local modifications.
89
90 Running the testsuite requires the prior installation of DejaGNU.
91The directory ftp://sources.redhat.com/pub/dejagnu/ will contain a
92recent snapshot. Once DejaGNU is installed or built and add the
93location of runtest into $PATH, you can run the tests in one of the
94four ways it mentioned in Quick Overview. The DejaGNU framework could
95be 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
122details.
123
124
125Componets in ltrace testsuite
126=============================
127
128 This testsuite include all the source code you need for ltrace
129test in a single directory, which is "ltrace-0.3.36/testsuite".
130This 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
142implemented in a shared library.
143
144 (2) ltrace.main/main-internal.exp does tests on tracing a function
145implemented in main executable.
146
147 (3) ltrace.main/signals.exp do test on tracing user-defined signals
148sent by program to itself.
149
150 (4) ltrace.main/system_calls.exp do test on tracing all the system
151calls 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
159calls.
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
164inside each call.
165
166 (5) ltrace.minor/time-record-tt.exp
167 (6) ltrace.minor/time-record-ttt.exp do test on printing absolute
168timestamps in different format.
169
170 (7) ltrace.minor/trace-clone.exp do test on following clone to child
171process.
172
173 (8) ltrace.minor/trace-fork.exp do test on following fork to child
174process.
175
176`ltrace.torture/`
177 some tests in extreme condations.
178
179 (1) ltrace.torture/signals.exp do test on tracing flooded signals
180send to program itself.
181
182Trouble shootings
183=================
184
185 (1) Running ltrace with -u option requires the superuser privilege.
186You 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
189some FAILs in the output. They are informative.
190
191 (3) Add --verbose option in RUNTESTFLAGS when 'make check' if you want
192to see more details of these tests.
193
194Test case extension
195===================
196
197 Current testsuite is quite basic. The framework of testsuite is
198extendable and scalealbe, so you can add new testcases into it easily.
199I 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
204necessary. The dejagnu framework can run that script automatically when
205you run "make check". The executable and object file would be generate
206in the test, please add them in 'clean' entry in Makefile.in to ensure
207that 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
212testsuite/ with the same pattern as others, for example ltrace.bar,
213and then create a Makefile.in, an Expect script foo.exp, and relative
214foo.c if necessary. Then modify the configure.ac in ltrace-0.3.36/,
215and add "testsuite/ltrace.bar/Makefile" into macro AC_OUTPUT,
216testsuite/ltrace.bar/Makefile will be generated when you configure
217this package.
218
219 Adding Makefile.in in the new directroy is just to remove
220intermediate files and log files automatically later, such as foo.ltrace,
221object files and executables. For example, if you want to remove A.ltrace,
222B.ltrace, A and B at the time of cleanup, you can write Makefile.in
223like 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
233in testsuite/Makefile.in.
234
235 Rerun the autoconf and ./configure in ./ltrace-0.3.36, the Makefile
236will be updated.
237
238
239
240^L
241(this is for editing this file with GNU emacs)
242Local Variables:
243mode: text
244End:
245