blob: 6099cd9ea4557be176f27af151124361055d2f72 [file] [log] [blame]
-*- mode: Outline -*-
This is version 0.92 of the unwind library. At the moment, only the
IA-64 Linux (IPF Linux) platform is fully supported. Some very basic
support for x86 exists also. However, the x86 support is based purely
on the frame-chain and does not use unwind information, so its utility
is limited.
* General Build Instructions
In general, this library can be built and installed with the following
commands:
$ ./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.
If, during the build, you're getting an error of the form:
../src/.libs/libunwind-ia64.so: undefined reference to `__tls_get_addr'
it indicates that you have a compiler which supports the `__thread'
keyword, but a runtime system (C library), which does not. As of
September 2003, this appears to be a common problem for Debian
"unstable" systems. To work around this issue, run "./configure" with
option "--disable-__thread".
* Building with Intel ECC
To build libunwind with the Intel Electron compiler (ECC), it is
recommended to run configure like this:
$ ./configure CC=ecc CXX=ecc CCAS=gcc
The reason for this is that ECC uses the Intel assembler, which
doesn't grok some of the IA-64 assembly code in the "tests" directory.
For an ECC-built version of libunwind to work properly, you also need
to ensure that /usr/include/asm/fpu.h contains a "long double" member
called "__dummy" in the declaration of "struct ia64_fpreg". Without
that member, variables of type unw_context_t won't be aligned
properly.
* Building on HP-UX
For the time being, libunwind must be built with GCC on HP-UX.
Unfortunately, gcc-3.0 ships with a bad version of sys/types.h.
The workaround for this is:
$ mkdir $top_dir/include/sys
$ cp /usr/include/sys/types.h $top_dir/include/sys
* Regression Testing
After building the library, you can run a set of regression tests with:
$ make check
Unless you have a very recent C library and compiler installed, it is
currently expected to have the following tests fail:
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.
* Contacting the Developers
Please direct all questions regarding this library to:
libunwind@linux.hpl.hp.com
For spam protection, you'll have to subscribe to this list before
posting a question. You can do this by sending a mail to
libunwind-request@linux.hpl.hp.com with a body of:
subscribe libunwind
Note: the host that is running this list is behind a firewall, so
you'll not be able to use the Web interface to manage your
subscription. Send a mail containing "help" to
libunwind-request@linux.hpl.hp.com for information on how to manage
your subscription via email.