Unlike gdb's command set, which is rather free-form, we tried to make the lldb command syntax fairly structured. The commands are all of the form:
<noun> <verb> [-options [option-value]] [argument [argument...]] The command line parsing is done before command execution, so it is uniform across all the commands. The command syntax for basic commands is very simple, arguments, options and option values are all white-space separated, and double-quotes are used to protect white-spaces in an argument. If you need to put a backslash or double-quote character in an argument you back-slash it in the argument. That makes the command syntax more regular, but it also means you may have to quote some arguments in lldb that you wouldn't in gdb.
Options can be placed anywhere on the command line, but if the arguments begin with a "-" then you have to tell lldb that you're done with options for the current command by adding an option termination: "--" So for instance if you want to launch a process and give the "process launch" command the "--stop-at-entry" option, yet you want the process you are about to launch to be launched with the arguments "-program_arg value", you would type:
(lldb) process launch --stop-at-entry -- -program_arg value We also tried to reduce the number of special purpose argument parsers, which sometimes forces the user to be a little more explicit about stating their intentions. The first instance you'll note of this is the breakpoint command. In gdb, to set a breakpoint, you might enter
(gdb) break foo.c:12 to break at line 12 of foo.c, and:
(gdb) break foo to break at the function foo. As time went on, the parser that tells foo.c:12 from foo from foo.c::foo (which means the function foo in the file foo.c) got more and more complex and bizarre, and especially in C++ there are times where there's really no way to specify the function you want to break on. The lldb commands are more verbose but also more precise and allow for intellegent auto completion.
To set the same file and line breakpoint in LLDB you can enter either of:
(lldb) breakpoint set --file foo.c --line 12
(lldb) breakpoint set -f foo.c -l 12 To set a breakpoint on a function named foo in LLDB you can enter either of:
(lldb) breakpoint set --name foo
(lldb) breakpoint set -n foo You can use the --name option multiple times to make a breakpoint on a set of functions as well. This is convenient since it allows you to set commmon conditions or commands without having to specify them multiple times:
(lldb) breakpoint set --name foo --name bar Setting breakpoints by name is even more specialized in LLDB as you can specify that you want to set a breakpoint at a function by method name. To set a breakpoint on all C++ methods named foo you can enter either of:
(lldb) breakpoint set --method foo
(lldb) breakpoint set -M foo To set a breakpoint Objective C selectors named alignLeftEdges: you can enter either of:
(lldb) breakpoint set --selector alignLeftEdges:
(lldb) breakpoint set -S alignLeftEdges: You can limit any breakpoints to a specific executable image by using the "--shlib <path>" ("-s <path>" for short):
(lldb) breakpoint set --shlib foo.dylib --name foo
(lldb) breakpoint set -s foo.dylib -n foo The --shlib option can also be repeated to specify several shared libraries.
Suggestions on more interesting primitives of this sort are also very welcome.
Just like gdb, the lldb command interpreter does a shortest unique string match on command names, so the following two commands will both execute the same command:
(lldb) breakpoint set -n "-[SKTGraphicView alignLeftEdges:]"
(lldb) br s -n "-[SKTGraphicView alignLeftEdges:]" lldb also supports command completion for source file names, symbol names, file names, etc. Completion is initiated by a hitting a TAB. Individual options in a command can have different completers, so for instance the "--file <path>" option in "breakpoint" completes to source files, the "--shlib <path>" option to currently loaded shared libraries, etc. We can even do things like if you specify "--shlib <path>", and are completing on "--file <path>", we will only list source files in the shared library specified by "--shlib <path>".
The individual commands are pretty extensively documented. You can use the help command to get an overview of which commands are available or to obtain details about specific commands. There is also an apropos command that will search the help text for all commands for a particular word and dump a summary help string for each matching command.
Finally, there is a mechanism to construct aliases for commonly used commands. So for instance if you get annoyed typing:
(lldb) breakpoint set --file foo.c --line 12 you can do:
(lldb) command alias bfl breakpoint set -f %1 -l %2
(lldb) bfl foo.c 12 We have added a few aliases for commonly used commands (e.g. "step", "next" and "continue") but we haven't tried to be exhaustive because in our experience it is more convenient to make the basic commands unique down to a letter or two, and then learn these sequences than to fill the namespace with lots of aliases, and then have to type them all the way out.
However, users are free to customize lldb's command set however they like, and since lldb reads the file ~/.lldbinit at startup, you can store all your aliases there and they will be generally available to you. Your aliases are also documented in the help command so you can remind yourself of what you've set up.
One alias of note that we do include by popular demand is a weak emulator of gdb's "break" command. It doesn't try to do everything that gdb's break command does (for instance, it doesn't handle foo.c::bar. But it mostly works, and makes the transition easier. Also by popular demand, it is aliased to b. If you actually want to learn the lldb command set natively, that means it will get in the way of the rest of the breakpoint commands. Fortunately, if you don't like one of our aliases, you an easily get rid of it by running (for example):
(lldb) command unalias b I actually also do:
(lldb) command alias b breakpoint so I can run the native lldb breakpoint command with just b
The lldb command parser also supports "raw" commands, where, after command options are stripped off, the rest of the command string is passed uninterpreted to the command. This is convenient for commands whose arguments might be some complex expression that would be painful to backslash protect. For instance the "expression" command is a "raw" command for obvious reasons. The "help" output for a command will tell you if it is "raw" or not, so you know what to expect. The one thing you have to watch out for is that since raw commands still can have options, if your command string has dashes in it, you'll have to indicate these are not option markers by putting "--" after the command name, but before your command string.
lldb also has a built-in Python interpreter, which is accessible by the "script" command. All the functionality of the debugger is available as classes in the Python interpreter, so the more complex commands that in gdb you would introduce with the "define" command can be done by writing Python functions using the lldb-Python library, then loading the scripts into your running session and accessing them with the "script" command.
Having given an overview of lldb's command syntax, we proceed to lay out the stages of a standard debug session.