dpearson2699/swift-ios-skills / skills/debugging-instruments
debugging-instruments
VerifiedDebug iOS apps and profile performance using LLDB, the interactive Memory Graph Debugger, and Instruments. Use for crashes, retain-cycle inspection, hangs, build failures, and generic CPU, memory, energy, or network profiling. Use ios-memgraph-analysis for .memgraph capture, leaks CLI ownership paths, or persistent heap growth; use ios-ettrace-performance for ETTrace capture and JSON.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 14.1 KB |
| evals/evals.json | config | 4.0 KB |
| references/instruments-guide.md | markdown | 12.3 KB |
| references/lldb-patterns.md | markdown | 9.5 KB |
references/lldb-patterns.md
View on GitHub# LLDB Patterns Reference
Complete LLDB command reference for iOS debugging. Companion to the main `debugging-instruments` skill.
## Contents
- [Inspection Commands](#inspection-commands)
- [Breakpoint Patterns](#breakpoint-patterns)
- [Expression Evaluation](#expression-evaluation)
- [Watchpoints](#watchpoints)
- [Thread and Stack Navigation](#thread-and-stack-navigation)
- [Memory Inspection](#memory-inspection)
- [Custom Type Summaries](#custom-type-summaries)
- [Python Scripting](#python-scripting)
- [Useful Symbolic Breakpoints](#useful-symbolic-breakpoints)
- [LLDB Init File](#lldb-init-file)
## Inspection Commands
### po vs p vs v
| Command | Mechanism | Side Effects | Speed |
|---------|-----------|--------------|-------|
| `po expr` | Calls `debugDescription` via expression eval | Yes — runs code | Slow |
| `p expr` | LLDB formatter on expression result | Yes — runs code | Medium |
| `v varname` | Reads frame memory directly | No | Fast |
```text
(lldb) po myArray # Calls CustomDebugStringConvertible
(lldb) p myArray # Shows type + formatted value
(lldb) v myArray # Fastest, no code execution
(lldb) v myArray[0] # Access elements directly
(lldb) v self.viewModel.state # Dot-path into properties
```
Use `v` as the default. Fall back to `po` when you need `debugDescription`
or custom string output. Use `p` when you need type information.
### Register and Memory
```text
(lldb) register read # All registers
(lldb) register read x0 x1 # Specific registers (ARM64)
(lldb) memory read 0x600003a04000 # Read raw memory
(lldb) memory read -s1 -fx -c32 addr # 32 bytes as hex
```
## Breakpoint Patterns
### File and Line
```text
(lldb) br set -f ViewModel.swift -l 42
(lldb) br set -f ViewModel.swift -l 42 -c "count > 10"
(lldb) br set -f ViewModel.swift -l 42 --one-shot true # Delete after first hit
```
### Function and Method Names
```text
(lldb) br set -n viewDidLoad # Any function named viewDidLoad
(lldb) br set -n "MyApp.ViewModel.loadData()" # Fully qualified Swift name
(lldb) br set -S "setValue:forKey:" # ObjC selector
(lldb) br set -r ".*Error.*" # Regex match on symbol name
(lldb) br set -r "MyModule\..*\.deinit" # All deinits in a module
```
### Breakpoint Actions
```text
(lldb) br set -n loadData
(lldb) br command add 1
> po "loadData called at \(Date())"
> bt
> continue
> DONE
```
### Logpoints (Auto-Continue Breakpoints)
```text
(lldb) br set -f File.swift -l 42
(lldb) br modify 1 --auto-continue true
(lldb) br command add 1
> po "state = \(self.state)"
> DONE
```
This prints the value every time line 42 is hit without stopping execution.
Equivalent to Xcode's "Log Message" breakpoint action with auto-continue.
### Listing and Managing
```text
(lldb) br list # Show all breakpoints
(lldb) br disable 1 # Disable breakpoint 1
(lldb) br enable 1 # Re-enable
(lldb) br delete 1 # Remove
(lldb) br delete # Remove ALL breakpoints
(lldb) br modify 1 -i 5 # Skip first 5 hits (ignore count)
```
## Expression Evaluation
### Swift Expressions
```text
(lldb) expr myArray.count
(lldb) expr myArray.filter { $0.isActive }.count
(lldb) expr let result = myFunc(); print(result)
(lldb) e -l swift -- import Foundation
(lldb) e -l swift -- self.title = "Debug Title"
```
### Objective-C Expressions (for UIKit internals)
```text
(lldb) e -l objc -- (void)[CATransaction flush]
(lldb) e -l objc -- (void)[[UIApplication sharedApplication] _performMemoryWarning]
(lldb) e -l objc -- (BOOL)[(id)0x7fc... isKindOfClass:[UIView class]]
(lldb) e -l objc -- (void)[0x7fc... recursiveDescription] # View hierarchy dump
```
### Modifying State at Runtime
```text
(lldb) e self.debugLabel.text = "Modified in debugger"
(lldb) e self.view.backgroundColor = UIColor.red
(lldb) e -l objc -- (void)[CATransaction flush] # Force redraw
```
### Calling Functions
```text
(lldb) e self.viewModel.reset()
(lldb) e UserDefaults.standard.set(true, forKey: "debug_mode")
(lldb) e NotificationCenter.default.post(name: .init("DebugReload"), object: nil)
```
## Watchpoints
```text
(lldb) w set v self.score # Watch for writes
(lldb) w set v self.score -w read # Watch for reads
(lldb) w set v self.score -w read_write # Watch both
(lldb) w set e -- 0x600003a04000 # Watch memory address
(lldb) w modify 1 -c "self.score > 100" # Conditional
(lldb) w list # Show active watchpoints
(lldb) w delete 1 # Remove
```
Hardware watchpoint limit on Apple Silicon: 4 watchpoints. Use them
sparingly for tracking unexpected mutations.
## Thread and Stack Navigation
```text
(lldb) thread list # All threads with status
(lldb) thread select 3 # Switch to thread 3
(lldb) bt # Backtrace current thread
(lldb) bt all # Backtrace every thread
(lldb) bt 5 # Show only top 5 frames
(lldb) frame select 2 # Jump to frame #2
(lldb) frame info # Current frame info
(lldb) frame variable # All variables in frame
(lldb) up # Move up one frame
(lldb) down # Move down one frame
```
### Thread Return (skip execution)
```text
(lldb) thread return # Return from current frame
(lldb) thread return false # Return false from a Bool func
```
Use `thread return` to skip the rest of a function during debugging.
Useful for bypassing a crash or testing a different code path.
## Memory Inspection
```text
(lldb) memory read 0x600003a04000 # Default format
(lldb) memory read -s4 -fx -c8 addr # 8 x 4-byte hex words
(lldb) memory read -f s addr # Read as C string
(lldb) memory find 0x100000 0x200000 -e "DEADBEEF" # Search memory range
(lldb) image lookup -a 0x100004500 # Symbol at address
(lldb) image lookup -n loadData # Address of symbol
(lldb) image list # All loaded images/frameworks
```
### Swift Metadata Inspection
```text
(lldb) e -l swift -- print(type(of: myObject))
(lldb) e -l swift -- dump(myObject) # Full mirror dump
(lldb) e -l swift -- Mirror(reflecting: myObject).children.map { $0.label }
```
## Custom Type Summaries
Add type summaries to `.lldbinit` for cleaner debugger output:
```text
# ~/.lldbinit
# Show CLLocationCoordinate2D as "lat, lon"
type summary add CLLocationCoordinate2D \
--summary-string "lat=${var.latitude}, lon=${var.longitude}"
# Show Date as readable string
type summary add Foundation.Date \
--summary-string "${var.timeIntervalSinceReferenceDate} secs since 2001"
# Custom summary for your own types
type summary add MyApp.UserProfile \
--summary-string "User(${var.name}, id=${var.id})"
```
## Python Scripting
### Inline Python
```text
(lldb) script import os
(lldb) script print(os.getpid())
(lldb) script lldb.debugger.GetSelectedTarget().GetProcess().GetNumThreads()
```
### Custom Python Command
Create `~/lldb_commands/dump_views.py`:
```python
import lldb
def dump_view_hierarchy(debugger, command, result, internal_dict):
"""Dump the key window's view hierarchy."""
target = debugger.GetSelectedTarget()
process = target.GetProcess()
thread = process.GetSelectedThread()
frame = thread.GetSelectedFrame()
expr = '(NSString *)[[UIApplication sharedApplication].keyWindow recursiveDescription]'
value = frame.EvaluateExpression(expr)
result.AppendMessage(str(value.GetObjectDescription()))
def __lldb_init_module(debugger, internal_dict):
debugger.HandleCommand(
'command script add -f dump_views.dump_view_hierarchy dump_views'
)
```
Load in `.lldbinit`:
```text
command script import ~/lldb_commands/dump_views.py
```
Then use in LLDB:
```text
(lldb) dump_views
```
## Useful Symbolic Breakpoints
Set these in Xcode's Breakpoint Navigator for common debugging scenarios:
| Symbol | Purpose |
|--------|---------|
| `UIViewAlertForUnsatisfiableConstraints` | Auto Layout constraint conflicts |
| `swift_willThrow` | Break on all Swift throws |
| `malloc_error_break` | Heap corruption detection |
| `_UITraitCollectionChangeObserverNotify` | Track trait collection changes |
| `objc_exception_throw` | Break on ObjC exceptions |
| `-[UIApplication _performMemoryWarning]` | Memory warning simulation |
| `NSInternalInconsistencyException` | Foundation assertion failures |
## LLDB Init File
Place commonly used configuration in `~/.lldbinit`:
```text
# Custom aliases
command alias -- pp e -l swift -- import Foundation
command alias -- pjson e -l swift -- print(String(data: try! JSONSerialization.data(withJSONObject: %1, options: .prettyPrinted), encoding: .utf8)!)
# Type summaries
type summary add --summary-string "${var.rawValue}" -x "^.*RawRepresentable$"
# Load custom scripts
command script import ~/lldb_commands/dump_views.py
# Settings
settings set target.language swift
settings set frame-format "frame #${frame.index}: ${frame.pc}{ ${module.file.basename}{\`${function.name-with-args}{${frame.no-debug}}}}\n"
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |