README for ltrace testsuite 18, October, 2005 by Yao Qi This is the README file for ltrace testsuite. Quick Overview ============== This testsuite is based on the dejagnu framework, which is again dependent on Expect and Tcl. So all these three package (tcl, expect and dejagnu) should be installed on your system before running these tests. After unpacking file ltrace-0.3.36.tar.gz: tar -zxvfm ltrace-0.3.36.tar.gz you'll find a directory named ltrace-0.3.36, which contains: debian etc testsuite sysdeps you can first build this package, then run the testsuite in the following steps: 1 cd ltrace-0.3.36 2 Confiugre ltrace for 32-bit mode or 64-bit mode. ./configure OR CC='gcc -m64' ./configure 3 Build ltace make 4 Run all the test in default mode. make check The default is to test the ltrace just built, using the default compiler options. You can control this by adding a symbol to 'make check': To test the shipped ltrace tool (as opposed to the just built by "make") --tool_exec=/usr/bin/ltrace To change compiler switches for the target test cases CFLAGS_FOR_TARGET=-m64 To change the target compiler (instead of shipped gcc) CC_FOR_TARGET=/opt/gcc-4.0/bin/gcc You can run all the tests in different mode respectively as follows, (1) ./run-my-tests.sh -m32 OR make check (test ltrace in build tree and compile test cases in 32-bit mode) (2) ./run-my-tests.sh -m64 OR make check RUNTESTFLAGS="CFLAGS_FOR_TARGET=-m64" (test ltrace in build tree and compile test cases in 64-bit mode) (3) ./run-my-tests.sh -m32 /usr/bin/ltrace OR make check RUNTESTFLAGS="--tool_exec=/usr/bin/ltrace" (test shipped ltrace and compile test cases in 32-bit mode) (4) ./run-my-tests.sh -m64 /usr/bin/ltrace OR make check RUNTESTFLAGS="--tool_exec=/usr/bin/ltrace CFLAGS_FOR_TARGET=-m64" (run shipped ltrace and compile test cases in 64-bit mode) (5) cd testsuite; make test (run ltrace in build tree and compile test cases same as ltrace itself) (6) make check RUNTESTFLAGS="--tool_exec=/usr/bin/ltrace CFLAGS_FOR_TARGET=-m64 CC_FOR_TARGET=/opt/gcc-4.0/bin/gcc" (run shipped ltrace and compile test cases in 64 bit mode by /opt/gcc-4.0/bin/gcc) Ltrace Testsuite ================ This testsuite for ltrace is a DejaGNU based testsuite that can either be used to test your newly built ltrace, or for regression testing a ltrace with local modifications. Running the testsuite requires the prior installation of DejaGNU. The directory ftp://sources.redhat.com/pub/dejagnu/ will contain a recent snapshot. Once DejaGNU is installed or built and add the location of runtest into $PATH, you can run the tests in one of the four ways it mentioned in Quick Overview. The DejaGNU framework could be built in following steps: 1 Uppack these three packages. tar zxvf dejagnu-1.4.4.tar.gz tar zxvf tcl8.4.9-src.tar.gz tar zxvf expect-5.43.0.tar.gz 2 Build them and install. cd dejagnu-1.4.4 ./configure make make install cd .. cd tcl8.4.9/unix ./configure make make install cd .. cd expect-5.43 ./configure make make install cd .. See the DejaGNU documentation and dejagnu-1.4.4/README for further details. Componets in ltrace testsuite ============================= This testsuite include all the source code you need for ltrace test in a single directory, which is "ltrace-0.3.36/testsuite". This directory includes the following files and sub-directories: `config/unix.exp` configuration file for dejagnu-based test. `lib/ltrace.exp` some basic functions used in all the test cases. `ltrace.main/` some basic tests for major fetures of ltrace. (1) ltrace.main/main.exp does tests on tracing a function implemented in a shared library. (2) ltrace.main/main-internal.exp does tests on tracing a function implemented in main executable. (3) ltrace.main/signals.exp do test on tracing user-defined signals sent by program to itself. (4) ltrace.main/system_calls.exp do test on tracing all the system calls in program. `ltrace.minor/` some tests for minor fetures of ltrace. (1) ltrace.minor/attach-process.exp do test on attching a process. (2) ltrace.minor/count-record.exp do test on counting time and calls. (3) ltrace.minor/demangle.exp do test on demangling the C++ symbols. (4) ltrace.minor/time-record-T.exp do test on showing the time spent inside each call. (5) ltrace.minor/time-record-tt.exp (6) ltrace.minor/time-record-ttt.exp do test on printing absolute timestamps in different format. (7) ltrace.minor/trace-clone.exp do test on following clone to child process. (8) ltrace.minor/trace-fork.exp do test on following fork to child process. `ltrace.torture/` some tests in extreme condations. (1) ltrace.torture/signals.exp do test on tracing flooded signals send to program itself. Trouble shootings ================= (1) Running ltrace with -u option requires the superuser privilege. You must make sure you are root or have already got root's password. (2) Check the *.ltrace files in each ltrace.* directories if there are some FAILs in the output. They are informative. (3) Add --verbose option in RUNTESTFLAGS when 'make check' if you want to see more details of these tests. Test case extension =================== Current testsuite is quite basic. The framework of testsuite is extendable and scalealbe, so you can add new testcases into it easily. I will describe how to do that in different ways. (1) Add new test case in an existed testcase directory. It is simple. Just add a foo.exp script and a relevant foo.c if necessary. The dejagnu framework can run that script automatically when you run "make check". The executable and object file would be generate in the test, please add them in 'clean' entry in Makefile.in to ensure that they could be cleaned up automatically when run 'make clean'. (2) Add new test case in a new testcase directory. It is a little complicated. Fisrt create a new directory in testsuite/ with the same pattern as others, for example ltrace.bar, and then create a Makefile.in, an Expect script foo.exp, and relative foo.c if necessary. Then modify the configure.ac in ltrace-0.3.36/, and add "testsuite/ltrace.bar/Makefile" into macro AC_OUTPUT, testsuite/ltrace.bar/Makefile will be generated when you configure this package. Adding Makefile.in in the new directroy is just to remove intermediate files and log files automatically later, such as foo.ltrace, object files and executables. For example, if you want to remove A.ltrace, B.ltrace, A and B at the time of cleanup, you can write Makefile.in like this: clean: -rm -f A B -rm -f *.o -rm -f *.ltrace distclean: clean -rm -f Makefile At last add the new directory 'ltrace.bar' into the macro SUBDIRS in testsuite/Makefile.in. Rerun the autoconf and ./configure in ./ltrace-0.3.36, the Makefile will be updated. ^L (this is for editing this file with GNU emacs) Local Variables: mode: text End: