github.com/neilgarb/delve@v1.9.2-nobreaks/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> <debugee>` - 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      hideSystemGoroutines<br>
    37      goroutineFilters
    38      </tr>
    39  <tr>
    40      <td>test<td>program                <td>dlvCwd<td>env<td>backend<td>args<td>cwd<td>buildFlags<td>output<td>noDebug</tr>
    41  <tr>
    42      <td>exec<td>program                <td>dlvCwd<td>env<td>backend<td>args<td>cwd<td>          <td>      <td>noDebug</tr>
    43  <tr>
    44      <td>core<td>program<br>corefilePath<td>dlvCwd<td>env<td>       <td>    <td>   <td>          <td>      <td>       </tr>
    45  <tr>
    46      <td>replay<td>traceDirPath         <td>dlvCwd<td>env<td>       <td>    <td>   <td>          <td>      <td>       </tr>
    47  <tr><td rowspan=2>attach<br><a href="https://pkg.go.dev/github.com/go-delve/delve/service/dap#AttachConfig">godoc</a>
    48      <td>local<td>processId             <td>      <td>   <td>backend<td>   <td>    <td>          <td>      <td>        </tr>
    49  <tr>
    50      <td>remote<td>                     <td>      <td>   <td>       <td>   <td>    <td>          <td>      <td>        </tr>
    51  </table>
    52  
    53  
    54  Not all of the configurations are supported by each of the two available DAP servers:
    55  
    56  <table border=1>
    57  <tr>
    58  <th>request<th>"mode":<th>`dlv dap`<th>`dlv --headless` <th> Description <th> Typical Client Usage
    59  </tr>
    60  <tr>
    61  <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.
    62  <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.
    63  <tr>
    64  <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.
    65  </tr>
    66  <tr>
    67  <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.
    68  <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>.
    69  </tr>
    70  </table>
    71  
    72  ## Disconnect and Shutdown
    73  
    74  ### Single-Client Mode
    75  
    76  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 debugee was attached to, `terminateDebuggee` option will be respected.
    77  
    78  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. 
    79  
    80  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. 
    81  
    82  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.
    83  
    84  ### Multi-Client Mode
    85  
    86  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.
    87  
    88  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.
    89  
    90  The server shuts down in response to a SIGTERM signal, taking down a launched process, but letting an attached process continue.
    91  
    92  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.
    93  
    94  ## Debugger Output
    95  
    96  The debugger always logs one of the following on start-up to stdout:
    97  * `dlv dap`:
    98     * `DAP server listening at: <host>:<port>`
    99  * `dlv --headless`: 
   100     * `API server listening at: <host>:<port>`
   101  
   102  This can be used to confirm that server start-up succeeded.
   103  
   104  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:
   105  
   106  ```
   107  Step interrupted by a breakpoint. Use 'Continue' to resume the original step command.
   108  invalid command: Unable to step while the previous step is interrupted by a breakpoint.
   109  Use 'Continue' to resume the original step command.
   110  Detaching and terminating target process
   111  ```
   112  
   113  More detailed logging can be enabled with `--log --log-output=dap` as part of the [`dlv` command](../../usage/dlv.md).
   114  It will record the server-side DAP message traffic. For example, 
   115  ```
   116  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}}
   117  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}}
   118  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"}}
   119  2022-01-04T00:27:57-08:00 debug layer=dap parsed launch config: {
   120  	"mode": "debug",
   121  	"program": "./temp.go",
   122  	"backend": "default",
   123  	"stackTraceDepth": 50,
   124  	"hideSystemGoroutines": true
   125  }
   126  ...
   127  ```
   128  This logging is written to stderr and is not forwarded via 
   129  [output events](https://microsoft.github.io/debug-adapter-protocol/specification#Events_Output).
   130  
   131  ## Debuggee Output
   132  
   133  Debuggee's stdout and stderr are written to stdout and stderr respectfully and are not forwarded via 
   134  [output events](https://microsoft.github.io/debug-adapter-protocol/specification#Events_Output).
   135  
   136  ## Versions
   137  
   138  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).
   139  
   140  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, 
   141  one must first update the [go-dap](https://github.com/google/go-dap) dependency.
   142  
   143  <!--- TODO:
   144  - most requests are handled synchronously and block
   145  - hence many commands not supported when running, but setting breakpoints is
   146  --->