From b501de3e1a743769e52717097d4976b16ef6cf73 Mon Sep 17 00:00:00 2001 From: "Hana (Hyang-Ah) Kim" Date: Fri, 19 Apr 2024 12:33:28 -0400 Subject: [PATCH] Revert "docs: update the debugging doc about remote mode default adapter" This reverts commit 5b0d6db961e2b0a346d2984b0d10d8137cc5aba5. Reason for revert: Need to address path mapping issue: golang/vscode-go#3175 Change-Id: Iade1d9f2438993025ac1ef5ec9ad6f1213d79ed6 Reviewed-on: https://go-review.googlesource.com/c/vscode-go/+/580019 kokoro-CI: kokoro Commit-Queue: Hyang-Ah Hana Kim Reviewed-by: Robert Findley Auto-Submit: Hyang-Ah Hana Kim --- docs/debugging-legacy.md | 4 +++- docs/debugging.md | 34 +++++++++++++++++++++++++++------- 2 files changed, 30 insertions(+), 8 deletions(-) diff --git a/docs/debugging-legacy.md b/docs/debugging-legacy.md index 734b6c5e16..6af77db32b 100644 --- a/docs/debugging-legacy.md +++ b/docs/debugging-legacy.md @@ -2,7 +2,7 @@ The Go extension historically used a small adapter program to work with the Go debugger, [Delve]. The extension transitioned to communicate with [Delve] directly but there are still cases you may -need to use the legacy debug adapter. This document explains how to use the +need to use the legacy debug adapter (e.g. remote debugging). This document explains how to use the ***legacy*** debug adapter. @@ -45,6 +45,8 @@ To opt in to use the legacy debug adapter (`legacy`) by default, add the followi ``` If you want to use the legacy mode for only a subset of your launch configurations, you can use [the `debugAdapter` attribute](#launchjson-attributes) to switch between `"dlv-dap"` and `"legacy"` mode. +For [Remote Debugging](#remote-debugging) (launch configuration with `"mode": "remote"` attribute), +the extension will use the `"legacy"` mode by default, so setting this attribute won't be necessary. Throughout this document, we assume that you opted in to use the legacy debug adapter. For debugging using the new debug adapter (default, `"dlv-dap"` mode), please see the documentation about [Debugging](https://github.com/golang/vscode-go/tree/master/docs/debugging-legacy.md). diff --git a/docs/debugging.md b/docs/debugging.md index 044519f458..643e9a3573 100644 --- a/docs/debugging.md +++ b/docs/debugging.md @@ -6,8 +6,26 @@ activities using [VS Code’s Debugging UI](https://code.visualstudio.com/docs/editor/debugging). These debugging features are possible by using -[Delve](https://github.com/go-delve/delve), the Go debugger, and its -[native debug adapter implementation](https://github.com/go-delve/delve/tree/master/service/dap). +[Delve](https://github.com/go-delve/delve), the Go debugger. + +Previously, the Go extension communicated with Delve through a custom debug +adaptor program (`legacy` mode). Since +[`Delve`'s native debug adapter implementation](https://github.com/go-delve/delve/tree/master/service/dap) +is available, the Go extension is transitioning to deprecate the legacy debug +adapter in favor of direct communication with Delve via +[DAP](https://microsoft.github.io/debug-adapter-protocol/overview). + + + 📣 **We are happy to announce that the new _`dlv-dap`_ mode of Delve + integration is enabled for _local_ _debugging_ by default. For + [_remote_ _debugging_](#remote-debugging) it is the default in + [Go Nightly](nightly.md) and is available with stable builds on demand with + `"debugAdapter": "dlv-dap"` attribute in `launch.json` or `settings.json`!** + +Many features and settings described in this document may be available only with +the new `dlv-dap` mode. For troubleshooting and configuring the legacy debug +adapter, see +[the legacy debug adapter documentation](https://github.com/golang/vscode-go/tree/master/docs/debugging-legacy.md). ## Get started @@ -64,9 +82,7 @@ from the tree head. ### Switch to legacy debug adapter -Previously, the Go extension communicated with Delve through a custom debug -adaptor program (aka `legacy` mode). This legacy adapter is no longer maintained -and will be removed by the end of 2024 H2. +Note: The extension still uses the legacy debug adapter for remote debugging. If you need to use the legacy debug adapter for local debugging (`legacy` mode) by default, add the following in your VSCode settings. @@ -77,6 +93,9 @@ by default, add the following in your VSCode settings. } ``` +When `mode` is set to `remote` you must explicitly set `debugAdapter` to +`dlv-dap` to override the legacy adapter default. + If you want to switch to `legacy` for only a subset of your launch configurations, you can use [the `debugAdapter` attribute](#launchjson-attributes) to switch between @@ -790,8 +809,8 @@ with a running target. The [headless dlv server](https://github.com/go-delve/delve/tree/master/Documentation/api) -can now be used with both `"debugAdapter": "dlv-dap"` (default) and -`"debugAdapter": "legacy"` (with Delve v1.7.3 or newer) as well as Delve's +can now be used with both `"debugAdapter": "legacy"` (default value) and +`"debugAdapter": "dlv-dap"` (with Delve v1.7.3 or newer) as well as Delve's [command-line interface](https://github.com/go-delve/delve/tree/master/Documentation/cli) via `dlv connect`. The `--accept-multiclient` flag makes this a multi-use server that persists on `Disconnect` from a client and allows repeated connections from @@ -818,6 +837,7 @@ Connect to it with a remote attach configuration in your `launch.json`: { "name": "Connect to external session", "type": "go", + "debugAdapter": "dlv-dap", // `legacy` by default "request": "attach", "mode": "remote", "port": 12345,