1# Debugger
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- Custom: Allows you to configure any debug adapter that supports the Debug Adapter Protocol, enabling debugging for additional languages or specialized environments not natively supported by Zed.
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## How To Get Started
30
31To start a debug session, we added few default debug configurations for each supported language that supports generic configuration options. To see all the available debug configurations, you can use the command palette `debugger: start` action, this should list all the available debug configurations.
32
33### Configuration
34
35To create a custom debug configuration you have to create a `.zed/debug.json` file in your project root directory. This file should contain an array of debug configurations, each with a unique label and adapter the other option are optional/required based on the adapter.
36
37```json
38[
39 {
40 // The label for the debug configuration and used to identify the debug session inside the debug panel
41 "label": "Example Start debugger config",
42 // The debug adapter that Zed should use to debug the program
43 "adapter": "custom",
44 // Request: defaults to launch
45 // - launch: Zed will launch the program if specified or shows a debug terminal with the right configuration
46 // - 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)
47 "request": "launch",
48 // cwd: defaults to the current working directory of your project ($ZED_WORKTREE_ROOT)
49 // this field also supports task variables e.g. $ZED_WORKTREE_ROOT
50 "cwd": "$ZED_WORKTREE_ROOT",
51 // program: The program that you want to debug
52 // this fields also support task variables e.g. $ZED_FILE
53 // Note: this field should only contain the path to the program you want to debug
54 "program": "path_to_program",
55 // initialize_args: This field should contain all the adapter specific initialization arguments that are directly send to the debug adapter
56 "initialize_args": {
57 // "stopOnEntry": true // e.g. to stop on the first line of the program (These args are DAP specific)
58 },
59 // connection: the connection that a custom debugger should use
60 "connection": "stdio",
61 // The cli command used to start the debug adapter e.g. `python3`, `node` or the adapter binary
62 "command": "path_to_cli"
63 }
64]
65```
66
67### Using Attach [WIP]
68
69Only javascript and lldb supports starting a debug session using attach.
70
71When using the attach request with a process ID the syntax is as follows:
72
73```json
74{
75 "label": "Attach to Process",
76 "adapter": "javascript",
77 "request": {
78 "attach": {
79 "process_id": "12345"
80 }
81 }
82}
83```
84
85Without process ID the syntax is as follows:
86
87```json
88{
89 "label": "Attach to Process",
90 "adapter": "javascript",
91 "request": {
92 "attach": {}
93 }
94}
95```
96
97#### JavaScript Configuration
98
99##### Debug Active File
100
101This configuration allows you to debug a JavaScript file in your project.
102
103```json
104{
105 "label": "JavaScript: Debug Active File",
106 "adapter": "javascript",
107 "program": "$ZED_FILE",
108 "request": "launch",
109 "cwd": "$ZED_WORKTREE_ROOT"
110}
111```
112
113##### Debug Terminal
114
115This configuration will spawn a debug terminal where you could start you program by typing `node test.js`, and the debug adapter will automatically attach to the process.
116
117```json
118{
119 "label": "JavaScript: Debug Terminal",
120 "adapter": "javascript",
121 "request": "launch",
122 "cwd": "$ZED_WORKTREE_ROOT",
123 // "program": "$ZED_FILE", // optional if you pass this in, you will see the output inside the terminal itself
124 "initialize_args": {
125 "console": "integratedTerminal"
126 }
127}
128```
129
130#### PHP Configuration
131
132##### Debug Active File
133
134This configuration allows you to debug a PHP file in your project.
135
136```json
137{
138 "label": "PHP: Debug Active File",
139 "adapter": "php",
140 "program": "$ZED_FILE",
141 "request": "launch",
142 "cwd": "$ZED_WORKTREE_ROOT"
143}
144```
145
146#### Python Configuration
147
148##### Debug Active File
149
150This configuration allows you to debug a Python file in your project.
151
152```json
153{
154 "label": "Python: Debug Active File",
155 "adapter": "python",
156 "program": "$ZED_FILE",
157 "request": "launch",
158 "cwd": "$ZED_WORKTREE_ROOT"
159}
160```
161
162#### GDB Configuration
163
164**NOTE:** This configuration is for Linux systems only & intel macbooks.
165
166##### Debug Program
167
168This configuration allows you to debug a program using GDB e.g. Zed itself.
169
170```json
171{
172 "label": "GDB: Debug program",
173 "adapter": "gdb",
174 "program": "$ZED_WORKTREE_ROOT/target/debug/zed",
175 "request": "launch",
176 "cwd": "$ZED_WORKTREE_ROOT"
177}
178```
179
180#### LLDB Configuration
181
182##### Debug Program
183
184This configuration allows you to debug a program using LLDB e.g. Zed itself.
185
186```json
187{
188 "label": "LLDB: Debug program",
189 "adapter": "lldb",
190 "program": "$ZED_WORKTREE_ROOT/target/debug/zed",
191 "request": "launch",
192 "cwd": "$ZED_WORKTREE_ROOT"
193}
194```
195
196## Breakpoints
197
198Zed currently supports these types of breakpoints
199
200- Log Breakpoints: Output a log message instead of stopping at the breakpoint when it's hit
201- Standard Breakpoints: Stop at the breakpoint when it's hit
202
203Standard breakpoints can be toggled by left clicking on the editor gutter or using the Toggle Breakpoint action. Right clicking on a breakpoint, code action symbol, or code runner symbol brings up the breakpoint context menu. That has options for toggling breakpoints and editing log breakpoints.
204
205Log breakpoints can also be edited/added through the edit log breakpoint action
206
207## Settings
208
209- `stepping_granularity`: Determines the stepping granularity.
210- `save_breakpoints`: Whether the breakpoints should be reused across Zed sessions.
211- `button`: Whether to show the debug button in the status bar.
212- `timeout`: Time in milliseconds until timeout error when connecting to a TCP debug adapter.
213- `log_dap_communications`: Whether to log messages between active debug adapters and Zed
214- `format_dap_log_messages`: Whether to format dap messages in when adding them to debug adapter logger
215
216### Stepping granularity
217
218- Description: The Step granularity that the debugger will use
219- Default: line
220- Setting: debugger.stepping_granularity
221
222**Options**
223
2241. Statement - The step should allow the program to run until the current statement has finished executing.
225 The meaning of a statement is determined by the adapter and it may be considered equivalent to a line.
226 For example 'for(int i = 0; i < 10; i++)' could be considered to have 3 statements 'int i = 0', 'i < 10', and 'i++'.
227
228```json
229{
230 "debugger": {
231 "stepping_granularity": "statement"
232 }
233}
234```
235
2362. Line - The step should allow the program to run until the current source line has executed.
237
238```json
239{
240 "debugger": {
241 "stepping_granularity": "line"
242 }
243}
244```
245
2463. Instruction - The step should allow one instruction to execute (e.g. one x86 instruction).
247
248```json
249{
250 "debugger": {
251 "stepping_granularity": "instruction"
252 }
253}
254```
255
256### Save Breakpoints
257
258- Description: Whether the breakpoints should be saved across Zed sessions.
259- Default: true
260- Setting: debugger.save_breakpoints
261
262**Options**
263
264`boolean` values
265
266```json
267{
268 "debugger": {
269 "save_breakpoints": true
270 }
271}
272```
273
274### Button
275
276- Description: Whether the button should be displayed in the debugger toolbar.
277- Default: true
278- Setting: debugger.show_button
279
280**Options**
281
282`boolean` values
283
284```json
285{
286 "debugger": {
287 "show_button": true
288 }
289}
290```
291
292### Timeout
293
294- Description: Time in milliseconds until timeout error when connecting to a TCP debug adapter.
295- Default: 2000ms
296- Setting: debugger.timeout
297
298**Options**
299
300`integer` values
301
302```json
303{
304 "debugger": {
305 "timeout": 3000
306 }
307}
308```
309
310### Log Dap Communications
311
312- Description: Whether to log messages between active debug adapters and Zed. (Used for DAP development)
313- Default: false
314- Setting: debugger.log_dap_communications
315
316**Options**
317
318`boolean` values
319
320```json
321{
322 "debugger": {
323 "log_dap_communications": true
324 }
325}
326```
327
328### Format Dap Log Messages
329
330- Description: Whether to format dap messages in when adding them to debug adapter logger. (Used for DAP development)
331- Default: false
332- Setting: debugger.format_dap_log_messages
333
334**Options**
335
336`boolean` values
337
338```json
339{
340 "debugger": {
341 "format_dap_log_messages": true
342 }
343}
344```
345
346## Theme
347
348The Debugger supports the following theme options
349
350 /// Color used to accent some of the debuggers elements
351 /// Only accent breakpoint & breakpoint related symbols right now
352
353**debugger.accent**: Color used to accent breakpoint & breakpoint related symbols
354**editor.debugger_active_line.background**: Background color of active debug line