dap

package
v1.7.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 23, 2021 License: MIT Imports: 30 Imported by: 3

Documentation

Overview

Package dap implements VSCode's Debug Adaptor Protocol (DAP). This allows delve to communicate with frontends using DAP without a separate adaptor. The frontend will run the debugger (which now doubles as an adaptor) in server mode listening on a port and communicating over TCP. This is work in progress, so for now Delve in dap mode only supports synchronous request-response communication, blocking while processing each request. For DAP details see https://microsoft.github.io/debug-adapter-protocol.

Index

Constants

View Source
const (
	UnsupportedCommand int = 9999
	InternalError      int = 8888
	NotYetImplemented  int = 7777

	// Where applicable and for consistency only,
	// values below are inspired the original vscode-go debug adaptor.
	FailedToLaunch             = 3000
	FailedToAttach             = 3001
	FailedToInitialize         = 3002
	UnableToSetBreakpoints     = 2002
	UnableToDisplayThreads     = 2003
	UnableToProduceStackTrace  = 2004
	UnableToListLocals         = 2005
	UnableToListArgs           = 2006
	UnableToListGlobals        = 2007
	UnableToLookupVariable     = 2008
	UnableToEvaluateExpression = 2009
	UnableToHalt               = 2010
	UnableToGetExceptionInfo   = 2011
	UnableToSetVariable        = 2012
	// Add more codes as we support more requests
	NoDebugIsRunning  = 3000
	DebuggeeIsRunning = 4000
	DisconnectError   = 5000
)

Unique identifiers for messages returned for errors from requests. These values are not mandated by DAP (other than the uniqueness requirement), so each implementation is free to choose their own.

View Source
const BetterBadAccessError = `` /* 211-byte string literal not displayed */
View Source
const BetterNextWhileNextingError = `Unable to step while the previous step is interrupted by a breakpoint.
Use 'Continue' to resume the original step command.`

Variables

View Source
var DefaultLoadConfig = proc.LoadConfig{
	FollowPointers:     true,
	MaxVariableRecurse: 1,

	MaxStringLen:    512,
	MaxArrayValues:  64,
	MaxStructFields: -1,
}

DefaultLoadConfig controls how variables are loaded from the target's memory. These limits are conservative to minimize performace overhead for bulk loading. With dlv-dap, users do not have a way to adjust these. Instead we are focusing in interacive loading with nested reloads, array/map paging and context-specific string limits.

Functions

This section is empty.

Types

type AttachConfig added in v1.7.2

type AttachConfig struct {
	// Acceptable values are:
	//   "local": attaches to the local process with the given ProcessID.
	//
	// Default is "local".
	Mode string `json:"mode"`

	// The numeric ID of the process to be debugged. Required and must not be 0.
	ProcessID int `json:"processId,omitempty"`

	LaunchAttachCommonConfig
}

AttachConfig is the collection of attach request attributes recognized by delve DAP implementation.

type LaunchAttachCommonConfig added in v1.7.2

type LaunchAttachCommonConfig struct {
	// Automatically stop program after launch or attach.
	StopOnEntry bool `json:"stopOnEntry,omitempty"`

	// Backend used by delve. See `dlv backend` for allowed values.
	// Default is "default".
	Backend string `json:"backend,omitempty"`

	// Maximum depth of stack trace collected from Delve.
	// Default is 50.
	StackTraceDepth int `json:"stackTraceDepth,omitempty"`

	// Boolean value to indicate whether global package variables
	// should be shown in the variables pane or not.
	ShowGlobalVariables bool `json:"showGlobalVariables,omitempty"`

	// An array of mappings from a local path (client) to the remote path (debugger).
	// 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.
	SubstitutePath []SubstitutePath `json:"substitutePath,omitempty"`
}

LaunchAttachCommonConfig is the attributes common in both launch/attach requests.

type LaunchConfig added in v1.7.2

type LaunchConfig struct {
	// Acceptable values are:
	//   "debug": compiles your program with optimizations disabled, starts and attaches to it.
	//   "test": compiles your unit test program with optimizations disabled, starts and attaches to it.
	//   "exec": executes a precompiled binary and begins a debug session.
	//   "replay": replays an rr trace.
	//   "core": examines a core dump.
	//
	// Default is "debug".
	Mode string `json:"mode,omitempty"`

	// Required when mode is `debug`, `test`, or `exec`.
	// Path to the program folder (or any go file within that folder)
	// when in `debug` or `test` mode, and to the pre-built binary file
	// to debug in `exec` mode.
	// If it is not an absolute path, it will be interpreted as a path
	// relative to the working directory of the delve process.
	Program string `json:"program,omitempty"`

	// Command line arguments passed to the debugged program.
	Args []string `json:"args,omitempty"`

	// Working directory of the program being debugged
	// if a non-empty value is specified. If a relative path is provided,
	// it will be interpreted as a relative path to the delve's
	// working directory.
	//
	// If not specified or empty, currently the built program's directory will
	// be used.
	// This is similar to delve's `--wd` flag.
	Cwd string `json:"cwd,omitempty"`

	// Build flags, to be passed to the Go compiler.
	// It is like delve's `--build-flags`. For example,
	//
	//    "buildFlags": "-tags=integration -mod=vendor -cover -v"
	BuildFlags string `json:"buildFlags,omitempty"`

	// Output path for the binary of the debugee.
	// Relative path is interpreted as the path relative to
	// the delve process's working directory.
	// This is deleted after the debug session ends.
	//
	// FIXIT: the built program's directory is used as the default
	// working directory of the debugged program, which means
	// the directory of `output` is used as the default working
	// directory. This is a bug and needs fix.
	Output string `json:"output,omitempty"`

	// NoDebug is used to run the program without debugging.
	NoDebug bool `json:"noDebug,omitempty"`

	// TraceDirPath is the trace directory path for replay mode.
	// This is required for "replay" mode but unused in other modes.
	TraceDirPath string `json:"traceDirPath,omitempty"`

	// CoreFilePath is the core file path for core mode.
	// This is required for "core" mode but unused in other modes.
	CoreFilePath string `json:"coreFilePath,omitempty"`

	LaunchAttachCommonConfig
}

LaunchConfig is the collection of launch request attributes recognized by delve DAP implementation.

type Server

type Server struct {
	// contains filtered or unexported fields
}

Server implements a DAP server that can accept a single client for a single debug session (for now). It does not yet support restarting. That means that in addition to explicit shutdown requests, program termination and failed or closed client connection would also result in stopping this single-use server.

The DAP server operates via the following goroutines:

(1) Main goroutine where the server is created via NewServer(), started via Run() and stopped via Stop(). Once the server is started, this goroutine blocks until it receives a stop-server signal that can come from an OS interrupt (such as Ctrl-C) or config.DisconnectChan (passed to NewServer()) as a result of client connection failure or closure or a DAP disconnect request.

(2) Run goroutine started from Run() that serves as both a listener and a client goroutine. It accepts a client connection, reads, decodes and dispatches each request from the client. For synchronous requests, it issues commands to the underlying debugger and sends back events and responses. These requests block while the debuggee is running, so, where applicable, the handlers need to check if debugging state is running, so there is a need for a halt request or a dummy/error response to avoid blocking.

This is the only goroutine that sends a stop-server signal via config.DisconnecChan when encountering a client connection error or responding to a (synchronous) DAP disconnect request. Once stop is triggered, the goroutine exits.

TODO(polina): add another layer of per-client goroutines to support multiple clients

(3) Per-request goroutine is started for each asynchronous request that resumes execution. We check if target is running already, so there should be no more than one pending asynchronous request at a time. This goroutine issues commands to the underlying debugger and sends back events and responses. It takes a setup-done channel as an argument and temporarily blocks the request loop until setup for asynchronous execution is complete and targe is running. Once done, it unblocks processing of parallel requests unblocks (e.g. disconnecting while the program is running).

These per-request goroutines never send a stop-server signal. They block on running debugger commands that are interrupted when halt is issued while stopping. At that point these goroutines wrap-up and exit.

func NewServer

func NewServer(config *service.Config) *Server

NewServer creates a new DAP Server. It takes an opened Listener via config and assumes its ownership. config.DisconnectChan has to be set; it will be closed by the server when the client fails to connect, disconnects or requests shutdown. Once config.DisconnectChan is closed, Server.Stop() must be called to shutdown this single-user server.

func (*Server) Run

func (s *Server) Run()

Run launches a new goroutine where it accepts a client connection and starts processing requests from it. Use Stop() to close connection. The server does not support multiple clients, serially or in parallel. The server should be restarted for every new debug session. The debugger won't be started until launch/attach request is received. TODO(polina): allow new client connections for new debug sessions, so the editor needs to launch delve only once?

func (*Server) Stop

func (s *Server) Stop()

Stop stops the DAP debugger service, closes the listener and the client connection. It shuts down the underlying debugger and kills the target process if it was launched by it or stops the noDebug process. This method mustn't be called more than once.

type SubstitutePath added in v1.7.2

type SubstitutePath struct {
	// The local path to be replaced when passing paths to the debugger.
	From string `json:"from,omitempty"`
	// The remote path to be replaced when passing paths back to the client.
	To string `json:"to,omitempty"`
}

SubstitutePath defines a mapping from a local path to the remote path. Both 'from' and 'to' must be specified and non-empty.

func (*SubstitutePath) UnmarshalJSON added in v1.7.2

func (m *SubstitutePath) UnmarshalJSON(data []byte) error

Directories

Path Synopsis
Package daptest provides a sample client with utilities for DAP mode testing.
Package daptest provides a sample client with utilities for DAP mode testing.
gen command
Binary gen generates service/dap/daptest/responses.go.
Binary gen generates service/dap/daptest/responses.go.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL