Struct SBDebugger

pub struct SBDebugger {
    pub raw: SBDebuggerRef,
}

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

Initialization and Teardown

LLDB must be initialized before the functionality is used. This is done with SBDebugger::initialize():

use lldb::SBDebugger;

SBDebugger::initialize();

Similarly, it must be terminated after you are done using it:

use lldb::SBDebugger;

SBDebugger::initialize();
// Use LLDB functionality ...
SBDebugger::terminate();

Once you’ve initialized LLDB, you’re ready to create an instance of SBDebugger:

use lldb::SBDebugger;

SBDebugger::initialize();

let debugger = SBDebugger::create(false);
// ... configure the debugger if needed ...
// ... create a target and do stuff ...

SBDebugger::terminate();

Configuration

Async Mode

While it is best to use LLDB in asynchronous mode, it does offer a synchronous mode, which can be easier to use for quick experiments or scripts.

In synchronous mode, calls to the LLDB API do not return until the underlying action has been completed. This means that the thread from which you call LLDB will be blocked during that time, so this is not an ideal way to use LLDB for building interactive tools or a new user interface.

In asynchronous mode, calls to the LLDB API will return immediately without waiting for the action to complete. This means that actions like launching a target, continuing the execution of a process and so on won’t be completed immediately and you must process events to see what the results of an action are.

Synchronous mode can be enabled by using SBDebugger::set_asynchronous() and passing it a false value. You can see if you’re in asynchronous mode or not by calling SBDebugger::asynchronous().

Platform Management

LLDB supports multiple platforms when debugging.

LLDB is aware of both available and active platforms. By default, the host platform is active for debugging processes on the local machine.

A number of additional platforms are available and can be activated via SBDebugger::set_current_platform().

The currently selected platform is controlled by SBDebugger::set_selected_platform() typically using instances of SBPlatform.

When doing remote debugging, additional confirmation and work is required. (See SBPlatform::connect_remote(). This is not yet wrapped in this library.)

See also:

• SBDebugger::available_platforms()
• SBDebugger::platforms()
• SBDebugger::selected_platform()
• SBDebugger::set_current_platform()
• SBDebugger::set_selected_platform()
• SBPlatform

Target Management

The SBDebugger instance tracks the various targets that are currently known to the debugger.

Typically, you create a target with SBDebugger::create_target(), SBDebugger::create_target_simple() or one of the related methods.

Sometimes, you’ll want to create a target without an associated executable. A common use case for this is to attach to a process by name or process ID where you don’t know the executable in advance. The most convenient way to do this is:

let debugger = SBDebugger::create(false);
if let Some(target) = debugger.create_target_simple("") {
    println!("Got a target: {:?}", target);
    // Now, maybe we'd like to attach to something.
}

You can iterate over these targets which have been created by using SBDebugger::targets():

// Iterate over the targets...
for target in debugger.targets() {
    println!("Hello {:?}!", target);
}
// Or collect them into a vector!
let targets = debugger.targets().collect::<Vec<SBTarget>>();

Fields

raw: SBDebuggerRef

The underlying raw SBDebuggerRef.

Implementations

impl SBDebugger

pub fn initialize()

Initialize LLDB.

This should be called before LLDB functionality is used.

Examples found in repository

examples/basic_synchronous.rs (line 4)

fn main() {
    SBDebugger::initialize();

    let debugger = SBDebugger::create(false);
    debugger.set_asynchronous(false);
    println!("{debugger:?}");

    if let Some(target) = debugger.create_target_simple("/usr/local/bin/servo") {
        println!("{target:?}");

        let launchinfo = SBLaunchInfo::new();
        launchinfo.set_launch_flags(LaunchFlags::STOP_AT_ENTRY);
        match target.launch(launchinfo) {
            Ok(process) => {
                println!("{process:?}");
                let _ = process.continue_execution();
                println!("{process:?}");
            }
            Err(e) => println!("Uhoh: {e:?}"),
        }
    }
    SBDebugger::terminate();
}

pub fn terminate()

Tear down LLDB.

This should be called once the application no longer needs to use LLDB functionality. Typically, this is called as the application exits.

Examples found in repository

examples/basic_synchronous.rs (line 24)

fn main() {
    SBDebugger::initialize();

    let debugger = SBDebugger::create(false);
    debugger.set_asynchronous(false);
    println!("{debugger:?}");

    if let Some(target) = debugger.create_target_simple("/usr/local/bin/servo") {
        println!("{target:?}");

        let launchinfo = SBLaunchInfo::new();
        launchinfo.set_launch_flags(LaunchFlags::STOP_AT_ENTRY);
        match target.launch(launchinfo) {
            Ok(process) => {
                println!("{process:?}");
                let _ = process.continue_execution();
                println!("{process:?}");
            }
            Err(e) => println!("Uhoh: {e:?}"),
        }
    }
    SBDebugger::terminate();
}

pub fn create(source_init_files: bool) -> SBDebugger

Create a new instance of SBDebugger.

If source_init_files is true, then ~/.lldbinit will be processed.

Examples found in repository

examples/basic_synchronous.rs (line 6)

fn main() {
    SBDebugger::initialize();

    let debugger = SBDebugger::create(false);
    debugger.set_asynchronous(false);
    println!("{debugger:?}");

    if let Some(target) = debugger.create_target_simple("/usr/local/bin/servo") {
        println!("{target:?}");

        let launchinfo = SBLaunchInfo::new();
        launchinfo.set_launch_flags(LaunchFlags::STOP_AT_ENTRY);
        match target.launch(launchinfo) {
            Ok(process) => {
                println!("{process:?}");
                let _ = process.continue_execution();
                println!("{process:?}");
            }
            Err(e) => println!("Uhoh: {e:?}"),
        }
    }
    SBDebugger::terminate();
}

pub fn asynchronous(&self) -> bool

Get whether or not the debugger is in asynchronous mode.

When in asynchronous mode, the debugger returns immediately when stepping or continuing without waiting for the process to change state.

pub fn set_asynchronous(&self, asynchronous: bool)

Set the debugger to be in asynchronous mode or not.

When in asynchronous mode, the debugger returns immediately when stepping or continuing without waiting for the process to change state.

Examples found in repository

examples/basic_synchronous.rs (line 7)

fn main() {
    SBDebugger::initialize();

    let debugger = SBDebugger::create(false);
    debugger.set_asynchronous(false);
    println!("{debugger:?}");

    if let Some(target) = debugger.create_target_simple("/usr/local/bin/servo") {
        println!("{target:?}");

        let launchinfo = SBLaunchInfo::new();
        launchinfo.set_launch_flags(LaunchFlags::STOP_AT_ENTRY);
        match target.launch(launchinfo) {
            Ok(process) => {
                println!("{process:?}");
                let _ = process.continue_execution();
                println!("{process:?}");
            }
            Err(e) => println!("Uhoh: {e:?}"),
        }
    }
    SBDebugger::terminate();
}

pub fn command_interpreter(&self) -> SBCommandInterpreter

pub fn execute_command(&self, command: &str) -> Result<&str, String>

Executes a command as lldb would run in the console and returns a result that contains a string of the output if the command execution was successful. If there was an error, it contains an error message.

(lldb) b main => Is equal to debugger.execute_command("b main")

pub fn enable_log(&self, channel: &str, categories: &[&str]) -> bool

Enable logging (defaults to stderr).

enable_log("lldb", &["default"]) is useful for troubleshooting in most cases. Include "all" in categories for extra verbosity.

See invocations to lldb_private::Log::Register for more channels and categories.

pub fn version() -> String

Get the LLDB version string.

pub fn create_target( &self, executable: &str, target_triple: Option<&str>, platform_name: Option<&str>, add_dependent_modules: bool, ) -> Result<SBTarget, SBError>

Create a target.

The executable name may be an empty string to create an empty target.

pub fn create_target_simple(&self, executable: &str) -> Option<SBTarget>

Create a target from just an executable name.

The executable name may be an empty string to create an empty target.

Using SBDebugger::create_target() is preferred in most cases as that provides access to an SBError to inform the caller about what might have gone wrong.

Examples found in repository

examples/basic_synchronous.rs (line 10)

fn main() {
    SBDebugger::initialize();

    let debugger = SBDebugger::create(false);
    debugger.set_asynchronous(false);
    println!("{debugger:?}");

    if let Some(target) = debugger.create_target_simple("/usr/local/bin/servo") {
        println!("{target:?}");

        let launchinfo = SBLaunchInfo::new();
        launchinfo.set_launch_flags(LaunchFlags::STOP_AT_ENTRY);
        match target.launch(launchinfo) {
            Ok(process) => {
                println!("{process:?}");
                let _ = process.continue_execution();
                println!("{process:?}");
            }
            Err(e) => println!("Uhoh: {e:?}"),
        }
    }
    SBDebugger::terminate();
}

pub fn targets(&self) -> SBDebuggerTargetIter<'_>

Get an iterator over the targets known to this debugger instance.

pub fn listener(&self) -> SBListener

Get the default SBListener associated with the debugger.

pub fn selected_target(&self) -> Option<SBTarget>

Get the currently selected SBTarget.

pub fn set_selected_target(&self, target: &SBTarget)

Set the selected SBTarget.

pub fn platforms(&self) -> SBDebuggerPlatformIter<'_>

Get an iterator over the currently active platforms.

By default, the host platform will be active. Additional platforms can be activated via SBDebugger::set_current_platform().

See also:

• SBDebugger::available_platforms()
• SBDebugger::selected_platform()
• SBDebugger::set_current_platform()
• SBDebugger::set_selected_platform()

pub fn selected_platform(&self) -> SBPlatform

Get the currently selected SBPlatform.

See also:

• SBDebugger::platforms()
• SBDebugger::set_current_platform()
• SBDebugger::set_selected_platform()

pub fn set_selected_platform(&self, platform: &SBPlatform)

Set the selected SBPlatform.

Selecting a platform by name rather than an instance of SBPlatform can be done via SBDebugger::set_current_platform().

See also:

• SBDebugger::platforms()
• SBDebugger::selected_platform()
• SBDebugger::set_current_platform()

pub fn available_platforms(&self) -> SBDebuggerAvailablePlatformIter<'_>

Get an iterator over the available platforms known to this debugger instance.

These correspond to the available platform plugins within LLDB. The platform name can be used with SBDebugger::set_current_platform() to activate and select it.

The structured data will have 2 string keys:

• "name" - Name of the platform plugin.
• "description" - The description of the platform plugin.

See also:

• SBDebugger::platforms()
• SBDebugger::selected_platform()
• SBDebugger::set_current_platform()
• SBDebugger::set_selected_platform()

pub fn set_current_platform(&self, platform_name: &str)

Activate and select an available platform by name.

The list of available platforms can be found via SBDebugger::available_platforms().

See also:

• SBDebugger::available_platforms()
• SBDebugger::platforms()
• SBDebugger::selected_platform()
• SBDebugger::set_current_platform_sdk_root()
• SBDebugger::set_selected_platform()

pub fn set_current_platform_sdk_root(&self, sysroot: &str)

pub fn set_use_external_editor(&self, use_external_editor: bool)

pub fn get_use_external_editor(&self) -> bool

pub fn set_use_color(&self, use_color: bool)

pub fn get_use_color(&self) -> bool

pub fn set_use_source_cache(&self, use_source_cache: bool)

pub fn get_use_source_cache(&self) -> bool

Trait Implementations

impl Clone for SBDebugger

fn clone(&self) -> SBDebugger

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SBDebugger

fn fmt(&self, fmt: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for SBDebugger

fn drop(&mut self)

Executes the destructor for this type.

impl Send for SBDebugger

impl Sync for SBDebugger