@mmerterden/multi-agent-pipeline 20.6.0 → 20.8.0

package/pipeline/skills/shared/external/debugging-instruments/references/lldb-patterns.md

@@ -1,298 +1,245 @@
-# LLDB Patterns Reference
+# LLDB Command Reference
 
-Complete LLDB command reference for iOS debugging. Companion to the main `debugging-instruments` skill.
+Companion to the `debugging-instruments` skill. Commands are typed at the
+`(lldb)` prompt in Xcode's console or in a standalone `lldb` session.
 
-## Contents
+## Printing Values: `v`, `p`, `po`
 
-- [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)
+| Command | How it works | Runs code in the target? | Speed |
+|---------|--------------|--------------------------|-------|
+| `v` | Reads the variable from the frame's memory | No | Fast |
+| `p` | Evaluates the expression, formats the result with LLDB's data formatters | Yes | Medium |
+| `po` | Evaluates the expression, then asks the object for its description | Yes | Slow |
 
-## Inspection Commands
+`po` shows what `CustomDebugStringConvertible` (`debugDescription`) returns.
+`p` shows the static type followed by the formatted value.
 
-### 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
+`v` understands subscripts and member paths:
 
 ```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
+(lldb) v invoices[0]
+(lldb) v self.store.selection
 ```
 
-## Breakpoint Patterns
+Default to `v`. Switch to `po` when you want the type's own description, and
+to `p` when you want to see the type as well.
 
-### File and Line
+## Registers and Raw Memory
 
 ```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
+(lldb) register read                 # every register
+(lldb) register read x0 x1           # two ARM64 argument registers
+(lldb) memory read 0x16fdfe2a0
+(lldb) memory read --size 1 --format x --count 32 0x16fdfe2a0   # 32 hex bytes
 ```
 
-### Function and Method Names
+## Breakpoint Recipes
 
 ```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
+(lldb) br set -f InvoiceStore.swift -l 57 -c "invoice.total < 0"
+(lldb) br set -f InvoiceStore.swift -l 57 --one-shot true     # removed after the first hit
+(lldb) br set -n "Billing.InvoiceStore.reload()"              # fully qualified Swift name
+(lldb) br set -r "Billing\..*\.deinit"                         # every deinit in a module
 ```
 
-### Breakpoint Actions
+Attach actions to a breakpoint:
 
 ```text
-(lldb) br set -n loadData
 (lldb) br command add 1
-> po "loadData called at \(Date())"
+> po "reload hit at \(Date())"
 > bt
 > continue
 > DONE
 ```
 
-### Logpoints (Auto-Continue Breakpoints)
+### Logpoints
+
+Print on every hit without stopping:
 
 ```text
-(lldb) br set -f File.swift -l 42
-(lldb) br modify 1 --auto-continue true
+(lldb) br set -f InvoiceStore.swift -l 57
+(lldb) breakpoint modify --auto-continue true 1
 (lldb) br command add 1
-> po "state = \(self.state)"
+> po invoice.number
 > 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.
+This is the command-line form of Xcode's "Log Message" action with
+"Automatically continue after evaluating actions" checked.
 
-### Listing and Managing
+### Housekeeping
 
 ```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)
+(lldb) br list
+(lldb) br enable 1
+(lldb) br modify --ignore-count 5 1    # skip the first five hits
+(lldb) br delete 1
+(lldb) br delete             # no id: deletes every breakpoint (asks first)
 ```
 
-## Expression Evaluation
+## Expressions
 
-### Swift Expressions
+Swift expressions can contain closures and several statements:
 
 ```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"
+(lldb) e invoices.filter { $0.isOverdue }.count
+(lldb) e let summary = store.summary(); print(summary)
+(lldb) expression -l swift -- import Foundation
+(lldb) expression -l swift -- self.navigationItem.title = "Debug"
 ```
 
-### Objective-C Expressions (for UIKit internals)
+Objective-C context is handy 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
+(lldb) expression -l objc -- (void)[[UIApplication sharedApplication] _performMemoryWarning]
+(lldb) expression -l objc -- (BOOL)[(id)0x10a3c4f00 isKindOfClass:[UIView class]]
+(lldb) expression -l objc -- (void)[0x10a3c4f00 recursiveDescription]
 ```
 
-### Modifying State at Runtime
+The first line calls a private method to simulate a memory warning; use it only
+while debugging. In Simulator, Debug > Simulate Memory Warning does the same.
+`recursiveDescription` prints the view tree under the given view.
+
+### Changing the UI while paused
 
 ```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
+(lldb) expression -l swift -- self.statusLabel.text = "Paid"
+(lldb) expression -l swift -- self.statusLabel.backgroundColor = UIColor.systemTeal
+(lldb) expression -l objc -- (void)[CATransaction flush]
 ```
 
-### Calling Functions
+### 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)
+(lldb) expression self.store.clearCache()
+(lldb) expression UserDefaults.standard.set(true, forKey: "showOnboarding")
+(lldb) expression NotificationCenter.default.post(name: .init("SessionExpired"), 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
+(lldb) w set v self.balance -w read_write      # reads and writes
+(lldb) w set e -- 0x600003d04f10               # raw address
 ```
 
-Hardware watchpoint limit on Apple Silicon: 4 watchpoints. Use them
-sparingly for tracking unexpected mutations.
+Apple Silicon offers four hardware watchpoints. Spend them carefully and delete
+the ones you no longer need.
 
-## Thread and Stack Navigation
+## Moving Through Threads and Frames
 
 ```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
+(lldb) bt 5                  # top five frames only
+(lldb) frame info            # where am I
+(lldb) frame variable        # every variable in this frame
+(lldb) up                    # one frame toward the caller
+(lldb) down                  # one frame back toward the callee
+(lldb) thread return         # leave the current function now
+(lldb) thread return false   # leave a Bool-returning function with false
 ```
 
-### 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.
+`thread return` skips the rest of a function. Use it to step past a line that
+would crash or to try the other branch of a decision without rebuilding.
 
 ## 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
+(lldb) memory read --size 4 --format x --count 8 0x600003d04f10   # eight 4-byte hex words
+(lldb) memory read -f s 0x600003d04f10             # a C string
+(lldb) memory find 0x600003d04000 0x600003d05000 -e "DEADBEEF"
+(lldb) image lookup -a 0x0000000104a1c3b8          # symbol at this address
+(lldb) image lookup -n InvoiceStore.reload         # address of this symbol
+(lldb) image list                                  # loaded images
 ```
 
-### Swift Metadata Inspection
+Inspecting Swift values at runtime:
 
 ```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 }
+(lldb) e print(type(of: store.current))
+(lldb) e dump(store.current)
+(lldb) e Mirror(reflecting: store.current).children.map { $0.label }
 ```
 
-## Custom Type Summaries
+## Type Summaries
 
-Add type summaries to `.lldbinit` for cleaner debugger output:
+Short summaries make `v` and `p` output easier to read. Put them in
+`~/.lldbinit`:
 
 ```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})"
+type summary add -s "(${var.latitude}, ${var.longitude})" CLLocationCoordinate2D
+type summary add -s "ref+${var._time}" Foundation.Date
+type summary add -s "#${var.number} ${var.total}" Billing.Invoice
 ```
 
+The `Date` line prints the raw seconds since the reference date
+(`timeIntervalSinceReferenceDate`); the stored field name can change between
+toolchains, so check it with `v -R` first.
+
 ## Python Scripting
 
-### Inline Python
+One-liners:
 
 ```text
 (lldb) script import os
 (lldb) script print(os.getpid())
-(lldb) script lldb.debugger.GetSelectedTarget().GetProcess().GetNumThreads()
+(lldb) script print(lldb.debugger.GetSelectedTarget().GetProcess().GetNumThreads())
 ```
 
-### Custom Python Command
-
-Create `~/lldb_commands/dump_views.py`:
+A custom command in `~/lldb_commands/window_tree.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 window_tree(debugger, command, result, internal_dict):
+    frame = (debugger.GetSelectedTarget()
+                     .GetProcess()
+                     .GetSelectedThread()
+                     .GetSelectedFrame())
+    options = lldb.SBExpressionOptions()
+    options.SetLanguage(lldb.eLanguageTypeObjC)
+    value = frame.EvaluateExpression(
+        "[[[UIApplication sharedApplication] keyWindow] recursiveDescription]",
+        options)
+    result.AppendMessage(value.GetObjectDescription() or "no key window")
 
 def __lldb_init_module(debugger, internal_dict):
     debugger.HandleCommand(
-        'command script add -f dump_views.dump_view_hierarchy dump_views'
-    )
+        "command script add -f window_tree.window_tree window_tree")
 ```
 
-Load in `.lldbinit`:
-
-```text
-command script import ~/lldb_commands/dump_views.py
-```
+Load it from `~/.lldbinit` with
+`command script import ~/lldb_commands/window_tree.py`, then type
+`window_tree`.
 
-Then use in LLDB:
+## Symbolic Breakpoints Worth Keeping
 
-```text
-(lldb) dump_views
-```
-
-## Useful Symbolic Breakpoints
-
-Set these in Xcode's Breakpoint Navigator for common debugging scenarios:
-
-| Symbol | Purpose |
-|--------|---------|
+| Symbol | Stops on |
+|--------|----------|
 | `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 |
+| `swift_willThrow` | Every Swift `throw` |
+| `malloc_error_break` | Heap corruption detected by malloc |
+| `_UITraitCollectionChangeObserverNotify` | Trait collection changes |
+| `objc_exception_throw` | Every Objective-C exception |
+| `-[UIApplication _performMemoryWarning]` | Simulated memory warnings |
 
-## LLDB Init File
+`NSInternalInconsistencyException` is an exception name, not a symbol, so a
+symbolic breakpoint on it never fires. Catch Foundation assertion failures with
+an exception breakpoint (`br set -E objc`, or Xcode's Exception Breakpoint) or
+with `objc_exception_throw`, then read the reason with `po $arg1`.
 
-Place commonly used configuration in `~/.lldbinit`:
+## `.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
+command alias -- swiftfound e -l swift -- import Foundation
+command alias pjson expression -l swift -- print(String(decoding: try! JSONSerialization.data(withJSONObject: %1, options: [.prettyPrinted, .sortedKeys]), as: UTF8.self))
+type summary add -x "^.*RawRepresentable$" -s "${var.rawValue}"
 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"
+settings set frame-format "#${frame.index} ${function.name}{ @ ${line.file.basename}:${line.number}}\n"
 ```
+
+- `command alias` gives a long command a short name.
+- `pjson` pretty-prints any JSON-compatible object passed as its argument
+  through `JSONSerialization` with `.prettyPrinted`; `%1` is the argument.
+- The `-x` flag makes the summary apply to every type whose name matches the
+  regex.
+- `frame-format` controls how each frame line looks in `bt` and when stepping.