From ec547b8ca3fdd53c42cbc0f580fca9825efef0be Mon Sep 17 00:00:00 2001 From: Remco Smits Date: Tue, 21 Jan 2025 23:43:11 +0100 Subject: [PATCH] Add debug configuration documentation (#96) * Start adding docs for configurations and adapters * Update debugger setting files with settings, attach config, & themes I also ran prettier and typos on it too." --------- Co-authored-by: Anthony Eid --- docs/src/debugger.md | 336 ++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 319 insertions(+), 17 deletions(-) diff --git a/docs/src/debugger.md b/docs/src/debugger.md index dc08421f26..b06f2f263c 100644 --- a/docs/src/debugger.md +++ b/docs/src/debugger.md @@ -1,35 +1,194 @@ # Debugger -## Debug Configuration +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. -To debug a program using Zed you must first create a debug configuration within your project located at `.zed/debug.json` +## 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 to use - // Zed supports javascript, python, lldb, go, and custom out of the box + // The debug adapter that Zed should use to debug the program "adapter": "custom", - // request: defaults to launch - // - launch: Zed will launch the program to be debugged - // - attach: Zed will attach to a running program to debug it + // 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 - // The current working directory to start the debugger from - // accepts zed task variables e.g. $ZED_WORKTREE_ROOT + // 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 to debug - // accepts zed task variables + // 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", - // Additional initialization arguments to be sent on DAP initialization + // 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 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 @@ -41,8 +200,151 @@ Standard breakpoints can be toggled by left clicking on the editor gutter or usi Log breakpoints can also be edited/added through the edit log breakpoint action -## Starting a Debugger Session +## Settings -A debugger session can be started by the Start Debugging action or clicking the "Choose Debugger" button in the debugger panel when there are no active sessions. +- `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 -Zed supports having multiple sessions +### 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