debugging-instruments

Name: debugging-instruments
Author: dpearson2699

915stars45forks

How to install debugging-instruments?

dpearson2699/swift-ios-skills/debugging-instruments

$npx -y skills add dpearson2699/swift-ios-skills --skill debugging-instruments

Installs into the current project.

Summary

Debug 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, leak

Files · 1

View on GitHub

SKILL.md

1	# Debugging and Instruments
2
3	Keep interactive graph and Instruments triage here. Route detailed `.memgraph`
4	command-line ownership/growth analysis and ETTrace work to their focused skills.
5
6	## Contents
7
8	- [LLDB Debugging](#lldb-debugging)
9	- [Memory Debugging](#memory-debugging)
10	- [Hang Diagnostics](#hang-diagnostics)
11	- [Build Failure Triage](#build-failure-triage)
12	- [Instruments Overview](#instruments-overview)
13	- [Common Mistakes](#common-mistakes)
14	- [Review Checklist](#review-checklist)
15	- [References](#references)
16
17	## LLDB Debugging
18
19	Start with a small, repeatable workflow:
20
21	1. Reproduce in a Debug build and stop at the narrowest useful breakpoint.
22	2. Inspect locals without executing code, then capture the current stack.
23	3. Move to the relevant frame or thread and verify the failing state.
24	4. Add a condition or watchpoint only when the bad transition is still unclear.
25
26	```text
27	(lldb) br set -f ViewModel.swift -l 42 # Stop at file and line
28	(lldb) v myLocal # Inspect without executing code
29	(lldb) po myObject # Use debugDescription when needed
30	(lldb) bt all # Capture every thread's backtrace
31	(lldb) frame select 3 # Inspect a relevant frame
32	(lldb) br modify 1 -c "count > 10" # Narrow a noisy breakpoint
33	(lldb) w set v self.score # Stop on an unexpected write
34	```
35
36	Use `v` over `po` when you only need a local variable value — it does not
37	execute code and cannot trigger side effects. Expression evaluation can execute
38	or mutate program state, and hardware watchpoints are scarce, so use both
39	deliberately.
40
41	Load [references/lldb-patterns.md](references/lldb-patterns.md) for the complete
42	inspection, breakpoint/logpoint, expression, watchpoint, thread navigation, and
43	symbolic-breakpoint command tables.
44
45	## Memory Debugging
46
47	### Memory Graph Debugger Workflow
48
49	1. Run the app in Debug configuration.
50	2. Reproduce the suspected leak (navigate to a screen, then back).
51	3. Tap the Memory Graph button in Xcode's debug bar.
52	4. Look for purple warning icons — these indicate leaked objects.
53	5. Select a leaked object to see its reference graph and backtrace.
54
55	Enable Malloc Stack Logging (Scheme > Diagnostics) before running so
56	the Memory Graph shows allocation backtraces.
57
58	### Common Retain Cycle Patterns
59
60	Closure capturing self strongly:
61
62	```swift
63	// LEAK — closure holds strong reference to self
64	class ProfileViewModel {
65	var onUpdate: (() -> Void)?
66
67	func startObserving() {
68	onUpdate = {
69	self.refresh() // strong capture of self
70	}
71	}
72	}
73
74	// FIXED — use [weak self]
75	func startObserving() {
76	onUpdate = { [weak self] in
77	self?.refresh()
78	}
79	}
80	```
81
82	Strong delegate reference:
83
84	```swift
85	// LEAK — strong delegate creates a cycle
86	protocol DataDelegate: AnyObject {
87	func didUpdate()
88	}
89
90	class DataManager {
91	var delegate: DataDelegate? // should be weak
92	}
93
94	// FIXED — weak delegate
95	class DataManager {
96	weak var delegate: DataDelegate?
97	}
98	```
99
100	Timer retaining target:
101
102	```swift
103	// LEAK — Timer.scheduledTimer retains its target
104	timer = Timer.scheduledTimer(
105	timeInterval: 1.0, target: self,
106	selector: #selector(tick), userInfo: nil, repeats: true
107	)
108
109	// FIXED — use closure-based API with [weak self]
110	timer = Timer.scheduledTimer(withTimeInterval: 1.0, repeats: true) { [weak self] _ in
111	self?.tick()
112	}
113	```
114
115	### Instruments: Allocations and Leaks
116
117	- Allocations template: Track memory growth over time. Use the
118	"Mark Generation" feature to isolate allocations created between
119	user actions (e.g., open/close a screen).
120	- Leaks template: Detects leaked allocations, including isolated retain
121	cycles the process can no longer reach. Run alongside Allocations for a
122	complete picture.
123	- Filter by your app's module name to exclude system allocations.
124
125	For leak or memory-growth triage, pair the tools: use Allocations **Mark
126	Generation** before and after the reproduction step to prove retained growth,
127	then use Memory Graph Debugger to inspect object ownership and Malloc Stack
128	Logging to recover allocation call stacks.
129
130	### Malloc Stack Logging
131
132	Enable in Scheme > Run > Diagnostics > Malloc Stack Logging. This records
133	allocation backtraces so the Memory Graph Debugger, Allocations instrument,
134	and exported `.memgraph` files can show where objects were created.
135
136	```bash
137	# Inspect an exported memory graph from Xcode or Instruments
138	leaks MyApp.memgraph
139	```
140
141	## Hang Diagnostics
142
143	### Identifying Main Thread Hangs

People who liked this also viewed

6 picks

Type

debugging-instruments

915stars45forks

View on GitHub

How to install debugging-instruments?

dpearson2699/swift-ios-skills/debugging-instruments

$npx -y skills add dpearson2699/swift-ios-skills --skill debugging-instruments

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Debugging and Instruments
2
3	Keep interactive graph and Instruments triage here. Route detailed `.memgraph`
4	command-line ownership/growth analysis and ETTrace work to their focused skills.
5
6	## Contents
7
8	- [LLDB Debugging](#lldb-debugging)
9	- [Memory Debugging](#memory-debugging)
10	- [Hang Diagnostics](#hang-diagnostics)
11	- [Build Failure Triage](#build-failure-triage)
12	- [Instruments Overview](#instruments-overview)
13	- [Common Mistakes](#common-mistakes)
14	- [Review Checklist](#review-checklist)
15	- [References](#references)
16
17	## LLDB Debugging
18
19	Start with a small, repeatable workflow:
20
21	1. Reproduce in a Debug build and stop at the narrowest useful breakpoint.
22	2. Inspect locals without executing code, then capture the current stack.
23	3. Move to the relevant frame or thread and verify the failing state.
24	4. Add a condition or watchpoint only when the bad transition is still unclear.
25
26	```text
27	(lldb) br set -f ViewModel.swift -l 42 # Stop at file and line
28	(lldb) v myLocal # Inspect without executing code
29	(lldb) po myObject # Use debugDescription when needed
30	(lldb) bt all # Capture every thread's backtrace
31	(lldb) frame select 3 # Inspect a relevant frame
32	(lldb) br modify 1 -c "count > 10" # Narrow a noisy breakpoint
33	(lldb) w set v self.score # Stop on an unexpected write
34	```
35
36	Use `v` over `po` when you only need a local variable value — it does not
37	execute code and cannot trigger side effects. Expression evaluation can execute
38	or mutate program state, and hardware watchpoints are scarce, so use both
39	deliberately.
40
41	Load [references/lldb-patterns.md](references/lldb-patterns.md) for the complete
42	inspection, breakpoint/logpoint, expression, watchpoint, thread navigation, and
43	symbolic-breakpoint command tables.
44
45	## Memory Debugging
46
47	### Memory Graph Debugger Workflow
48
49	1. Run the app in Debug configuration.
50	2. Reproduce the suspected leak (navigate to a screen, then back).
51	3. Tap the Memory Graph button in Xcode's debug bar.
52	4. Look for purple warning icons — these indicate leaked objects.
53	5. Select a leaked object to see its reference graph and backtrace.
54
55	Enable Malloc Stack Logging (Scheme > Diagnostics) before running so
56	the Memory Graph shows allocation backtraces.
57
58	### Common Retain Cycle Patterns
59
60	Closure capturing self strongly:
61
62	```swift
63	// LEAK — closure holds strong reference to self
64	class ProfileViewModel {
65	var onUpdate: (() -> Void)?
66
67	func startObserving() {
68	onUpdate = {
69	self.refresh() // strong capture of self
70	}
71	}
72	}
73
74	// FIXED — use [weak self]
75	func startObserving() {
76	onUpdate = { [weak self] in
77	self?.refresh()
78	}
79	}
80	```
81
82	Strong delegate reference:
83
84	```swift
85	// LEAK — strong delegate creates a cycle
86	protocol DataDelegate: AnyObject {
87	func didUpdate()
88	}
89
90	class DataManager {
91	var delegate: DataDelegate? // should be weak
92	}
93
94	// FIXED — weak delegate
95	class DataManager {
96	weak var delegate: DataDelegate?
97	}
98	```
99
100	Timer retaining target:
101
102	```swift
103	// LEAK — Timer.scheduledTimer retains its target
104	timer = Timer.scheduledTimer(
105	timeInterval: 1.0, target: self,
106	selector: #selector(tick), userInfo: nil, repeats: true
107	)
108
109	// FIXED — use closure-based API with [weak self]
110	timer = Timer.scheduledTimer(withTimeInterval: 1.0, repeats: true) { [weak self] _ in
111	self?.tick()
112	}
113	```
114
115	### Instruments: Allocations and Leaks
116
117	- Allocations template: Track memory growth over time. Use the
118	"Mark Generation" feature to isolate allocations created between
119	user actions (e.g., open/close a screen).
120	- Leaks template: Detects leaked allocations, including isolated retain
121	cycles the process can no longer reach. Run alongside Allocations for a
122	complete picture.
123	- Filter by your app's module name to exclude system allocations.
124
125	For leak or memory-growth triage, pair the tools: use Allocations **Mark
126	Generation** before and after the reproduction step to prove retained growth,
127	then use Memory Graph Debugger to inspect object ownership and Malloc Stack
128	Logging to recover allocation call stacks.
129
130	### Malloc Stack Logging
131
132	Enable in Scheme > Run > Diagnostics > Malloc Stack Logging. This records
133	allocation backtraces so the Memory Graph Debugger, Allocations instrument,
134	and exported `.memgraph` files can show where objects were created.
135
136	```bash
137	# Inspect an exported memory graph from Xcode or Instruments
138	leaks MyApp.memgraph
139	```
140
141	## Hang Diagnostics
142
143	### Identifying Main Thread Hangs

People who liked this also viewed

6 picks

Type