3 This is version 1.0 of the unwind library. This library supports
4 several architecture/operating-system combinations:
6 Linux/x86-64: Works well.
9 Linux/IA-64: Fully tested and supported.
10 Linux/PARISC: Works well, but C library missing unwind-info.
11 HP-UX/IA-64: Mostly works but known to have some serious limitations.
12 Linux/PPC64: Newly added.
13 Linux/SuperH: Newly added.
14 FreeBSD/i386: Newly added.
15 FreeBSD/x86-64: Newly added (FreeBSD architecture is known as amd64).
18 * General Build Instructions
20 In general, this library can be built and installed with the following
23 $ autoreconf -i # Needed only for building from git. Depends on libtool.
26 $ make install prefix=PREFIX
28 where PREFIX is the installation prefix. By default, a prefix of
29 /usr/local is used, such that libunwind.a is installed in
30 /usr/local/lib and unwind.h is installed in /usr/local/include. For
31 testing, you may want to use a prefix of /usr/local instead.
34 * Building with Intel compiler
36 ** Version 8 and later
38 Starting with version 8, the preferred name for the IA-64 Intel
39 compiler is "icc" (same name as on x86). Thus, the configure-line
40 should look like this:
42 $ ./configure CC=icc CFLAGS="-g -O3 -ip" CXX=icc CCAS=gcc CCASFLAGS=-g \
43 LDFLAGS="-L$PWD/src/.libs"
48 For the time being, libunwind must be built with GCC on HP-UX.
50 libunwind should be configured and installed on HP-UX like this:
52 $ ./configure CFLAGS="-g -O2 -mlp64" CXXFLAGS="-g -O2 -mlp64"
54 Caveat: Unwinding of 32-bit (ILP32) binaries is not supported
57 ** Workaround for older versions of GCC
59 GCC v3.0 and GCC v3.2 ship with a bad version of sys/types.h. The
60 workaround is to issue the following commands before running
63 $ mkdir $top_dir/include/sys
64 $ cp /usr/include/sys/types.h $top_dir/include/sys
66 GCC v3.3.2 or later have been fixed and do not require this
69 * Building for PowerPC64 / Linux
71 For building for power64 you should use:
73 $ ./configure CFLAGS="-g -O2 -m64" CXXFLAGS="-g -O2 -m64"
75 If your power support altivec registers:
76 $ ./configure CFLAGS="-g -O2 -m64 -maltivec" CXXFLAGS="-g -O2 -m64 -maltivec"
78 To check if your processor has support for vector registers (altivec):
79 cat /proc/cpuinfo | grep altivec
80 and should have something like this:
81 cpu : PPC970, altivec supported
83 If libunwind seems to not work (backtracing failing), try to compile
84 it with -O0, without optimizations. There are some compiler problems
85 depending on the version of your gcc.
89 General building instructions apply. To build and execute several tests,
90 you need libexecinfo library available in ports as devel/libexecinfo.
92 Development of the port was done of FreeBSD 8.0-STABLE. The library
93 was build with the system compiler that is modified version of gcc 4.2.1,
94 as well as the gcc 4.4.3.
98 After building the library, you can run a set of regression tests with:
102 ** Expected results on IA-64 Linux
104 Unless you have a very recent C library and compiler installed, it is
105 currently expected to have the following tests fail on IA-64 Linux:
107 Gtest-init (should pass starting with glibc-2.3.x/gcc-3.4)
108 Ltest-init (should pass starting with glibc-2.3.x/gcc-3.4)
109 test-ptrace (should pass starting with glibc-2.3.x/gcc-3.4)
110 run-ia64-test-dyn1 (should pass starting with glibc-2.3.x)
112 This does not mean that libunwind cannot be used with older compilers
113 or C libraries, it just means that for certain corner cases, unwinding
114 will fail. Since they're corner cases, it is not likely for
115 applications to trigger them.
117 Note: If you get lots of errors in Gia64-test-nat and Lia64-test-nat, it's
118 almost certainly a sign of an old assembler. The GNU assembler used
119 to encode previous-stack-pointer-relative offsets incorrectly.
120 This bug was fixed on 21-Sep-2004 so any later assembler will be
123 ** Expected results on x86 Linux
125 The following tests are expected to fail on x86 Linux:
127 Gtest-resume-sig (fails to get SIGUSR2)
128 Ltest-resume-sig (likewise)
129 Gtest-dyn1 (no dynamic unwind info support yet)
130 Ltest-dyn1 (no dynamic unwind info support yet)
131 test-setjmp (longjmp() not implemented yet)
132 run-check-namespace (no _Ux86_getcontext yet)
135 ** Expected results on x86-64 Linux
137 The following tests are expected to fail on x86-64 Linux:
139 Gtest-dyn1 (no dynamic unwind info support yet)
140 Ltest-dyn1 (no dynamic unwind info support yet)
141 Gtest-init (see http://gcc.gnu.org/bugzilla/show_bug.cgi?id=18743)
142 Ltest-init (likewise)
143 test-async-sig (crashes due to bad unwind-info?)
144 test-setjmp (longjmp() not implemented yet)
145 run-check-namespace (no _Ux86_64_getcontext yet)
146 run-ptrace-mapper (??? investigate)
147 run-ptrace-misc (see http://gcc.gnu.org/bugzilla/show_bug.cgi?id=18748
148 and http://gcc.gnu.org/bugzilla/show_bug.cgi?id=18749)
150 ** Expected results on PARISC Linux
152 Caveat: GCC v3.4 or newer is needed on PA-RISC Linux. Earlier
153 versions of the compiler failed to generate the exception-handling
154 program header (GNU_EH_FRAME) needed for unwinding.
156 The following tests are expected to fail on x86-64 Linux:
158 Gtest-bt (backtrace truncated at kill() due to lack of unwind-info)
160 Gtest-resume-sig (Gresume.c:my_rt_sigreturn() is wrong somehow)
161 Ltest-resume-sig (likewise)
162 Gtest-init (likewise)
163 Ltest-init (likewise)
164 Gtest-dyn1 (no dynamic unwind info support yet)
165 Ltest-dyn1 (no dynamic unwind info support yet)
166 test-setjmp (longjmp() not implemented yet)
167 run-check-namespace (toolchain doesn't support HIDDEN yet)
169 ** Expected results on HP-UX
171 "make check" is currently unsupported for HP-UX. You can try to run
172 it, but most tests will fail (and some may fail to terminate). The
173 only test programs that are known to work at this time are:
178 tests/test-static-link
181 tests/Gtest-resume-sig
182 tests/Ltest-resume-sig
184 ** Expected results on PPC64 Linux
186 "make check" should run with no more than 10 out of 24 tests failed.
189 * Performance Testing
191 This distribution includes a few simple performance tests which give
192 some idea of the basic cost of various libunwind operations. After
193 building the library, you can run these tests with the following
199 * Contacting the Developers
201 Please direct all questions regarding this library to:
203 libunwind-devel@nongnu.org
205 You can do this by sending a mail to libunwind-request@nongnu.org with
208 subscribe libunwind-devel
210 or you can subscribe and manage your subscription via the
213 https://savannah.nongnu.org/mail/?group=libunwind