Crate lldb

Expand description

LLDB

This crate provides a safe binding to the public API for LLDB, the debugger provided by the LLVM project. LLDB provides a modern, high performance debugger framework and is the default debugger for macOS and iOS.

Installation

This crate works with Cargo and is on crates.io. Add it to your Cargo.toml like so:

lldb = "0.0.11"

macOS Installation Notes

On macOS, this library relies upon being able to find the LLDB.framework that is provided by Xcode.app.

In your own application, you will need to configure the @rpath for your executable to point to the location of the LLDB.framework that you are using. Doing this automatically is not currently supported by Cargo.

For testing, you can use the version provided by Xcode.app by setting an environment variable:

export DYLD_FRAMEWORK_PATH=/Applications/Xcode.app/Contents/SharedFrameworks

Linux Installation Notes

Install the lldb and lldb-dev packages for your platform so that you have both LLDB itself installed as well as the headers and other support files required.

Windows Installation Notes

Support for building this has not yet been provided for Windows. Contributions are welcome!

Usage

The primary entry point is SBDebugger. This will be how you create a debug target and begin the actually interesting stuff.

Important Classes

The LLDB API provides many structs and a wide range of functionality. Some of the most common usages will involve these structs and their corresponding methods:

SBDebugger: Manages the entire debug experience and creates SBTargets.
SBTarget: The target program running under the debugger.
SBProcess: The process associated with the target program.
SBThread: A thread of execution. SBProcess contains SBThreads.
SBFrame: One of the stack frames associated with a thread. SBThread contains SBFrames.
SBSymbolContext: A container that stores various debugger related info.
SBValue: The value of a variable, a register, or an expression.
SBModule: An executable image and its associated object and symbol files. SBTarget contains SBModules.
SBBreakpoint: A logical breakpoint and its associated settings. SBTarget contains SBBreakpoints.
SBSymbol: The symbol possibly associated with a stack frame.
SBCompileUnit: A compilation unit, or compiled source file.
SBFunction: A generic function, which can be inlined or not.
SBBlock: A lexical block. SBFunction contains SBBlocks.
SBLineEntry: Specifies an association with a contiguous range of instructions and a source file location. SBCompileUnit contains SBLineEntrys.

Support and Maintenance

I am developing this library largely on my own so far. I am able to offer support and maintenance, but would very much appreciate donations via Patreon. I can also provide commercial support, so feel free to contact me.

Re-exports

pub extern crate lldb_sys as sys;

Structs

CommandFlags

EmulateInstructionOptions

A section + offset based address class.

SBAttachInfo

Configuration for attaching to a process.

SBBlock

A lexical block.

SBBreakpoint

A logical breakpoint and its associated settings.

SBBreakpointList

A list of breakpoints.

SBBreakpointListIter

An iterator over the breakpoints in an SBBreakpointList.

SBBreakpointLocation

One unique instance (by address) of a logical breakpoint.

SBBreakpointLocationIter

An iterator over the locations in an SBBreakpoint.

SBBroadcaster

An entity which can broadcast events.

SBCommandInterpreter

SBCompileUnit

A compilation unit or compiled source file.

SBData

A block of data.

SBDebugger

Creates SBTargets, provides access to them and manages the overall debugging experience.

SBDebuggerTargetIter

Iterate over the targets known to a debugger.

SBError

A container for holding any error code and an error message.

An event.

Represents a file.

A file specification that divides the path into a directory and basename.

SBFileSpecList

A list of filespecs.

SBFileSpecListIter

An iterator over the filespecs in an SBFileSpecList.

SBFrame

One of the stack frames associated with a thread.

SBFunction

A generic function, which can be inlined or not.

SBInstruction

A machine instruction.

SBInstructionList

A list of machine instructions.

SBInstructionListIter

An iterator over the instructions in an SBInstructionList.

SBLaunchInfo

Configuration for launching a process.

SBLineEntry

Specifies an association with a contiguous range of instructions and a source file location.

SBListener

Listen for debugger events.

SBModule

An executable image and its associated object and symbol files.

SBModuleSectionIter

Iterate over the sections in a module.

SBModuleSpec

A description of an SBModule.

SBPlatform

A platform that can represent the current host or a remote host debug platform.

SBProcess

The process associated with the target program.

SBProcessEvent

SBProcessEventRestartedReasonIter

Iterate over the restart reasons in a process event.

SBProcessInfo

SBProcessQueueIter

Iterate over the queues in a process.

SBProcessThreadIter

Iterate over the threads in a process.

SBQueue

A libdispatch (aka Grand Central Dispatch) queue.

SBQueueItem

A work item enqueued on a libdispatch aka Grand Central Dispatch (GCD) queue.

SBQueueQueueItemIter

Iterate over the queue items in a queue.

SBQueueThreadIter

Iterate over the threads associated with a queue.

SBSection

SBSectionSubSectionIter

Iterate over the subsections in a section.

SBStream

A destination for streaming data output. By default, this is a string stream, but it can be redirected to a file.

SBStringList

A list of strings.

SBStringListIter

An iterator over an SBStringList.

SBStructuredData

The value of a variable, register or expression.

SBSymbol

The symbol possibly associated with a stack frame.

SBSymbolContext

A container that stores various debugger related info.

SBSymbolContextList

A list of symbol contexts.

SBTarget

The target program running under the debugger.

SBTargetBreakpointIter

Iterate over the breakpoints in a target.

SBTargetEvent

SBTargetEventModuleIter

Iterate over the modules referenced from a target event.

SBTargetModuleIter

Iterate over the modules in a target.

SBTargetWatchpointIter

Iterate over the watchpoints in a target.

SBThread

A thread of execution.

SBThreadEvent

A thread event.

SBThreadFrameIter

Iterate over the frames in a thread.

SBType

SBTypeList

A list of types.

SBTypeListIter

An iterator over the types in an SBTypeList.

SBValue

The value of a variable, register or expression.

SBValueList

A list of values.

SBValueListIter

An iterator over the values in an SBValueList.

SBVariablesOptions

SBWatchpoint

An instance of a watch point for a specific target program.

SymbolContextItem

These mask bits allow a common interface for queries that can limit the amount of information that gets parsed to only the information that is requested. These bits also can indicate what actually did get resolved during query function calls.