Heads up... You're reading this book for free, with parts of this chapter shown beyond this point astext.
LLDB has several ways you can use to create your own customized commands. The first way is through the easy-to-use
command alias you saw in Chapter 9, “Persisting and Customizing”. This command simply creates an alias for a static command. While easy to implement, it really only allowed you to execute commands with no input.
After that came the
command regex, which let you specify a regular expression to capture input then apply it to a command. You learned about this command in Chapter 10, “Regex Commands”. This command works well when you want to feed input to an LLDB command, but it was inconvenient to execute multiline commands and supplying multiple, optional parameters could get really messy.
Next up in the tradeoff between convenience and complexity is LLDB’s script bridging. With script bridging, you can do nearly anything you like. Script bridging is a Python interface LLDB uses to help extend the debugger to accomplish your wildest debugging dreams.
However, there’s a cost to the script bridging interface. It has a steep learning curve, and the documentation, to put it professionally, sucks. Fortunately, you’ve got this book in your hands to help guide you through learning script bridging. Once you’ve a grasp on LLDB’s Python module, you can do some very cool (and very scary!) things.
Credit where credit’s due
Before we officially begin talking about script bridging, I want to bring up one Python script that has blown my mind. If it wasn’t for this script, this book would not be in your hands.
This is the script that made me take a deep dive into learning LLDB. I’ve never had a mental butt-kicking as good as I did trying to initially understand what was happening in this code.
This script had it all: finding stack traces for
malloc’d objects (
malloc_info -s), getting all instances of a particular subclass of
obj_refs -O), finding all pointers to a particular reference in memory (
ptr_refs), finding C strings in memory (
You can load the contents of this script with the following LLDB command:
(lldb) command script import lldb.macosx.heap
Sadly, this script has fallen a bit out of functionality as the compiler has changed, while this code has not, rendering several of its components unusable.
When you’re done reading this section, I would strongly encourage you to attempt to understand the contents of this script. You can learn a lot from it.
Ok, now back to our regularly scheduled, reading program…
As mentioned, LLDB’s script bridge is a Python interface to the debugger. This means you can load and execute Python scripts in LLDB. In those Python scripts, you include the
lldb module to interface with the debugger to obtain information such as the arguments to a custom command.
(lldb) script import sys (lldb) script print (sys.version)
>>> import sys >>> print (sys.version)
Playing around in Python
If you are unfamiliar with Python, this section will help you quickly get familiar with the language. If you’re already knowledgeable about Python, feel free to jump to the next section.
>>> h = "hello world" >>> h
>>> h.split(" ") ['hello', 'world']
var h: [Any] = 
>>> h.split(" ").__class__ <type 'list'>
>>> h.__class__ <type 'str'>
>>> help (str)
>>> help (str.split)
Help on method_descriptor: split(...) S.split([sep [,maxsplit]]) -> list of strings Return a list of the words in the string S, using sep as the delimiter string. If maxsplit is given, at most maxsplit splits are done. If sep is not specified or is None, any whitespace string is a separator and empty strings are removed from the result.
>>> h.split(" ", 0)
>>> def test(a): ...
... print(a + " world!")
Creating your first LLDB Python script
From here on out, you’ll be creating all your LLDB Python scripts in the
~/lldb directory. If you want to have them in a different directory, everytime I say
~/lldb, you’ll need to invoke your “mental symlink” to whatever directory you’ve decided to use.
def your_first_command(debugger, command, result, internal_dict): print ("hello world!")
(lldb) command script import ~/lldb/helloworld.py
(lldb) script import helloworld
(lldb) script dir(helloworld)
['__builtins__', '__doc__', '__file__', '__name__', '__package__', 'your_first_command']
(lldb) command script add -f helloworld.your_first_command yay
Setting up commands efficiently
Once the high of creating a custom function in script bridging has worn off, you’ll come to realize you don’t want to type this stuff each time you start LLDB. You want those commands to be there ready for you as soon as LLDB starts.
def __lldb_init_module(debugger, internal_dict): debugger.HandleCommand('command script add -f helloworld.your_first_command yay')
(lldb) script help(lldb.SBDebugger.HandleCommand)
HandleCommand(self, *args) unbound lldb.SBDebugger method HandleCommand(self, str command)
command script import ~/lldb/helloworld.py
Where to go from here?
If you don’t feel comfortable with Python, now is the time to start brushing up on it. If you have past development experience, you’ll find Python to be a fun and friendly language to learn. It’s a great language for quickly building other tools to help with everyday programming tasks.