Debugger Adapter Protocol (Debugging with GDB)

## 29 Debugger Adapter Protocol ¶

The Debugger Adapter Protocol is a generic API that is used by some IDEs to communicate with debuggers. It is documented at https://microsoft.github.io/debug-adapter-protocol/.

Generally, GDB implements the Debugger Adapter Protocol as written. However, in some cases, extensions are either needed or even expected.

GDB defines some parameters that can be passed to the `launch` request:

`args`

  If provided, this should be an array of strings. These strings are provided as command-line arguments to the inferior, as if by `set args`. See Your Program’s Arguments.

`cwd`

  If provided, this should be a string. GDB will change its working directory to this directory, as if by the `cd` command (see Your Program’s Working Directory). The launched program will inherit this as its working directory. Note that change of directory happens before the `program` parameter is processed. This will affect the result if `program` is a relative filename.

`env`

  If provided, this should be an object. Each key of the object will be used as the name of an environment variable; each value must be a string and will be the value of that variable. The environment of the inferior will be set to exactly as passed in. See Your Program’s Environment.

`program`

  If provided, this is a string that specifies the program to use. This corresponds to the `file` command. See Commands to Specify Files.

`stopAtBeginningOfMainSubprogram`

  If provided, this must be a boolean. When ‘`True`’, GDB will set a temporary breakpoint at the program’s main procedure, using the same approach as the `start` command. See Starting your Program.

`stopOnEntry`

  If provided, this must be a boolean. When ‘`True`’, GDB will set a temporary breakpoint at the program’s first instruction, using the same approach as the `starti` command. See Starting your Program.

GDB defines some parameters that can be passed to the `attach` request. Either `pid` or `target` must be specified, but if both are specified then `target` will be ignored.

`pid`

  The process ID to which GDB should attach. See Debugging an Already-running Process.

`program`

  If provided, this is a string that specifies the program to use. This corresponds to the `file` command. See Commands to Specify Files. In some cases, GDB can automatically determine which program is running. However, for many remote targets, this is not the case, and so this should be supplied.

`target`

  The target to which GDB should connect. This is a string and is passed to the `target remote` command. See Connecting to a Remote Target.

In response to the `disassemble` request, DAP allows the client to return the bytes of each instruction in an implementation-defined format. GDB implements this by sending a string with the bytes encoded in hex, like `"55a2b900"`.

When the `repl` context is used for the `evaluate` request, GDB evaluates the provided expression as a CLI command.

Evaluation in general can cause the inferior to continue execution. For example, evaluating the `continue` command could do this, as could evaluating an expression that involves an inferior function call.

`repl` evaluation can also cause GDB to appear to stop responding to requests, for example if a CLI script does a lengthy computation.

Evaluations like this can be interrupted using the DAP `cancel` request. (In fact, `cancel` should work for any request, but it is unlikely to be useful for most of them.)

GDB provides a couple of logging settings that can be used in DAP mode. These can be set on the command line using the `-iex` option (see Choosing Files).

`set debug dap-log-file [filename]`

  Enable DAP logging. Logs are written to filename. If no filename is given, logging is stopped.

`set debug dap-log-level level`

  Set the DAP logging level. The default is ‘`1`’, which logs the DAP protocol, whatever debug messages the developers thought were useful, and unexpected exceptions. Level ‘`2`’ can be used to log all exceptions, including ones that are considered to be expected. For example, a failure to parse an expression would be considered a normal exception and not normally be logged.