| -*- mode: Outline -*- |
| |
| This is version 1.0 of the unwind library. This library supports |
| several architecture/operating-system combinations: |
| |
| Linux/x86-64: Works well. |
| Linux/x86: Works well. |
| Linux/ARM: Works well. |
| Linux/IA-64: Fully tested and supported. |
| Linux/PARISC: Works well, but C library missing unwind-info. |
| HP-UX/IA-64: Mostly works but known to have some serious limitations. |
| Linux/PPC64: Newly added. |
| FreeBSD/i386: Newly added. |
| FreeBSD/x86-64: Newly added (FreeBSD architecture is known as amd64). |
| |
| |
| * General Build Instructions |
| |
| In general, this library can be built and installed with the following |
| commands: |
| |
| $ autoreconf -i # Needed only for building from git. Depends on libtool. |
| $ ./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" |
| |
| |
| * 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. |
| |
| * Building for PowerPC64 / Linux |
| |
| For building for power64 you should use: |
| |
| $ ./configure CFLAGS="-g -O2 -m64" CXXFLAGS="-g -O2 -m64" |
| |
| If your power support altivec registers: |
| $ ./configure CFLAGS="-g -O2 -m64 -maltivec" CXXFLAGS="-g -O2 -m64 -maltivec" |
| |
| To check if your processor has support for vector registers (altivec): |
| cat /proc/cpuinfo | grep altivec |
| and should have something like this: |
| cpu : PPC970, altivec supported |
| |
| If libunwind seems to not work (backtracing failing), try to compile |
| it with -O0, without optimizations. There are some compiler problems |
| depending on the version of your gcc. |
| |
| * Building on FreeBSD |
| |
| General building instructions apply. To build and execute several tests, |
| you need libexecinfo library available in ports as devel/libexecinfo. |
| |
| Development of the port was done of FreeBSD 8.0-STABLE. The library |
| was build with the system compiler that is modified version of gcc 4.2.1, |
| as well as the gcc 4.4.3. |
| |
| * 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-resume-sig (fails to get SIGUSR2) |
| 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) |
| test-ptrace |
| |
| ** 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 |
| |
| ** Expected results on PPC64 Linux |
| |
| "make check" should run with no more than 10 out of 24 tests failed. |
| |
| |
| * 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-devel@nongnu.org |
| |
| You can do this by sending a mail to libunwind-request@nongnu.org with |
| a body of: |
| |
| subscribe libunwind-devel |
| |
| or you can subscribe and manage your subscription via the |
| web-interface at: |
| |
| https://savannah.nongnu.org/mail/?group=libunwind |