Debugger implementation (#13433)
### DISCLAIMER > As of 6th March 2025, debugger is still in development. We plan to merge it behind a staff-only feature flag for staff use only, followed by non-public release and then finally a public one (akin to how Git panel release was handled). This is done to ensure the best experience when it gets released. ### END OF DISCLAIMER **The current state of the debugger implementation:** https://github.com/user-attachments/assets/c4deff07-80dd-4dc6-ad2e-0c252a478fe9 https://github.com/user-attachments/assets/e1ed2345-b750-4bb6-9c97-50961b76904f ---- 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: ```cli 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) - Debug console - 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: - N/A --------- Co-authored-by: Piotr Osiewicz <24362066+osiewicz@users.noreply.github.com> Co-authored-by: Anthony Eid <hello@anthonyeid.me> Co-authored-by: Anthony <anthony@zed.dev> Co-authored-by: Piotr Osiewicz <peterosiewicz@gmail.com> Co-authored-by: Piotr <piotr@zed.dev>
This commit is contained in:
Remco Smits
co-authored by
Piotr Osiewicz
Anthony Eid
Anthony
Piotr Osiewicz
Piotr
Piotr Osiewicz
Anthony Eid
Anthony
Piotr Osiewicz
Piotr
parent
ed4e654fdf
commit
41a60ffecf
@@ -0,0 +1,350 @@
|
||||
# Debugger
|
||||
|
||||
Zed uses the Debug Adapter Protocol (DAP) to provide debugging functionality across multiple programming languages.
|
||||
DAP is a standardized protocol that defines how debuggers, editors, and IDEs communicate with each other.
|
||||
It allows Zed to support various debuggers without needing to implement language-specific debugging logic.
|
||||
This protocol enables features like setting breakpoints, stepping through code, inspecting variables,
|
||||
and more, in a consistent manner across different programming languages and runtime environments.
|
||||
|
||||
## Supported Debug Adapters
|
||||
|
||||
Zed supports a variety of debug adapters for different programming languages:
|
||||
|
||||
- JavaScript (node): Enables debugging of Node.js applications, including setting breakpoints, stepping through code, and inspecting variables in JavaScript.
|
||||
|
||||
- Python (debugpy): Provides debugging capabilities for Python applications, supporting features like remote debugging, multi-threaded debugging, and Django/Flask application debugging.
|
||||
|
||||
- LLDB: A powerful debugger for C, C++, Objective-C, and Swift, offering low-level debugging features and support for Apple platforms.
|
||||
|
||||
- GDB: The GNU Debugger, which supports debugging for multiple programming languages including C, C++, Go, and Rust, across various platforms.
|
||||
|
||||
- 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.
|
||||
|
||||
- PHP (xdebug): Provides debugging and profiling capabilities for PHP applications, including remote debugging and code coverage analysis.
|
||||
|
||||
- Custom: Allows you to configure any debug adapter that supports the Debug Adapter Protocol, enabling debugging for additional languages or specialized environments not natively supported by Zed.
|
||||
|
||||
These adapters enable Zed to provide a consistent debugging experience across multiple languages while leveraging the specific features and capabilities of each debugger.
|
||||
|
||||
## How To Get Started
|
||||
|
||||
To start a debug session, we added few default debug configurations for each supported language that supports generic configuration options. To see all the available debug configurations, you can use the command palette `debugger: start` action, this should list all the available debug configurations.
|
||||
|
||||
### Configuration
|
||||
|
||||
To create a custom debug configuration you have to create a `.zed/debug.json` file in your project root directory. This file should contain an array of debug configurations, each with a unique label and adapter the other option are optional/required based on the adapter.
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
// The label for the debug configuration and used to identify the debug session inside the debug panel
|
||||
"label": "Example Start debugger config"
|
||||
// The debug adapter that Zed should use to debug the program
|
||||
"adapter": "custom",
|
||||
// Request: defaults to launch
|
||||
// - launch: Zed will launch the program if specified or shows a debug terminal with the right configuration
|
||||
// - 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)
|
||||
"request": "launch",
|
||||
// cwd: defaults to the current working directory of your project ($ZED_WORKTREE_ROOT)
|
||||
// this field also supports task variables e.g. $ZED_WORKTREE_ROOT
|
||||
"cwd": "$ZED_WORKTREE_ROOT",
|
||||
// program: The program that you want to debug
|
||||
// this fields also support task variables e.g. $ZED_FILE
|
||||
// Note: this field should only contain the path to the program you want to debug
|
||||
"program": "path_to_program",
|
||||
// initialize_args: This field should contain all the adapter specific initialization arguments that are directly send to the debug adapter
|
||||
"initialize_args": {
|
||||
// "stopOnEntry": true // e.g. to stop on the first line of the program (These args are DAP specific)
|
||||
}
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### Using Attach [WIP]
|
||||
|
||||
Only javascript and lldb supports starting a debug session using attach.
|
||||
|
||||
When using the attach request with a process ID the syntax is as follows:
|
||||
|
||||
```json
|
||||
{
|
||||
"label": "Attach to Process",
|
||||
"adapter": "javascript",
|
||||
"request": {
|
||||
"attach": {
|
||||
"process_id": "12345"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Without process ID the syntax is as follows:
|
||||
|
||||
```json
|
||||
{
|
||||
"label": "Attach to Process",
|
||||
"adapter": "javascript",
|
||||
"request": {
|
||||
"attach": {}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### JavaScript Configuration
|
||||
|
||||
##### Debug Active File
|
||||
|
||||
This configuration allows you to debug a JavaScript file in your project.
|
||||
|
||||
```json
|
||||
{
|
||||
"label": "JavaScript: Debug Active File",
|
||||
"adapter": "javascript",
|
||||
"program": "$ZED_FILE",
|
||||
"request": "launch",
|
||||
"cwd": "$ZED_WORKTREE_ROOT"
|
||||
}
|
||||
```
|
||||
|
||||
##### Debug Terminal
|
||||
|
||||
This configuration will spawn a debug terminal where you could start you program by typing `node test.js`, and the debug adapter will automatically attach to the process.
|
||||
|
||||
```json
|
||||
{
|
||||
"label": "JavaScript: Debug Terminal",
|
||||
"adapter": "javascript",
|
||||
"request": "launch",
|
||||
"cwd": "$ZED_WORKTREE_ROOT",
|
||||
// "program": "$ZED_FILE", // optional if you pass this in, you will see the output inside the terminal itself
|
||||
"initialize_args": {
|
||||
"console": "integratedTerminal"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### PHP Configuration
|
||||
|
||||
##### Debug Active File
|
||||
|
||||
This configuration allows you to debug a PHP file in your project.
|
||||
|
||||
```json
|
||||
{
|
||||
"label": "PHP: Debug Active File",
|
||||
"adapter": "php",
|
||||
"program": "$ZED_FILE",
|
||||
"request": "launch",
|
||||
"cwd": "$ZED_WORKTREE_ROOT"
|
||||
}
|
||||
```
|
||||
|
||||
#### Python Configuration
|
||||
|
||||
##### Debug Active File
|
||||
|
||||
This configuration allows you to debug a Python file in your project.
|
||||
|
||||
```json
|
||||
{
|
||||
"label": "Python: Debug Active File",
|
||||
"adapter": "python",
|
||||
"program": "$ZED_FILE",
|
||||
"request": "launch",
|
||||
"cwd": "$ZED_WORKTREE_ROOT"
|
||||
}
|
||||
```
|
||||
|
||||
#### GDB Configuration
|
||||
|
||||
**NOTE:** This configuration is for Linux systems only & intel macbooks.
|
||||
|
||||
##### Debug Program
|
||||
|
||||
This configuration allows you to debug a program using GDB e.g. Zed itself.
|
||||
|
||||
```json
|
||||
{
|
||||
"label": "GDB: Debug program",
|
||||
"adapter": "gdb",
|
||||
"program": "$ZED_WORKTREE_ROOT/target/debug/zed",
|
||||
"request": "launch",
|
||||
"cwd": "$ZED_WORKTREE_ROOT"
|
||||
}
|
||||
```
|
||||
|
||||
#### LLDB Configuration
|
||||
|
||||
##### Debug Program
|
||||
|
||||
This configuration allows you to debug a program using LLDB e.g. Zed itself.
|
||||
|
||||
```json
|
||||
{
|
||||
"label": "LLDB: Debug program",
|
||||
"adapter": "lldb",
|
||||
"program": "$ZED_WORKTREE_ROOT/target/debug/zed",
|
||||
"request": "launch",
|
||||
"cwd": "$ZED_WORKTREE_ROOT"
|
||||
}
|
||||
```
|
||||
|
||||
## Breakpoints
|
||||
|
||||
Zed currently supports these types of breakpoints
|
||||
|
||||
- Log Breakpoints: Output a log message instead of stopping at the breakpoint when it's hit
|
||||
- Standard Breakpoints: Stop at the breakpoint when it's hit
|
||||
|
||||
Standard breakpoints can be toggled by left clicking on the editor gutter or using the Toggle Breakpoint action. Right clicking on a breakpoint, code action symbol, or code runner symbol brings up the breakpoint context menu. That has options for toggling breakpoints and editing log breakpoints.
|
||||
|
||||
Log breakpoints can also be edited/added through the edit log breakpoint action
|
||||
|
||||
## Settings
|
||||
|
||||
- `stepping_granularity`: Determines the stepping granularity.
|
||||
- `save_breakpoints`: Whether the breakpoints should be reused across Zed sessions.
|
||||
- `button`: Whether to show the debug button in the status bar.
|
||||
- `timeout`: Time in milliseconds until timeout error when connecting to a TCP debug adapter.
|
||||
- `log_dap_communications`: Whether to log messages between active debug adapters and Zed
|
||||
- `format_dap_log_messages`: Whether to format dap messages in when adding them to debug adapter logger
|
||||
|
||||
### Stepping granularity
|
||||
|
||||
- Description: The Step granularity that the debugger will use
|
||||
- Default: line
|
||||
- Setting: debugger.stepping_granularity
|
||||
|
||||
**Options**
|
||||
|
||||
1. Statement - The step should allow the program to run until the current statement has finished executing.
|
||||
The meaning of a statement is determined by the adapter and it may be considered equivalent to a line.
|
||||
For example 'for(int i = 0; i < 10; i++)' could be considered to have 3 statements 'int i = 0', 'i < 10', and 'i++'.
|
||||
|
||||
```json
|
||||
{
|
||||
"debugger": {
|
||||
"stepping_granularity": "statement"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
2. Line - The step should allow the program to run until the current source line has executed.
|
||||
|
||||
```json
|
||||
{
|
||||
"debugger": {
|
||||
"stepping_granularity": "line"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
3. Instruction - The step should allow one instruction to execute (e.g. one x86 instruction).
|
||||
|
||||
```json
|
||||
{
|
||||
"debugger": {
|
||||
"stepping_granularity": "instruction"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Save Breakpoints
|
||||
|
||||
- Description: Whether the breakpoints should be saved across Zed sessions.
|
||||
- Default: true
|
||||
- Setting: debugger.save_breakpoints
|
||||
|
||||
**Options**
|
||||
|
||||
`boolean` values
|
||||
|
||||
```json
|
||||
{
|
||||
"debugger": {
|
||||
"save_breakpoints": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Button
|
||||
|
||||
- Description: Whether the button should be displayed in the debugger toolbar.
|
||||
- Default: true
|
||||
- Setting: debugger.show_button
|
||||
|
||||
**Options**
|
||||
|
||||
`boolean` values
|
||||
|
||||
```json
|
||||
{
|
||||
"debugger": {
|
||||
"show_button": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Timeout
|
||||
|
||||
- Description: Time in milliseconds until timeout error when connecting to a TCP debug adapter.
|
||||
- Default: 2000ms
|
||||
- Setting: debugger.timeout
|
||||
|
||||
**Options**
|
||||
|
||||
`integer` values
|
||||
|
||||
```json
|
||||
{
|
||||
"debugger": {
|
||||
"timeout": 3000
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Log Dap Communications
|
||||
|
||||
- Description: Whether to log messages between active debug adapters and Zed. (Used for DAP development)
|
||||
- Default: false
|
||||
- Setting: debugger.log_dap_communications
|
||||
|
||||
**Options**
|
||||
|
||||
`boolean` values
|
||||
|
||||
```json
|
||||
{
|
||||
"debugger": {
|
||||
"log_dap_communications": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Format Dap Log Messages
|
||||
|
||||
- Description: Whether to format dap messages in when adding them to debug adapter logger. (Used for DAP development)
|
||||
- Default: false
|
||||
- Setting: debugger.format_dap_log_messages
|
||||
|
||||
**Options**
|
||||
|
||||
`boolean` values
|
||||
|
||||
```json
|
||||
{
|
||||
"debugger": {
|
||||
"format_dap_log_messages": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Theme
|
||||
|
||||
The Debugger supports the following theme options
|
||||
|
||||
/// Color used to accent some of the debuggers elements
|
||||
/// Only accent breakpoint & breakpoint related symbols right now
|
||||
|
||||
**debugger.accent**: Color used to accent breakpoint & breakpoint related symbols
|
||||
**editor.debugger_active_line.background**: Background color of active debug line
|
||||
Reference in New Issue
Block a user