README

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