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 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 then 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#### 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 or on a code runner symbol brings up the breakpoint context menu. This 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 debugger's elements
222    /// Only accents 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