lldb/docs/resources/overview.rst

   1 Overview
   2 ========
   3
   4 LLDB is a large and complex codebase. This section will help you become more
   5 familiar with the pieces that make up LLDB and give a general overview of the
   6 general architecture.
   7
   8 LLDB has many code groupings that makeup the source base:
   9
  10 API
  11 ---
  12
  13 The API folder contains the public interface to LLDB.
  14
  15 We are currently vending a C++ API. In order to be able to add methods to this
  16 API and allow people to link to our classes, we have certain rules that we must
  17 follow:
  18
  19 - Classes can't inherit from any other classes.
  20 - Classes can't contain virtual methods.
  21 - Classes should be compatible with script bridging utilities like swig.
  22 - Classes should be lightweight and be backed by a single member. Pointers (or
  23   shared pointers) are the preferred choice since they allow changing the
  24   contents of the backend without affecting the public object layout.
  25 - The interface should be as minimal as possible in order to give a complete
  26   API.
  27
  28 By adhering to these rules we should be able to continue to vend a C++ API, and
  29 make changes to the API as any additional methods added to these classes will
  30 just be a dynamic loader lookup and they won't affect the class layout (since
  31 they aren't virtual methods, and no members can be added to the class).
  32
  33 Breakpoint
  34 ----------
  35
  36 A collection of classes that implement our breakpoint classes. Breakpoints are
  37 resolved symbolically and always continue to resolve themselves as your program
  38 runs. Whether settings breakpoints by file and line, by symbol name, by symbol
  39 regular expression, or by address, breakpoints will keep trying to resolve new
  40 locations each time shared libraries are loaded. Breakpoints will of course
  41 unresolve themselves when shared libraries are unloaded. Breakpoints can also
  42 be scoped to be set only in a specific shared library. By default, breakpoints
  43 can be set in any shared library and will continue to attempt to be resolved
  44 with each shared library load.
  45
  46 Breakpoint options can be set on the breakpoint, or on the individual
  47 locations. This allows flexibility when dealing with breakpoints and allows us
  48 to do what the user wants.
  49
  50 Commands
  51 --------
  52
  53 The command source files represent objects that implement the functionality for
  54 all textual commands available in our command line interface.
  55
  56 Every command is backed by a ``lldb_private::CommandObject`` or
  57 ``lldb_private::CommandObjectMultiword`` object.
  58
  59 ``lldb_private::CommandObjectMultiword`` are commands that have subcommands and
  60 allow command line commands to be logically grouped into a hierarchy.
  61
  62 ``lldb_private::CommandObject`` command line commands are the objects that
  63 implement the functionality of the command. They can optionally define options
  64 for themselves, as well as group those options into logical groups that can go
  65 together. The help system is tied into these objects and can extract the syntax
  66 and option groupings to display appropriate help for each command.
  67
  68 Core
  69 ----
  70
  71 The Core source files contain basic functionality that is required in the
  72 debugger as well as the class representing the debugger itself (Debugger). A
  73 wide variety of classes are implemented:
  74
  75 - Address (section offset addressing)
  76 - AddressRange
  77 - Broadcaster / Event / Listener
  78 - Communication classes that use Connection objects
  79 - Mangled names
  80 - Source manager
  81 - Value objects
  82
  83 Data Formatters
  84 ---------------
  85
  86 A collection of classes that implement the data formatters subsystem.
  87
  88 Data formatters provide a set of user-tweakable hooks in the ValueObjects world
  89 that allow to customize presentation aspects of variables. While users interact
  90 with formatters mostly through the type command, inside LLDB there are a few
  91 layers to the implementation: DataVisualization at the highest end of the
  92 spectrum, backed by classes implementing individual formatters, matching rules,
  93 etc.
  94
  95 For a general user-level introduction to data formatters, see :doc:`/use/variable`.
  96
  97 More details on their architecture can be found in :doc:`/resources/dataformatters`.
  98
  99 Expression
 100 ----------
 101
 102 Expression parsing files cover everything from evaluating DWARF expressions, to
 103 evaluating expressions using Clang.
 104
 105 The DWARF expression parser has been heavily modified to support type
 106 promotion, new opcodes needed for evaluating expressions with symbolic variable
 107 references (expression local variables, program variables), and other operators
 108 required by typical expressions such as assign, address of, float/double/long
 109 double floating point values, casting, and more. The DWARF expression parser
 110 uses a stack of lldb_private::Value objects. These objects know how to do the
 111 standard C type promotion, and allow for symbolic references to variables in
 112 the program and in the LLDB process (expression local and expression global
 113 variables).
 114
 115 The expression parser uses a full instance of the Clang compiler in order to
 116 accurately evaluate expressions. Hooks have been put into Clang so that the
 117 compiler knows to ask about identifiers it doesn't know about. Once expressions
 118 have be compiled into an AST, we can then traverse this AST and either generate
 119 a DWARF expression that contains simple opcodes that can be quickly
 120 re-evaluated each time an expression needs to be evaluated, or JIT'ed up into
 121 code that can be run on the process being debugged.
 122
 123 Host
 124 ----
 125
 126 LLDB tries to abstract itself from the host upon which it is currently running
 127 by providing a host abstraction layer. This layer includes functionality, whose
 128 implementation varies wildly from host to host.
 129
 130 Host functionality includes abstraction layers for:
 131
 132 - Information about the host system (triple, list of running processes, etc.)
 133 - Launching processes
 134 - Various OS primitives like pipes and sockets
 135
 136 It also includes the base classes of the NativeProcess/Thread hierarchy, which
 137 is used by lldb-server.
 138
 139 Interpreter
 140 -----------
 141
 142 The interpreter classes are the classes responsible for being the base classes
 143 needed for each command object, and is responsible for tracking and running
 144 command line commands.
 145
 146 Symbol
 147 ------
 148
 149 Symbol classes involve everything needed in order to parse object files and
 150 debug symbols. All the needed classes for compilation units (code and debug
 151 info for a source file), functions, lexical blocks within functions, inlined
 152 functions, types, declaration locations, and variables are in this section.
 153
 154 Target
 155 ------
 156
 157 Classes that are related to a debug target include:
 158
 159 - Target
 160 - Process
 161 - Thread
 162 - Stack frames
 163 - Stack frame registers
 164 - ABI for function calling in process being debugged
 165 - Execution context batons
 166
 167 Utility
 168 -------
 169
 170 This module contains the lowest layers of LLDB. A lot of these classes don't
 171 really have anything to do with debugging -- they are just there because the
 172 higher layers of the debugger use these classes to implement their
 173 functionality. Others are data structures used in many other parts of the
 174 debugger. Most of the functionality in this module could be useful in an
 175 application that is not a debugger; however, providing a general purpose C++
 176 library is an explicit non-goal of this module..
 177
 178 This module provides following functionality:
 179
 180 - Abstract path manipulation (FileSpec)
 181 - Architecture specification
 182 - Data buffers (DataBuffer, DataEncoder, DataExtractor)
 183 - Logging
 184 - Structured data manipulation (JSON)
 185 - Streams
 186 - Timers
 187
 188 For historic reasons, some of this functionality overlaps that which is
 189 provided by the LLVM support library.