Struct lldb::SBDebugger
source · [−]pub struct SBDebugger {
pub raw: SBDebuggerRef,
}
Expand description
Creates SBTarget
s, 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
sourceimpl SBDebugger
impl SBDebugger
sourcepub fn initialize()
pub fn initialize()
Initialize LLDB.
This should be called before LLDB functionality is used.
sourcepub fn 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.
sourcepub fn create(source_init_files: bool) -> SBDebugger
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.
sourcepub fn asynchronous(&self) -> bool
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.
sourcepub fn set_asynchronous(&self, asynchronous: bool)
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.
pub fn command_interpreter(&self) -> SBCommandInterpreter
sourcepub fn enable_log(&self, channel: &str, categories: &[&str]) -> bool
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.
sourcepub fn create_target(
&self,
executable: &str,
target_triple: Option<&str>,
platform_name: Option<&str>,
add_dependent_modules: bool
) -> Result<SBTarget, SBError>
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.
sourcepub fn create_target_simple(&self, executable: &str) -> Option<SBTarget>
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.
sourcepub fn targets(&self) -> SBDebuggerTargetIter<'_>ⓘNotable traits for SBDebuggerTargetIter<'d>impl<'d> Iterator for SBDebuggerTargetIter<'d> type Item = SBTarget;
pub fn targets(&self) -> SBDebuggerTargetIter<'_>ⓘNotable traits for SBDebuggerTargetIter<'d>impl<'d> Iterator for SBDebuggerTargetIter<'d> type Item = SBTarget;
Get an iterator over the targets known to this debugger instance.
sourcepub fn listener(&self) -> SBListener
pub fn listener(&self) -> SBListener
Get the default SBListener
associated with the debugger.
sourcepub fn selected_target(&self) -> Option<SBTarget>
pub fn selected_target(&self) -> Option<SBTarget>
Get the currently selected SBTarget
.
sourcepub fn set_selected_target(&self, target: &SBTarget)
pub fn set_selected_target(&self, target: &SBTarget)
Set the selected SBTarget
.
sourcepub fn platforms(&self) -> SBDebuggerPlatformIter<'_>
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:
sourcepub fn selected_platform(&self) -> SBPlatform
pub fn selected_platform(&self) -> SBPlatform
Get the currently selected SBPlatform
.
See also:
sourcepub fn set_selected_platform(&self, platform: &SBPlatform)
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:
sourcepub fn available_platforms(&self) -> SBDebuggerAvailablePlatformIter<'_>
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:
sourcepub fn set_current_platform(&self, platform_name: &str)
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:
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
sourceimpl Clone for SBDebugger
impl Clone for SBDebugger
sourcefn clone(&self) -> SBDebugger
fn clone(&self) -> SBDebugger
1.0.0 · sourcefn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source
. Read more