| -*- 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. |