Python Extensions

LLDB provides scriptable extensions to augment the debugger’s capabilities. This gives users the ability to tailor their debugging experience to their own needs.

This page describes some of these scripting extensions:

Operating System Thread Plugins

Any(*args, **kwargs)	Special type indicating an unconstrained type.
OperatingSystem(process)	Class that provides data for an instance of a LLDB 'OperatingSystemPython' plug-in class.

Parsed Command Plugins

This module implements a couple of utility classes to make writing lldb parsed commands more Pythonic. The way to use it is to make a class for your command that inherits from ParsedCommandBase. That will make an LLDBOptionValueParser which you will use for your option definition, and to fetch option values for the current invocation of your command. For concision, I’ll call this the OVParser. Access to the OVParser is through:

ParsedCommandBase.get_parser()

Next, implement setup_command_definition() in your new command class, and call:

self.get_parser().add_option()

to add all your options. The order doesn’t matter for options, lldb will sort them alphabetically for you when it prints help.

Similarly you can define the arguments with:

self.get_parser().add_argument()

At present, lldb doesn’t do as much work as it should verifying arguments, it only checks that commands that take no arguments don’t get passed arguments.

Then implement the execute function for your command as:

def __call__(self, debugger, args_list, exe_ctx, result):

The arguments will be a list of strings.

You can access the option values using the ‘dest’ string you passed in when defining the option. And if you need to know whether a given option was set by the user or not, you can use the was_set API.

So for instance, if you have an option whose “dest” is “my_option”, then:

self.get_parser().my_option

will fetch the value, and:

self.get_parser().was_set(“my_option”)

will return True if the user set this option, and False if it was left at its default value.

Custom Completions:

You can also implement custom completers for your custom command, either for the arguments to your command or to the option values in your command. If you use enum values or if your option/argument uses is one of the types we have completers for, you should not need to do this. But if you have your own completeable types, or if you want completion of one option to be conditioned by other options on the command line, you can use this interface to take over the completion.

You can choose to add a completion for the option values defined for your command, or for the arguments, separately. For the option values, define:

def handle_option_argument_completion(self, long_option, cursor_pos):

The line to be completed will be parsed up to the option containint the cursor position, and the values will be set in the OptionValue parser object. long_option will be the option name containing the cursor, and cursor_pos will be the position of the cursor in that option’s value. You can call the OVParser method: dest_for_option(long_option) to get the value for that option. The other options that came before the cursor in the command line will also be set in the OVParser when the completion handler is called.

For argument values, define:

def handle_argument_completion(self, args, arg_pos, cursor_pos):

Again, the command line will be parsed up to the cursor position, and all the options before the cursor pose will be set in the OVParser. args is a python list of the arguments, arg_pos is the index of the argument with the cursor, and cursor_pos is the position of the cursor in the argument.

In both cases, the return value determines the completion.

Return False to mean “Not Handled” - in which case lldb will fall back on the standard completion machinery.

Return True to mean “Handled with no completions”.

If there is a single unique completion, return a Python dictionary with two elements:

return {“completion” : “completed_value”, “mode” : <”partial”, “complete”>}

If the mode is “partial”, then the completion is to a common base, if it is “complete” then the argument is considered done - mostly meaning lldb will put a space after the completion string. “complete” is the default if no “mode” is specified.

If there are multiple completion options, then return:

return {“values” : [“option1”, “option2”]}

Optionally, you can return a parallel array of “descriptions” which the completer will print alongside the options:

return {“values” : [“option1”, “option2”], “descriptions” : [“the first option”, “the second option”]}

The cmdtemplate example currently uses the parsed command infrastructure:

llvm-project/lldb/examples/python/cmdtemplate.py

There are also a few example commands in the lldb testsuite at:

llvm-project/lldb/test/API/commands/command/script/add/test_commands.py

LLDBOptionValueParser()	This class holds the option definitions for the command, and when the command is run, you can ask the parser for the current values.
ParsedCommand(debugger, unused)

Scripted Breakpoint Resolver Plugins

ScriptedBreakpointResolver(bkpt, args)

The base class for a scripted breakpoint resolver.

Scripted Command Plugins

ScriptedCommand(debugger)

The base class for a scripted (raw) command.

Scripted Frame Provider Plugins

ScriptedFrameProvider(input_frames, args)

The base class for a scripted frame provider.

Scripted Hook Plugins

ScriptedHook(target, args)

The base class for a scripted target hook.

Scripted Platform Plugins

ScriptedPlatform(exe_ctx, args)

The base class for a scripted platform.

Scripted Process Plugins

Any(*args, **kwargs)	Special type indicating an unconstrained type.
PassthroughScriptedProcess(exe_ctx, args[, ...])	A reference ScriptedProcess subclass that forwards every request to a "driving" process running in another target of the same debugger.
PassthroughScriptedThread(process, args)	A reference ScriptedThread subclass that forwards every request to a specific thread of a driving process.
ScriptedFrame(thread, args)	The base class for a scripted frame.
ScriptedProcess(exe_ctx, args)	The base class for a scripted process.
ScriptedThread(process, args)	The base class for a scripted thread.

Scripted Stack Frame Recognizer Plugins

ScriptedStackFrameRecognizer()

The base class for a scripted stack frame recognizer.

Scripted String Summary Plugins

ScriptedStringSummary()

The base class for a scripted string summary provider.

Scripted Synthetic Children Plugins

ScriptedSyntheticChildren(valobj)

The base class for a scripted synthetic children provider.

Scripted Thread Plan Plugins

ScriptedThreadPlan(thread_plan)

Class that provides data for an instance of a LLDB 'ScriptedThreadPlan' plug-in class used to construct custom stepping logic.