From 908ae95cf86930893140bee37cf37c8918ac90e8 Mon Sep 17 00:00:00 2001 From: Mikayla Maki Date: Thu, 16 Oct 2025 17:36:47 -0700 Subject: [PATCH] docs: Improve debug adapter documentation (#40441) docs. docs. docs. Release Notes: - N/A --- docs/src/debugger.md | 8 +++++--- docs/src/languages/c.md | 3 +++ docs/src/languages/cpp.md | 3 +++ docs/src/languages/go.md | 4 +++- docs/src/languages/javascript.md | 12 ++++++++---- docs/src/languages/python.md | 2 ++ docs/src/languages/rust.md | 5 ++++- docs/src/languages/swift.md | 2 ++ docs/src/languages/typescript.md | 8 +++++++- 9 files changed, 37 insertions(+), 10 deletions(-) diff --git a/docs/src/debugger.md b/docs/src/debugger.md index 88d5dc78f165bd7f631b0ca69c46418979df15d7..ed2d6782cfbbbde8bf9b6d390eadbbb4a65d7eb1 100644 --- a/docs/src/debugger.md +++ b/docs/src/debugger.md @@ -68,7 +68,9 @@ Compared to launching, attaching to an existing process might seem inferior, but ## Configuration -While configuration fields are debug adapter-dependent, most adapters support the following fields: +Zed requires the `adapter` and `label` fields for all debug tasks. In addition, Zed will use the `build` field to run any necessary setup steps before the debugger starts [(see below)](#build-tasks), and can accept a `tcp_connection` field to connect to an existing process. + +All other fields are provided by the debug adapter and can contain [task variables](./tasks.md#variables). Most adapters support `request`, `program`, and `cwd`: ```json [debug] [ @@ -89,11 +91,11 @@ While configuration fields are debug adapter-dependent, most adapters support th ] ``` -All configuration fields support [task variables](./tasks.md#variables). +Check your debug adapter's documentation for more information on the fields it supports. ### Build tasks -Zed 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. +Zed allows embedding a Zed task in the `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. ```json [debug] [ diff --git a/docs/src/languages/c.md b/docs/src/languages/c.md index ca84cd54de02c86721c7ca92022b53fffb8ce97f..7f6e0ba6b2ed24dd958c02a7606e2a569d08f8f1 100644 --- a/docs/src/languages/c.md +++ b/docs/src/languages/c.md @@ -67,6 +67,9 @@ After building your project, CMake will generate the `compile_commands.json` fil You can use CodeLLDB or GDB to debug native binaries. (Make sure that your build process passes `-g` to the C compiler, so that debug information is included in the resulting binary.) See below for examples of debug configurations that you can add to `.zed/debug.json`. +- [CodeLLDB configuration documentation](https://github.com/vadimcn/codelldb/blob/master/MANUAL.md#starting-a-new-debug-session) +- [GDB configuration documentation](https://sourceware.org/gdb/current/onlinedocs/gdb.html/Debugger-Adapter-Protocol.html) + ### Build and Debug Binary ```json [debug] diff --git a/docs/src/languages/cpp.md b/docs/src/languages/cpp.md index ce4c163cf9d310e114c30c63e228b39aefe3e82c..90e1934c16b5ff62b1eb8611c06af4c04cfa879d 100644 --- a/docs/src/languages/cpp.md +++ b/docs/src/languages/cpp.md @@ -135,6 +135,9 @@ After building your project, CMake will generate the `compile_commands.json` fil You can use CodeLLDB or GDB to debug native binaries. (Make sure that your build process passes `-g` to the C++ compiler, so that debug information is included in the resulting binary.) See below for examples of debug configurations that you can add to `.zed/debug.json`. +- [CodeLLDB configuration documentation](https://github.com/vadimcn/codelldb/blob/master/MANUAL.md#starting-a-new-debug-session) +- [GDB configuration documentation](https://sourceware.org/gdb/current/onlinedocs/gdb.html/Debugger-Adapter-Protocol.html) + ### Build and Debug Binary ```json [debug] diff --git a/docs/src/languages/go.md b/docs/src/languages/go.md index d8125953f42b96bfcff69998bb6ce60cbb655a0f..3c4e505f8f1e64f91fc6945b2d614895a106ea20 100644 --- a/docs/src/languages/go.md +++ b/docs/src/languages/go.md @@ -75,10 +75,12 @@ See [gopls inlayHints documentation](https://github.com/golang/tools/blob/master ## Debugging -Zed supports zero-configuration debugging of Go tests and entry points (`func main`). Run {#action debugger::Start} ({#kb debugger::Start}) to see a contextual list of these preconfigured debug tasks. +Zed supports zero-configuration debugging of Go tests and entry points (`func main`) using Delve. Run {#action debugger::Start} ({#kb debugger::Start}) to see a contextual list of these preconfigured debug tasks. For more control, you can add debug configurations to `.zed/debug.json`. See below for examples. +- [Delve configuration documentation](https://github.com/go-delve/delve/blob/master/Documentation/api/dap/README.md#launch-and-attach-configurations) + ### Debug Go Packages To 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. diff --git a/docs/src/languages/javascript.md b/docs/src/languages/javascript.md index 77cee5d9f4ac8e87b07f778528b1cf96676eaed8..98018ce60e6990ea47eebed294e25961f1849637 100644 --- a/docs/src/languages/javascript.md +++ b/docs/src/languages/javascript.md @@ -175,7 +175,7 @@ You can configure ESLint's `workingDirectory` setting: ## Debugging -Zed supports debugging JavaScript code out of the box. +Zed supports debugging JavaScript code out of the box with `vscode-js-debug`. The following can be debugged without writing additional configuration: - Tasks from `package.json` @@ -191,7 +191,13 @@ As for all languages, configurations from `.vscode/launch.json` are also availab If your use-case isn't covered by any of these, you can take full control by adding debug configurations to `.zed/debug.json`. See below for example configurations. -### Debug the current file +### Configuring JavaScript debug tasks + +JavaScript debugging is more complicated than other languages because there are two different environments: Node.js and the browser. `vscode-js-debug` exposes a `type` field, that you can use to specify the environment, either `node` or `chrome`. + +- [vscode-js-debug configuration documentation](https://github.com/microsoft/vscode-js-debug/blob/main/OPTIONS.md) + +### Debug the current file with Node ```json [debug] [ @@ -206,8 +212,6 @@ If your use-case isn't covered by any of these, you can take full control by add ] ``` -This implicitly runs the current file using `node`. - ### Launch a web app in Chrome ```json [debug] diff --git a/docs/src/languages/python.md b/docs/src/languages/python.md index 87e5abeaa3bc5985d8f46555454176fb4e818669..204258a8e736dc68ef51e338ecb0ee8ba7e0a737 100644 --- a/docs/src/languages/python.md +++ b/docs/src/languages/python.md @@ -275,6 +275,8 @@ Zed uses `debugpy` under the hood, but no manual adapter configuration is requir For reusable setups, create a `.zed/debug.json` file in your project root. This gives you more control over how Zed runs and debugs your code. +- [debugpy configuration documentation](https://github.com/microsoft/debugpy/wiki/Debug-configuration-settings#launchattach-settings) + #### Debug Active File ```json [debug] diff --git a/docs/src/languages/rust.md b/docs/src/languages/rust.md index 3d4fe3f8eeb3801a3b87b5c5d0c0c5028f30786b..d696cfe41129b2d4405a40d7d82ed3790a5888b2 100644 --- a/docs/src/languages/rust.md +++ b/docs/src/languages/rust.md @@ -294,10 +294,13 @@ There's a way to get custom completion items from rust-analyzer, that will trans ## Debugging -Zed supports debugging Rust binaries and tests out of the box. Run {#action debugger::Start} ({#kb debugger::Start}) to launch one of these preconfigured debug tasks. +Zed supports debugging Rust binaries and tests out of the box with `CodeLLDB` and `GDB`. Run {#action debugger::Start} ({#kb debugger::Start}) to launch one of these preconfigured debug tasks. For more control, you can add debug configurations to `.zed/debug.json`. See the examples below. +- [CodeLLDB configuration documentation](https://github.com/vadimcn/codelldb/blob/master/MANUAL.md#starting-a-new-debug-session) +- [GDB configuration documentation](https://sourceware.org/gdb/current/onlinedocs/gdb.html/Debugger-Adapter-Protocol.html) + ### Build binary then debug ```json [debug] diff --git a/docs/src/languages/swift.md b/docs/src/languages/swift.md index 3462083a3135930d78dec0b2b72e5942c0103b1e..1492942fe8d33e63949ad0037b12405c373a9770 100644 --- a/docs/src/languages/swift.md +++ b/docs/src/languages/swift.md @@ -18,6 +18,8 @@ Zed's name for the adapter (in the UI and `debug.json`) is `Swift`, and under th The extension tries to find an `lldb-dap` binary using `swiftly`, using `xcrun`, and by searching `$PATH`, in that order of preference. The extension doesn't attempt to download `lldb-dap` if it's not found. +- [lldb-dap configuration documentation](https://github.com/llvm/llvm-project/blob/main/lldb/tools/lldb-dap/README.md#configuration-settings-reference) + ### Examples #### Build and debug a Swift binary diff --git a/docs/src/languages/typescript.md b/docs/src/languages/typescript.md index 8df4a1685d1dc75a6c9ae32d8ee77a3b09599c0b..a6ec5b71ecb1815aeb4ff3811eec6f9a5c57a54b 100644 --- a/docs/src/languages/typescript.md +++ b/docs/src/languages/typescript.md @@ -158,7 +158,7 @@ When using `vtsls`: ## Debugging -Zed supports debugging TypeScript code out of the box. +Zed supports debugging TypeScript code out of the box with `vscode-js-debug`. The following can be debugged without writing additional configuration: - Tasks from `package.json` @@ -174,6 +174,12 @@ As for all languages, configurations from `.vscode/launch.json` are also availab If your use-case isn't covered by any of these, you can take full control by adding debug configurations to `.zed/debug.json`. See below for example configurations. +### Configuring JavaScript debug tasks + +JavaScript debugging is more complicated than other languages because there are two different environments: Node.js and the browser. `vscode-js-debug` exposes a `type` field, that you can use to specify the environment, either `node` or `chrome`. + +- [vscode-js-debug configuration documentation](https://github.com/microsoft/vscode-js-debug/blob/main/OPTIONS.md) + ### Attach debugger to a server running in web browser (`npx serve`) Given 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.