Chisel is a collection of LLDB commands to assist in the debugging of iOS apps.

[Installation • Commands • Custom Commands • Development Workflow Contributing • License]

brew update
brew install chisel

Or, download chisel and add the following line to your ~/.lldbinit file. If it doesn't exist, create it.

# ~/.lldbinit
...
command script import /path/to/fblldb.py

The commands will be available the next time Xcode starts.

There are many commands; here's a few:

To see the list of all of the commands execute the help command in LLDB.

(lldb) help
The following is a list of built-in, permanent debugger commands:
...

The following is a list of your current user-defined commands:
...

The bottom of the list will contain all of the commands sourced from Chisel.

You can also inspect a specific command by passing its name as an argument to the help command (as with all other LLDB commands).

(lldb) help border
Draws a border around <viewOrLayer>. Color and width can be optionally provided.

Arguments:
  <viewOrLayer>; Type: UIView*; The view to border.

Options:
  --color/-c <color>; Type: string; A color name such as 'red', 'green', 'magenta', etc.
  --width/-w <width>; Type: CGFloat; Desired width of border.

Syntax: border [--color=color] [--width=width] <viewOrLayer>

All of the commands provided by Chisel come with verbose help. Be sure to read it when in doubt!

You can add local, custom commands. Here's a contrived example.

#!/usr/bin/python
# Example file with custom commands, located at /magical/commands/example.py

import lldb
import fblldbbase as fb

def lldbcommands():
  return [ PrintKeyWindowLevel() ]
  
class PrintKeyWindowLevel(fb.FBCommand):
  def name(self):
    return 'pkeywinlevel'
    
  def description(self):
    return 'An incredibly contrived command that prints the window level of the key window.'
    
  def run(self, arguments, options):
    # It's a good habit to explicitly cast the type of all return
    # values and arguments. LLDB can't always find them on its own.
    lldb.debugger.HandleCommand('p (CGFloat)[(id)[(id)[UIApplication sharedApplication] keyWindow] windowLevel]')

Then all that's left is to source the commands in lldbinit. Chisel has a python function just for this, loadCommandsInDirectory in the fblldb.py module.

# ~/.lldbinit
...
command script import /path/to/fblldb.py
script fblldb.loadCommandsInDirectory('/magical/commands/')

There's also builtin support to make it super easy to specify the arguments and options that a command takes. See the border and pinvocation commands for example use.

Developing commands, whether for local use or contributing to Chisel directly, both follow the same workflow. Create a command as described in the Custom Commands section and then

1. Start LLDB
2. Reach a breakpoint (or simply pause execution via the pause button in Xcode's debug bar or process interrupt if attached directly)
3. Execute command source ~/.lldbinit in LLDB to source the commands
4. Run the command you are working on
5. Modify the command
6. Repeat steps 3-5 until the command becomes a source of happiness

Please contribute any generic commands that you make. If it helps you then it will likely help many others! :D See CONTRIBUTING.md to learn how to contribute.

Chisel is BSD-licensed. See LICENSE.