llvm/llvm-project

lldb

lldb/ is the LLVM debugger — a modern source-level debugger for C, C++, Objective-C, Swift (out-of-tree), and other languages. It serves the role GDB serves on Linux, but is built on top of Clang and LLVM libraries for expression evaluation, type information, and symbolication.

Purpose

LLDB exists to provide a debugger that can reuse the compiler infrastructure already shipped with LLVM. Instead of reimplementing a parser and type system for print expressions, it links Clang and uses the real C++ parser. Instead of writing an ad hoc DWARF parser, it uses llvm/lib/DebugInfo. The same architectural choice that made Clang a successful library makes LLDB possible.

Directory layout

lldb/
├── source/             # Implementation
│   ├── API/            # SBAPI — the stable C++ public API
│   ├── Breakpoint/
│   ├── Commands/       # The CLI command framework
│   ├── Core/
│   ├── DataFormatters/ # Pretty-printers
│   ├── Expression/     # ClangUserExpression and the IR-eval engine
│   ├── Host/           # Per-OS process launching, threads, files
│   ├── Initialization/
│   ├── Interpreter/
│   ├── Plugins/        # By far the largest tree — see below
│   ├── Symbol/         # Symbol-table abstractions
│   ├── Target/         # Process / thread / module abstractions
│   ├── Utility/
│   ├── ValueObject/
│   └── Version/
├── include/lldb/       # Public headers
├── tools/              # Drivers: lldb (CLI), lldb-server (gdb-remote stub), lldb-vscode/lldb-dap
├── packages/           # Python script bridge package
├── scripts/            # Python build helpers
├── bindings/           # SWIG bindings (Python, Lua)
├── docs/
├── examples/
├── test/               # API tests (Python)
├── unittests/          # C++ unit tests
├── utils/              # lldb-tblgen, formatter helpers
├── Maintainers.md
└── third_party/

The plugins tree

lldb/source/Plugins/ is most of LLDB by line count. Plugin categories:

ABI/ — calling convention rules per arch
Architecture/ — register descriptions, instruction-emulation hooks
Disassembler/ — wrapper around llvm-mc
DynamicLoader/ — runtime-linker integration per OS (POSIX-DYLD, Mach-O dyld, Windows, Wasm, ...)
ExpressionParser/ — currently Clang and Swift hooks
JITLoader/ — JIT-emitted-code support
Language/ — language plugins (C++, Objective-C, ObjC++, CPlusPlus templates, ...)
LanguageRuntime/ — runtime-introspection helpers (e.g., the C++ ABI runtime)
MemoryHistory/, MemoryRegion/
ObjectContainer/, ObjectFile/ — per-format parsers (ELF, Mach-O, PE/COFF, Wasm, JIT, BreakPad, ...)
OperatingSystem/ — bare-metal target glue
Platform/ — per-OS metadata (macOS, iOS, Linux, Windows, Android, FreeBSD, NetBSD, OpenBSD, QEMU-user, ...)
Process/ — debug-server backends (gdb-remote, MacOSX-Native, Linux, Windows, FreeBSDKernel, ...)
ScriptInterpreter/ — Python and Lua
SymbolFile/ — per-format debug-info parsers (DWARF, PDB, Breakpad, JSON, NativePDB, CTF, ...)
SymbolLocator/, SymbolVendor/
Trace/ — Intel PT and friends
TraceExporter/
TypeSystem/ — Clang-based, Swift-based (out-of-tree), etc.
UnwindAssembly/ — fallback unwinding when no DWARF CFI is available

The plugin system is what lets LLDB support so many platform/format combinations without coupling them.

How it works

graph LR
    user["User: lldb CLI<br/>or DAP / SB API"] --> drv["Driver / interpreter"]
    drv --> tgt[Target]
    tgt --> proc[Process plugin]
    proc -->|ptrace / kdp /<br/>gdb-remote| os[OS / remote debug stub]
    tgt --> sym[Symbol files]
    sym --> dwarf["DWARF / PDB parsers<br/>(Plugins/SymbolFile)"]
    user -->|expr foo + bar| expr[Expression parser]
    expr --> clang[Clang (lib)]
    clang --> jit[ORC JIT]
    jit --> proc

A typical session:

The user runs lldb a.out. The CLI driver builds a Target from the file.
process launch (or attach) spawns/attaches via the appropriate ProcessPlugin (POSIX, Mach, Windows, gdb-remote, etc.).
As the process loads images, DynamicLoader plugins notify LLDB to load symbols. SymbolFile plugins parse DWARF/PDB.
Breakpoints set by the user are realized as software/hardware breakpoints in the inferior.
expr foo + bar runs through the Clang-based ClangUserExpression, which compiles a tiny AST snippet to LLVM IR, then to machine code via ORC, then injects it into the inferior.
Pretty-printing of values goes through DataFormatters and language TypeSystem plugins.

Drivers

lldb (lldb/tools/driver/) — the CLI.
lldb-server (lldb/tools/lldb-server/) — the gdb-remote stub used for cross-machine debugging.
lldb-dap (lldb/tools/lldb-dap/) — Debug Adapter Protocol implementation for IDEs.
lldb-test, lldb-instr, helper executables.

Integration points

Clang is linked as a library and used for expression compilation and type imports. Bug fixes in Clang's templates frequently fix LLDB expression evaluation.
LLVM core provides DWARF parsing, MC disassembly, and the ORC JIT.
Python bindings are generated by SWIG from lldb/bindings/. Python scripts are first-class extensions of the debugger.

Entry points for modification

Adding a platform: implement a Platform plugin under lldb/source/Plugins/Platform/<NewPlatform>/.
Adding a debug-info format: a SymbolFile plugin under lldb/source/Plugins/SymbolFile/.
Adding a CLI command: subclass CommandObjectRaw or CommandObjectParsed under lldb/source/Commands/.
Adding a Python-callable API: add to the SB API headers under lldb/include/lldb/API/ and regenerate the SWIG bindings.

Reference

Built by Factory AutoWiki from public repository content. It is a generated preview for codebase exploration, not source-maintained documentation.