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 up the `New Session Modal` either by the `debugger: start` (default: f4) or clicking the plus icon at the top right of the debug panel. Once the `New Session Modal` is open you can click custom on the bottom left to open a view that allows you to create a custom debug configuration. Once you have created a configuration you can save it to your workspace's `.zed/debug.json` by clicking on the save button on the bottom left.
32
33For more advance use cases you can create debug configurations by directly editing the `.zed/debug.json` file in your project root directory. Once you fill out the adapter and label fields completions will show you the available options of the selected debug adapter.
34
35You can then use the `New Session Modal` to select a configuration then start debugging.
36
37### Configuration
38
39While configuration fields are debug adapter dependent, most adapters support the follow 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#### Task Variables
62
63All configuration fields support task variables. See [Tasks](./tasks.md)
64
65## Breakpoints
66
67Zed currently supports these types of breakpoints
68
69- Standard Breakpoints: Stop at the breakpoint when it's hit
70- Log Breakpoints: Output a log message instead of stopping at the breakpoint when it's hit
71- Conditional Breakpoints: Stop at the breakpoint when it's hit if the condition is met
72- Hit Breakpoints: Stop at the breakpoint when it's hit a certain number of times
73
74Standard breakpoints can be toggled by left clicking on the editor gutter or using the Toggle Breakpoint action. Right clicking on a breakpoint, right clicking on a code runner symbol brings up the breakpoint context menu. That has options for toggling breakpoints and editing log breakpoints.
75
76Other kinds of breakpoints can be toggled/edited by right clicking on the breakpoint icon in the gutter and selecting the desired option.
77
78## Settings
79
80- `stepping_granularity`: Determines the stepping granularity.
81- `save_breakpoints`: Whether the breakpoints should be reused across Zed sessions.
82- `button`: Whether to show the debug button in the status bar.
83- `timeout`: Time in milliseconds until timeout error when connecting to a TCP debug adapter.
84- `log_dap_communications`: Whether to log messages between active debug adapters and Zed
85- `format_dap_log_messages`: Whether to format dap messages in when adding them to debug adapter logger
86
87### Stepping granularity
88
89- Description: The Step granularity that the debugger will use
90- Default: line
91- Setting: debugger.stepping_granularity
92
93**Options**
94
951. Statement - The step should allow the program to run until the current statement has finished executing.
96 The meaning of a statement is determined by the adapter and it may be considered equivalent to a line.
97 For example 'for(int i = 0; i < 10; i++)' could be considered to have 3 statements 'int i = 0', 'i < 10', and 'i++'.
98
99```json
100{
101 "debugger": {
102 "stepping_granularity": "statement"
103 }
104}
105```
106
1072. Line - The step should allow the program to run until the current source line has executed.
108
109```json
110{
111 "debugger": {
112 "stepping_granularity": "line"
113 }
114}
115```
116
1173. Instruction - The step should allow one instruction to execute (e.g. one x86 instruction).
118
119```json
120{
121 "debugger": {
122 "stepping_granularity": "instruction"
123 }
124}
125```
126
127### Save Breakpoints
128
129- Description: Whether the breakpoints should be saved across Zed sessions.
130- Default: true
131- Setting: debugger.save_breakpoints
132
133**Options**
134
135`boolean` values
136
137```json
138{
139 "debugger": {
140 "save_breakpoints": true
141 }
142}
143```
144
145### Button
146
147- Description: Whether the button should be displayed in the debugger toolbar.
148- Default: true
149- Setting: debugger.show_button
150
151**Options**
152
153`boolean` values
154
155```json
156{
157 "debugger": {
158 "show_button": true
159 }
160}
161```
162
163### Timeout
164
165- Description: Time in milliseconds until timeout error when connecting to a TCP debug adapter.
166- Default: 2000ms
167- Setting: debugger.timeout
168
169**Options**
170
171`integer` values
172
173```json
174{
175 "debugger": {
176 "timeout": 3000
177 }
178}
179```
180
181### Log Dap Communications
182
183- Description: Whether to log messages between active debug adapters and Zed. (Used for DAP development)
184- Default: false
185- Setting: debugger.log_dap_communications
186
187**Options**
188
189`boolean` values
190
191```json
192{
193 "debugger": {
194 "log_dap_communications": true
195 }
196}
197```
198
199### Format Dap Log Messages
200
201- Description: Whether to format dap messages in when adding them to debug adapter logger. (Used for DAP development)
202- Default: false
203- Setting: debugger.format_dap_log_messages
204
205**Options**
206
207`boolean` values
208
209```json
210{
211 "debugger": {
212 "format_dap_log_messages": true
213 }
214}
215```
216
217## Theme
218
219The Debugger supports the following theme options
220
221 /// Color used to accent some of the debuggers elements
222 /// Only accent breakpoint & breakpoint related symbols right now
223
224**debugger.accent**: Color used to accent breakpoint & breakpoint related symbols
225**editor.debugger_active_line.background**: Background color of active debug line