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/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).
  16
  17
  18 * General Build Instructions
  19
  20 In general, this library can be built and installed with the following
  21 commands:
  22
  23         $ autoreconf -i # Needed only for building from git. Depends on libtool.
  24         $ ./configure
  25         $ make
  26         $ make install prefix=PREFIX
  27
  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.
  32
  33
  34 * Building with Intel compiler
  35
  36 ** Version 8 and later
  37
  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:
  41
  42     $ ./configure CC=icc CFLAGS="-g -O3 -ip" CXX=icc CCAS=gcc CCASFLAGS=-g \
  43                 LDFLAGS="-L$PWD/src/.libs"
  44
  45
  46 * Building on HP-UX
  47
  48 For the time being, libunwind must be built with GCC on HP-UX.
  49
  50 libunwind should be configured and installed on HP-UX like this:
  51
  52     $ ./configure CFLAGS="-g -O2 -mlp64" CXXFLAGS="-g -O2 -mlp64"
  53
  54 Caveat: Unwinding of 32-bit (ILP32) binaries is not supported
  55         at the moment.
  56
  57 ** Workaround for older versions of GCC
  58
  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
  61 "configure":
  62
  63     $ mkdir $top_dir/include/sys
  64     $ cp /usr/include/sys/types.h $top_dir/include/sys
  65
  66 GCC v3.3.2 or later have been fixed and do not require this
  67 workaround.
  68
  69 * Building for PowerPC64 / Linux
  70
  71 For building for power64 you should use:
  72
  73   $ ./configure CFLAGS="-g -O2 -m64" CXXFLAGS="-g -O2 -m64"
  74
  75 If your power support altivec registers:
  76   $ ./configure CFLAGS="-g -O2 -m64 -maltivec" CXXFLAGS="-g -O2 -m64 -maltivec"
  77
  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
  82
  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.
  86
  87 * Building on FreeBSD
  88
  89 General building instructions apply. To build and execute several tests,
  90 you need libexecinfo library available in ports as devel/libexecinfo.
  91
  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.
  95
  96 * Regression Testing
  97
  98 After building the library, you can run a set of regression tests with:
  99
 100         $ make check
 101
 102 ** Expected results on IA-64 Linux
 103
 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:
 106
 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)
 111
 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.
 116
 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
 121       fine.
 122
 123 ** Expected results on x86 Linux
 124
 125 The following tests are expected to fail on x86 Linux:
 126
 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)
 133         test-ptrace
 134
 135 ** Expected results on x86-64 Linux
 136
 137 The following tests are expected to fail on x86-64 Linux:
 138
 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)
 149
 150 ** Expected results on PARISC Linux
 151
 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.
 155
 156 The following tests are expected to fail on x86-64 Linux:
 157
 158         Gtest-bt   (backtrace truncated at kill() due to lack of unwind-info)
 159         Ltest-bt   (likewise)
 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)
 168
 169 ** Expected results on HP-UX
 170
 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:
 174
 175      tests/bt
 176      tests/Gperf-simple
 177      tests/test-proc-info
 178      tests/test-static-link
 179      tests/Gtest-init
 180      tests/Ltest-init
 181      tests/Gtest-resume-sig
 182      tests/Ltest-resume-sig
 183
 184 ** Expected results on PPC64 Linux
 185
 186 "make check" should run with no more than 10 out of 24 tests failed.
 187
 188
 189 * Performance Testing
 190
 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
 194 commands:
 195
 196  $ cd tests
 197  $ make perf
 198
 199 * Contacting the Developers
 200
 201 Please direct all questions regarding this library to:
 202
 203         libunwind-devel@nongnu.org
 204
 205 You can do this by sending a mail to libunwind-request@nongnu.org with
 206 a body of:
 207
 208         subscribe libunwind-devel
 209
 210 or you can subscribe and manage your subscription via the
 211 web-interface at:
 212
 213         https://savannah.nongnu.org/mail/?group=libunwind