1# Debugger (Beta)
2
3Zed uses the Debug Adapter Protocol (DAP) to provide debugging functionality across multiple programming languages.
4DAP is a standardized protocol that defines how debuggers, editors, and IDEs communicate with each other.
5It allows Zed to support various debuggers without needing to implement language-specific debugging logic.
6This protocol enables features like setting breakpoints, stepping through code, inspecting variables,
7and more, in a consistent manner across different programming languages and runtime environments.
8
9## Supported Debug Adapters
10
11Zed supports a variety of debug adapters for different programming languages:
12
13- JavaScript (node): Enables debugging of Node.js applications, including setting breakpoints, stepping through code, and inspecting variables in JavaScript.
14
15- Python (debugpy): Provides debugging capabilities for Python applications, supporting features like remote debugging, multi-threaded debugging, and Django/Flask application debugging.
16
17- LLDB: A powerful debugger for C, C++, Objective-C, and Swift, offering low-level debugging features and support for Apple platforms.
18
19- GDB: The GNU Debugger, which supports debugging for multiple programming languages including C, C++, Go, and Rust, across various platforms.
20
21- Go (dlv): Delve, a debugger for the Go programming language, offering both local and remote debugging capabilities with full support for Go's runtime and standard library.
22
23- PHP (xdebug): Provides debugging and profiling capabilities for PHP applications, including remote debugging and code coverage analysis.
24
25- Ruby (rdbg): Provides debugging capabilities for Ruby applications
26
27These adapters enable Zed to provide a consistent debugging experience across multiple languages while leveraging the specific features and capabilities of each debugger.
28
29## Getting Started
30
31For basic debugging, you can set up a new configuration by opening the `New Session Modal` either via the `debugger: start` (default: f4) or by clicking the plus icon at the top right of the debug panel.
32
33For more advanced use cases, you can create debug configurations by directly editing the `.zed/debug.json` file in your project root directory.
34
35You can then use the `New Session Modal` to select a configuration and start debugging.
36
37### Configuration
38
39While configuration fields are debug adapter-dependent, most adapters support the following fields:
40
41```json
42[
43 {
44 // The label for the debug configuration and used to identify the debug session inside the debug panel & new session modal
45 "label": "Example Start debugger config",
46 // The debug adapter that Zed should use to debug the program
47 "adapter": "Example adapter name",
48 // Request:
49 // - launch: Zed will launch the program if specified or shows a debug terminal with the right configuration
50 // - attach: Zed will attach to a running program to debug it or when the process_id is not specified we will show a process picker (only supported for node currently)
51 "request": "launch",
52 // program: The program that you want to debug
53 // This field supports path resolution with ~ or . symbols
54 "program": "path_to_program",
55 // cwd: defaults to the current working directory of your project ($ZED_WORKTREE_ROOT)
56 "cwd": "$ZED_WORKTREE_ROOT"
57 }
58]
59```
60
61#### Tasks
62
63All configuration fields support task variables. See [Tasks Variables](./tasks.md#variables)
64
65Zed also allows embedding a task that is run before the debugger starts. This is useful for setting up the environment or running any necessary setup steps before the debugger starts.
66
67See an example [here](#build-binary-then-debug)
68
69#### Python Examples
70
71##### Python Active File
72
73```json
74[
75 {
76 "label": "Active File",
77 "adapter": "Debugpy",
78 "program": "$ZED_FILE",
79 "request": "launch"
80 }
81]
82```
83
84##### Flask App
85
86For a common Flask Application with a file structure similar to the following:
87
88- .venv/
89- app/
90 - **init**.py
91 - **main**.py
92 - routes.py
93- templates/
94 - index.html
95- static/
96 - style.css
97- requirements.txt
98
99```json
100[
101 {
102 "label": "Python: Flask",
103 "adapter": "Debugpy",
104 "request": "launch",
105 "module": "app",
106 "cwd": "$ZED_WORKTREE_ROOT",
107 "env": {
108 "FLASK_APP": "app",
109 "FLASK_DEBUG": "1"
110 },
111 "args": [
112 "run",
113 "--reload", // Enables Flask reloader that watches for file changes
114 "--debugger" // Enables Flask debugger
115 ],
116 "autoReload": {
117 "enable": true
118 },
119 "jinja": true,
120 "justMyCode": true
121 }
122]
123```
124
125#### Rust/C++/C
126
127##### Using pre-built binary
128
129```json
130[
131 {
132 "label": "Debug native binary",
133 "program": "$ZED_WORKTREE_ROOT/build/binary",
134 "request": "launch",
135 "adapter": "CodeLLDB" // GDB is available on non arm macs as well as linux
136 }
137]
138```
139
140##### Build binary then debug
141
142```json
143[
144 {
145 "label": "Build & Debug native binary",
146 "build": {
147 "command": "cargo",
148 "args": ["build"]
149 },
150 "program": "$ZED_WORKTREE_ROOT/target/debug/binary",
151 "request": "launch",
152 "adapter": "CodeLLDB" // GDB is available on non arm macs as well as linux
153 }
154]
155```
156
157## Breakpoints
158
159To set a breakpoint, simply click next to the line number in the editor gutter.
160Breakpoints can be tweaked depending on your needs; to access additional options of a given breakpoint, right-click on the breakpoint icon in the gutter and select the desired option.
161At present, you can:
162
163- Standard Breakpoints: Stop at the breakpoint when it's hit
164- Log Breakpoints: Output a log message instead of stopping at the breakpoint when it's hit
165- Conditional Breakpoints: Stop at the breakpoint when it's hit if the condition is met
166- Hit Breakpoints: Stop at the breakpoint when it's hit a certain number of times
167
168Standard breakpoints can be toggled by left-clicking on the editor gutter or using the Toggle Breakpoint action. Right-clicking on a breakpoint or on a code runner symbol brings up the breakpoint context menu. This has options for toggling breakpoints and editing log breakpoints.
169
170Other kinds of breakpoints can be toggled/edited by right-clicking on the breakpoint icon in the gutter and selecting the desired option.
171
172## Settings
173
174- `stepping_granularity`: Determines the stepping granularity.
175- `save_breakpoints`: Whether the breakpoints should be reused across Zed sessions.
176- `button`: Whether to show the debug button in the status bar.
177- `timeout`: Time in milliseconds until timeout error when connecting to a TCP debug adapter.
178- `log_dap_communications`: Whether to log messages between active debug adapters and Zed.
179- `format_dap_log_messages`: Whether to format DAP messages when adding them to the debug adapter logger.
180
181### Stepping granularity
182
183- Description: The Step granularity that the debugger will use
184- Default: line
185- Setting: debugger.stepping_granularity
186
187**Options**
188
1891. Statement - The step should allow the program to run until the current statement has finished executing.
190 The meaning of a statement is determined by the adapter and it may be considered equivalent to a line.
191 For example 'for(int i = 0; i < 10; i++)' could be considered to have 3 statements 'int i = 0', 'i < 10', and 'i++'.
192
193```json
194{
195 "debugger": {
196 "stepping_granularity": "statement"
197 }
198}
199```
200
2012. Line - The step should allow the program to run until the current source line has executed.
202
203```json
204{
205 "debugger": {
206 "stepping_granularity": "line"
207 }
208}
209```
210
2113. Instruction - The step should allow one instruction to execute (e.g. one x86 instruction).
212
213```json
214{
215 "debugger": {
216 "stepping_granularity": "instruction"
217 }
218}
219```
220
221### Save Breakpoints
222
223- Description: Whether the breakpoints should be saved across Zed sessions.
224- Default: true
225- Setting: debugger.save_breakpoints
226
227**Options**
228
229`boolean` values
230
231```json
232{
233 "debugger": {
234 "save_breakpoints": true
235 }
236}
237```
238
239### Button
240
241- Description: Whether the button should be displayed in the debugger toolbar.
242- Default: true
243- Setting: debugger.show_button
244
245**Options**
246
247`boolean` values
248
249```json
250{
251 "debugger": {
252 "show_button": true
253 }
254}
255```
256
257### Timeout
258
259- Description: Time in milliseconds until timeout error when connecting to a TCP debug adapter.
260- Default: 2000
261- Setting: debugger.timeout
262
263**Options**
264
265`integer` values
266
267```json
268{
269 "debugger": {
270 "timeout": 3000
271 }
272}
273```
274
275### Log Dap Communications
276
277- Description: Whether to log messages between active debug adapters and Zed. (Used for DAP development)
278- Default: false
279- Setting: debugger.log_dap_communications
280
281**Options**
282
283`boolean` values
284
285```json
286{
287 "debugger": {
288 "log_dap_communications": true
289 }
290}
291```
292
293### Format Dap Log Messages
294
295- Description: Whether to format DAP messages when adding them to the debug adapter logger. (Used for DAP development)
296- Default: false
297- Setting: debugger.format_dap_log_messages
298
299**Options**
300
301`boolean` values
302
303```json
304{
305 "debugger": {
306 "format_dap_log_messages": true
307 }
308}
309```
310
311## Theme
312
313The Debugger supports the following theme options:
314
315**debugger.accent**: Color used to accent breakpoint & breakpoint-related symbols
316**editor.debugger_active_line.background**: Background color of active debug line