Debug Adapter

The Debug Adapter runs in a separate Node.js process, which is spawned by VS Code when you debug Go code.

Please see the Debug Adapter Protocol (DAP) to understand how the Debug Adapter acts as an intermediary between VS Code and the debugger (Delve).

This codebase is currently in flux: We are working on using Delve's native DAP implementation instead of this one. Follow along with golang/vscode-go#23 for updates on that work.


Before you begin

Before you start working on your change, please read the contribution guidelines. This document assumes that you are already familiar with the process of building, running, and sideloading the VS Code Go extension.

Debug only the Debug Adapter

As a next step, you may want to debug the Debug Adapter, in order to understand how your change work with Delve.

NOTE: Since the Debug Adapter runs in a separate process from the rest of the extension, the steps below only enable you to debug the Debug Adapter code, not the entire extension. To debug the entire extension, as well as the debug adapter, see the instructions below.

  1. Open the vscode-go folder in VS Code.
  2. Go the Run view and choose the Launch as server debug configuration.
  3. Add breakpoints as needed to the vscode-go/src/debugAdapter/goDebug.ts file.
  4. Open another instance of VS Code and open the Go project to debug.
  5. Create a debug configuration for the Go project if it doesn't exist. Set "debugServer": 4711 in the root of the configuration.
  6. Start debugging your Go program using this configuration. This will trigger the breakpoints in goDebug.ts file.

Debug the entire extension, including the Debug Adapter

You should take this step if your change modifies both the Debug Adapter and the main extension. This setup requires three instances of VS Code.

  1. Open the root vscode-go folder in one instance of VS Code.
  2. Choose the Launch Extension debug target and run it (F5). This will launch the second instance of VS Code.
  3. In this second instance, open the Go application you'd like to debug. Here, as above, create a debug configuration pointing to the program you want to debug. Add "debugServer": 4711 to the root of the configuration.
  4. Open the vscode-go/src/debugAdapter folder in a third VS Code instance. Select the Launch as server configuration and run it (F5).
  5. Return to the second VS Code instance with the Go program. Run the debug configuration (F5). Debuggers from the other two VS Code windows are attached to the Debug Adapter and the Go extension, so you can set breakpoints, step through code, and inspect state as needed.

Debug VS Code and the Debug Adapter

In some very rare cases, you may find it helpful to debug VS Code itself. An example of such a case might be veryfing workbench behavior and state before executing debug adapter API calls.

First, ensure that you can build and run VS Code from source successfully.

Next, follow these steps:

  1. Open an instance of VS Code that you have built from source.
  2. Sideload your local vscode-go extension to the local instance of VS Code. This can be done by copying the contents of the vscode-go directory into $HOME/.vscode-oss-dev/extensions/ms-vscode.go (the exact location may vary by OS).
  3. Open the vscode folder in Visual Studio Code.
  4. Launch the VS Code debug instance (OSS - Code) by choosing the Launch VS Code debug configuraion from the drop-down in the Run view. Add breakpoints as needed.
  5. In another instance of VS Code, open the vscode-go folder. Choose the Launch as server debug configuration in the Run view. Add breakpoints as desired in the vscode-go/src/debugAdapter/goDebug.ts file.
  6. Open the Go application that you want to debug in the OSS Code instance initiated in step 4.
  7. Create a debug configuration with the setting "debugServer": 4711.
  8. Start debugging your Go application. Observe that any breakpoints you set in the VS Code and debug adapter codebases will be triggered.