[vscode-go] docs/dlv-dap: add features and images
592 views
Skip to first unread message
Hyang-Ah Hana Kim (Gerrit)
Jun 25, 2021, 10:34:50 PM6/25/21
to Hyang-Ah Hana Kim, goph...@pubsubhelper.golang.org, golang-...@googlegroups.com, kokoro, Suzy Mueller, Polina Sokolova, golang-co...@googlegroups.com
Hyang-Ah Hana Kim submitted this change.
Approvals:
Suzy Mueller: Looks good to me, approved; Trusted
Hyang-Ah Hana Kim: Trusted; Run TryBots
kokoro: TryBots succeeded
docs/dlv-dap: add features and images
Change-Id: I0316746d67020cf3af4ccff35208e903f130bd98
Reviewed-on: https://go-review.googlesource.com/c/vscode-go/+/331051
Trust: Hyang-Ah Hana Kim <hya...@gmail.com>
Trust: Suzy Mueller <suz...@golang.org>
Run-TryBot: Hyang-Ah Hana Kim <hya...@gmail.com>
TryBot-Result: kokoro <noreply...@google.com>
Reviewed-by: Suzy Mueller <suz...@golang.org>
---
M docs/dlv-dap.md
A docs/images/attach-terminate.gif
A docs/images/attach.gif
A docs/images/callstack-section-annotated.gif
A docs/images/conditional-breakpoint.gif
A docs/images/create-launch-json.gif
A docs/images/debug-console.png
A docs/images/debug-output.png
A docs/images/debug-toolbar.png
A docs/images/dlv-load-config-warning.png
A docs/images/dlvdap-install.gif
A docs/images/function-breakpoint.gif
A docs/images/invalid-breakpoint.png
A docs/images/panicinfo.png
A docs/images/remote-debugging.png
A docs/images/shadowed-variables.png
A docs/images/variable-hover.png
A docs/images/variables.png
A docs/images/vscode-go-debug-arch.png
19 files changed, 374 insertions(+), 70 deletions(-)
diff --git a/docs/dlv-dap.md b/docs/dlv-dap.md
index 85462e2..de2c410 100644
--- a/docs/dlv-dap.md
+++ b/docs/dlv-dap.md
@@ -1,92 +1,237 @@
-# Dlv DAP - Delve's native DAP implementation
+# Debugging using Delve DAP (aka `dlv-dap`)
-[`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.
+The Go extension allows you to launch or attach to Go programs for debugging. You can inspect variables and stacks, setting breakpoints, and do other debugging activities using [VS Code’s Debugging UI](https://code.visualstudio.com/docs/editor/debugging).
-_________________
-**🔥 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.**
-_________________
+These debugging features are possible by using [Delve](https://github.com/go-delve/delve), the Go debugger. The Go extension has been communicating with Delve through a custom debug adapter program. As the new [`Delve`'s native DAP implementation](https://github.com/go-delve/delve/tree/master/service/dap) becomes available, the Go extension is now transitioning to skip the legacy debug adapter and directly communicate with 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`.
+> 📣We are happy to announce that now this new mode of Delve integration (`dlv-dap` mode) is ready for use in local debugging! We plan to make it default sometime in 2021 H2.
-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)).
+In this document, we assume you are using the new Delve's native debug adapter implementation (`dlv-dap`).
+<!-- TOC -->
-## Getting Started
+## **Getting Started**
-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).
-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" 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:
-
-```json5
-{
- "name": "Launch file",
- "type": "go",
- "request": "launch",
- "mode": "auto",
- "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.
-
-If you want to install it manually, `go get` with the following command and rename it to `dlv-dap`.
+To opt in to use this new adapter (`dlv-dap`), add the following in your VSCode settings.json.
```
-$ GO111MODULE=on GOBIN=/tmp/ go get github.com/go-delve/delve/cmd/dlv@master
-$ mv /tmp/dlv $GOPATH/bin/dlv-dap
+ "go.delveConfig": {
+ "debugAdapter": "dlv-dap",
+ }
```
-## Features and Caveats
-<!-- TODO: update the debugging section of features.md using dlv-dap mode -->
+If you want to use dlv-dap for only a subset of your launch configurations, you can use
+[the `debugAdapter` attribute](#launchjson-attributes) to switch between “dlv-dap” and “legacy” mode. If you are using [the Nightly version of this extension](https://github.com/golang/vscode-go/blob/master/docs/nightly.md#go-nightly), dlv-dap is already the default debug adapter for local debugging scenarios, so the above setting is unnecessary.
-🎉 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.
+### Start Debugging
-* User-friendly inlined presentation of variables of all complex types (map, struct, pointer, array, slice, ...)
-* Auto-loading of nested variables without extra configuration. (See [delve PR/2455](https://github.com/go-delve/delve/pull/2455#issuecomment-827884652))
-* 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.
+Open a file to debug (either `package main` source file or the test file) in the editor, and select the `Run and Debug` button from [the Run view](https://code.visualstudio.com/docs/editor/debugging#_run-view). Alternatively, you can start debugging using `Start Debugging (F5)` command from [the Run menu](https://code.visualstudio.com/docs/editor/debugging#_run-menu) or from the Command Palette.
-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.
+When no configuration is configured yet (no `launch.json`), the extension will choose a default configuration based on the file open in the editor.
-💡 Notes:
+If you already have launch configurations for the project (.vscode/launch.json), the Run view will display the configuration list you can choose from.
-* `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. For large strings, use `DEBUG CONSOLE`, "Copy Value", or hover in editor. The new debug adapter supports [paging of large arrays, bytes, and maps](https://github.com/go-delve/delve/pull/2512#issuecomment-849021775) instead.
-* Traditional [remote debugging](https://github.com/golang/vscode-go/blob/master/docs/debugging.md#remote-debugging) is not supported yet (Work-In-Progress).
+❗When you start debugging in `dlv-dap` mode for the first time, the extension will ask to install the Delve built from the head (`dlv-dap`). Please follow the instructions, and start the debugging session again (i.e. selecting the source file, pressing F5 or click the codelens).
-## Reporting issues
-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.
+<p align="center">
+<img src="images/dlvdap-install.gif" alt="Delve DAP Install" width="75%">
+</p>
-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).
+<div style="text-align: center;"></div>
-Please report issues in [our issue tracker](https://github.com/golang/vscode-go/issues) with the following information.
-* `go version`
-* `go version -m <path/to/dlv-dap>`
-* VS Code and VS Code Go version.
-* Instruction to reproduce the issue (code snippets, your `launch.json`, screenshot)
+Watch [“Go: Writing and debugging fast, reliable, and efficient software”](https://www.youtube.com/watch?v=6r08zGi38Tk&list=PLj6YeMhvp2S40Q-TEPEKOeypLvTVd5uME&index=1) to learn more about debugging features.
+
+Please review
+[the Features section](#features) that provides an overview of the debug UI and available features.
+
+### Staying Up-To-Date
+
+[Delve’s native DAP implementation](https://github.com/go-delve/delve/tree/master/service/dap) is under active development, so take advantage of the most recent features and bug fixes by using Delve built from its master branch. The Go extension maintains this newest version of Delve separately from the officially released version of ‘dlv’ and installs it with the name `dlv-dap`.
+
+The easiest way to update `dlv-dap` on demand 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 `dlv-dap`, and the extension will build the tool at master.
+
+Once `dlv-dap` is installed on your system, the extension will prompt you for update whenever installing a newer version is necessary (usually after the Go extension upgrade). You can set the ``go.toolsManagement.autoUpdate`` setting so the extension can update `dlv-dap` automatically for you.
+
+If you need to install `dlv-dap` manually outside of VS Code (for example, you are building a dev container with necessary tools preinstalled), please see the [Manual Installation](#bookmark=id.xuaxofprncd5) section.
+
+## Features
+
+For general debugging features such as inspecting variables, setting breakpoints, and other activities that aren't language-dependent, review [VS Code debugging](https://code.visualstudio.com/docs/editor/debugging).
+
+### Configure
+
+When you need more than the default debugging setup, you can create a launch configuration file for the project by clicking the “create a launch.json file” link in [the Run view](https://code.visualstudio.com/docs/editor/debugging#_run-view). Then, choose from the debug configuration drop-down menu. Then VS Code will create a `launch.json` file in a .vscode folder in your workspace (project root folder) or in your [user settings](https://code.visualstudio.com/docs/editor/debugging#_global-launch-configuration) or [workspace settings](https://code.visualstudio.com/docs/editor/multi-root-workspaces#_workspace-launch-configurations).
+
+If you already have a `launch.json` for your project, you can open it using `Open launch.json`.
+
+To add a new configuration to an existing `launch.json`, choose the “Add Configuration…” button to invoke the snippet IntelliSense.
+
+<p align="center">
+<img src="images/create-launch-json.gif" alt="Create launch.json" width="75%">
+</p>
+
+There are many configuration attributes ([the Launch.json attributes](#bookmark=id.p7ufi02pn0sq)). IntelliSense in VS Code’s launch.json editor will help you navigate available options and documentation.
+
+### Launch
+
+You can choose “Start Debugging (F5)” and “Run Without Debugging (^F5)” a.k.a the `noDebug` mode. This feature uses a `launch` request type configuration. Its `program` attribute needs to be either the go file or folder of the main package or test file. In this mode, the Go extension will start the debug session by building and launching the program. The launched program will be terminated when the debug session ends.
+
+* Supported modes
+ * `debug`: build and debug a main package
+ * `test`: build and debug a test
+ * `exec`: debug a precompiled binary. The binary needs to be built with `-gcflags=all=”-N -l” flags to avoid stripping debugging information.
+ * `auto`: automatically choose between `debug` and `test` depending on the open file.
+
+### Attach
+
+You can debug an already running program using the `attach` request type configuration. With the attach request, the Go extension starts `dlv-dap` and configures it to attach to the specified process. Users can select the process to debug with one of the following options:
+
+
+* Specifying the numeric process id (PID) with the `processId` attribute.
+* Specifying the target program name in the `processId` attribute. If there are multiple processes matching the specified program name, the extension will show the list of matching processes at the start of the debug session.
+* Specifying `0` in the `processId` attribute and selecting the process from the drop-down menu at the start of the debug session.
+
+<p align="center">
+<img src="images/attach.gif" alt="Attach to a running process" width="75%">
+</p>
+
+When you end the debug session, the debug UI allows you to choose either
+
+* Disconnect: detach and leave the process running. (default)
+* Terminate: terminate the attached process.
+
+<p align="center">
+<img src="images/attach-terminate.gif" alt="Terminate Debugging started with Attach" style="width: 30%">
+</p>
+
+<!-- TODO:[SupportSuspendDebuggee](https://code.visualstudio.com/updates/v1_56#_disconnect-debugger-and-keep-debuggee-suspended) -->
+
+### Debug Actions
+
+Once a debug session starts, the Debug toolbar will appear on the top of the editor.
+
+<p align="center">
+<img src="images/debug-toolbar.png" alt="Debug Tool Bar" width="30%">
+</p>
+
+* Continue / Pause F5
+* Step Over (aka `next` in Delve) F10
+* Step Into (aka `step` in Delve) F11
+* Step Out (aka `stepout` in Delve) ⇧F11
+* Restart (currently this is “Stop + Start”) ⇧⌘F5
+* Stop (terminate the debugee. Available in Launch request) ⇧F5
+* Disconnect (detach from the debugee. Available only in Attach request) ⇧F5
+* Terminate (terminate the debugee. Available only in Attach request) ⌥⇧F5
+
+### Breakpoints
+
+See [VS Code’s Debug Documentation on Breakpoints](https://code.visualstudio.com/docs/editor/debugging#_breakpoints) to get familiar with VS Code’s UI. Go debugger supports multiple ways to configure breakpoints.
+
+* **Breakpoints**: you can set breakpoints by clicking on the editor margin or using F9 on the current line. If the breakpoints can’t be set by Delve, VS Code will show the failure reason and grey out the dot.
+
+<p align="center">
+<img src="images/invalid-breakpoint.png" alt="Invalid breakpoint" width="75%">
+</p>
+
+* **Conditional breakpoints**: you can specify breakpoint conditions (similar to Delve’s [`condition` command](https://github.com/go-delve/delve/tree/master/Documentation/cli#condition)).
+ * Expression condition: takes a boolean expression.
+ * Hit count: supports comparison operators (`>`, `>=`, `<`, `<=`, `==`, `!=`) and `%n` form means we should stop at the breakpoint when the hitcount is a multiple of `n`.
+
+<p align="center">
+<img src="images/conditional-breakpoint.gif" alt="Conditional Breakpoint" width="50%">
+</p>
+
+* **Function Breakpoints**: breakpoints can be set based on function names. Press the + button in the BREAKPOINTS section header and enter the location in the form of `<function>[:<line>]`. This sets the breakpoint in the `line` inside the `function`. The full syntax for `function` is `<package>.(*<receiver type>).<function_name>` as specified in [Delve’s location spec](https://github.com/go-delve/delve/blob/master/Documentation/cli/locspec.md#location-specifiers). Function breakpoints are shown with a red triangle in the BREAKPOINTS section.
+
+<p align="center">
+<img src="images/function-breakpoint.gif" alt="Function breakpoint" width="75%">
+</p>
+
+* Logpoint (WIP)
+
+
+### Data Inspection
+
+You can inspect variables in the VARIABLES section of the Run view or by hovering over their source in the editor. Variable values and expression evaluation are relative to the selected stack frame in the CALL section.
+
+By default, the VARIABLES section hides global variables, and shows only local variables and function arguments. However, you can still inspect global variables from the DEBUG CONSOLE panel. If you prefer to have the VARIABLES section show global variables, set the `showGlobalVariables` attribute in the `launch.json` configuration, or set it in the `go.delveConfig` setting.
+
+When you select a variable and right click from the VARIABLES section, the context menu will present shortcuts to features such as:
+
+* Set Value: you can set/modify simple string, numeric, pointer values. Using composite literals, or memory allocation
+* Copy Value: this copies the value in clipboard.
+* Copy as Expression: this is useful when you need to query from the REPL in the DEBUG CONSOLE panel.
+* Add to Watch: this will automatically add the expression to the WATCH section.
+
+Shadowed variables will be marked with `()`.
+
+<p align="center">
+<img src="images/shadowed-variables.png" alt="Shadowed Variables" style="width: 50%">
+</p>
+
+⚠️ Delve debugger imposes variable loading limits to prevent loading too many variables at once and negatively impacting debugging latency. The `dlv-dap` mode uses a different approach. It takes advantage of the interactive UI features to provide on-demand loading of individual variables, paging of arrays, slices and maps and increased string limits depending on the context. We continue to explore additional interactive features to balance performance and usability of variable loading and look forward to your feedback.
+
+You can inspect variables and evaluate expressions from the DEBUG CONSOLE panel too. Acceptable expressions are either
+
+
+
+* A valid [Delve’s expression](https://github.com/go-delve/delve/blob/master/Documentation/cli/expr.md), or
+* `call <function_call_expression>` to call functions.
+
+<p align="center">
+<img src="images/debug-console.png" alt="Debug Console" width="50%">
+</p>
+
+
+Variables and expressions accepted in DEBUG CONSOLE can be also registered in the Run view’s WATCH section, so they can be evaluated automatically as you debug. The “Add to Watch” feature from the VARIABLES section is convenient when you want to register interesting variables.
+
+⚠️ Funcion call feature is highly EXPERIMENTAL due to the limitation in Go runtime. Registering function calls in the WATCH section can be often problematic. Pause, stop, disconnect will not work while a function call is running.
+
+Hover over variables in editors during debugging shows the value of the variable. For this feature, VS Code extracts the variable expression and requests the debugger to evaluate the expression. Delve evaluates the expression relative to the highlighted stack frame chosen in the CALL STACK. By default, that is the current top-most frame.
+
+<p align="center"><img src="images/variable-hover.png" alt="Hover over Variable in Source Code" width="50%">
+ </p>
+
+⚠️ Limitation
+
+* VS Code heuristically determines the variable expression without full understanding of the scope & the currently selected frame, and Delve tries to evaluate the provided expression in the selected frame. As a result, hover over variables outside the selected frame’s function may be incorrectly presented.
+
+### Call Stack
+
+You can inspect all goroutines and their stacks in the CALL STACK section. The CALL STACK section UI allows switching between goroutines or selecting a different stack frame. As a different stack frame or different goroutine is selected, the scope shown in the VARIABLE section will be updated for the newly selected stack frame, and the expressions in the WATCH section will be reevaluated relative to the newly selected stack frame automatically.
+
+<p align="center"><img src="images/callstack-section-annotated.gif" alt="Call Stack Section Overview" width="75%"> </p>
+
+
+1. Goroutine stacks are annotated with their internal goroutine IDs.
+2. Current goroutine (that hit breakpoint) is marked with `**\*` **symbol. If multiple goroutines hit breakpoints concurrently, Delve will pick one randomly. There might not be a current goroutine (e.g. deadlock, pause or internal breakpoint hit by a system thread not running a goroutine)
+3. If you click a goroutine call stack from the CALL STACK section, the goroutine is _selected_.
+4. You can select a frame of the selected goroutine. The VARIABLE and WATCH sections will be updated accordingly and the cursor in the editor will be moved to the corresponding location in the source code.
+5. Runtime stack frames are deemphasized (greyed out or collapsed).
+6. Thread IDs are shown for scheduled goroutines.
+7. Stop reason. It’s possible that there are multiple reasons goroutines were stopped, but currently only one reason is presented.
+8. File name and line number of the frame.
+9. You can trigger a debug action with the selected goroutine. Note: Resuming or stopping only a single goroutine (Go Issue [25578](https://github.com/golang/go/issues/25578), [31132](https://github.com/golang/go/issues/31132)) is currently not supported, so the action will cause all the goroutines to get activated or paused.
+10. Function name of the frame.
+
+When the program stops due to exception, panic, or bad access error, the CALL STACK shows the stop reason and the editor highlights the source location with more details.
+
+<p align="center"><img src="images/panicinfo.png" alt="Panic" width="75%"></p>
## Configuration
+
+### Launch.json Attributes
+
+There are many attributes that you can adjust in the launch and attach debug configuration. The following general attributes are mandatory for all launch configurations.
+
+* `name`: the name of your configuration as it appears in the drop-down in the Run view.
+* `type`: the debugging type VS Code uses to decide which debugging extension should be used. Always leave this set to `”go”`.
+* `request`: `launch` or `attach`.
+
+Here is the list of attributes specific to Go debugging.
+
<!-- DO NOT EDIT: Auto-generated by go run tools/generate -->
<!-- SETTINGS BEGIN -->
| Property | Launch | Attach |
@@ -115,13 +260,167 @@
| `substitutePath` | An array of mappings from a local path (editor) to the remote path (debugee). This setting is useful when working in a file system with symbolic links, running remote debugging, or debugging an executable compiled externally. The debug adapter will replace the local path with the remote path in all of the calls.<br/><p><br/><ul><li>`"from"`: The absolute local path to be replaced when passing paths to the debugger.<br/>(Default: `""`)<br/></li><li>`"to"`: The absolute remote path to be replaced when passing paths back to the client.<br/>(Default: `""`)<br/></li></ul><br/> | An array of mappings from a local path (editor) to the remote path (debugee). This setting is useful when working in a file system with symbolic links, running remote debugging, or debugging an executable compiled externally. The debug adapter will replace the local path with the remote path in all of the calls. Overriden by `remotePath`.<br/><p><br/><ul><li>`"from"`: The absolute local path to be replaced when passing paths to the debugger.<br/>(Default: `""`)<br/></li><li>`"to"`: The absolute remote path to be replaced when passing paths back to the client.<br/>(Default: `""`)<br/></li></ul><br/> |
| `trace` | Various levels of logging shown in the debug console & 'Go Debug' output channel. When using the `legacy` debug adapter, the logs will also be written to a file if it is set to a value other than `error`.<br/><p>Allowed Values: `"verbose"`, `"trace"`, `"log"`, `"info"`, `"warn"`, `"error"`<br/>(Default: `"error"`)<br/> | <center>_same as Launch_</center>|
<!-- SETTINGS END -->
+
+⚠️ `dlv-dap` needs file or directory values in the launch configuration to be absolute paths. When configuring those values, use [the VS Code variables substitution](https://code.visualstudio.com/docs/editor/variables-reference) - VS Code will resolve the variables inside strings in `launch.json` before passing the configuration to the Go extension and `dlv-dap`. For example, `${workspaceFolder}` will be replaced with the absolute path to the workspace root folder. When appropriate, the Go extension will resolve relative paths or home directory (~) before using the configuration to `dlv-dap`.
+
+
+### **Debugging symlink directories**
+
+Since the debugger and go compiler use the actual filenames, extra configuration is required to debug symlinked directories. Use the substitutePath property to tell the `debugAdapter` how to properly translate the paths. For example, if your project lives in `/path/to/actual/helloWorld`, but the project is open in vscode under the linked folder `/path/to/hello`, you can add the following to your config to set breakpoints in the files in `/path/to/hello`:
+
+```
+{
+ "name": "Launch remote",
+ "type": "go",
+ "request": "launch",
+ "mode": "debug",
+ "program": "/path/to/actual/helloWorld",
+ "substitutePath": [
+ {
+ "from": "/path/to/hello",
+ "to": "/path/to/actual/helloWorld",
+ },
+ ],
+}
+```
+
+<!--### Options for “Add Configuration”
+
+TODO: clean up the snippets in package.json
+
+TODO: auto-generate from package.json. -->
+
+### Settings
+
+You can adjust the default value of the following configuration properties using `go.delveConfig` settings. These default values are useful when you choose to run a debug session without the launch configuration set in `launch.json`. For example, debug sessions start using the `Debug Test` code lenses use the adjusted values from these settings.
+
+* [`go.delveConfig`](settings.md#go.delveConfig)
+ * `debugAdapter`: Controls which debug adapter to use (default: `legacy`). Select ‘dlv-dap’.
+ * `showGlobalVariables`: Show global variables in the Debug view (default: `false`).
+ * `substitutePath`: Path mappings to apply to get from a path in the editor to a path in the compiled program (default: `[]`).
+
+⚠️ where is the `dlvLoadConfig` setting? Delve debugger imposes variable loading limits to avoid loading too many variables at once and negatively impacting debugging latency. The legacy adapter supported `dlvLoadConfig` to adjust these limits for the duration of the session. The user therefore had to come up with a one-size-fits-all limit if the default behavior was not satisfactory. `dlv-dap` mode uses a different approach as described in [the Data Inspection section](#data-inspection). If this setting is configured and `dlv-dap` mode is used, the extension will show a warning prompt now. If the current variable loading behavior and internal limits are not working for you, please open an issue and share your feedback.
+
+<p align="center"><img src="images/dlv-load-config-warning.png" alt="dlvLoadConfig is invalid" width="50%"> </p>
+
+## Advanced Topics
+
+
+### Go Debug Extension Architecture Overview
+
+VS Code implements a generic, language-agnostic debugger UI based on [Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/) (DAP), an abstract protocol for communicating with debugger backend. Previously, the Go extension was using an intermediary typescript program (legacy debug adapter) to launch Delve and adapt Delve to DAP. With [the new, native DAP implementation in Delve](https://github.com/go-delve/delve/tree/master/service/dap), the intermediary program is no longer necessary and efficient and tight integration with Delve becomes possible.
+
+<p align="center"><img src="images/vscode-go-debug-arch.png" alt="vscode-go debug architecture"> </p>
+
+For the information on debugging using the legacy debug adapter, please see the old [Debugging Documentation](https://github.com/golang/vscode-go/blob/master/docs/debugging.md). Note that many new or enhanced features discussed in this document may not be available with the legacy debug adapter.
+
+### Manually installing `dlv-dap`
+
+On rare occasions, you may want to install `dlv-dap` by yourself instead of letting the extension handle its installation.
+
+First, find where the Go extension finds tools. Like [other tools the extension uses](https://github.com/golang/vscode-go/blob/master/docs/tools.md#tools), the Go extension searches the `dlv-dap` executable from `${GOPATH}/bin`, `${GOBIN}` and `${PATH}` (or `Path` in Windows). So, install `dlv-dap` in the directory. The easiest way to check the tool installation location the Go extension uses is currently by running the `Go: Locate Configured Go Tools` command from the command palette (⇧+⌘+P or Ctrl+Shift+P).
+
+
+The following commands download the source of Delve from the master branch, build & store as `dlv-dap` in `~/go/bin/` directory assuming the directory is the place you found from the first step.
+
+If your Go version is 1.16 or newer:
+
+```
+$ GOBIN=/tmp/ go install github.com/go-delve/delve/cmd/dlv@master
+$ mv /tmp/dlv $GOPATH/bin/dlv-dap
+```
+
+If your Go version is older than 1.16:
+
+
+```
+$ cd $(mktemp -d)
+$ GO111MODULE=on GOBIN=/tmp/ go get github.com/go-delve/delve/cmd/dlv@master
+$ mv /tmp/dlv $GOPATH/bin/dlv-dap
+```
+
+If you want to explicitly specify the location of the delve binary, use the `go.alternateTools` setting:
+```json5
+"go.alternateTools": {
+ "dlv-dap": "<absolute path to your dlv binary>"
+}
+```
+
+### Remote Debugging
+
+
+> If you are able to use the [Remote Development](https://aka.ms/vscode-remote/download/extension) extensions and VS Code’s universal [remote development capabilities](https://code.visualstudio.com/docs/remote/remote-overview), that is the recommended way to remote debug Go programs. Check out the [Getting started](https://code.visualstudio.com/docs/remote/remote-overview#_getting-started) section and [Remote tutorials](https://code.visualstudio.com/docs/remote/remote-overview#_remote-tutorials) to learn more.
+
+Remote debugging is the debug mode where the debug target runs in a different machine or a container. Support for remote debugging using Delve’s native DAP implementation is still a work-in-progress. This section describes a current temporary workaround and its limitations. If the following workaround is not working for your case, please file an issue and help us understand remote debugging use cases better.
+
+<p align="center"><img src="images/remote-debugging.png" alt="Remote Debugging"> </p>
+
+When using the dlv-dap mode, the delve instance running remotely needs to be able to process DAP, instead of the traditional Delve JSON-RPC. The following command starts a Delve DAP server on port 12345 and outputs `dap` specific events.
+
+```
+$ dlv-dap dap --listen=:2345
+```
+
+Then, use the following `launch` configuration:
+
+```json5
+{
+ “name”: “Connect to server (DAP)”,
+ “type”: “go”,
+ “request”: “launch”,
+ “port”: 2345,
+ “host”: “127.0.0.1”,
+ “mode”: “exec”,
+ “program”: “/path/to/remote/workspace/program/executable”,
+ “substitutePath”: [
+ { “from”: ${workspaceFolder}, “to”: “/path/to/remote/workspace” },
+ ...
+ ]
+}
+```
+
+When seeing the `”port”` attribute being used in the launch request, Go extension will assume a Delve DAP server is started externally and accessible through the specified `host:port` and tell VS Code to connect to it directly. The `program` attribute must point to the absolute path to the package or binary to debug in the remote host’s file system even when `substitutePath` is specified.
+
+⚠️ Limitations
+* Unlike `dlv <debug|exec|attach> --headless` commands traditionally used for remote debugging scenarios, Delve’s new `dap` sub command does not launch or attach to the debuggee process until it receives a Launch/Attach request. We understand this limitation, and we are currently working on addressing this limitation.
+* Anyone who can connect to the Delve DAP server’s host:port can exploit it to run arbitrary programs.
+* When using `”attach”` requests, you will need to specify the `processId` since
+[the processId resolution feature](#attach) cannot gather process information running remotely.
+* Delve DAP does not support `--allow-multiclient` or `--continue` flags yet, which means after a debug session ends, the dlv-dap process will exit.
+* If you want to use `debug` or `test` mode `launch` requests, that involves Delve to build the target binary. Delve tries to build the target from the directory where the `dlv` (or `dlv-dap`) process is running, so make sure to run the `dlv-dap` command from the directory you’d run the `go build` or `go test` command.
+
+### Running Debugee Externally
+
+Sometimes you’d like to launch the program for debugging outside VS Code (e.g., as a workaround of the missing `console` support), there are currently two options.
+
+* Compile and run the program from the external terminal and use [the “attach” configuration](#attach).
+* Use [“Remote Debugging”](#remote-debugging); run `dlv-dap dap --listen=:<port>` from the external terminal, and set the `”port”` attribute in your launch configuration.
+
+## 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 provide 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 problems 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 <path/to/dlv-dap>`
+* VS Code and VS Code Go version.
+* Instruction to reproduce the issue (code snippets, your `launch.json`, screenshot)
+
## Developing
### Code location
+
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.
+
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.
### Testing
+
For simple launch cases, build the delve binary, and configure `"go.alternateTools"` setting.
```json5
@@ -130,7 +429,8 @@
}
```
-Set `logOutput` and `showLog` attributes in `launch.json` to enable `dlv'-side logging and DAP message tracing.
+Set `logOutput` and `showLog` attributes in `launch.json` to enable Delve-side logging (server-side) and DAP message tracing.
+
```json5
{
"name": "Launch file",
@@ -142,8 +442,9 @@
}
```
-Set `trace` attribute to control the verbosity of debug extension's logging.
-The logging will appear in the `Go Debug` output channel (Command Palette -> "View: Toggle Output" -> Select "Go Debug" from the dropdown menu).
+Set `trace` attribute to control the verbosity of Go extension's side logging (client-side).
+
+
```json5
{
@@ -155,7 +456,10 @@
}
```
-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.
+The logging will appear in the `Go Debug` output channel (Command Palette -> "View: Toggle Output" -> Select "Go Debug" from the dropdown menu).
+
+<p align="center"><img src="images/debug-output.png" alt="Go Debug output channel" width="100%"></p>
+If you are having issues with seeing logs and or suspect problems in extension's integration, you can start the Delve DAP server from a separate terminal and configure the extension to directly connect to it. Please remember to file an issue if you encounter such logging-related issues.
```
$ dlv-dap dap --listen=:12345 --log --log-output=dap
diff --git a/docs/images/attach-terminate.gif b/docs/images/attach-terminate.gif
new file mode 100644
index 0000000..8dc4902
--- /dev/null
+++ b/docs/images/attach-terminate.gif
Binary files differ
diff --git a/docs/images/attach.gif b/docs/images/attach.gif
new file mode 100644
index 0000000..d69cb82
--- /dev/null
+++ b/docs/images/attach.gif
Binary files differ
diff --git a/docs/images/callstack-section-annotated.gif b/docs/images/callstack-section-annotated.gif
new file mode 100644
index 0000000..408825c
--- /dev/null
+++ b/docs/images/callstack-section-annotated.gif
Binary files differ
diff --git a/docs/images/conditional-breakpoint.gif b/docs/images/conditional-breakpoint.gif
new file mode 100644
index 0000000..d78a5f4
--- /dev/null
+++ b/docs/images/conditional-breakpoint.gif
Binary files differ
diff --git a/docs/images/create-launch-json.gif b/docs/images/create-launch-json.gif
new file mode 100644
index 0000000..5adf939
--- /dev/null
+++ b/docs/images/create-launch-json.gif
Binary files differ
diff --git a/docs/images/debug-console.png b/docs/images/debug-console.png
new file mode 100644
index 0000000..480c829
--- /dev/null
+++ b/docs/images/debug-console.png
Binary files differ
diff --git a/docs/images/debug-output.png b/docs/images/debug-output.png
new file mode 100644
index 0000000..d324eaa
--- /dev/null
+++ b/docs/images/debug-output.png
Binary files differ
diff --git a/docs/images/debug-toolbar.png b/docs/images/debug-toolbar.png
new file mode 100644
index 0000000..7cbf61e
--- /dev/null
+++ b/docs/images/debug-toolbar.png
Binary files differ
diff --git a/docs/images/dlv-load-config-warning.png b/docs/images/dlv-load-config-warning.png
new file mode 100644
index 0000000..efbeaea
--- /dev/null
+++ b/docs/images/dlv-load-config-warning.png
Binary files differ
diff --git a/docs/images/dlvdap-install.gif b/docs/images/dlvdap-install.gif
new file mode 100644
index 0000000..3c9eeb5
--- /dev/null
+++ b/docs/images/dlvdap-install.gif
Binary files differ
diff --git a/docs/images/function-breakpoint.gif b/docs/images/function-breakpoint.gif
new file mode 100644
index 0000000..2a25127
--- /dev/null
+++ b/docs/images/function-breakpoint.gif
Binary files differ
diff --git a/docs/images/invalid-breakpoint.png b/docs/images/invalid-breakpoint.png
new file mode 100644
index 0000000..226fe51
--- /dev/null
+++ b/docs/images/invalid-breakpoint.png
Binary files differ
diff --git a/docs/images/panicinfo.png b/docs/images/panicinfo.png
new file mode 100644
index 0000000..ba16a55
--- /dev/null
+++ b/docs/images/panicinfo.png
Binary files differ
diff --git a/docs/images/remote-debugging.png b/docs/images/remote-debugging.png
new file mode 100644
index 0000000..6377e68
--- /dev/null
+++ b/docs/images/remote-debugging.png
Binary files differ
diff --git a/docs/images/shadowed-variables.png b/docs/images/shadowed-variables.png
new file mode 100644
index 0000000..f09bfb4
--- /dev/null
+++ b/docs/images/shadowed-variables.png
Binary files differ
diff --git a/docs/images/variable-hover.png b/docs/images/variable-hover.png
new file mode 100644
index 0000000..208c200
--- /dev/null
+++ b/docs/images/variable-hover.png
Binary files differ
diff --git a/docs/images/variables.png b/docs/images/variables.png
new file mode 100644
index 0000000..f3d6f84
--- /dev/null
+++ b/docs/images/variables.png
Binary files differ
diff --git a/docs/images/vscode-go-debug-arch.png b/docs/images/vscode-go-debug-arch.png
new file mode 100644
index 0000000..be0a88c
--- /dev/null
+++ b/docs/images/vscode-go-debug-arch.png
Binary files differ
3 is the latest approved patch-set.
The change was submitted with unreviewed changes in the following files:
The name of the file: docs/dlv-dap.md
Insertions: 5, Deletions: 5.
```
@@ -292:293, +292:293 @@
- ### Settings
+ ### Settings
@@ -318:319, +318:319 @@
- On rare occasions, you may want to install `dlv-dap` by yourself instead of letting the extension handle its installation.
+ On rare occasions, you may want to install `dlv-dap` by yourself instead of letting the extension handle its installation.
@@ -344:345, +344:345 @@
- "dlv-dap": "<absolute path to your dlv binary>"
+ "dlv-dap": "<absolute path to your dlv binary>"
@@ -373:374, +373:374 @@
- “program”: “/path/to/remote/workspace/program/executable”,
+ “program”: “/path/to/remote/workspace/program/executable”,
@@ -385:386, +385:386 @@
- * Anyone who can connect to the Delve DAP server’s host:port can exploit it to run arbitrary programs.
+ * Anyone who can connect to the Delve DAP server’s host:port can exploit it to run arbitrary programs.
```
To view, visit change 331051. To unsubscribe, or for help writing mail filters, visit settings.
Reply all
Reply to author
Forward
0 new messages