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> We currently offer onboarding support for users. We are eager to hear from you if you encounter any issues or have suggestions for improvement for our debugging experience.
 10> You can schedule a call via [Cal.com](https://cal.com/team/zed-research/debugger)
 11
 12## Supported Debug Adapters
 13
 14Zed supports a variety of debug adapters for different programming languages out of the box:
 15
 16- JavaScript ([vscode-js-debug](https://github.com/microsoft/vscode-js-debug.git)): Enables debugging of Node.js applications, including setting breakpoints, stepping through code, and inspecting variables in JavaScript.
 17
 18- Python ([debugpy](https://github.com/microsoft/debugpy.git)): Provides debugging capabilities for Python applications, supporting features like remote debugging, multi-threaded debugging, and Django/Flask application debugging.
 19
 20- LLDB ([CodeLLDB](https://github.com/vadimcn/codelldb.git)): A powerful debugger for C, C++, Objective-C, and Swift, offering low-level debugging features and support for Apple platforms.
 21
 22- GDB ([GDB](https://sourceware.org/gdb/)): The GNU Debugger, which supports debugging for multiple programming languages including C, C++, Go, and Rust, across various platforms.
 23
 24- Go ([Delve](https://github.com/go-delve/delve)): 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.
 25
 26- PHP ([Xdebug](https://xdebug.org/)): Provides debugging and profiling capabilities for PHP applications, including remote debugging and code coverage analysis.
 27
 28- Ruby ([rdbg](https://github.com/ruby/debug)): Provides debugging for Ruby.
 29
 30These adapters enable Zed to provide a consistent debugging experience across multiple languages while leveraging the specific features and capabilities of each debugger.
 31
 32> Is your desired debugger not listed? You can install a [Debug Adapter extension](https://zed.dev/extensions?filter=debug-adapters) to add support for your favorite debugger.
 33> If that's not enough, you can contribute by creating an extension yourself. Check out our [debugger extensions](extensions/debugger-extensions.md) documentation for more information.
 34
 35## Getting Started
 36
 37For 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.
 38
 39For more advanced use cases, you can create debug configurations by directly editing the `.zed/debug.json` file in your project root directory.
 40
 41You can then use the `New Session Modal` to select a configuration and start debugging.
 42
 43### Launching & Attaching
 44
 45Zed debugger offers two ways to debug your program; you can either _launch_ a new instance of your program or _attach_ to an existing process.
 46Which one you choose depends on what you are trying to achieve.
 47
 48When 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. Running unit tests or a debug build of your application is a good use case for launching.
 49
 50Compared 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 e.g. the bug is not reproducible outside of a production environment or some other circumstances.
 51
 52## Configuration
 53
 54While configuration fields are debug adapter-dependent, most adapters support the following fields:
 55
 56```json
 57[
 58  {
 59    // The label for the debug configuration and used to identify the debug session inside the debug panel & new session modal
 60    "label": "Example Start debugger config",
 61    // The debug adapter that Zed should use to debug the program
 62    "adapter": "Example adapter name",
 63    // Request:
 64    //  - launch: Zed will launch the program if specified or shows a debug terminal with the right configuration
 65    //  - 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)
 66    "request": "launch",
 67    // program: The program that you want to debug
 68    // This field supports path resolution with ~ or . symbols
 69    "program": "path_to_program",
 70    // cwd: defaults to the current working directory of your project ($ZED_WORKTREE_ROOT)
 71    "cwd": "$ZED_WORKTREE_ROOT"
 72  }
 73]
 74```
 75
 76All configuration fields support task variables. See [Tasks Variables](./tasks.md#variables)
 77
 78### Build tasks
 79
 80Zed 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.
 81
 82```json
 83[
 84  {
 85    "label": "Build Binary",
 86    "adapter": "CodeLLDB",
 87    "program": "path_to_program",
 88    "request": "launch",
 89    "build": {
 90      "command": "make",
 91      "args": ["build", "-j8"]
 92    }
 93  }
 94]
 95```
 96
 97Build tasks can also refer to the existing tasks by unsubstituted label:
 98
 99```json
100[
101  {
102    "label": "Build Binary",
103    "adapter": "CodeLLDB",
104    "program": "path_to_program",
105    "request": "launch",
106    "build": "my build task" // Or "my build task for $ZED_FILE"
107  }
108]
109```
110
111### Automatic scenario creation
112
113Given a Zed task, Zed can automatically create a scenario for you. Automatic scenario creation also powers our scenario creation from gutter.
114Automatic scenario creation is currently supported for Rust, Go and Python. Javascript/TypeScript support being worked on.
115
116### Example Configurations
117
118#### JavaScript
119
120##### Debug Active File
121
122```json
123[
124  {
125    "label": "Debug with node",
126    "adapter": "JavaScript",
127    "program": "$ZED_FILE",
128    "request": "launch",
129    "console": "integratedTerminal",
130    "type": "pwa-node"
131  }
132]
133```
134
135##### Attach debugger to a server running in web browser (`npx serve`)
136
137Given an externally-ran web server (e.g. with `npx serve` or `npx live-server`) one can attach to it and open it with a browser.
138
139```json
140[
141  {
142    "label": "Inspect ",
143    "adapter": "JavaScript",
144    "type": "pwa-chrome",
145    "request": "launch",
146    "url": "http://localhost:5500", // Fill your URL here.
147    "program": "$ZED_FILE",
148    "webRoot": "${ZED_WORKTREE_ROOT}"
149  }
150]
151```
152
153#### Python
154
155##### Debug Active File
156
157```json
158[
159  {
160    "label": "Python Active File",
161    "adapter": "Debugpy",
162    "program": "$ZED_FILE",
163    "request": "launch"
164  }
165]
166```
167
168##### Flask App
169
170For a common Flask Application with a file structure similar to the following:
171
172```
173.venv/
174app/
175  init.py
176  main.py
177  routes.py
178templates/
179  index.html
180static/
181  style.css
182requirements.txt
183```
184
185the following configuration can be used:
186
187```json
188[
189  {
190    "label": "Python: Flask",
191    "adapter": "Debugpy",
192    "request": "launch",
193    "module": "app",
194    "cwd": "$ZED_WORKTREE_ROOT",
195    "env": {
196      "FLASK_APP": "app",
197      "FLASK_DEBUG": "1"
198    },
199    "args": [
200      "run",
201      "--reload", // Enables Flask reloader that watches for file changes
202      "--debugger" // Enables Flask debugger
203    ],
204    "autoReload": {
205      "enable": true
206    },
207    "jinja": true,
208    "justMyCode": true
209  }
210]
211```
212
213#### Rust/C++/C
214
215##### Using pre-built binary
216
217```json
218[
219  {
220    "label": "Debug native binary",
221    "program": "$ZED_WORKTREE_ROOT/build/binary",
222    "request": "launch",
223    "adapter": "CodeLLDB" // GDB is available on non arm macs as well as linux
224  }
225]
226```
227
228##### Build binary then debug
229
230```json
231[
232  {
233    "label": "Build & Debug native binary",
234    "build": {
235      "command": "cargo",
236      "args": ["build"]
237    },
238    "program": "$ZED_WORKTREE_ROOT/target/debug/binary",
239    "request": "launch",
240    "adapter": "CodeLLDB" // GDB is available on non arm macs as well as linux
241  }
242]
243```
244
245#### TypeScript
246
247##### Attach debugger to a server running in web browser (`npx serve`)
248
249Given an externally-ran web server (e.g. with `npx serve` or `npx live-server`) one can attach to it and open it with a browser.
250
251```json
252[
253  {
254    "label": "Launch Chrome (TypeScript)",
255    "adapter": "JavaScript",
256    "type": "pwa-chrome",
257    "request": "launch",
258    "url": "http://localhost:5500",
259    "program": "$ZED_FILE",
260    "webRoot": "${ZED_WORKTREE_ROOT}",
261    "sourceMaps": true,
262    "build": {
263      "command": "npx",
264      "args": ["tsc"]
265    }
266  }
267]
268```
269
270#### Go
271
272Zed uses [delve](https://github.com/go-delve/delve?tab=readme-ov-file) to debug Go applications. Zed will automatically create debug scenarios for `func main` in your main packages, and also
273for any tests, so you can use the Play button in the gutter to debug these without configuration.
274
275##### Debug Go Packages
276
277To debug a specific package, you can do so by setting the Delve mode to "debug". In this case "program" should be set to the package name.
278
279```json
280[
281  {
282    "label": "Go (Delve)",
283    "adapter": "Delve",
284    "program": "$ZED_FILE",
285    "request": "launch",
286    "mode": "debug"
287  }
288]
289```
290
291```json
292[
293  {
294    "label": "Run server",
295    "adapter": "Delve",
296    "request": "launch",
297    "mode": "debug",
298    // For Delve, the program can be a package name
299    "program": "./cmd/server"
300    // "args": [],
301    // "buildFlags": [],
302  }
303]
304```
305
306##### Debug Go Tests
307
308To debug the tests for a package, set the Delve mode to "test". The "program" is still the package name, and you can use the "buildFlags" to do things like set tags, and the "args" to set args on the test binary. (See `go help testflags` for more information on doing that).
309
310```json
311[
312  {
313    "label": "Run integration tests",
314    "adapter": "Delve",
315    "request": "launch",
316    "mode": "test",
317    "program": ".",
318    "buildFlags": ["-tags", "integration"]
319    // To filter down to just the test your cursor is in:
320    // "args": ["-test.run", "$ZED_SYMBOL"]
321  }
322]
323```
324
325##### Build and debug separately
326
327If you need to build your application with a specific command, you can use the "exec" mode of Delve. In this case "program" should point to an executable,
328and the "build" command should build that.
329
330```json
331{
332  "label": "Debug Prebuilt Unit Tests",
333  "adapter": "Delve",
334  "request": "launch",
335  "mode": "exec",
336  "program": "${ZED_WORKTREE_ROOT}/__debug_unit",
337  "args": ["-test.v", "-test.run=${ZED_SYMBOL}"],
338  "build": {
339    "command": "go",
340    "args": [
341      "test",
342      "-c",
343      "-tags",
344      "unit",
345      "-gcflags\"all=-N -l\"",
346      "-o",
347      "__debug_unit",
348      "./pkg/..."
349    ]
350  }
351}
352```
353
354##### Attaching to an existing instance of Delve
355
356You might find yourself needing to connect to an existing instance of Delve that's not necessarily running on your machine; in such case, you can use `tcp_arguments` to instrument Zed's connection to Delve.
357
358```
359{
360  "adapter": "Delve",
361  "label": "Connect to a running Delve instance",
362  "program": "/Users/zed/Projects/language_repositories/golang/hello/hello",
363  "cwd": "/Users/zed/Projects/language_repositories/golang/hello",
364  "args": [],
365  "env": {},
366  "request": "launch",
367  "mode": "exec",
368  "stopOnEntry": false,
369  "tcp_connection": { "host": "123.456.789.012", "port": 53412 }
370}
371```
372
373In such case Zed won't spawn a new instance of Delve, as it opts to use an existing one. The consequence of this is that _there will be no terminal_ in Zed; you have to interact with the Delve instance directly, as it handles stdin/stdout of the debuggee.
374
375#### Ruby
376
377To run a ruby task in the debugger, you will need to configure it in the `.zed/debug.json` file in your project. We don't yet have automatic detection of ruby tasks, nor do we support connecting to an existing process.
378
379The configuration should look like this:
380
381```json
382{
383  {
384    "adapter": "Ruby",
385    "label": "Run CLI",
386    "script": "cli.rb"
387    // If you want to customize how the script is run (for example using bundle exec)
388    // use "command" instead.
389    // "command": "bundle exec cli.rb"
390    //
391    // "args": []
392    // "env": {}
393    // "cwd": ""
394  }
395}
396```
397
398## Breakpoints
399
400To set a breakpoint, simply click next to the line number in the editor gutter.
401Breakpoints 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.
402At present, you can:
403
404- Add a log to a breakpoint, which will output a log message whenever that breakpoint is hit.
405- Make the breakpoint conditional, which will only stop at the breakpoint when the condition is met. The syntax for conditions is adapter-specific.
406- Add a hit count to a breakpoint, which will only stop at the breakpoint after it's hit a certain number of times.
407- Disable a breakpoint, which will prevent it from being hit while leaving it visible in the gutter.
408
409Some 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.
410
411All 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.
412The debug adapter will then stop whenever an exception of a given kind occurs. Which exception types are supported depends on the debug adapter.
413
414## Settings
415
416- `dock`: Determines the position of the debug panel in the UI.
417- `stepping_granularity`: Determines the stepping granularity.
418- `save_breakpoints`: Whether the breakpoints should be reused across Zed sessions.
419- `button`: Whether to show the debug button in the status bar.
420- `timeout`: Time in milliseconds until timeout error when connecting to a TCP debug adapter.
421- `log_dap_communications`: Whether to log messages between active debug adapters and Zed.
422- `format_dap_log_messages`: Whether to format DAP messages when adding them to the debug adapter logger.
423
424### Dock
425
426- Description: The position of the debug panel in the UI.
427- Default: `bottom`
428- Setting: debugger.dock
429
430**Options**
431
4321. `left` - The debug panel will be docked to the left side of the UI.
4332. `right` - The debug panel will be docked to the right side of the UI.
4343. `bottom` - The debug panel will be docked to the bottom of the UI.
435
436```json
437"debugger": {
438  "dock": "bottom"
439},
440```
441
442### Stepping granularity
443
444- Description: The Step granularity that the debugger will use
445- Default: line
446- Setting: debugger.stepping_granularity
447
448**Options**
449
4501. Statement - The step should allow the program to run until the current statement has finished executing.
451   The meaning of a statement is determined by the adapter and it may be considered equivalent to a line.
452   For example 'for(int i = 0; i < 10; i++)' could be considered to have 3 statements 'int i = 0', 'i < 10', and 'i++'.
453
454```json
455{
456  "debugger": {
457    "stepping_granularity": "statement"
458  }
459}
460```
461
4622. Line - The step should allow the program to run until the current source line has executed.
463
464```json
465{
466  "debugger": {
467    "stepping_granularity": "line"
468  }
469}
470```
471
4723. Instruction - The step should allow one instruction to execute (e.g. one x86 instruction).
473
474```json
475{
476  "debugger": {
477    "stepping_granularity": "instruction"
478  }
479}
480```
481
482### Save Breakpoints
483
484- Description: Whether the breakpoints should be saved across Zed sessions.
485- Default: true
486- Setting: debugger.save_breakpoints
487
488**Options**
489
490`boolean` values
491
492```json
493{
494  "debugger": {
495    "save_breakpoints": true
496  }
497}
498```
499
500### Button
501
502- Description: Whether the button should be displayed in the debugger toolbar.
503- Default: true
504- Setting: debugger.show_button
505
506**Options**
507
508`boolean` values
509
510```json
511{
512  "debugger": {
513    "show_button": true
514  }
515}
516```
517
518### Timeout
519
520- Description: Time in milliseconds until timeout error when connecting to a TCP debug adapter.
521- Default: 2000
522- Setting: debugger.timeout
523
524**Options**
525
526`integer` values
527
528```json
529{
530  "debugger": {
531    "timeout": 3000
532  }
533}
534```
535
536### Log Dap Communications
537
538- Description: Whether to log messages between active debug adapters and Zed. (Used for DAP development)
539- Default: false
540- Setting: debugger.log_dap_communications
541
542**Options**
543
544`boolean` values
545
546```json
547{
548  "debugger": {
549    "log_dap_communications": true
550  }
551}
552```
553
554### Format Dap Log Messages
555
556- Description: Whether to format DAP messages when adding them to the debug adapter logger. (Used for DAP development)
557- Default: false
558- Setting: debugger.format_dap_log_messages
559
560**Options**
561
562`boolean` values
563
564```json
565{
566  "debugger": {
567    "format_dap_log_messages": true
568  }
569}
570```
571
572## Theme
573
574The Debugger supports the following theme options:
575
576**debugger.accent**: Color used to accent breakpoint & breakpoint-related symbols
577**editor.debugger_active_line.background**: Background color of active debug line