README - platform/external/libunwind - Gitiles

 -*- mode: Outline -*-

 This is version 0.96 of the unwind library.  At the moment, only the
 IA-64 Linux (IPF Linux) platform is fully supported.  Some very basic
 support for x86 and HP-UX/IPF exists also.  However, the x86 support
 is based purely on the frame-chain and does not use unwind
 information, so its utility is limited.  Similarly, the HP-UX/IPF
 support is incomplete, though it is sufficient to do a basic
 backtrace.  unw_resume() is not supported, however.

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

 ** Up to 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

 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.

 ** 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 CXX=icc CCAS=gcc

 * Building on HP-UX

 For the time being, libunwind must be built with GCC on HP-UX.
 Unfortunately, gcc-3.0 and gcc-3.2 ship 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

 Apart from this glitch, libunwind should configure and install on
 HP-UX like this:

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

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

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

 ** Expected results on x86 Linux

 The following tests are expected to fail on x86 Linux:

 	test-proc-info		(x86 unwinder doesn't use unwind-info yet)
 	Gtest-exc		(unw_resume() not implmented yet)
 	Ltest-exc		(unw_resume() not implmented yet)
 	test-setjmp		(unw_resume() not implmented yet)

 ** Expected results on HP-UX

 "make check" is currently unsupported for HP-UX.  The only test
 programs that are known to work at this time are tests/bt (which
 produces various backtraces) and tests/Gperf-simple, which does some
 simple performance measurements.

 * 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.
	-- mode: Outline --

	This is version 0.96 of the unwind library. At the moment, only the
	IA-64 Linux (IPF Linux) platform is fully supported. Some very basic
	support for x86 and HP-UX/IPF exists also. However, the x86 support
	is based purely on the frame-chain and does not use unwind
	information, so its utility is limited. Similarly, the HP-UX/IPF
	support is incomplete, though it is sufficient to do a basic
	backtrace. unw_resume() is not supported, however.

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

	** Up to 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

	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.

	** 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 CXX=icc CCAS=gcc

	* Building on HP-UX

	For the time being, libunwind must be built with GCC on HP-UX.
	Unfortunately, gcc-3.0 and gcc-3.2 ship 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

	Apart from this glitch, libunwind should configure and install on
	HP-UX like this:

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

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

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

	** Expected results on x86 Linux

	The following tests are expected to fail on x86 Linux:

	test-proc-info (x86 unwinder doesn't use unwind-info yet)
	Gtest-exc (unw_resume() not implmented yet)
	Ltest-exc (unw_resume() not implmented yet)
	test-setjmp (unw_resume() not implmented yet)

	** Expected results on HP-UX

	"make check" is currently unsupported for HP-UX. The only test
	programs that are known to work at this time are tests/bt (which
	produces various backtraces) and tests/Gperf-simple, which does some
	simple performance measurements.

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