1# libunwind 2 3[](https://github.com/libunwind/libunwind/actions/workflows/CI-unix.yml) 4[](https://github.com/libunwind/libunwind/actions/workflows/CI-win.yml) 5 6This library supports several architecture/operating-system combinations: 7 8| System | Architecture | Status | 9| :------ | :----------- | :----- | 10| Linux | x86-64 | ✓ | 11| Linux | x86 | ✓ | 12| Linux | ARM | ✓ | 13| Linux | AArch64 | ✓ | 14| Linux | PPC32 | ✓ | 15| Linux | PPC64 | ✓ | 16| Linux | SuperH | ✓ | 17| Linux | IA-64 | ✓ | 18| Linux | PARISC | Works well, but C library missing unwind-info | 19| Linux | MIPS | ✓ | 20| Linux | RISC-V | 64-bit only | 21| Linux | LoongArch | 64-bit only | 22| HP-UX | IA-64 | Mostly works, but known to have serious limitations | 23| FreeBSD | x86-64 | ✓ | 24| FreeBSD | x86 | ✓ | 25| FreeBSD | AArch64 | ✓ | 26| FreeBSD | PPC32 | ✓ | 27| FreeBSD | PPC64 | ✓ | 28| QNX | Aarch64 | ✓ | 29| QNX | x86-64 | ✓ | 30| Solaris | x86-64 | ✓ | 31 32## Libc Requirements 33 34libunwind depends on getcontext(), setcontext() functions which are missing 35from C libraries like musl-libc because they are considered to be "obsolescent" 36API by POSIX document. The following table tries to track current status of 37such dependencies 38 39 - r, requires 40 - p, provides its own implementation 41 - empty, no requirement 42 43| Architecture | getcontext | setcontext | 44|--------------|------------|------------| 45| aarch64 | p | | 46| arm | p | | 47| hppa | p | p | 48| ia64 | p | r | 49| loongarch | p | | 50| mips | p | | 51| ppc32 | r | | 52| ppc64 | r | r | 53| riscv | p | p | 54| s390x | p | p | 55| sh | r | | 56| x86 | p | r | 57| x86_64 | p | p | 58 59## General Build Instructions 60 61In general, this library can be built and installed with the following 62commands: 63 64 $ autoreconf -i # Needed only for building from git. Depends on libtool. 65 $ ./configure --prefix=PREFIX 66 $ make 67 $ make install 68 69where `PREFIX` is the installation prefix. By default, a prefix of 70`/usr/local` is used, such that `libunwind.a` is installed in 71`/usr/local/lib` and `unwind.h` is installed in `/usr/local/include`. For 72testing, you may want to use a prefix of `/usr/local` instead. 73 74 75### Building with Intel compiler 76 77#### Version 8 and later 78 79Starting with version 8, the preferred name for the IA-64 Intel 80compiler is `icc` (same name as on x86). Thus, the configure-line 81should look like this: 82 83 $ ./configure CC=icc CFLAGS="-g -O3 -ip" CXX=icc CCAS=gcc CCASFLAGS=-g \ 84 LDFLAGS="-L$PWD/src/.libs" 85 86 87### Building on HP-UX 88 89For the time being, libunwind must be built with GCC on HP-UX. 90 91libunwind should be configured and installed on HP-UX like this: 92 93 $ ./configure CFLAGS="-g -O2 -mlp64" CXXFLAGS="-g -O2 -mlp64" 94 95Caveat: Unwinding of 32-bit (ILP32) binaries is not supported at the moment. 96 97### Building for PowerPC64 / Linux 98 99For building for power64 you should use: 100 101 $ ./configure CFLAGS="-g -O2 -m64" CXXFLAGS="-g -O2 -m64" 102 103If your power support altivec registers: 104 105 $ ./configure CFLAGS="-g -O2 -m64 -maltivec" CXXFLAGS="-g -O2 -m64 -maltivec" 106 107To check if your processor has support for vector registers (altivec): 108 109 cat /proc/cpuinfo | grep altivec 110 111and should have something like this: 112 113 cpu : PPC970, altivec supported 114 115If libunwind seems to not work (backtracing failing), try to compile 116it with `-O0`, without optimizations. There are some compiler problems 117depending on the version of your gcc. 118 119### Building on FreeBSD 120 121General building instructions apply. To build and execute several tests 122on older versions of FreeBSD, you need libexecinfo library available in 123ports as devel/libexecinfo. This port has been removed as of 2017 and is 124indeed no longer needed. 125 126## Regression Testing 127 128After building the library, you can run a set of regression tests with: 129 130 $ make check 131 132### Expected results on x86 Linux 133 134The following tests are expected to fail on x86 Linux: 135 136* `test-ptrace` 137 138### Expected results on x86-64 Linux 139 140The following tests are expected to fail on x86-64 Linux: 141 142* `run-ptrace-misc` (see <http://gcc.gnu.org/bugzilla/show_bug.cgi?id=18748> 143 and <http://gcc.gnu.org/bugzilla/show_bug.cgi?id=18749>) 144 145### Expected results on PARISC Linux 146 147The following tests are expected to fail on x86-64 Linux: 148 149* `Gtest-bt` (backtrace truncated at `kill()` due to lack of unwind-info) 150* `Ltest-bt` (likewise) 151* `Gtest-resume-sig` (`Gresume.c:my_rt_sigreturn()` is wrong somehow) 152* `Ltest-resume-sig` (likewise) 153* `Gtest-init` (likewise) 154* `Ltest-init` (likewise) 155* `Gtest-dyn1` (no dynamic unwind info support yet) 156* `Ltest-dyn1` (no dynamic unwind info support yet) 157* `test-setjmp` (`longjmp()` not implemented yet) 158* `run-check-namespace` (toolchain doesn't support `HIDDEN` yet) 159 160### Expected results on HP-UX 161 162`make check` is currently unsupported for HP-UX. You can try to run 163it, but most tests will fail (and some may fail to terminate). The 164only test programs that are known to work at this time are: 165 166* `tests/bt` 167* `tests/Gperf-simple` 168* `tests/test-proc-info` 169* `tests/test-static-link` 170* `tests/Gtest-init` 171* `tests/Ltest-init` 172* `tests/Gtest-resume-sig` 173* `tests/Ltest-resume-sig` 174 175### Expected results on PPC64 Linux 176 177`make check` should run with no more than 10 out of 24 tests failed. 178 179### Expected results on Solaris x86-64 180 181`make check` is passing 27 out of 33 tests. The following six tests are consistently 182failing: 183 184* `Gtest-concurrent` 185* `Ltest-concurrent` 186* `Ltest-init-local-signal` 187* `Lrs-race` 188* `test-setjmp` 189* `x64-unwind-badjmp-signal-frame` 190 191## Performance Testing 192 193This distribution includes a few simple performance tests which give 194some idea of the basic cost of various libunwind operations. After 195building the library, you can run these tests with the following 196commands: 197 198 $ cd tests 199 $ make perf 200 201## Contacting the Developers 202 203Please raise issues and pull requests through the GitHub repository: 204<https://github.com/libunwind/libunwind>. 205
){kind=link}
){kind=link}