diff options
-rw-r--r-- | README | 204 |
1 files changed, 99 insertions, 105 deletions
@@ -1,53 +1,56 @@ --*- mode: Outline -*- +# libunwind [![Build Status](https://travis-ci.org/libunwind/libunwind.svg?branch=master)](https://travis-ci.org/libunwind/libunwind) This is version 1.3 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: Works well. - Linux/PARISC: Works well, but C library missing unwind-info. - HP-UX/IA-64: Mostly works but known to have some serious limitations. - MIPS: Newly added. - Linux/AArch64: Works well. - Linux/PPC64: Newly added. - Linux/SuperH: Newly added. - FreeBSD/i386: Works well. - FreeBSD/x86-64: Newly added (FreeBSD architecture is known as amd64). - Linux/Tilegx: Newly added (64-bit mode only). - -* General Build Instructions +| System | Architecture | Status | +| :------ | :----------- | :----- | +| Linux | x86-64 | ✓ | +| Linux | x86 | ✓ | +| Linux | ARM | ✓ | +| Linux | AArch64 | ✓ | +| Linux | PPC64 | ✓ | +| Linux | SuperH | ✓ | +| Linux | IA-64 | ✓ | +| Linux | PARISC | Works well, but C library missing unwind-info | +| Linux | Tilegx | 64-bit mode only | +| Linux | MIPS | Newly added | +| HP-UX | IA-64 | Mostly works, but known to have serious limitations | +| FreeBSD | x86-64 | ✓ | +| FreeBSD | x86 | ✓ | +| FreeBSD | AArch64 | ✓ | + +## 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 + $ ./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. +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 +### Building with Intel compiler -** Version 8 and later +#### 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 +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" + LDFLAGS="-L$PWD/src/.libs" -* Building on HP-UX +### Building on HP-UX For the time being, libunwind must be built with GCC on HP-UX. @@ -55,14 +58,13 @@ 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. +Caveat: Unwinding of 32-bit (ILP32) binaries is not supported at the moment. -** Workaround for older versions of GCC +### Workaround for older versions of GCC -GCC v3.0 and GCC v3.2 ship with a bad version of sys/types.h. The +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": +`configure`: $ mkdir $top_dir/include/sys $ cp /usr/include/sys/types.h $top_dir/include/sys @@ -70,138 +72,130 @@ workaround is to issue the following commands before running GCC v3.3.2 or later have been fixed and do not require this workaround. -* Building for PowerPC64 / Linux +### Building for PowerPC64 / Linux For building for power64 you should use: - $ ./configure CFLAGS="-g -O2 -m64" CXXFLAGS="-g -O2 -m64" + $ ./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" + + $ ./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 +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. +### Building on FreeBSD -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. +General building instructions apply. To build and execute several tests +on older versions of FreeBSD, you need libexecinfo library available in +ports as devel/libexecinfo. This port has been removed as of 2017 and is +indeed no longer needed. -* Regression Testing +## Regression Testing After building the library, you can run a set of regression tests with: - $ make check + $ make check -** Expected results on IA-64 Linux +### 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) +* `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. +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 +### Expected results on x86 Linux The following tests are expected to fail on x86 Linux: - test-ptrace +* `test-ptrace` -** Expected results on x86-64 Linux +### Expected results on x86-64 Linux The following tests are expected to fail on x86-64 Linux: - 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) +* `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 +### 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. +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) +* `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 +### Expected results on HP-UX -"make check" is currently unsupported for HP-UX. You can try to run +`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 +* `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 +### Expected results on PPC64 Linux -"make check" should run with no more than 10 out of 24 tests failed. +`make check` should run with no more than 10 out of 24 tests failed. -* Performance Testing +## 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 + $ cd tests + $ make perf -or you can subscribe and manage your subscription via the -web-interface at: +## Contacting the Developers - https://savannah.nongnu.org/mail/?group=libunwind +Please direct all questions regarding this library to <libunwind-devel@nongnu.org>. -Or interact at the github page: +You can do this by sending an email 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>. - https://github.com/libunwind/libunwind +You can also interact on our GitHub page: <https://github.com/libunwind/libunwind>. |