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 10API 11--- 12 13The API folder contains the public interface to LLDB. 14 15We are currently vending a C++ API. In order to be able to add methods to this 16API and allow people to link to our classes, we have certain rules that we must 17follow: 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 28By adhering to these rules we should be able to continue to vend a C++ API, and 29make changes to the API as any additional methods added to these classes will 30just be a dynamic loader lookup and they won't affect the class layout (since 31they aren't virtual methods, and no members can be added to the class). 32 33Breakpoint 34---------- 35 36A collection of classes that implement our breakpoint classes. Breakpoints are 37resolved symbolically and always continue to resolve themselves as your program 38runs. Whether settings breakpoints by file and line, by symbol name, by symbol 39regular expression, or by address, breakpoints will keep trying to resolve new 40locations each time shared libraries are loaded. Breakpoints will of course 41unresolve themselves when shared libraries are unloaded. Breakpoints can also 42be scoped to be set only in a specific shared library. By default, breakpoints 43can be set in any shared library and will continue to attempt to be resolved 44with each shared library load. 45 46Breakpoint options can be set on the breakpoint, or on the individual 47locations. This allows flexibility when dealing with breakpoints and allows us 48to do what the user wants. 49 50Commands 51-------- 52 53The command source files represent objects that implement the functionality for 54all textual commands available in our command line interface. 55 56Every 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 60allow command line commands to be logically grouped into a hierarchy. 61 62``lldb_private::CommandObject`` command line commands are the objects that 63implement the functionality of the command. They can optionally define options 64for themselves, as well as group those options into logical groups that can go 65together. The help system is tied into these objects and can extract the syntax 66and option groupings to display appropriate help for each command. 67 68Core 69---- 70 71The Core source files contain basic functionality that is required in the 72debugger as well as the class representing the debugger itself (Debugger). A 73wide 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 83Data Formatters 84--------------- 85 86A collection of classes that implement the data formatters subsystem. 87 88Data formatters provide a set of user-tweakable hooks in the ValueObjects world 89that allow to customize presentation aspects of variables. While users interact 90with formatters mostly through the type command, inside LLDB there are a few 91layers to the implementation: DataVisualization at the highest end of the 92spectrum, backed by classes implementing individual formatters, matching rules, 93etc. 94 95For a general user-level introduction to data formatters, see :doc:`/use/variable`. 96 97More details on their architecture can be found in :doc:`/resources/dataformatters`. 98 99Expression 100---------- 101 102Expression parsing files cover everything from evaluating DWARF expressions, to 103evaluating expressions using Clang. 104 105The DWARF expression parser has been heavily modified to support type 106promotion, new opcodes needed for evaluating expressions with symbolic variable 107references (expression local variables, program variables), and other operators 108required by typical expressions such as assign, address of, float/double/long 109double floating point values, casting, and more. The DWARF expression parser 110uses a stack of lldb_private::Value objects. These objects know how to do the 111standard C type promotion, and allow for symbolic references to variables in 112the program and in the LLDB process (expression local and expression global 113variables). 114 115The expression parser uses a full instance of the Clang compiler in order to 116accurately evaluate expressions. Hooks have been put into Clang so that the 117compiler knows to ask about identifiers it doesn't know about. Once expressions 118have be compiled into an AST, we can then traverse this AST and either generate 119a DWARF expression that contains simple opcodes that can be quickly 120re-evaluated each time an expression needs to be evaluated, or JIT'ed up into 121code that can be run on the process being debugged. 122 123Host 124---- 125 126LLDB tries to abstract itself from the host upon which it is currently running 127by providing a host abstraction layer. This layer includes functionality, whose 128implementation varies wildly from host to host. 129 130Host 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 136It also includes the base classes of the NativeProcess/Thread hierarchy, which 137is used by lldb-server. 138 139Interpreter 140----------- 141 142The interpreter classes are the classes responsible for being the base classes 143needed for each command object, and is responsible for tracking and running 144command line commands. 145 146Symbol 147------ 148 149Symbol classes involve everything needed in order to parse object files and 150debug symbols. All the needed classes for compilation units (code and debug 151info for a source file), functions, lexical blocks within functions, inlined 152functions, types, declaration locations, and variables are in this section. 153 154Target 155------ 156 157Classes 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 167Utility 168------- 169 170This module contains the lowest layers of LLDB. A lot of these classes don't 171really have anything to do with debugging -- they are just there because the 172higher layers of the debugger use these classes to implement their 173functionality. Others are data structures used in many other parts of the 174debugger. Most of the functionality in this module could be useful in an 175application that is not a debugger; however, providing a general purpose C++ 176library is an explicit non-goal of this module.. 177 178This 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 188For historic reasons, some of this functionality overlaps that which is 189provided by the LLVM support library. 190