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
159Zed currently supports these types of breakpoints:
160
161- Standard Breakpoints: Stop at the breakpoint when it's hit
162- Log Breakpoints: Output a log message instead of stopping at the breakpoint when it's hit
163- Conditional Breakpoints: Stop at the breakpoint when it's hit if the condition is met
164- Hit Breakpoints: Stop at the breakpoint when it's hit a certain number of times
165
166Standard 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.
167
168Other kinds of breakpoints can be toggled/edited by right-clicking on the breakpoint icon in the gutter and selecting the desired option.
169
170## Settings
171
172- `stepping_granularity`: Determines the stepping granularity.
173- `save_breakpoints`: Whether the breakpoints should be reused across Zed sessions.
174- `button`: Whether to show the debug button in the status bar.
175- `timeout`: Time in milliseconds until timeout error when connecting to a TCP debug adapter.
176- `log_dap_communications`: Whether to log messages between active debug adapters and Zed.
177- `format_dap_log_messages`: Whether to format DAP messages when adding them to the debug adapter logger.
178
179### Stepping granularity
180
181- Description: The Step granularity that the debugger will use
182- Default: line
183- Setting: debugger.stepping_granularity
184
185**Options**
186
1871. Statement - The step should allow the program to run until the current statement has finished executing.
188 The meaning of a statement is determined by the adapter and it may be considered equivalent to a line.
189 For example 'for(int i = 0; i < 10; i++)' could be considered to have 3 statements 'int i = 0', 'i < 10', and 'i++'.
190
191```json
192{
193 "debugger": {
194 "stepping_granularity": "statement"
195 }
196}
197```
198
1992. Line - The step should allow the program to run until the current source line has executed.
200
201```json
202{
203 "debugger": {
204 "stepping_granularity": "line"
205 }
206}
207```
208
2093. Instruction - The step should allow one instruction to execute (e.g. one x86 instruction).
210
211```json
212{
213 "debugger": {
214 "stepping_granularity": "instruction"
215 }
216}
217```
218
219### Save Breakpoints
220
221- Description: Whether the breakpoints should be saved across Zed sessions.
222- Default: true
223- Setting: debugger.save_breakpoints
224
225**Options**
226
227`boolean` values
228
229```json
230{
231 "debugger": {
232 "save_breakpoints": true
233 }
234}
235```
236
237### Button
238
239- Description: Whether the button should be displayed in the debugger toolbar.
240- Default: true
241- Setting: debugger.show_button
242
243**Options**
244
245`boolean` values
246
247```json
248{
249 "debugger": {
250 "show_button": true
251 }
252}
253```
254
255### Timeout
256
257- Description: Time in milliseconds until timeout error when connecting to a TCP debug adapter.
258- Default: 2000
259- Setting: debugger.timeout
260
261**Options**
262
263`integer` values
264
265```json
266{
267 "debugger": {
268 "timeout": 3000
269 }
270}
271```
272
273### Log Dap Communications
274
275- Description: Whether to log messages between active debug adapters and Zed. (Used for DAP development)
276- Default: false
277- Setting: debugger.log_dap_communications
278
279**Options**
280
281`boolean` values
282
283```json
284{
285 "debugger": {
286 "log_dap_communications": true
287 }
288}
289```
290
291### Format Dap Log Messages
292
293- Description: Whether to format DAP messages when adding them to the debug adapter logger. (Used for DAP development)
294- Default: false
295- Setting: debugger.format_dap_log_messages
296
297**Options**
298
299`boolean` values
300
301```json
302{
303 "debugger": {
304 "format_dap_log_messages": true
305 }
306}
307```
308
309## Theme
310
311The Debugger supports the following theme options:
312
313**debugger.accent**: Color used to accent breakpoint & breakpoint-related symbols
314**editor.debugger_active_line.background**: Background color of active debug line