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