README

-*- mode: Outline -*-

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

 Linux/IA-64:	Fully tested and supported.
 Linux/x86-64:	Works well.
 Linux/x86:	Works well, but C library is missing some unwind-info.
 Linux/PARISC:	Works well, but C library missing unwind-info.
 HP-UX/IA-64:	Mostly works but known to have some serious limitations.
 Linux/PPC64:	Newly added.


* 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.


* 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"

** Version 7

To build libunwind with the Intel Electron compiler (ECC), it is
recommended to run configure like this:

	$ ./configure CC=ecc CXX=ecc CCAS=gcc CCASFLAGS=-g \
		LDFLAGS="-L$PWD/src/.libs"

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.

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.


* 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

* 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@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.