| (index)= |
| |
| # libunwind LLVM Unwinder |
| |
| ## Overview |
| |
| libunwind is an implementation of the interface defined by the HP libunwind |
| project. It was contributed by Apple as a way to enable clang++ to port to |
| platforms that do not have a system unwinder. It is intended to be a small and |
| fast implementation of the ABI, leaving off some features of HP's libunwind |
| that never materialized (e.g. remote unwinding). |
| |
| The unwinder has two levels of API. The high level APIs are the `_Unwind_*` |
| functions which implement functionality required by `__cxa_*` exception |
| functions. The low level APIs are the `unw_*` functions which are an interface |
| defined by the old HP libunwind project. |
| |
| ### Getting Started with libunwind |
| |
| :::{toctree} |
| :maxdepth: 2 |
| |
| BuildingLibunwind |
| ::: |
| |
| ### Current Status |
| |
| libunwind is a production-quality unwinder, with platform support for DWARF |
| unwind info, SjLj, and ARM EHABI. |
| |
| The low level libunwind API was designed to work either in-process (aka local) |
| or to operate on another process (aka remote), but only the local path has been |
| implemented. Remote unwinding remains as future work. |
| |
| ### Platform and Compiler Support |
| |
| libunwind is known to work on the following platforms: |
| |
| | OS | Arch | Compilers | Unwind Info | |
| | ---------- | ------------------------ | ---------- | ----------- | |
| | Any | i386, x86_64, ARM | Clang | SjLj | |
| | Bare Metal | ARM | Clang, GCC | EHABI | |
| | FreeBSD | i386, x86_64, ARM64 | Clang | DWARF CFI | |
| | iOS | ARM | Clang | SjLj | |
| | Linux | ARM | Clang, GCC | EHABI | |
| | Linux | i386, x86_64, ARM64 | Clang, GCC | DWARF CFI | |
| | macOS | i386, x86_64 | Clang, GCC | DWARF CFI | |
| | NetBSD | x86_64 | Clang, GCC | DWARF CFI | |
| | Windows | i386, x86_64, ARM, ARM64 | Clang | DWARF CFI | |
| |
| The following minimum compiler versions are strongly recommended. |
| |
| - Clang 3.5 and above |
| - GCC 4.7 and above. |
| |
| Anything older *may* work. |
| |
| ### Notes and Known Issues |
| |
| - TODO |
| |
| ## Getting Involved |
| |
| First please review our [Developer's Policy](https://llvm.org/docs/DeveloperPolicy.html) |
| and [Getting started with LLVM](https://llvm.org/docs/GettingStarted.html). |
| |
| **Bug Reports** |
| |
| If you think you've found a bug in libunwind, please report it using |
| the [LLVM bug tracker]. If you're not sure, you |
| can ask for support on the [Runtimes forum] or on Discord. |
| Please use the tag "libunwind" for new threads. |
| |
| **Patches** |
| |
| If you want to contribute a patch to libunwind, please start by reading the LLVM |
| [documentation about contributing](https://www.llvm.org/docs/Contributing.html). |
| |
| **Discussion and Questions** |
| |
| Send discussions and questions to the [Runtimes forum]. Please add the tag "libunwind" to your post. |
| |
| ## Quick Links |
| |
| - [LLVM Homepage](https://llvm.org/) |
| - [LLVM Bug Tracker](https://github.com/llvm/llvm-project/labels/libunwind/) |
| - [Clang Discourse Forums](https://discourse.llvm.org/c/clang/6) |
| - [cfe-commits Mailing List](http://lists.llvm.org/mailman/listinfo/cfe-commits) |
| - [Runtimes Forum](https://discourse.llvm.org/tags/c/runtimes) |
| - [Browse libunwind Sources](https://github.com/llvm/llvm-project/blob/main/libunwind/) |
| |
