docs/dlv-dap: add the link to the list of dlv-dap only features
And rearrange to highlight 'getting started' step more.
Added the tool installation popup screenshot.
Change-Id: Icedc7dbc2ebf64550cee7716844519e315d64099
Reviewed-on: https://go-review.googlesource.com/c/vscode-go/+/307609
Trust: Hyang-Ah Hana Kim <hyangah@gmail.com>
Reviewed-by: Polina Sokolova <polina@google.com>
diff --git a/docs/dlv-dap.md b/docs/dlv-dap.md
index a79a5f8..ca0d9cc 100644
--- a/docs/dlv-dap.md
+++ b/docs/dlv-dap.md
@@ -2,25 +2,22 @@
[`Delve`'s native DAP implementation](https://github.com/go-delve/delve/tree/master/service/dap) is now available to be used to debug Go programs.
-This debug adapter runs in a separate `go` process, which is spawned by VS Code when you debug Go code. Since `dlv dap` is under active development, we need the Delve built at master to get all recent updates. The Go extension currently maintains this unstable version of Delve separately from the stable version (`dlv`), and installs it as `dlv-dap`.
+_________________
+**🔥 This new adapter is still in active development, so to take advantage of the most recent features and bug fixes, you need to use Delve built from the dev branch. When the extension asks to install/update `dlv-dap`, please follow the instruction and rebuild the tool.**
+_________________
-Please see the [Debug Adapter Protocol (DAP)](https://microsoft.github.io/debug-adapter-protocol/) to understand how the Debug Adapter acts as an intermediary between VS Code and the debugger ([Delve](https://github.com/go-delve/delve)).
+The Go extension currently maintains this development version of Delve separately from the stable version of `dlv`. This version is installed with the name `dlv-dap`. Please follow the instruction in [Getting Started](#getting-started) to configure the extension and install `dlv-dap`.
-Follow along with [golang/vscode-go#23](https://github.com/golang/vscode-go/issues/23) and the [project dashboard](https://github.com/golang/vscode-go/projects/3) for updates on the implementation.
+This new debug adapter runs in a separate `go` process, which is spawned by VS Code when you debug Go code.
+Please see the [Debug Adapter Protocol (DAP)](https://microsoft.github.io/debug-adapter-protocol/) to learn about how the Debug Adapter acts as an intermediary between VS Code and the debugger ([Delve](https://github.com/go-delve/delve)).
-## Overview
-* [How to use dlv dap](#how-to-use-dlv-dap)
-* [Features & Caveats](#features-and-caveats)
-* [Reporting issues](#reporting-issues)
-* [How to contribute](#developing)
+## Getting Started
-## How to use dlv dap
-
-You can choose which debug adapter to use with the `"debugAdapter"` field in [your `launch.json` configuration](https://github.com/golang/vscode-go/blob/master/docs/debugging.md#snippets). Most settings will continue to work with in `"dlv-dap" debugAdapter` mode except [a few caveats](#features-and-caveats).
+You can choose which debug adapter to use with the `"debugAdapter"` field in [your `launch.json` configuration](https://github.com/golang/vscode-go/blob/master/docs/debugging.md#snippets). Most settings will continue to work with in this new `"dlv-dap"` mode except [a few caveats](#features-and-caveats).
If you do not already have a `launch.json`, select `create a launch.json file` from the debug pane and choose an initial Go debug configuration.
-<div style="text-align: center;"><img src="images/createlaunchjson.png" alt="The debug pane with the option to create launch.json"> </div>
+<div style="text-align: center;"><img src="images/createlaunchjson.png" width=200 alt="The debug pane with the option to create launch.json"> </div>
In your launch configuration, set the `"debugAdapter"` field to be `"dlv-dap"`. For example, a launch configuration for a file would look like:
@@ -30,13 +27,19 @@
"type": "go",
"request": "launch",
"mode": "auto",
- "program": "${file}",
+ "program": "${fileDirname}",
"debugAdapter": "dlv-dap"
}
```
To switch back to the legacy adapter, set `"debugAdapter"` to `"legacy"`.
+When you start debugging using the configuration for the first time, the extension will ask you to install `dlv-dap`.
+
+<div style="text-align: center;"><img src="images/dlv-dap-install-prompt.gif" width=350 alt="missing tool notification"> </div>
+
+Once `dlv-dap` is installed, the extension will prompt you for update whenever installing a newer version is necessary (usually after the Go extension update).
+
### Updating dlv dap
The easiest way is to use the `"Go: Install/Update Tools"` command from the command palette (⇧+⌘+P or Ctrl+Shift+P). The command will show `dlv-dap` in the tool list. Select it, and the extension will build the tool at master.
@@ -48,28 +51,45 @@
```
## Features and Caveats
+<!-- TODO: update the debugging section of features.md using dlv-dap mode -->
-Dlv DAP implementation offers the following advantages:
-* Better map key presentation. ([Issue 1267](https://github.com/golang/vscode-go/issues/1267#issuecomment-800607474))
-<!-- TODO(polinasok,suzmue): add more unique features -->
+🎉 The new debug adapter offers many improvements and fixes bugs that existed in the old adapter. [Here](https://github.com/golang/vscode-go/issues?q=is%3Aissue+label%3Afixedindlvdaponly) is a partial list of enhancement/fixes available only in the new adapter.
-The following features are still under development.
+* User-friendly inlined presentation of variables of all complex types (map, struct, pointer, array, slice, ...)
+* Fixed handling of maps with compound keys
+* Improved CALL STACK presentation
+* Fixed automated "Add to Watch" / "Copy as Expression" expressions.
+* Support to switch goroutines while stepping.
+* Robust `call` evaluation.
+* Good test coverage.
-* Stop/pause/restart while the debugged program is running does not work.
+
+Most of all, the new adapter is written in Go and integrated in `dlv`. That will make it easier for the Go community to contribute. </br>
+Because it is native, we hope for improvement in speed and reliability.
+
+⚒️ The following features are still under development.
+
+* Stop/pause/restart while the debugged program is running does not work yet.
* Cannot be used with `debug test` codelens.
* Support for `"dlvFlags"` attributes in launch configuration is not available.
* `dlvLoadConfig` to configure max string/bytes length in [`"go.delveConfig"`](https://github.com/golang/vscode-go/blob/master/docs/debugging.md#configuration) does not work.
* [Remote debugging](https://github.com/golang/vscode-go/blob/master/docs/debugging.md#remote-debugging) is not supported.
+Follow along with [golang/vscode-go#23](https://github.com/golang/vscode-go/issues/23) and the [project dashboard](https://github.com/golang/vscode-go/projects/3) for updates on the implementation.
+
## Reporting issues
-The VS Code Go maintainers are reachable via the issue tracker and the #vscode-dev channel in the Gophers Slack. Please reach out on Slack with questions, suggestions, or ideas. If you have trouble getting started on an issue, we'd be happy to give pointers and advice.
+The VS Code Go maintainers are reachable via the issue tracker and the #vscode-dev channel in the Gophers Slack. </br>
+Please reach out on Slack with questions, suggestions, or ideas. If you have trouble getting started on an issue, we'd be happy to give pointers and advice.
+
+When you are having issues in `dlv-dap` mode, first check if the problems are reproducible after updating `dlv-dap`. It's possible that the issues are already fixed. Follow the instruction for [updating dlv-dap](#updating-dlv-dap)) and [updating extension](https://code.visualstudio.com/docs/editor/extension-gallery#_extension-autoupdate).
Please report issues in [our issue tracker](https://github.com/golang/vscode-go/issues) with the following information.
* `go version`
* `go version -m dlv-dap`
-* Instruction to reproduce the issue (code snippets, `launch.json`, screenshot)
+* VS Code and VS Code Go version.
+* Instruction to reproduce the issue (code snippets, your `launch.json`, screenshot)
## Developing
@@ -91,11 +111,10 @@
{
"name": "Launch file",
"type": "go",
- "request": "launch",
"debugAdapter": "dlv-dap",
"showLog": true,
+ "logOutput": "dap",
...
- "logOutput": "dap"
}
```
@@ -114,4 +133,4 @@
...
"port": 12345
}
-```
\ No newline at end of file
+```
diff --git a/docs/images/dlv-dap-install-prompt.gif b/docs/images/dlv-dap-install-prompt.gif
new file mode 100644
index 0000000..03c9c9e
--- /dev/null
+++ b/docs/images/dlv-dap-install-prompt.gif
Binary files differ
