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 LLVM
  10 Project, such as the Clang expression parser and LLVM disassembler.
  11
  12 LLDB is the default debugger in Xcode on macOS and supports debugging C,
  13 Objective-C and C++ on the desktop and iOS devices and simulator.
  14
  15 All of the code in the LLDB project is available under the
  16 `"Apache 2.0 License with LLVM exceptions"`_.
  17
  18 .. _"Apache 2.0 License with LLVM exceptions": https://llvm.org/docs/DeveloperPolicy.html#new-llvm-project-license-framework
  19
  20 Using LLDB
  21 ----------
  22
  23 For an introduction into the LLDB command language, head over to the `LLDB
  24 Tutorial <https://lldb.llvm.org/use/tutorial.html>`_. For users already familiar
  25 with GDB there is a cheat sheet listing common tasks and their LLDB equivalent
  26 in the `GDB to LLDB command map <https://lldb.llvm.org/use/map.html>`_.
  27
  28 There are also multiple resources on how to script LLDB using Python `Python
  29 Reference <https://lldb.llvm.org/use/python-reference.html>`_ is a great
  30 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 Get Involved
  85 ------------
  86
  87 Check out the LLVM source-tree with git and find the sources in the `lldb`
  88 subdirectory:
  89
  90 ::
  91
  92   $ git clone https://github.com/llvm/llvm-project.git
  93
  94 Note that LLDB generally builds from top-of-trunk using CMake and Ninja.
  95 Additionally it builds:
  96
  97 * on macOS with a :ref:`generated Xcode project <CMakeGeneratedXcodeProject>`
  98 * on Linux and FreeBSD with Clang and libstdc++/libc++
  99 * on NetBSD with GCC/Clang and libstdc++/libc++
 100 * on Windows with a generated project for VS 2017 or higher
 101
 102 See the :doc:`LLDB Build Page <resources/build>` for build instructions.
 103
 104 Discussions about LLDB should go to the `LLDB forum
 105 <https://discourse.llvm.org/c/subprojects/lldb>`__. Commit
 106 messages are automatically sent to the `lldb-commits
 107 <http://lists.llvm.org/mailman/listinfo/lldb-commits>`__ mailing list, and
 108 this is also the preferred mailing list for patch submissions.
 109
 110 See the :doc:`Projects page <status/projects>` if you are looking for some
 111 interesting areas to contribute to lldb.
 112
 113 .. toctree::
 114    :hidden:
 115    :maxdepth: 1
 116    :caption: Project
 117
 118    status/goals
 119    status/features
 120    status/status
 121    status/projects
 122    status/releases
 123
 124 .. toctree::
 125    :hidden:
 126    :maxdepth: 1
 127    :caption: Use & Extension
 128
 129    use/tutorial
 130    use/map
 131    use/formatting
 132    use/variable
 133    use/symbolication
 134    use/symbols
 135    use/extensions
 136    use/python
 137    use/python-reference
 138    use/remote
 139    use/qemu-testing
 140    use/intel_pt
 141    use/ondemand
 142    use/troubleshooting
 143    use/links
 144
 145 .. toctree::
 146    :hidden:
 147    :maxdepth: 1
 148    :caption: Development
 149
 150    resources/contributing
 151    resources/build
 152    resources/test
 153    resources/fuzzing
 154    resources/bots
 155    resources/caveats
 156
 157
 158 .. toctree::
 159    :hidden:
 160    :maxdepth: 1
 161    :caption: Design
 162
 163    design/overview
 164    design/sbapi
 165
 166 .. toctree::
 167    :hidden:
 168    :maxdepth: 1
 169    :caption: Reference
 170
 171    Public Python API <python_api>
 172    Public C++ API <https://lldb.llvm.org/cpp_reference/namespacelldb.html>
 173    Private C++ API <https://lldb.llvm.org/cpp_reference/index.html>
 174    Man Page <man/lldb>
 175
 176 .. toctree::
 177    :hidden:
 178    :maxdepth: 1
 179    :caption: External Links
 180
 181    Source Code <https://github.com/llvm/llvm-project>
 182    Code Reviews <https://reviews.llvm.org>
 183    Bug Reports <https://github.com/llvm/llvm-project/issues/labels/lldb/>