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