a60a76b797
This snapshot establishes the camera-to-result recognition flow and related tests while checking in the project skill/docs assets required for the configured local tooling.
481 lines
14 KiB
Markdown
481 lines
14 KiB
Markdown
---
|
|
name: axiom-lldb-ref
|
|
description: Complete LLDB command reference — variable inspection, breakpoints, threads, expression evaluation, process control, memory commands, and .lldbinit customization
|
|
license: MIT
|
|
---
|
|
|
|
# LLDB Command Reference
|
|
|
|
Complete command reference for LLDB in Xcode. Organized by task so you can find the exact command you need.
|
|
|
|
For debugging workflows and decision trees, see `/skill axiom-lldb`.
|
|
|
|
---
|
|
|
|
## Part 1: Variable Inspection
|
|
|
|
### `v` / `frame variable`
|
|
|
|
Reads memory directly. No compilation. Most reliable for Swift values.
|
|
|
|
```
|
|
(lldb) v # All variables in current frame
|
|
(lldb) v self # Self in current context
|
|
(lldb) v self.propertyName # Specific property
|
|
(lldb) v localVariable # Local variable
|
|
(lldb) v self.array[0] # Collection element
|
|
(lldb) v self._showDetails # SwiftUI @State backing store (underscore prefix)
|
|
```
|
|
|
|
**Flags:**
|
|
|
|
| Flag | Effect |
|
|
|------|--------|
|
|
| `-d run` | Run dynamic type resolution (slower but more accurate) |
|
|
| `-T` | Show types |
|
|
| `-R` | Show raw (unformatted) output |
|
|
| `-D N` | Limit depth of nested types to N levels |
|
|
| `-P N` | Limit pointer depth to N levels |
|
|
| `-F` | Flat output (no hierarchy) |
|
|
|
|
**Limitations:** Cannot evaluate expressions, computed properties, or function calls. Use `p` for those.
|
|
|
|
### `p` / `expression` (with format)
|
|
|
|
Compiles and executes an expression. Shows formatted result.
|
|
|
|
```
|
|
(lldb) p self.computedProperty
|
|
(lldb) p items.count
|
|
(lldb) p someFunction()
|
|
(lldb) p String(describing: someValue)
|
|
(lldb) p (1...10).map { $0 * 2 }
|
|
```
|
|
|
|
Result stored in numbered variables:
|
|
|
|
```
|
|
(lldb) p someValue
|
|
$R0 = 42
|
|
(lldb) p $R0 + 10
|
|
$R1 = 52
|
|
```
|
|
|
|
### `po` / `expression --object-description`
|
|
|
|
Calls `debugDescription` (or `description`) on the result.
|
|
|
|
```
|
|
(lldb) po myObject
|
|
(lldb) po error
|
|
(lldb) po notification.userInfo
|
|
(lldb) po NSHomeDirectory()
|
|
```
|
|
|
|
**When `po` adds value:** Classes with `CustomDebugStringConvertible`, `NSError`, `NSNotification`, collections of objects.
|
|
|
|
**When `po` fails:** Swift structs without `CustomDebugStringConvertible`, protocol-typed values (use `v` instead — it performs iterative dynamic type resolution that `po` doesn't).
|
|
|
|
### `expression` (full form)
|
|
|
|
Full expression evaluation with all options.
|
|
|
|
```
|
|
(lldb) expression self.view.backgroundColor = UIColor.red
|
|
(lldb) expression self.debugFlag = true
|
|
(lldb) expression myArray.append("test")
|
|
(lldb) expression CATransaction.flush() # Force UI update
|
|
(lldb) expression Self._printChanges() # SwiftUI debug
|
|
```
|
|
|
|
**Flags:**
|
|
|
|
| Flag | Effect |
|
|
|------|--------|
|
|
| `-l objc` | Evaluate as Objective-C |
|
|
| `-l swift` | Evaluate as Swift (default) |
|
|
| `-O` | Object description (same as `po`) |
|
|
| `-i false` | Stop on breakpoints hit during evaluation (default: ignore) |
|
|
| `--` | Separator between flags and expression |
|
|
|
|
**ObjC expressions for Swift debugging:**
|
|
|
|
```
|
|
(lldb) expr -l objc -- (void)[[[UIApplication sharedApplication] keyWindow] recursiveDescription]
|
|
(lldb) expr -l objc -- (void)[CATransaction flush]
|
|
(lldb) expr -l objc -- (int)[[UIApplication sharedApplication] _isForeground]
|
|
```
|
|
|
|
### `register read`
|
|
|
|
Low-level register inspection:
|
|
|
|
```
|
|
(lldb) register read
|
|
(lldb) register read x0 x1 # Specific registers (ARM64)
|
|
(lldb) register read --all # All register sets
|
|
```
|
|
|
|
---
|
|
|
|
## Part 2: Breakpoints
|
|
|
|
### Setting Breakpoints
|
|
|
|
```
|
|
(lldb) breakpoint set -f File.swift -l 42 # File + line
|
|
(lldb) b File.swift:42 # Short form
|
|
(lldb) breakpoint set -n methodName # By function name
|
|
(lldb) breakpoint set -n "MyClass.myMethod" # Qualified name
|
|
(lldb) breakpoint set -S layoutSubviews # ObjC selector
|
|
(lldb) breakpoint set -r "viewDid.*" # Regex on name
|
|
(lldb) breakpoint set -a 0x100abc123 # Memory address
|
|
```
|
|
|
|
### Conditional Breakpoints
|
|
|
|
```
|
|
(lldb) breakpoint set -f File.swift -l 42 -c "value == nil"
|
|
(lldb) breakpoint set -f File.swift -l 42 -c "index > 100"
|
|
(lldb) breakpoint set -f File.swift -l 42 -c 'name == "test"'
|
|
```
|
|
|
|
### Ignore Count
|
|
|
|
```
|
|
(lldb) breakpoint set -f File.swift -l 42 -i 50 # Skip first 50 hits
|
|
```
|
|
|
|
### One-Shot Breakpoints
|
|
|
|
```
|
|
(lldb) breakpoint set -f File.swift -l 42 -o # Delete after first hit
|
|
```
|
|
|
|
### Breakpoint Commands (Logpoints)
|
|
|
|
Add commands that execute when breakpoint hits:
|
|
|
|
```
|
|
(lldb) breakpoint command add 1
|
|
> v self.state
|
|
> p self.items.count
|
|
> continue
|
|
> DONE
|
|
```
|
|
|
|
Or in one line:
|
|
|
|
```
|
|
(lldb) breakpoint command add 1 -o "v self.state"
|
|
```
|
|
|
|
### Exception Breakpoints
|
|
|
|
```
|
|
(lldb) breakpoint set -E swift # All Swift errors
|
|
(lldb) breakpoint set -E objc # All ObjC exceptions
|
|
# Filtering by exception name requires Xcode's GUI (Edit Breakpoint → Exception field)
|
|
```
|
|
|
|
### Symbolic Breakpoints
|
|
|
|
```
|
|
(lldb) breakpoint set -n UIViewAlertForUnsatisfiableConstraints # Auto Layout
|
|
(lldb) breakpoint set -n "-[UIApplication _run]" # App launch
|
|
(lldb) breakpoint set -n swift_willThrow # Swift throw
|
|
```
|
|
|
|
### Managing Breakpoints
|
|
|
|
```
|
|
(lldb) breakpoint list # List all
|
|
(lldb) breakpoint list -b # Brief format
|
|
(lldb) breakpoint enable 3 # Enable breakpoint 3
|
|
(lldb) breakpoint disable 3 # Disable breakpoint 3
|
|
(lldb) breakpoint delete 3 # Delete breakpoint 3
|
|
(lldb) breakpoint delete # Delete ALL (asks confirmation)
|
|
(lldb) breakpoint modify 3 -c "x > 10" # Add condition to existing
|
|
```
|
|
|
|
### Watchpoints
|
|
|
|
Break when a variable's memory changes:
|
|
|
|
```
|
|
(lldb) watchpoint set variable self.count # Watch for write
|
|
(lldb) watchpoint set variable -w read_write myGlobal # Watch for read or write
|
|
(lldb) watchpoint set expression -- &myVariable # Watch memory address
|
|
(lldb) watchpoint list # List all
|
|
(lldb) watchpoint delete 1 # Delete watchpoint 1
|
|
(lldb) watchpoint modify 1 -c "self.count > 10" # Add condition
|
|
```
|
|
|
|
**Note:** Hardware watchpoints are limited (~4 per process). Use sparingly.
|
|
|
|
---
|
|
|
|
## Part 3: Thread & Backtrace
|
|
|
|
### Backtraces
|
|
|
|
```
|
|
(lldb) bt # Current thread backtrace
|
|
(lldb) bt 10 # Limit to 10 frames
|
|
(lldb) bt all # All threads
|
|
(lldb) thread backtrace all # Same as bt all
|
|
```
|
|
|
|
### Thread Navigation
|
|
|
|
```
|
|
(lldb) thread list # List all threads with state
|
|
(lldb) thread info # Current thread details + stop reason
|
|
(lldb) thread select 3 # Switch to thread 3
|
|
```
|
|
|
|
### Frame Navigation
|
|
|
|
```
|
|
(lldb) frame info # Current frame details
|
|
(lldb) frame select 5 # Jump to frame 5
|
|
(lldb) up # Go up one frame (toward caller)
|
|
(lldb) down # Shortcut: go down one frame
|
|
```
|
|
|
|
### Thread Return (Skip Code)
|
|
|
|
Force an early return from the current function:
|
|
|
|
```
|
|
(lldb) thread return # Return void
|
|
(lldb) thread return 42 # Return specific value
|
|
```
|
|
|
|
**Use with caution** — skips cleanup code, can leave state inconsistent.
|
|
|
|
---
|
|
|
|
## Part 4: Expression Evaluation
|
|
|
|
### Swift Expressions
|
|
|
|
```
|
|
(lldb) expr let x = 42; print(x)
|
|
(lldb) expr self.view.backgroundColor = UIColor.red
|
|
(lldb) expr UIApplication.shared.windows.first?.rootViewController
|
|
(lldb) expr UserDefaults.standard.set(true, forKey: "debug")
|
|
```
|
|
|
|
### Objective-C Expressions
|
|
|
|
Switch to ObjC when Swift expression parser fails:
|
|
|
|
```
|
|
(lldb) expr -l objc -- (void)[CATransaction flush]
|
|
(lldb) expr -l objc -- (id)[[UIApplication sharedApplication] keyWindow]
|
|
(lldb) expr -l objc -- (void)[[NSNotificationCenter defaultCenter] postNotificationName:@"test" object:nil]
|
|
```
|
|
|
|
### UI Debugging Expressions
|
|
|
|
```
|
|
(lldb) expr -l objc -- (void)[[[UIApplication sharedApplication] keyWindow] recursiveDescription]
|
|
(lldb) po UIApplication.shared.windows.first?.rootViewController?.view.recursiveDescription()
|
|
```
|
|
|
|
### SwiftUI Debugging
|
|
|
|
```
|
|
(lldb) expr Self._printChanges() # Print what triggered body re-eval (inside view body only)
|
|
```
|
|
|
|
### Runtime Type Information
|
|
|
|
```
|
|
(lldb) expr type(of: someValue)
|
|
(lldb) expr String(describing: type(of: someValue))
|
|
```
|
|
|
|
---
|
|
|
|
## Part 5: Process Control
|
|
|
|
### Execution Control
|
|
|
|
```
|
|
(lldb) continue # Resume execution (c)
|
|
(lldb) c # Short form
|
|
(lldb) process interrupt # Pause running process
|
|
(lldb) thread step-over # Step over (n / next)
|
|
(lldb) n # Short form
|
|
(lldb) thread step-in # Step into (s / step)
|
|
(lldb) s # Short form
|
|
(lldb) thread step-out # Step out (finish)
|
|
(lldb) finish # Short form
|
|
(lldb) thread step-inst # Step one instruction (assembly-level)
|
|
(lldb) ni # Step over one instruction
|
|
```
|
|
|
|
### Process Management
|
|
|
|
```
|
|
(lldb) process launch # Launch/restart
|
|
(lldb) process attach --pid 1234 # Attach to running process
|
|
(lldb) process attach --name MyApp # Attach by name
|
|
(lldb) process detach # Detach without killing
|
|
(lldb) kill # Kill debugged process
|
|
```
|
|
|
|
---
|
|
|
|
## Part 6: Memory & Image
|
|
|
|
### Memory Reading
|
|
|
|
```
|
|
(lldb) memory read 0x100abc123 # Read memory at address
|
|
(lldb) memory read -c 64 0x100abc123 # Read 64 bytes
|
|
(lldb) memory read -f x 0x100abc123 # Format as hex
|
|
(lldb) memory read -f s 0x100abc123 # Format as string
|
|
```
|
|
|
|
### Memory Search
|
|
|
|
```
|
|
(lldb) memory find -s "searchString" -- 0x100000000 0x200000000
|
|
```
|
|
|
|
### Image/Module Inspection
|
|
|
|
```
|
|
(lldb) image lookup -a 0x100abc123 # Lookup symbol at address
|
|
(lldb) image lookup -n myFunction # Find function by name
|
|
(lldb) image lookup -rn "MyClass.*" # Regex search
|
|
(lldb) image list # List all loaded images/frameworks
|
|
(lldb) image list -b # Brief format
|
|
```
|
|
|
|
**Common use:** Finding which framework a crash address belongs to:
|
|
|
|
```
|
|
(lldb) image lookup -a 0x1a2b3c4d5
|
|
```
|
|
|
|
---
|
|
|
|
## Part 7: .lldbinit & Customization
|
|
|
|
### File Location
|
|
|
|
LLDB reads `~/.lldbinit` at startup. Per-project init files are also supported when configured in Xcode's scheme settings.
|
|
|
|
### Useful Aliases
|
|
|
|
Add to `~/.lldbinit`:
|
|
|
|
```
|
|
# Quick reload — flush UI changes made via expression
|
|
command alias flush expr -l objc -- (void)[CATransaction flush]
|
|
|
|
# Print view hierarchy
|
|
command alias views expr -l objc -- (void)[[[UIApplication sharedApplication] keyWindow] recursiveDescription]
|
|
|
|
# Print auto layout constraints
|
|
command alias constraints po [[UIWindow keyWindow] _autolayoutTrace]
|
|
```
|
|
|
|
### Custom Type Summaries
|
|
|
|
```
|
|
# Show CLLocationCoordinate2D as "lat, lon"
|
|
type summary add CLLocationCoordinate2D --summary-string "${var.latitude}, ${var.longitude}"
|
|
```
|
|
|
|
### Settings
|
|
|
|
```
|
|
(lldb) settings show target.language # Current language
|
|
(lldb) settings set target.language swift # Force Swift mode
|
|
(lldb) settings set target.max-children-count 100 # Show more collection items
|
|
```
|
|
|
|
### Per-Project .lldbinit
|
|
|
|
In Xcode: Edit Scheme → Run → Options → "LLDB Init File" field.
|
|
|
|
Put project-specific aliases and breakpoints in a `.lldbinit` file in your project root.
|
|
|
|
---
|
|
|
|
## Part 8: Troubleshooting LLDB Itself
|
|
|
|
### "expression failed to parse"
|
|
|
|
**Cause:** Swift expression parser can't resolve types from the current module.
|
|
|
|
**Fixes:**
|
|
1. Use `v` instead (no compilation needed)
|
|
2. Simplify the expression
|
|
3. Try `expr -l objc -- ...` for ObjC-bridge types
|
|
4. Clean derived data and rebuild
|
|
|
|
### "variable not available"
|
|
|
|
**Cause:** Compiler optimized the variable out.
|
|
|
|
**Fixes:**
|
|
1. Switch to Debug build configuration
|
|
2. Set `-Onone` for the specific file (Build Settings → per-file compiler flags)
|
|
3. Use `register read` to check if the value is in a register
|
|
|
|
### "wrong language mode"
|
|
|
|
**Cause:** LLDB defaults to ObjC in some contexts (especially in frameworks).
|
|
|
|
**Fix:**
|
|
```
|
|
(lldb) settings set target.language swift
|
|
(lldb) expr -l swift -- mySwiftExpression
|
|
```
|
|
|
|
### "expression caused a crash"
|
|
|
|
**Cause:** The expression you evaluated had a side effect that crashed.
|
|
|
|
**Fix:**
|
|
1. Don't evaluate expressions that modify state unless you intend to
|
|
2. Use `v` for read-only inspection
|
|
3. If the crash corrupted state, restart the debug session
|
|
|
|
### LLDB Hangs or Is Slow
|
|
|
|
**Cause:** Usually compiling a complex expression or resolving types in a large project.
|
|
|
|
**Fix:**
|
|
1. Use `v` instead of `p`/`po` (no compilation)
|
|
2. Reduce expression complexity
|
|
3. If LLDB hangs during `po`, Ctrl+C to cancel and use `v` instead
|
|
|
|
### Breakpoint Not Hit
|
|
|
|
**Causes and fixes:**
|
|
|
|
| Cause | Fix |
|
|
|-------|-----|
|
|
| Wrong file/line (code moved) | Re-set breakpoint on current code |
|
|
| Breakpoint disabled | `breakpoint enable N` |
|
|
| Code not executed | Verify the code path is reached |
|
|
| Optimized out (Release) | Switch to Debug configuration |
|
|
| In a framework/SPM package | Set symbolic breakpoint by function name |
|
|
|
|
---
|
|
|
|
## Resources
|
|
|
|
**WWDC**: 2019-429, 2018-412, 2022-110370, 2015-402
|
|
|
|
**Docs**: /xcode/stepping-through-code-and-inspecting-variables-to-isolate-bugs, /xcode/setting-breakpoints-to-pause-your-running-app
|
|
|
|
**Skills**: axiom-lldb, axiom-xcode-debugging
|