lldb/docs/index.rst

   1 .. title:: LLDB Homepage
   2
   3 The LLDB Debugger
   4 =================
   5
   6 Welcome to the LLDB documentation!
   7
   8 LLDB is a next generation, high-performance debugger. It is built as a set of
   9 reusable components which highly leverage existing libraries in the larger
  10 `LLVM Project <https://llvm.org>`_, such as the Clang expression parser and
  11 LLVM disassembler.
  12
  13 LLDB is the default debugger in Xcode on macOS and supports debugging C,
  14 Objective-C and C++ on the desktop and iOS devices and simulator.
  15
  16 All of the code in the LLDB project is available under the
  17 `"Apache 2.0 License with LLVM exceptions"`_.
  18
  19 .. _"Apache 2.0 License with LLVM exceptions": https://llvm.org/docs/DeveloperPolicy.html#new-llvm-project-license-framework
  20
  21 Using LLDB
  22 ----------
  23
  24 For an introduction into the LLDB command language, head over to the `LLDB
  25 Tutorial <https://lldb.llvm.org/use/tutorial.html>`_. For users already familiar
  26 with GDB there is a cheat sheet listing common tasks and their LLDB equivalent
  27 in the `GDB to LLDB command map <https://lldb.llvm.org/use/map.html>`_.
  28
  29 There are also multiple resources on how to script LLDB using Python: the
  30 :doc:`use/python-reference` is a great starting point for that.
  31
  32 Compiler Integration Benefits
  33 -----------------------------
  34
  35 LLDB converts debug information into Clang types so that it can
  36 leverage the Clang compiler infrastructure. This allows LLDB to support the
  37 latest C, C++, Objective-C and Objective-C++ language features and runtimes in
  38 expressions without having to reimplement any of this functionality. It also
  39 leverages the compiler to take care of all ABI details when making functions
  40 calls for expressions, when disassembling instructions and extracting
  41 instruction details, and much more.
  42
  43 The major benefits include:
  44
  45 - Up to date language support for C, C++, Objective-C
  46 - Multi-line expressions that can declare local variables and types
  47 - Utilize the JIT for expressions when supported
  48 - Evaluate expression Intermediate Representation (IR) when JIT can't be used
  49
  50 Reusability
  51 -----------
  52
  53 The LLDB debugger APIs are exposed as a C++ object oriented interface in a
  54 shared library. The lldb command line tool links to, and uses this public API.
  55 On macOS the shared library is exposed as a framework named LLDB.framework,
  56 and Unix systems expose it as lldb.so. The entire API is also then exposed
  57 through Python script bindings which allow the API to be used within the LLDB
  58 embedded script interpreter, and also in any python script that loads the
  59 lldb.py module in standard python script files. See the Python Reference page
  60 for more details on how and where Python can be used with the LLDB API.
  61
  62 Sharing the LLDB API allows LLDB to not only be used for debugging, but also
  63 for symbolication, disassembly, object and symbol file introspection, and much
  64 more.
  65
  66 Platform Support
  67 ----------------
  68
  69 LLDB is known to work on the following platforms, but ports to new platforms
  70 are welcome:
  71
  72 * macOS debugging for i386, x86_64 and AArch64
  73 * iOS, tvOS, and watchOS simulator debugging on i386, x86_64 and AArch64
  74 * iOS, tvOS, and watchOS device debugging on ARM and AArch64
  75 * Linux user-space debugging for i386, x86_64, ARM, AArch64, PPC64le, s390x
  76 * FreeBSD user-space debugging for i386, x86_64, ARM, AArch64, MIPS64, PPC
  77 * NetBSD user-space debugging for i386 and x86_64
  78 * Windows user-space debugging for i386, x86_64, ARM and AArch64 (*)
  79
  80 (*) Support for Windows is under active development. Basic functionality is
  81 expected to work, with functionality improving rapidly. ARM and AArch64 support
  82 is more experimental, with more known issues than the others.
  83
  84 Support for the following architectures is in active development. For their
  85 current state, follow the links to their respective issues:
  86
  87 * `RISC-V <https://github.com/llvm/llvm-project/issues/55383>`_
  88 * `LoongArch <https://github.com/llvm/llvm-project/issues/112693>`_
  89
  90 Get Involved
  91 ------------
  92
  93 Check out the LLVM source-tree with git and find the sources in the `lldb`
  94 subdirectory:
  95
  96 ::
  97
  98   $ git clone https://github.com/llvm/llvm-project.git
  99
 100 Note that LLDB generally builds from top-of-trunk using CMake and Ninja.
 101 Additionally it builds:
 102
 103 * on macOS with a :ref:`generated Xcode project <CMakeGeneratedXcodeProject>`
 104 * on Linux and FreeBSD with Clang and libstdc++/libc++
 105 * on NetBSD with GCC/Clang and libstdc++/libc++
 106 * on Windows with a generated project for VS 2017 or higher
 107
 108 See the :doc:`LLDB Build Page <resources/build>` for build instructions.
 109
 110 Discussions about LLDB should go to the `LLDB forum
 111 <https://discourse.llvm.org/c/subprojects/lldb>`__ or the ``lldb`` channel on
 112 the `LLVM Discord server <https://discord.com/invite/xS7Z362>`__.
 113
 114 For contributions follow the
 115 `LLVM contribution process <https://llvm.org/docs/Contributing.html>`__. Commit
 116 messages are automatically sent to the `lldb-commits
 117 <http://lists.llvm.org/mailman/listinfo/lldb-commits>`__ mailing list.
 118
 119 See the :doc:`Projects page <resources/projects>` if you are looking for some
 120 interesting areas to contribute to lldb.
 121
 122 .. toctree::
 123    :hidden:
 124    :maxdepth: 1
 125    :caption: Using LLDB
 126
 127    use/tutorial
 128    use/map
 129    use/formatting
 130    use/variable
 131    use/symbolication
 132    use/symbols
 133    use/remote
 134    use/intel_pt
 135    use/ondemand
 136    use/aarch64-linux
 137    use/symbolfilejson
 138    use/troubleshooting
 139    use/links
 140    Man Page <man/lldb>
 141
 142 .. toctree::
 143    :hidden:
 144    :maxdepth: 1
 145    :caption: Scripting LLDB
 146
 147    use/python
 148    use/python-reference
 149    Python API <python_api>
 150    Python Extensions <python_extensions>
 151
 152
 153 .. toctree::
 154    :hidden:
 155    :maxdepth: 1
 156    :caption: Developing LLDB
 157
 158    resources/overview
 159    resources/contributing
 160    resources/build
 161    resources/test
 162    resources/qemu-testing
 163    resources/debugging
 164    resources/fuzzing
 165    resources/sbapi
 166    resources/dataformatters
 167    resources/extensions
 168    resources/lldbgdbremote
 169    resources/lldbplatformpackets
 170    resources/caveats
 171    resources/projects
 172    resources/lldbdap
 173    resources/addinglanguagesupport
 174    Public C++ API <https://lldb.llvm.org/cpp_reference/namespacelldb.html>
 175    Private C++ API <https://lldb.llvm.org/cpp_reference/index.html>
 176
 177 .. toctree::
 178    :hidden:
 179    :maxdepth: 1
 180    :caption: External Links
 181
 182    Source Code <https://github.com/llvm/llvm-project>
 183    Releases <https://github.com/llvm/llvm-project/releases>
 184    Discord <https://discord.com/channels/636084430946959380/636732809708306432>
 185    Discussion Forums <https://discourse.llvm.org/c/subprojects/lldb/8>
 186    Developer Policy <https://llvm.org/docs/DeveloperPolicy.html>
 187    Bug Reports <https://github.com/llvm/llvm-project/issues?q=is%3Aissue+label%3Alldb+is%3Aopen>
 188    Code Reviews <https://github.com/llvm/llvm-project/pulls?q=is%3Apr+label%3Alldb+is%3Aopen>