1# Debugger
  2
  3Zed uses the [Debug Adapter Protocol (DAP)](https://microsoft.github.io/debug-adapter-protocol/) 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.
  6Zed implements the client side of the protocol, and various _debug adapters_ implement the server side.
  7
  8This protocol enables features like setting breakpoints, stepping through code, inspecting variables,
  9and more, in a consistent manner across different programming languages and runtime environments.
 10
 11## Supported Languages
 12
 13To debug code written in a specific language, Zed needs to find a debug adapter for that language. Some debug adapters are provided by Zed without additional setup, and some are provided by [language extensions](./extensions/debugger-extensions.md). The following languages currently have debug adapters available:
 14
 15<!-- keep this sorted -->
 16
 17- [C](./languages/c.md#debugging) (built-in)
 18- [C++](./languages/cpp.md#debugging) (built-in)
 19- [Go](./languages/go.md#debugging) (built-in)
 20- [JavaScript](./languages/javascript.md#debugging) (built-in)
 21- [PHP](./languages/php.md#debugging) (built-in)
 22- [Python](./languages/python.md#debugging) (built-in)
 23- [Ruby](./languages/ruby.md#debugging) (provided by extension)
 24- [Rust](./languages/rust.md#debugging) (built-in)
 25- [Swift](./languages/swift.md#debugging) (provided by extension)
 26- [TypeScript](./languages/typescript.md#debugging) (built-in)
 27
 28> If your language isn't listed, you can contribute by adding a debug adapter for it. Check out our [debugger extensions](./extensions/debugger-extensions.md) documentation for more information.
 29
 30Follow those links for language- and adapter-specific information and examples, or read on for more about Zed's general debugging features that apply to all adapters.
 31
 32## Getting Started
 33
 34For most languages, the fastest way to get started is to run {#action debugger::Start} ({#kb debugger::Start}). This opens the _new process modal_, which shows you a contextual list of preconfigured debug tasks for the current project. Debug tasks are created from tests, entry points (like a `main` function), and from other sources — consult the documentation for your language for full information about what's supported.
 35
 36You can open the same modal by clicking the "plus" button at the top right of the debug panel.
 37
 38For languages that don't provide preconfigured debug tasks (this includes C, C++, and some extension-supported languages), you can define debug configurations in the `.zed/debug.json` file in your project root. This file should be an array of configuration objects:
 39
 40```json
 41[
 42  {
 43    "adapter": "CodeLLDB",
 44    "label": "First configuration"
 45    // ...
 46  },
 47  {
 48    "adapter": "Debugpy",
 49    "label": "Second configuration"
 50    // ...
 51  }
 52]
 53```
 54
 55Check the documentation for your language for example configurations covering typical use-cases. Once you've added configurations to `.zed/debug.json`, they'll appear in the list in the new process modal.
 56
 57Zed will also load debug configurations from `.vscode/launch.json`, and show them in the new process modal if no configurations are found in `.zed/debug.json`.
 58
 59### Launching & Attaching
 60
 61Zed debugger offers two ways to debug your program; you can either _launch_ a new instance of your program or _attach_ to an existing process.
 62Which one you choose depends on what you are trying to achieve.
 63
 64When launching a new instance, Zed (and the underlying debug adapter) can often do a better job at picking up the debug information compared to attaching to an existing process, since it controls the lifetime of a whole program.
 65Running unit tests or a debug build of your application is a good use case for launching.
 66
 67Compared to launching, attaching to an existing process might seem inferior, but that's far from truth; there are cases where you cannot afford to restart your program, because for example, the bug is not reproducible outside of a production environment or some other circumstances.
 68
 69## Configuration
 70
 71While configuration fields are debug adapter-dependent, most adapters support the following fields:
 72
 73```json
 74[
 75  {
 76    // The label for the debug configuration and used to identify the debug session inside the debug panel & new process modal
 77    "label": "Example Start debugger config",
 78    // The debug adapter that Zed should use to debug the program
 79    "adapter": "Example adapter name",
 80    // Request:
 81    //  - launch: Zed will launch the program if specified, or show a debug terminal with the right configuration
 82    //  - attach: Zed will attach to a running program to debug it, or when the process_id is not specified, will show a process picker (only supported for node currently)
 83    "request": "launch",
 84    // The program to debug. This field supports path resolution with ~ or . symbols.
 85    "program": "path_to_program",
 86    // cwd: defaults to the current working directory of your project ($ZED_WORKTREE_ROOT)
 87    "cwd": "$ZED_WORKTREE_ROOT"
 88  }
 89]
 90```
 91
 92All configuration fields support [task variables](./tasks.md#variables).
 93
 94### Build tasks
 95
 96Zed also allows embedding a Zed task in a `build` field 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.
 97
 98```json
 99[
100  {
101    "label": "Build Binary",
102    "adapter": "CodeLLDB",
103    "program": "path_to_program",
104    "request": "launch",
105    "build": {
106      "command": "make",
107      "args": ["build", "-j8"]
108    }
109  }
110]
111```
112
113Build tasks can also refer to the existing tasks by unsubstituted label:
114
115```json
116[
117  {
118    "label": "Build Binary",
119    "adapter": "CodeLLDB",
120    "program": "path_to_program",
121    "request": "launch",
122    "build": "my build task" // Or "my build task for $ZED_FILE"
123  }
124]
125```
126
127### Automatic scenario creation
128
129Given a Zed task, Zed can automatically create a scenario for you. Automatic scenario creation also powers our scenario creation from gutter.
130Automatic scenario creation is currently supported for Rust, Go, Python, JavaScript, and TypeScript.
131
132## Breakpoints
133
134To set a breakpoint, simply click next to the line number in the editor gutter.
135Breakpoints 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.
136At present, you can:
137
138- Add a log to a breakpoint, which will output a log message whenever that breakpoint is hit.
139- Make the breakpoint conditional, which will only stop at the breakpoint when the condition is met. The syntax for conditions is adapter-specific.
140- Add a hit count to a breakpoint, which will only stop at the breakpoint after it's hit a certain number of times.
141- Disable a breakpoint, which will prevent it from being hit while leaving it visible in the gutter.
142
143Some debug adapters (e.g. CodeLLDB and JavaScript) will also _verify_ whether your breakpoints can be hit; breakpoints that cannot be hit are surfaced more prominently in the UI.
144
145All breakpoints enabled for a given project are also listed in "Breakpoints" item in your debugging session UI. From "Breakpoints" item in your UI you can also manage exception breakpoints.
146The debug adapter will then stop whenever an exception of a given kind occurs. Which exception types are supported depends on the debug adapter.
147
148## Settings
149
150The settings for the debugger are grouped under the `debugger` key in `settings.json`:
151
152- `dock`: Determines the position of the debug panel in the UI.
153- `stepping_granularity`: Determines the stepping granularity.
154- `save_breakpoints`: Whether the breakpoints should be reused across Zed sessions.
155- `button`: Whether to show the debug button in the status bar.
156- `timeout`: Time in milliseconds until timeout error when connecting to a TCP debug adapter.
157- `log_dap_communications`: Whether to log messages between active debug adapters and Zed.
158- `format_dap_log_messages`: Whether to format DAP messages when adding them to the debug adapter logger.
159
160### Dock
161
162- Description: The position of the debug panel in the UI.
163- Default: `bottom`
164- Setting: debugger.dock
165
166**Options**
167
1681. `left` - The debug panel will be docked to the left side of the UI.
1692. `right` - The debug panel will be docked to the right side of the UI.
1703. `bottom` - The debug panel will be docked to the bottom of the UI.
171
172```json
173"debugger": {
174  "dock": "bottom"
175},
176```
177
178### Stepping granularity
179
180- Description: The Step granularity that the debugger will use
181- Default: `line`
182- Setting: `debugger.stepping_granularity`
183
184**Options**
185
1861. Statement - The step should allow the program to run until the current statement has finished executing.
187   The meaning of a statement is determined by the adapter and it may be considered equivalent to a line.
188   For example 'for(int i = 0; i < 10; i++)' could be considered to have 3 statements 'int i = 0', 'i < 10', and 'i++'.
189
190```json
191{
192  "debugger": {
193    "stepping_granularity": "statement"
194  }
195}
196```
197
1982. Line - The step should allow the program to run until the current source line has executed.
199
200```json
201{
202  "debugger": {
203    "stepping_granularity": "line"
204  }
205}
206```
207
2083. Instruction - The step should allow one instruction to execute (e.g. one x86 instruction).
209
210```json
211{
212  "debugger": {
213    "stepping_granularity": "instruction"
214  }
215}
216```
217
218### Save Breakpoints
219
220- Description: Whether the breakpoints should be saved across Zed sessions.
221- Default: `true`
222- Setting: `debugger.save_breakpoints`
223
224**Options**
225
226`boolean` values
227
228```json
229{
230  "debugger": {
231    "save_breakpoints": true
232  }
233}
234```
235
236### Button
237
238- Description: Whether the button should be displayed in the debugger toolbar.
239- Default: `true`
240- Setting: `debugger.show_button`
241
242**Options**
243
244`boolean` values
245
246```json
247{
248  "debugger": {
249    "show_button": true
250  }
251}
252```
253
254### Timeout
255
256- Description: Time in milliseconds until timeout error when connecting to a TCP debug adapter.
257- Default: `2000`
258- Setting: `debugger.timeout`
259
260**Options**
261
262`integer` values
263
264```json
265{
266  "debugger": {
267    "timeout": 3000
268  }
269}
270```
271
272### Inline Values
273
274- Description: Whether to enable editor inlay hints showing the values of variables in your code during debugging sessions.
275- Default: `true`
276- Setting: `inlay_hints.show_value_hints`
277
278**Options**
279
280```json
281{
282  "inlay_hints": {
283    "show_value_hints": false
284  }
285}
286```
287
288Inline value hints can also be toggled from the Editor Controls menu in the editor toolbar.
289
290### Log Dap Communications
291
292- Description: Whether to log messages between active debug adapters and Zed. (Used for DAP development)
293- Default: false
294- Setting: debugger.log_dap_communications
295
296**Options**
297
298`boolean` values
299
300```json
301{
302  "debugger": {
303    "log_dap_communications": true
304  }
305}
306```
307
308### Format Dap Log Messages
309
310- Description: Whether to format DAP messages when adding them to the debug adapter logger. (Used for DAP development)
311- Default: false
312- Setting: debugger.format_dap_log_messages
313
314**Options**
315
316`boolean` values
317
318```json
319{
320  "debugger": {
321    "format_dap_log_messages": true
322  }
323}
324```
325
326### Customizing Debug Adapters
327
328- Description: Custom program path and arguments to override how Zed launches a specific debug adapter.
329- Default: Adapter-specific
330- Setting: `dap.$ADAPTER.binary` and `dap.$ADAPTER.args`
331
332You can pass `binary`, `args`, or both. `binary` should be a path to a _debug adapter_ (like `lldb-dap`) not a _debugger_ (like `lldb` itself). The `args` setting overrides any arguments that Zed would otherwise pass to the adapter.
333
334```json
335{
336  "dap": {
337    "CodeLLDB": {
338      "binary": "/Users/name/bin/lldb-dap",
339      "args": ["--wait-for-debugger"]
340    }
341  }
342}
343```
344
345## Theme
346
347The Debugger supports the following theme options:
348
349- `debugger.accent`: Color used to accent breakpoint & breakpoint-related symbols
350- `editor.debugger_active_line.background`: Background color of active debug line
351
352## Troubleshooting
353
354If you're running into problems with the debugger, please [open a GitHub issue](https://github.com/zed-industries/zed/issues/new?template=04_bug_debugger.yml) or [schedule an onboarding call](https://cal.com/team/zed-research/debugger) with us so we can help understand and fix your issue.
355
356There are also some features you can use to gather more information about the problem:
357
358- When you have a session running in the debug panel, you can run the {#action dev::CopyDebugAdapterArguments} action to copy a JSON blob to the clipboard that describes how Zed initialized the session. This is especially useful when the session failed to start, and is great context to add if you open a GitHub issue.
359- You can also use the {#action dev::OpenDebugAdapterLogs} action to see a trace of all of Zed's communications with debug adapters during the most recent debug sessions.