1.. _index:
2
3=======================
4libunwind LLVM Unwinder
5=======================
6
7Overview
8========
9
10libunwind is an implementation of the interface defined by the HP libunwind
11project. It was contributed by Apple as a way to enable clang++ to port to
12platforms that do not have a system unwinder. It is intended to be a small and
13fast implementation of the ABI, leaving off some features of HP's libunwind
14that never materialized (e.g. remote unwinding).
15
16The unwinder has two levels of API. The high level APIs are the `_Unwind_*`
17functions which implement functionality required by `__cxa_*` exception
18functions. The low level APIs are the `unw_*` functions which are an interface
19defined by the old HP libunwind project.
20
21Getting Started with libunwind
22------------------------------
23
24.. toctree::
25   :maxdepth: 2
26
27   BuildingLibunwind
28
29Current Status
30--------------
31
32libunwind is a production-quality unwinder, with platform support for DWARF
33unwind info, SjLj, and ARM EHABI.
34
35The low level libunwind API was designed to work either in-process (aka local)
36or to operate on another process (aka remote), but only the local path has been
37implemented. Remote unwinding remains as future work.
38
39Platform and Compiler Support
40-----------------------------
41
42libunwind is known to work on the following platforms:
43
44============ ======================== ============ ========================
45OS           Arch                     Compilers    Unwind Info
46============ ======================== ============ ========================
47Any          i386, x86_64, ARM        Clang        SjLj
48Bare Metal   ARM                      Clang, GCC   EHABI
49FreeBSD      i386, x86_64, ARM64      Clang        DWARF CFI
50iOS          ARM                      Clang        SjLj
51Linux        ARM                      Clang, GCC   EHABI
52Linux        i386, x86_64, ARM64      Clang, GCC   DWARF CFI
53macOS        i386, x86_64             Clang, GCC   DWARF CFI
54NetBSD       x86_64                   Clang, GCC   DWARF CFI
55Windows      i386, x86_64, ARM, ARM64 Clang        DWARF CFI
56============ ======================== ============ ========================
57
58The following minimum compiler versions are strongly recommended.
59
60* Clang 3.5 and above
61* GCC 4.7 and above.
62
63Anything older *may* work.
64
65Notes and Known Issues
66----------------------
67
68* TODO
69
70
71Getting Involved
72================
73
74First please review our `Developer's Policy <https://llvm.org/docs/DeveloperPolicy.html>`__
75and `Getting started with LLVM <https://llvm.org/docs/GettingStarted.html>`__.
76
77**Bug Reports**
78
79If you think you've found a bug in libunwind, please report it using
80the `LLVM Bugzilla`_. If you're not sure, you
81can post a message to the `cfe-dev mailing list`_ or on IRC.
82Please include "libunwind" in your subject.
83
84**Patches**
85
86If you want to contribute a patch to libunwind, the best place for that is
87`Phabricator <https://llvm.org/docs/Phabricator.html>`_. Please include [libunwind] in the subject and
88add `cfe-commits` as a subscriber. Also make sure you are subscribed to the
89`cfe-commits mailing list <http://lists.llvm.org/mailman/listinfo/cfe-commits>`_.
90
91**Discussion and Questions**
92
93Send discussions and questions to the
94`cfe-dev mailing list <http://lists.llvm.org/mailman/listinfo/cfe-dev>`_.
95Please include [libunwind] in the subject.
96
97
98Quick Links
99===========
100* `LLVM Homepage <https://llvm.org/>`_
101* `LLVM Bugzilla <https://bugs.llvm.org/>`_
102* `cfe-commits Mailing List`_
103* `cfe-dev Mailing List`_
104* `Browse libunwind Sources <https://github.com/llvm/llvm-project/blob/master/libunwind/>`_
105