NameDateSize

..09-Dec-201726

.gitignoreH A D10-Nov-20151.1 KiB

aarch64/H10-Nov-201536

arm/H29-Apr-201939

AUTHORSH A D10-Nov-201539

ChangeLogH A D10-Nov-20151.9 KiB

config.hH A D10-Nov-20156.8 KiB

COPYINGH A D10-Nov-20151 KiB

coredump/H10-Nov-201519

dwarf/H10-Nov-201517

elf32.cH A D10-Nov-201571

elf32.hH A D10-Nov-2015134

elf64.cH A D10-Nov-201571

elf64.hH A D10-Nov-2015134

elfxx.cH A D10-Nov-201510.4 KiB

elfxx.hH A D07-Aug-20163.2 KiB

hppa/H10-Nov-201533

ia64/H10-Nov-201553

JamfileH A D17-Nov-2015268

LICENSEH A D10-Nov-20151,023

Makefile.amH A D10-Nov-201527.5 KiB

mi/H10-Nov-201538

mips/H10-Nov-201533

NEWSH A D10-Nov-20158.2 KiB

os-freebsd.cH A D10-Nov-20153.7 KiB

os-hpux.cH A D10-Nov-20152.2 KiB

os-linux.cH A D10-Nov-20151.9 KiB

os-linux.hH A D29-Apr-20196.9 KiB

os-qnx.cH A D10-Nov-20153.5 KiB

ppc/H10-Nov-201514

ppc32/H10-Nov-201521

ppc64/H10-Nov-201521

ptrace/H10-Nov-201516

READMEH A D10-Nov-20156.8 KiB

setjmp/H10-Nov-20157

sh/H10-Nov-201531

tilegx/H10-Nov-201533

TODOH A D10-Nov-20155 KiB

unwind/H10-Nov-201521

x86/H10-Nov-201536

x86_64/H10-Nov-201543

README

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