libunwind/docs/index.rst

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