|
1 | | -# Dlv DAP - Delve's native DAP implementationa |
| 1 | +# Dlv DAP - Delve's native DAP implementation |
2 | 2 |
|
3 | 3 | [`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. |
4 | 4 |
|
5 | | -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 recommend that `dlv` be installed at master to get all recent updates. |
| 5 | +_________________ |
| 6 | +**🔥 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.** |
| 7 | +_________________ |
6 | 8 |
|
| 9 | +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`. |
| 10 | + |
| 11 | +This new debug adapter runs in a separate `go` process, which is spawned by VS Code when you debug Go code. |
| 12 | +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)). |
| 13 | + |
| 14 | + |
| 15 | +## Getting Started |
| 16 | + |
| 17 | +You can select the default debug adapter to use in all launch configurations and codelenses through the `"debugAdapter"` field in the [`"go.delveConfig"`](settings.md#go.delveConfig) setting. You can choose which debug adapter to use for individual launch configurations 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). |
| 18 | +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. |
| 19 | + |
| 20 | +<div style="text-align: center;"><img src="images/createlaunchjson.png" width=200 alt="The debug pane with the option to create launch.json"> </div> |
| 21 | + |
| 22 | +In your launch configuration, set the `"debugAdapter"` field to be `"dlv-dap"`. For example, a launch configuration for a file would look like: |
| 23 | + |
| 24 | +```json5 |
| 25 | +{ |
| 26 | + "name": "Launch file", |
| 27 | + "type": "go", |
| 28 | + "request": "launch", |
| 29 | + "mode": "auto", |
| 30 | + "program": "${fileDirname}", |
| 31 | + "debugAdapter": "dlv-dap" |
| 32 | +} |
7 | 33 | ``` |
8 | | -$ GO111MODULES=on go get github.com/go-delve/delve@master |
| 34 | + |
| 35 | +To switch back to the legacy adapter, set `"debugAdapter"` to `"legacy"`. |
| 36 | + |
| 37 | +When you start debugging using the configuration for the first time, the extension will ask you to install `dlv-dap`. |
| 38 | + |
| 39 | +<div style="text-align: center;"><img src="images/dlv-dap-install-prompt.gif" width=350 alt="missing tool notification"> </div> |
| 40 | + |
| 41 | +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). |
| 42 | + |
| 43 | +### Updating dlv dap |
| 44 | +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. |
| 45 | + |
| 46 | +If you want to install it manually, `go get` with the following command and rename it to `dlv-dap`. |
| 47 | + |
9 | 48 | ``` |
| 49 | +$ GO111MODULE=on GOBIN=/tmp/ go get github.com/go-delve/delve/cmd/dlv@master |
| 50 | +$ mv /tmp/dlv $GOPATH/bin/dlv-dap |
| 51 | +``` |
| 52 | + |
| 53 | +## Features and Caveats |
| 54 | +<!-- TODO: update the debugging section of features.md using dlv-dap mode --> |
| 55 | + |
| 56 | +🎉 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. |
10 | 57 |
|
11 | | -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)). |
| 58 | +* User-friendly inlined presentation of variables of all complex types (map, struct, pointer, array, slice, ...) |
| 59 | +* Fixed handling of maps with compound keys |
| 60 | +* Improved CALL STACK presentation |
| 61 | +* Fixed automated "Add to Watch" / "Copy as Expression" expressions. |
| 62 | +* Support to switch goroutines while stepping. |
| 63 | +* Robust `call` evaluation. |
| 64 | +* Good test coverage. |
| 65 | + |
| 66 | + |
| 67 | +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> |
| 68 | +Because it is native, we hope for improvement in speed and reliability. |
| 69 | + |
| 70 | +⚒️ The following features are still under development. |
| 71 | + |
| 72 | +* Stop/pause/restart while the debugged program is running does not work yet. |
| 73 | +* Cannot be used with `debug test` codelens. |
| 74 | +* Support for `"dlvFlags"` attributes in launch configuration is not available. |
| 75 | +* `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. |
| 76 | +* [Remote debugging](https://github.com/golang/vscode-go/blob/master/docs/debugging.md#remote-debugging) is not supported. |
12 | 77 |
|
13 | 78 | 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. |
14 | 79 |
|
15 | | -## Overview |
| 80 | +## Reporting issues |
16 | 81 |
|
17 | | -* [How to use dlv dap](#how-to-use-dlv-dap) |
| 82 | +The VS Code Go maintainers are reachable via the issue tracker and the #vscode-dev channel in the Gophers Slack. </br> |
| 83 | +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. |
18 | 84 |
|
19 | | -## How to use dlv dap |
| 85 | +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). |
20 | 86 |
|
21 | | -You can choose which debug adapter to use with the `"debugAdapter"` field in your launch configuration. 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. |
| 87 | +Please report issues in [our issue tracker](https://github.com/golang/vscode-go/issues) with the following information. |
22 | 88 |
|
23 | | -<div style="text-align: center;"><img src="images/createlaunchjson.png" alt="The debug pane with the option to create launch.json"> </div> |
| 89 | +* `go version` |
| 90 | +* `go version -m dlv-dap` |
| 91 | +* VS Code and VS Code Go version. |
| 92 | +* Instruction to reproduce the issue (code snippets, your `launch.json`, screenshot) |
24 | 93 |
|
25 | | -In your launch configuration, set the `"debugAdapter"` field to be `"dlv-dap"`. For example, a launch configuration for a file would look like: |
| 94 | +## Developing |
| 95 | + |
| 96 | +### Code location |
| 97 | +The core part of Delve DAP implementation is in the [`service/dap`](https://github.com/go-delve/delve/tree/master/service/dap) package. Follow Delve project's [contribution guideline](https://github.com/go-delve/delve/blob/master/CONTRIBUTING.md#contributing-code) to send PRs. |
| 98 | +Code for integration with the Go extension is mostly in [`src/goDebugFactory.ts`](https://github.com/golang/vscode-go/blob/master/src/goDebugFactory.ts) and tests are in [`test/integration/goDebug.test.ts`](https://github.com/golang/vscode-go/blob/master/test/integration/goDebug.test.ts). Please take a look at VS Code Go project's [contribution guideline](https://github.com/golang/vscode-go/blob/master/docs/contributing.md) to learn about how to prepare a change and send it for review. |
| 99 | + |
| 100 | +### Testing |
| 101 | +For simple launch cases, build the delve binary, and configure `"go.alternateTools"` setting. |
26 | 102 |
|
| 103 | +```json5 |
| 104 | +"go.alternateTools": { |
| 105 | + "dlv-dap": <path_to_your_delve> |
| 106 | +} |
| 107 | +``` |
| 108 | + |
| 109 | +Set `logOutput` and `showLog` attributes in `launch.json` to enable logging and DAP message tracing. |
27 | 110 | ```json5 |
28 | 111 | { |
29 | 112 | "name": "Launch file", |
30 | 113 | "type": "go", |
31 | | - "request": "launch", |
32 | | - "mode": "auto", |
33 | | - "program": "${file}", |
34 | | - "debugAdapter": "dlv-dap" |
| 114 | + "debugAdapter": "dlv-dap", |
| 115 | + "showLog": true, |
| 116 | + "logOutput": "dap", |
| 117 | + ... |
35 | 118 | } |
36 | 119 | ``` |
37 | 120 |
|
38 | | -To switch back to the legacy adapter, set `"debugAdapter"` to `"legacy"`. |
| 121 | +If you are having issues with seeing logs and or suspect problems in extension's integration, you can start Delve DAP server from a separate terminal and configure the extension to directly connect to it. |
| 122 | + |
| 123 | +``` |
| 124 | +$ dlv-dap dap --listen=:12345 --log-output=dap |
| 125 | +``` |
| 126 | + |
| 127 | +```json5 |
| 128 | +{ |
| 129 | + "name": "Launch file", |
| 130 | + "type": "go", |
| 131 | + "request": "launch", |
| 132 | + "debugAdapter": "dlv-dap", |
| 133 | + ... |
| 134 | + "port": 12345 |
| 135 | +} |
| 136 | +``` |
0 commit comments