1-*- mode: Outline -*- 2 3This is version 1.0 of the unwind library. This library supports 4several 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 21In general, this library can be built and installed with the following 22commands: 23 24 $ autoreconf -i # Needed only for building from git. Depends on libtool. 25 $ ./configure 26 $ make 27 $ make install prefix=PREFIX 28 29where 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 32testing, 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 39Starting with version 8, the preferred name for the IA-64 Intel 40compiler is "icc" (same name as on x86). Thus, the configure-line 41should 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 49For the time being, libunwind must be built with GCC on HP-UX. 50 51libunwind should be configured and installed on HP-UX like this: 52 53 $ ./configure CFLAGS="-g -O2 -mlp64" CXXFLAGS="-g -O2 -mlp64" 54 55Caveat: Unwinding of 32-bit (ILP32) binaries is not supported 56 at the moment. 57 58** Workaround for older versions of GCC 59 60GCC v3.0 and GCC v3.2 ship with a bad version of sys/types.h. The 61workaround 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 67GCC v3.3.2 or later have been fixed and do not require this 68workaround. 69 70* Building for PowerPC64 / Linux 71 72For building for power64 you should use: 73 74 $ ./configure CFLAGS="-g -O2 -m64" CXXFLAGS="-g -O2 -m64" 75 76If your power support altivec registers: 77 $ ./configure CFLAGS="-g -O2 -m64 -maltivec" CXXFLAGS="-g -O2 -m64 -maltivec" 78 79To check if your processor has support for vector registers (altivec): 80 cat /proc/cpuinfo | grep altivec 81and should have something like this: 82 cpu : PPC970, altivec supported 83 84If libunwind seems to not work (backtracing failing), try to compile 85it with -O0, without optimizations. There are some compiler problems 86depending on the version of your gcc. 87 88* Building on FreeBSD 89 90General building instructions apply. To build and execute several tests, 91you need libexecinfo library available in ports as devel/libexecinfo. 92 93Development of the port was done of FreeBSD 8.0-STABLE. The library 94was build with the system compiler that is modified version of gcc 4.2.1, 95as well as the gcc 4.4.3. 96 97* Regression Testing 98 99After 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 105Unless you have a very recent C library and compiler installed, it is 106currently 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 113This does not mean that libunwind cannot be used with older compilers 114or C libraries, it just means that for certain corner cases, unwinding 115will fail. Since they're corner cases, it is not likely for 116applications to trigger them. 117 118Note: 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 126The 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 138The 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 153Caveat: GCC v3.4 or newer is needed on PA-RISC Linux. Earlier 154versions of the compiler failed to generate the exception-handling 155program header (GNU_EH_FRAME) needed for unwinding. 156 157The 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 173it, but most tests will fail (and some may fail to terminate). The 174only 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 192This distribution includes a few simple performance tests which give 193some idea of the basic cost of various libunwind operations. After 194building the library, you can run these tests with the following 195commands: 196 197 $ cd tests 198 $ make perf 199 200* Contacting the Developers 201 202Please direct all questions regarding this library to: 203 204 libunwind-devel@nongnu.org 205 206You can do this by sending a mail to libunwind-request@nongnu.org with 207a body of: 208 209 subscribe libunwind-devel 210 211or you can subscribe and manage your subscription via the 212web-interface at: 213 214 https://savannah.nongnu.org/mail/?group=libunwind 215