README

   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  Linux/Tilegx:  Newly added (64-bit mode only).
  18
  19 * General Build Instructions
  20
  21 In general, this library can be built and installed with the following
  22 commands:
  23
  24         $ ./autogen.sh # 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@nongnu.org
 205
 206 You can do this by sending a mail to libunwind-request@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