Fork of the libunwind official github repo — http://www.nongnu.org/libunwind/

Dave Watson a77b0cd7bd Bump version to v1.2.1 2 years ago
aux c6a529d390 mvdir 15 years ago
doc ec262e127b siglongjmp documentation fix 7 years ago
include 620d1c3b0b Add aarch64 getcontext functionality. 2 years ago
scripts 03395a1c4b Turn back on execute-permission on script files. 13 years ago
src 5f354cb7b9 mips/tilegx: Add missing unwind_i.h header file 2 years ago
tests 544cdb3b43 tests/Gtest-trace.c: show differing addresses 4 years ago
.gitignore 5b55e556ca test-resume-sig-rt: test unw_resume() in presence of "realtime" signal frame 7 years ago
AUTHORS 3550b501b1 Update mailing-list info. 12 years ago
COPYING 445f16a033 Switch to MIT license. 17 years ago
ChangeLog 3c109eef98 Update ChangeLog to point to GIT log instead of Bitkeeper log. 13 years ago
LICENSE 63a6a95489 Delete obsolete BitKeeper files, add LICENSE file. 13 years ago
Makefile.am 6e3254ea6e [PATCH] Fix build from scratch 5 years ago
NEWS d7322f0f64 Update to v1.1 7 years ago
README b2db825e8a Update README to use autogen.sh 4 years ago
TODO bc22c6ecf2 Update. 15 years ago
acinclude.m4 9ef9445558 Don't check for atomic_ops library for now. 15 years ago
autogen.sh 6e3254ea6e [PATCH] Fix build from scratch 5 years ago
configure.ac a77b0cd7bd Bump version to v1.2.1 2 years ago

README

-*- mode: Outline -*-

This is version 1.0 of the unwind library. This library supports
several architecture/operating-system combinations:

Linux/x86-64: Works well.
Linux/x86: Works well.
Linux/ARM: Works well.
Linux/IA-64: Fully tested and supported.
Linux/PARISC: Works well, but C library missing unwind-info.
HP-UX/IA-64: Mostly works but known to have some serious limitations.
Linux/AArch64: Newly added.
Linux/PPC64: Newly added.
Linux/SuperH: Newly added.
FreeBSD/i386: Newly added.
FreeBSD/x86-64: Newly added (FreeBSD architecture is known as amd64).
Linux/Tilegx: Newly added (64-bit mode only).

* General Build Instructions

In general, this library can be built and installed with the following
commands:

$ ./autogen.sh # Needed only for building from git. Depends on libtool.
$ ./configure
$ make
$ make install prefix=PREFIX

where PREFIX is the installation prefix. By default, a prefix of
/usr/local is used, such that libunwind.a is installed in
/usr/local/lib and unwind.h is installed in /usr/local/include. For
testing, you may want to use a prefix of /usr/local instead.


* Building with Intel compiler

** Version 8 and later

Starting with version 8, the preferred name for the IA-64 Intel
compiler is "icc" (same name as on x86). Thus, the configure-line
should look like this:

$ ./configure CC=icc CFLAGS="-g -O3 -ip" CXX=icc CCAS=gcc CCASFLAGS=-g \
LDFLAGS="-L$PWD/src/.libs"


* Building on HP-UX

For the time being, libunwind must be built with GCC on HP-UX.

libunwind should be configured and installed on HP-UX like this:

$ ./configure CFLAGS="-g -O2 -mlp64" CXXFLAGS="-g -O2 -mlp64"

Caveat: Unwinding of 32-bit (ILP32) binaries is not supported
at the moment.

** Workaround for older versions of GCC

GCC v3.0 and GCC v3.2 ship with a bad version of sys/types.h. The
workaround is to issue the following commands before running
"configure":

$ mkdir $top_dir/include/sys
$ cp /usr/include/sys/types.h $top_dir/include/sys

GCC v3.3.2 or later have been fixed and do not require this
workaround.

* Building for PowerPC64 / Linux

For building for power64 you should use:

$ ./configure CFLAGS="-g -O2 -m64" CXXFLAGS="-g -O2 -m64"

If your power support altivec registers:
$ ./configure CFLAGS="-g -O2 -m64 -maltivec" CXXFLAGS="-g -O2 -m64 -maltivec"

To check if your processor has support for vector registers (altivec):
cat /proc/cpuinfo | grep altivec
and should have something like this:
cpu : PPC970, altivec supported

If libunwind seems to not work (backtracing failing), try to compile
it with -O0, without optimizations. There are some compiler problems
depending on the version of your gcc.

* Building on FreeBSD

General building instructions apply. To build and execute several tests,
you need libexecinfo library available in ports as devel/libexecinfo.

Development of the port was done of FreeBSD 8.0-STABLE. The library
was build with the system compiler that is modified version of gcc 4.2.1,
as well as the gcc 4.4.3.

* Regression Testing

After building the library, you can run a set of regression tests with:

$ make check

** Expected results on IA-64 Linux

Unless you have a very recent C library and compiler installed, it is
currently expected to have the following tests fail on IA-64 Linux:

Gtest-init (should pass starting with glibc-2.3.x/gcc-3.4)
Ltest-init (should pass starting with glibc-2.3.x/gcc-3.4)
test-ptrace (should pass starting with glibc-2.3.x/gcc-3.4)
run-ia64-test-dyn1 (should pass starting with glibc-2.3.x)

This does not mean that libunwind cannot be used with older compilers
or C libraries, it just means that for certain corner cases, unwinding
will fail. Since they're corner cases, it is not likely for
applications to trigger them.

Note: If you get lots of errors in Gia64-test-nat and Lia64-test-nat, it's
almost certainly a sign of an old assembler. The GNU assembler used
to encode previous-stack-pointer-relative offsets incorrectly.
This bug was fixed on 21-Sep-2004 so any later assembler will be
fine.

** Expected results on x86 Linux

The following tests are expected to fail on x86 Linux:

Gtest-resume-sig (fails to get SIGUSR2)
Ltest-resume-sig (likewise)
Gtest-dyn1 (no dynamic unwind info support yet)
Ltest-dyn1 (no dynamic unwind info support yet)
test-setjmp (longjmp() not implemented yet)
run-check-namespace (no _Ux86_getcontext yet)
test-ptrace

** Expected results on x86-64 Linux

The following tests are expected to fail on x86-64 Linux:

Gtest-dyn1 (no dynamic unwind info support yet)
Ltest-dyn1 (no dynamic unwind info support yet)
Gtest-init (see http://gcc.gnu.org/bugzilla/show_bug.cgi?id=18743)
Ltest-init (likewise)
test-async-sig (crashes due to bad unwind-info?)
test-setjmp (longjmp() not implemented yet)
run-check-namespace (no _Ux86_64_getcontext yet)
run-ptrace-mapper (??? investigate)
run-ptrace-misc (see http://gcc.gnu.org/bugzilla/show_bug.cgi?id=18748
and http://gcc.gnu.org/bugzilla/show_bug.cgi?id=18749)

** Expected results on PARISC Linux

Caveat: GCC v3.4 or newer is needed on PA-RISC Linux. Earlier
versions of the compiler failed to generate the exception-handling
program header (GNU_EH_FRAME) needed for unwinding.

The following tests are expected to fail on x86-64 Linux:

Gtest-bt (backtrace truncated at kill() due to lack of unwind-info)
Ltest-bt (likewise)
Gtest-resume-sig (Gresume.c:my_rt_sigreturn() is wrong somehow)
Ltest-resume-sig (likewise)
Gtest-init (likewise)
Ltest-init (likewise)
Gtest-dyn1 (no dynamic unwind info support yet)
Ltest-dyn1 (no dynamic unwind info support yet)
test-setjmp (longjmp() not implemented yet)
run-check-namespace (toolchain doesn't support HIDDEN yet)

** Expected results on HP-UX

"make check" is currently unsupported for HP-UX. You can try to run
it, but most tests will fail (and some may fail to terminate). The
only test programs that are known to work at this time are:

tests/bt
tests/Gperf-simple
tests/test-proc-info
tests/test-static-link
tests/Gtest-init
tests/Ltest-init
tests/Gtest-resume-sig
tests/Ltest-resume-sig

** Expected results on PPC64 Linux

"make check" should run with no more than 10 out of 24 tests failed.


* Performance Testing

This distribution includes a few simple performance tests which give
some idea of the basic cost of various libunwind operations. After
building the library, you can run these tests with the following
commands:

$ cd tests
$ make perf

* Contacting the Developers

Please direct all questions regarding this library to:

libunwind-devel@nongnu.org

You can do this by sending a mail to libunwind-request@nongnu.org with
a body of:

subscribe libunwind-devel

or you can subscribe and manage your subscription via the
web-interface at:

https://savannah.nongnu.org/mail/?group=libunwind