Debugger implementation

[RemcoSmitsDev]

Closes #5307
Closes #5065

The current state of the debugger implementation:

Screen.Recording.2024-10-16.at.15.02.20.mov

Screen.Recording.2025-01-19.at.17.45.06.mov

---

All the todo's are in the following channel, so it's easier to work on this together:
https://zed.dev/channel/zed-debugger-11370

If you are on Linux, you can use the following command to join the channel:

zed https://zed.dev/channel/zed-debugger-11370 

Current Features

• Collab
  • Breakpoints
    • Sync when you (re)join a project
    • Sync when you add/remove a breakpoint
  • Sync active debug line
  • Stack frames
    • Click on stack frame
      • View variables that belong to the stack frame
      • Visit the source file
    • Restart stack frame (if adapter supports this)
  • Variables
  • Loaded sources
  • Modules
  • Controls
    • Continue
    • Step back
      • Stepping granularity (configurable)
    • Step into
      • Stepping granularity (configurable)
    • Step over
      • Stepping granularity (configurable)
    • Step out
      • Stepping granularity (configurable)
• Breakpoints
  • Log breakpoints
  • line breakpoints
  • Persistent between zed sessions (configurable)
  • Multi buffer support
  • Toggle disable/enable all breakpoints
• Stack frames
  • Click on stack frame
    • View variables that belong to the stack frame
    • Visit the source file
    • Show collapsed stack frames
  • Restart stack frame (if adapter supports this)
• Loaded sources
  • View all used loaded sources if supported by adapter.
• Modules
  • View all used modules (if adapter supports this)
• Variables
  • Copy value
  • Copy name
  • Copy memory reference
  • Set value (if adapter supports this)
  • keyboard navigation
• Debug Console
  • See logs
  • View output that was sent from debug adapter
    • Output grouping
  • Evaluate code
    • Updates the variable list
    • Auto completion
      • If not supported by adapter, we will show auto-completion for existing variables
• Debug Terminal
  • Run custom commands and change env values right inside your Zed terminal
• Attach to process (if adapter supports this)
  • Process picker
• Controls
  • Continue
  • Step back
    • Stepping granularity (configurable)
  • Step into
    • Stepping granularity (configurable)
  • Step over
    • Stepping granularity (configurable)
  • Step out
    • Stepping granularity (configurable)
  • Disconnect
  • Restart
  • Stop
• Warning when a debug session exited without hitting any breakpoint
• Debug view to see Adapter/RPC log messages
• Testing
  • Fake debug adapter
    • Fake requests & events

---

Release Notes:

• Added debugger implementation.

[davidbuzz]

Add documententation and/or an example on how to configure and/enable this for a specific debugger... if not as part of this PR then to the todo list ?

[osiewicz]

Change client id to be language id because you should only run one client per language at the same time

What if you have e.g. a monorepo with multiple services written in the same language?

[RemcoSmitsDev]

Uhm, I think most of the debug adapters support multiple threads, but need to look more in to that. Not sure how VS Code handles this, if they allow you to run the same debugger adapter twice or more.

[davidbuzz]

I'd love to see another more up-to-date video of the current status of this, if u can find time. :-)

[jonahcui]

HI, I have started a dlv(go dap server) to debug go program, but i need bring env to the dlv commend. I read the code DebugAdapterClient, i think when create_tcp_client or create_stdio_client, we should bring env configuration to command.

[RemcoSmitsDev]

HI, I have started a dlv(go dap server) to debug go program, but i need bring env to the dlv commend. I read the code DebugAdapterClient, i think when create_tcp_client or create_stdio_client, we should bring env configuration to command.

Hey, I think most debug adapters support this already by passing in an env prop through the launch or attach request. See the JS debugger config options. We already support passing in your own config values, so I don't think we need to add more configuration for this. Because it's on the debug adapter for getting this data and handling it how they want.

[jonahcui]

HI, I have started a dlv(go dap server) to debug go program, but i need bring env to the dlv commend. I read the code DebugAdapterClient, i think when create_tcp_client or create_stdio_client, we should bring env configuration to command.

Hey, I think most debug adapters support this already by passing in an env prop through the launch or attach request. See the JS debugger config options. We already support passing in your own config values, so I don't think we need to add more configuration for this. Because it's on the debug adapter for getting this data and handling it how they want.

Ok, understand.... I will test it on js debugger and go delve and study your code.

[davidbuzz]

for those of us trying to follow-along at home on this PR, it would be helpful of there was a sample tasks.json ( or wherever the debug settings are being stored if not there ) and any relevent settings.json we need enable, as I compiled and ran this PR, but was unable to get the same behaviour as either of the screen recordings.
for example: ctrl-shift-p[command palette] -> 'debug panel: open panel' gave me an empty lower panel with no start/stop/pause etc, and none of the other demonstrated command-palette/s seemed to do anything.

[RemcoSmitsDev]

Hey @davidbuzz, sorry for not posting any examples of starting a debug adapter. I did this for a reason, because I'm not happy yet with the naming of the fields & structure of the task. But here is an example task to start a debug adapter:

If you want to follow a bit more about what we are working on, you can join the following channel: https://zed.dev/channel/zed-debugger-11370.

{
  "label": "Xdebug debug adapter",
  "command": "bun",
  "args": [
    "/Users/remcosmits/Documents/code/vscode-php-debug/out/phpDebug.js",
    "--server=8132"
  ],
  "task_type": "debug",
  "cwd": "/Users/remcosmits/Documents/code/symfony_demo",
  "debug_adapter": {
    "id": "xdebug",
    "port": 8132,
    "request_args": {
      "skipFiles": ["**/vendor/**"],
      "pathMappings": {
        "/Users/remcosmits/Documents/code/symfony_demo/public": "/Users/remcosmits/Documents/code/symfony_demo/public"
      },
      "localSourceRoot": "/Users/remcosmits/Documents/code/symfony_demo",
      "serverSourceRoot": "/Users/remcosmits/Documents/code/symfony_demo",
      "xdebugSettings": {
        "show_hidden": 1
      }
    }
  }
}

[davidbuzz]

i think u mean this discord channel, but u were close.. https://discord.com/channels/869392257814519848/1255246362220691456 ... i pop in to the Zed discord occassionally. :-)

[RemcoSmitsDev]

i think u mean this discord channel, but u were close.. https://discord.com/channels/869392257814519848/1255246362220691456 ... i pop in to the Zed discord occassionally. :-)

No, that's not what I mean. What do you mean by I'm close? It sounds a bit disparaging...

[davidbuzz]

I was just trying to say that the link u gave starting with https://zed.dev doesn't work for me.

[RemcoSmitsDev]

Ahh oké. it seems to work for other people. Also it's the same as the one that i posted in the discord channel. Does it still not work for you?

[davidbuzz]

Ahh oké. it seems to work for other people. Also it's the same as the one that i posted in the discord channel. Does it still not work for you?

... im on linux. :-)

[berkaydedeoglu-eva]

It truly looks amazing. I was considering switching to Zed, but the lack of a debugger was holding me back. Being able to use it with attach mode is exactly what I was looking for. I suppose we can use it with node --inspect as well. Great work, I’m eagerly following the progress!

[LurkingLearner]

Hey, I was really excited to try this for my workflow but have run into some problems/oddities I was hoping to clear up:

In debugger.md it says at the start: "To debug a program using Zed you must first create a debug configuration within your project located at .zed/debug.json"

I have created that file with the following contents:

[
  {
    "label": "Debug Backend",
    "adapter": "python",
    "request": "launch",
    "cwd": "$ZED_WORKPLACE_ROOT",
    "program": "manage.py runserver_plus 0.0.0.0:9002",
    "initialize_args": {}
  }
]

I have a few problems:

1. I am trying to debug a Django application, but based solely on the example tasks I have no idea how to pass args to a program (i.e. runserver_plus, the IP and port)
2. This debug.json file located in my project root directory at .zed/debug.json does not seem to register with Zed/the debugger
3. Modifications to ~/.config/zed/debug.json do not seem to save/matter

When I open the debugger panel and click "Choose a debugger" I am presented with only the default debug options from the ~/.config/zed debug file. My project-local file is completely ignored. If I rename or otherwise modify the defaults it seems to do nothing even after restarting zed with the file modified.

So, my first question is how am I meant to implement a debugger task for something like Django where my target "program" is a file with multiple arguments? Maybe what I have is close, but since I can't actually see this task to run it I haven't been able to verify. Secondly, any ideas why it seems like my changes to either my local or the default debug.json files are being completely ignored?

I am building the latest as of this writing (953843a) on an M2 Mac running MacOS 15.2.

[RemcoSmitsDev]

Hey @LurkingLearner, thanks for trying out the debugger branch. I noticed a typo inside the docs $ZED_WORKPLACE_ROOT should be $ZED_WORKTREE_ROOT, but besides that, do you mind if we transfer the question to discord so not 28 people get notifications for all the comments?