-*- mode: Outline -*- This is version 0.99 of the unwind library. This library supports several architecture/operating-system combinations: Linux/IA-64: Fully tested and supported. Linux/x86-64: Works well. Linux/x86: Works well, but C library is missing some unwind-info. Linux/PARISC: Works well, but C library missing unwind-info. HP-UX/IA-64: Mostly works but known to have some serious limitations. * General Build Instructions In general, this library can be built and installed with the following commands: $ ./configure $ make $ make install prefix=PREFIX where PREFIX is the installation prefix. By default, a prefix of /usr/local is used, such that libunwind.a is installed in /usr/local/lib and unwind.h is installed in /usr/local/include. For testing, you may want to use a prefix of /usr/local instead. * Building with Intel compiler ** Version 8 and later Starting with version 8, the preferred name for the IA-64 Intel compiler is "icc" (same name as on x86). Thus, the configure-line should look like this: $ ./configure CC=icc CFLAGS="-g -O3 -ip" CXX=icc CCAS=gcc CCASFLAGS=-g \ LDFLAGS="-L$PWD/src/.libs" ** Version 7 To build libunwind with the Intel Electron compiler (ECC), it is recommended to run configure like this: $ ./configure CC=ecc CXX=ecc CCAS=gcc CCASFLAGS=-g \ LDFLAGS="-L$PWD/src/.libs" The reason for this is that ECC uses the Intel assembler, which doesn't grok some of the IA-64 assembly code in the "tests" directory. For an ECC-built version of libunwind to work properly, you also need to ensure that /usr/include/asm/fpu.h contains a "long double" member called "__dummy" in the declaration of "struct ia64_fpreg". Without that member, variables of type unw_context_t won't be aligned properly. * Building on HP-UX For the time being, libunwind must be built with GCC on HP-UX. libunwind should be configured and installed on HP-UX like this: $ ./configure CFLAGS="-g -O2 -mlp64" CXXFLAGS="-g -O2 -mlp64" Caveat: Unwinding of 32-bit (ILP32) binaries is not supported at the moment. ** Workaround for older versions of GCC GCC v3.0 and GCC v3.2 ship with a bad version of sys/types.h. The workaround is to issue the following commands before running "configure": $ mkdir $top_dir/include/sys $ cp /usr/include/sys/types.h $top_dir/include/sys GCC v3.3.2 or later have been fixed and do not require this workaround. * Regression Testing After building the library, you can run a set of regression tests with: $ make check ** Expected results on IA-64 Linux Unless you have a very recent C library and compiler installed, it is currently expected to have the following tests fail on IA-64 Linux: Gtest-init (should pass starting with glibc-2.3.x/gcc-3.4) Ltest-init (should pass starting with glibc-2.3.x/gcc-3.4) test-ptrace (should pass starting with glibc-2.3.x/gcc-3.4) run-ia64-test-dyn1 (should pass starting with glibc-2.3.x) This does not mean that libunwind cannot be used with older compilers or C libraries, it just means that for certain corner cases, unwinding will fail. Since they're corner cases, it is not likely for applications to trigger them. Note: If you get lots of errors in Gia64-test-nat and Lia64-test-nat, it's almost certainly a sign of an old assembler. The GNU assembler used to encode previous-stack-pointer-relative offsets incorrectly. This bug was fixed on 21-Sep-2004 so any later assembler will be fine. ** Expected results on x86 Linux The following tests are expected to fail on x86 Linux: Gtest-bt (see http://sources.redhat.com/bugzilla/show_bug.cgi?id=595) Ltest-bt (likewise) Gtest-resume-sig (likewise) Ltest-resume-sig (likewise) Gtest-dyn1 (no dynamic unwind info support yet) Ltest-dyn1 (no dynamic unwind info support yet) test-setjmp (longjmp() not implemented yet) run-check-namespace (no _Ux86_getcontext yet) In addition, the following are failing on Debian (Sarge): Gtest-init (lack of unwind info for __libc_start_main, libc ought to be compiled without -fno-frame-pointer or with -fexceptions) Ltest-init (likewise) test-ptrace (likewise?) ** Expected results on x86-64 Linux The following tests are expected to fail on x86-64 Linux: Gtest-dyn1 (no dynamic unwind info support yet) Ltest-dyn1 (no dynamic unwind info support yet) Gtest-init (see http://gcc.gnu.org/bugzilla/show_bug.cgi?id=18743) Ltest-init (likewise) test-async-sig (crashes due to bad unwind-info?) test-setjmp (longjmp() not implemented yet) run-check-namespace (no _Ux86_64_getcontext yet) run-ptrace-mapper (??? investigate) run-ptrace-misc (see http://gcc.gnu.org/bugzilla/show_bug.cgi?id=18748 and http://gcc.gnu.org/bugzilla/show_bug.cgi?id=18749) ** Expected results on PARISC Linux Caveat: GCC v3.4 or newer is needed on PA-RISC Linux. Earlier versions of the compiler failed to generate the exception-handling program header (GNU_EH_FRAME) needed for unwinding. The following tests are expected to fail on x86-64 Linux: Gtest-bt (backtrace truncated at kill() due to lack of unwind-info) Ltest-bt (likewise) Gtest-resume-sig (Gresume.c:my_rt_sigreturn() is wrong somehow) Ltest-resume-sig (likewise) Gtest-init (likewise) Ltest-init (likewise) Gtest-dyn1 (no dynamic unwind info support yet) Ltest-dyn1 (no dynamic unwind info support yet) test-setjmp (longjmp() not implemented yet) run-check-namespace (toolchain doesn't support HIDDEN yet) ** Expected results on HP-UX "make check" is currently unsupported for HP-UX. You can try to run it, but most tests will fail (and some may fail to terminate). The only test programs that are known to work at this time are: tests/bt tests/Gperf-simple tests/test-proc-info tests/test-static-link tests/Gtest-init tests/Ltest-init tests/Gtest-resume-sig tests/Ltest-resume-sig * Performance Testing This distribution includes a few simple performance tests which give some idea of the basic cost of various libunwind operations. After building the library, you can run these tests with the following commands: $ cd tests $ make perf * Contacting the Developers Please direct all questions regarding this library to: libunwind@linux.hpl.hp.com For spam protection, you'll have to subscribe to this list before posting a question. You can do this by sending a mail to libunwind-request@linux.hpl.hp.com with a body of: subscribe libunwind Note: the host that is running this list is behind a firewall, so you'll not be able to use the Web interface to manage your subscription. Send a mail containing "help" to libunwind-request@linux.hpl.hp.com for information on how to manage your subscription via email.