gitlab.com/Raven-IO/raven-delve@v1.22.4/Documentation/api/dap/README.md (about)

     1  # DAP Interface
     2  
     3  Delve exposes a [DAP](https://microsoft.github.io/debug-adapter-protocol/overview) API interface.
     4  
     5  This interface is served over a streaming TCP socket using `dlv` server in one of the two headless modes:
     6  1. [`dlv dap`](../../usage/dlv_dap.md) - starts a single-use DAP-only server that waits for a client to specify launch/attach configuration for starting the debug session.
     7  2. `dlv --headless <command> <debuggee>` - starts a general server, enters a debug session for the specified debuggee and waits for a [JSON-RPC](../json-rpc/README.md) or a [DAP](https://microsoft.github.io/debug-adapter-protocol/overview) remote-attach client to begin interactive debugging. Can be used in multi-client mode with the following options:
     8     *  `--accept-multiclient` - use to support connections from multiple clients
     9     *  `--continue` - use to resume debuggee execution as soon as server session starts
    10  
    11  See [Launch and Attach Configurations](#launch-and-attach-configurations) for more usage details of these two options.
    12  
    13  The primary user of this mode is [VS Code Go](https://github.com/golang/vscode-go). Please see its 
    14  detailed [debugging documentation](https://github.com/golang/vscode-go/blob/master/docs/debugging.md) for additional information.
    15  
    16  ## Debug Adapter Protocol
    17  
    18  [DAP](https://microsoft.github.io/debug-adapter-protocol/specification) is a general debugging protocol supported by many [tools](https://microsoft.github.io/debug-adapter-protocol/implementors/tools/) and [programming languages](https://microsoft.github.io/debug-adapter-protocol/implementors/adapters/). We tailored it to Go specifics, such as mapping [threads request](https://microsoft.github.io/debug-adapter-protocol/specification#Requests_Threads) to communicate goroutines and [exceptionInfo request](https://microsoft.github.io/debug-adapter-protocol/specification#Requests_ExceptionInfo) to support panics and fatal errors.
    19  
    20  See [dap.Server.handleRequest](https://github.com/go-delve/delve/search?q=handleRequest) and capabilities set in [dap.Server.onInitializeRequest](https://github.com/go-delve/delve/search?q=onInitializeRequest) for an up-to-date list of supported requests and options.
    21  
    22  ## Launch and Attach Configurations
    23  
    24  In addition to the general [DAP spec](https://microsoft.github.io/debug-adapter-protocol/specification), the server supports the following implementation-specific configuration options for starting the debug session:
    25  
    26  <table border=1>
    27  <tr><th>request<th>mode<th>required<th colspan=9>optional<th></tr>
    28  <tr><td rowspan=5>launch<br><a href="https://pkg.go.dev/github.com/go-delve/delve/service/dap#LaunchConfig">godoc</a>
    29      <td>debug<td>program               <td>dlvCwd<td>env<td>backend<td>args<td>cwd<td>buildFlags<td>output<td>noDebug
    30      <td rowspan=7>
    31      substitutePath<br>
    32      stopOnEntry<br>
    33      stackTraceDepth<br>
    34      showGlobalVariables<br>
    35      showRegisters<br>
    36      showPprofLabels<br>
    37      hideSystemGoroutines<br>
    38      goroutineFilters
    39      </tr>
    40  <tr>
    41      <td>test<td>program                <td>dlvCwd<td>env<td>backend<td>args<td>cwd<td>buildFlags<td>output<td>noDebug</tr>
    42  <tr>
    43      <td>exec<td>program                <td>dlvCwd<td>env<td>backend<td>args<td>cwd<td>          <td>      <td>noDebug</tr>
    44  <tr>
    45      <td>core<td>program<br>corefilePath<td>dlvCwd<td>env<td>       <td>    <td>   <td>          <td>      <td>       </tr>
    46  <tr>
    47      <td>replay<td>traceDirPath         <td>dlvCwd<td>env<td>       <td>    <td>   <td>          <td>      <td>       </tr>
    48  <tr><td rowspan=2>attach<br><a href="https://pkg.go.dev/github.com/go-delve/delve/service/dap#AttachConfig">godoc</a>
    49      <td>local<td>processId             <td>      <td>   <td>backend<td>   <td>    <td>          <td>      <td>        </tr>
    50  <tr>
    51      <td>remote<td>                     <td>      <td>   <td>       <td>   <td>    <td>          <td>      <td>        </tr>
    52  </table>
    53  
    54  
    55  Not all of the configurations are supported by each of the two available DAP servers:
    56  
    57  <table border=1>
    58  <tr>
    59  <th>request<th>"mode":<th>`dlv dap`<th>`dlv --headless` <th> Description <th> Typical Client Usage
    60  </tr>
    61  <tr>
    62  <td>launch<td>"debug"<br>"test"<br>"exec"<br>"replay"<br>"core"<td>supported<td>NOT supported <td> Tells the `dlv dap` server to launch the specified target and start debugging it.
    63  <td rowspan=2>The client would launch the `dlv dap` server for the user or allow them to specify `host:port` of an external (a.k.a. remote) server.
    64  <tr>
    65  <td>attach<td>"local"<td>supported<td>NOT supported<td>Tells the `dlv dap` server to attach to an existing process local to the server.
    66  </tr>
    67  <tr>
    68  <td>attach<td>"remote"<td>NOT supported<td>supported<td>Tells the `dlv --headless` server that it is expected to already be debugging a target specified as part of its command-line invocation.
    69  <td>The client would expect `host:port` specification of an external (a.k.a. remote) server that the user already started with target <a href="https://github.com/go-delve/delve/blob/master/Documentation/usage/README.md">command and args</a>.
    70  </tr>
    71  </table>
    72  
    73  ## Disconnect and Shutdown
    74  
    75  ### Single-Client Mode
    76  
    77  When used with `dlv dap` or `dlv --headless --accept-multiclient=false` (default), the DAP server will shut itself down at the end of the debug session, when the client sends a [disconnect request](https://microsoft.github.io/debug-adapter-protocol/specification#Requests_Disconnect). If the debuggee was launched, it will be taken down as well. If the debuggee was attached to, `terminateDebuggee` option will be respected.
    78  
    79  When the program terminates, we send a [terminated event](https://microsoft.github.io/debug-adapter-protocol/specification#Events_Terminated), which is expected to trigger a [disconnect request](https://microsoft.github.io/debug-adapter-protocol/specification#Requests_Disconnect) from the client for a session and a server shutdown. The [restart request](https://microsoft.github.io/debug-adapter-protocol/specification#Requests_Restart) is not yet supported. 
    80  
    81  The server also shuts down in case of a client connection error or SIGTERM signal, taking down a launched process, but letting an attached process continue. 
    82  
    83  Pressing Ctrl-C on the terminal where a headless server is running sends SIGINT to the debuggee, foregrounded in headless mode to support debugging interactive programs.
    84  
    85  ### Multi-Client Mode
    86  
    87  When used with `dlv --headless --accept-multiclient=true`, the DAP server will honor the multi-client mode when a client [disconnects](https://microsoft.github.io/debug-adapter-protocol/specification#Requests_Disconnect) or client connection fails. The server will remain running and ready for a new client connection, and the debuggee will remain in whatever state it was at the time of disconnect - running or halted. Once [`suspendDebuggee`](https://microsoft.github.io/debug-adapter-protocol/specification#Requests_Disconnect) option is supported by frontends like VS Code ([vscode/issues/134412](https://github.com/microsoft/vscode/issues/134412)), we will update the server to offer this as a way to specify debuggee state on disconnect.
    88  
    89  The client may request full shutdown of the server and the debuggee with [`terminateDebuggee`](https://microsoft.github.io/debug-adapter-protocol/specification#Requests_Disconnect) option.
    90  
    91  The server shuts down in response to a SIGTERM signal, taking down a launched process, but letting an attached process continue.
    92  
    93  Pressing Ctrl-C on the terminal where a headless server is running sends SIGINT to the debuggee, foregrounded in headless mode to support debugging interactive programs.
    94  
    95  ## Debugger Output
    96  
    97  The debugger always logs one of the following on start-up to stdout:
    98  * `dlv dap`:
    99     * `DAP server listening at: <host>:<port>`
   100  * `dlv --headless`: 
   101     * `API server listening at: <host>:<port>`
   102  
   103  This can be used to confirm that server start-up succeeded.
   104  
   105  The server uses [output events](https://microsoft.github.io/debug-adapter-protocol/specification#Events_Output) to communicate errors and select status messages to the client. For example:
   106  
   107  ```
   108  Step interrupted by a breakpoint. Use 'Continue' to resume the original step command.
   109  invalid command: Unable to step while the previous step is interrupted by a breakpoint.
   110  Use 'Continue' to resume the original step command.
   111  Detaching and terminating target process
   112  ```
   113  
   114  More detailed logging can be enabled with `--log --log-output=dap` as part of the [`dlv` command](../../usage/dlv.md).
   115  It will record the server-side DAP message traffic. For example, 
   116  ```
   117  2022-01-04T00:27:57-08:00 debug layer=dap [<- from client]{"seq":1,"type":"request","command":"initialize","arguments":{"clientID":"vscode","clientName":"Visual Studio Code","adapterID":"go","locale":"en-us","linesStartAt1":true,"columnsStartAt1":true,"pathFormat":"path","supportsVariableType":true,"supportsVariablePaging":true,"supportsRunInTerminalRequest":true,"supportsMemoryReferences":true,"supportsProgressReporting":true,"supportsInvalidatedEvent":true}}
   118  2022-01-04T00:27:57-08:00 debug layer=dap [-> to client]{"seq":0,"type":"response","request_seq":1,"success":true,"command":"initialize","body":{"supportsConfigurationDoneRequest":true,"supportsFunctionBreakpoints":true,"supportsConditionalBreakpoints":true,"supportsEvaluateForHovers":true,"supportsSetVariable":true,"supportsExceptionInfoRequest":true,"supportTerminateDebuggee":true,"supportsDelayedStackTraceLoading":true,"supportsLogPoints":true,"supportsDisassembleRequest":true,"supportsClipboardContext":true,"supportsSteppingGranularity":true,"supportsInstructionBreakpoints":true}}
   119  2022-01-04T00:27:57-08:00 debug layer=dap [<- from client]{"seq":2,"type":"request","command":"launch","arguments":{"name":"Launch file","type":"go","request":"launch","mode":"debug","program":"./temp.go","hideSystemGoroutines":true,"__buildDir":"/Users/polina/go/src","__sessionId":"2ad0f0c1-a1fd-4fff-9fff-b8bc9a933fe5"}}
   120  2022-01-04T00:27:57-08:00 debug layer=dap parsed launch config: {
   121  	"mode": "debug",
   122  	"program": "./temp.go",
   123  	"backend": "default",
   124  	"stackTraceDepth": 50,
   125  	"hideSystemGoroutines": true
   126  }
   127  ...
   128  ```
   129  This logging is written to stderr and is not forwarded via 
   130  [output events](https://microsoft.github.io/debug-adapter-protocol/specification#Events_Output).
   131  
   132  ## Debuggee Output
   133  
   134  Debuggee's stdout and stderr are written to stdout and stderr respectfully and are not forwarded via 
   135  [output events](https://microsoft.github.io/debug-adapter-protocol/specification#Events_Output).
   136  
   137  ## Versions
   138  
   139  The initial DAP support was released in [v1.6.1](https://github.com/go-delve/delve/releases/tag/v1.6.1) with many additional improvements in subsequent versions. The [remote attach](https://github.com/go-delve/delve/issues/2328) support was added in [v1.7.3](https://github.com/go-delve/delve/releases/tag/v1.7.3).
   140  
   141  The DAP API changes are backward-compatible as all new features are opt-in only. To update to a new [DAP version](https://microsoft.github.io/debug-adapter-protocol/changelog) and import a new DAP feature into delve, 
   142  one must first update the [go-dap](https://github.com/google/go-dap) dependency.
   143  
   144  <!--- TODO:
   145  - most requests are handled synchronously and block
   146  - hence many commands not supported when running, but setting breakpoints is
   147  --->