Debugger Adapter Protocol (Debugging with GDB)

Next: JIT Interface, Previous: Annotations, Up: Top [Contents][Index]

## 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 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 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 Environment.

`program`

  If provided, this is a string that specifies the program to use. This corresponds to the `file` command. See 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.

`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.

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 Attach.

`program`

  If provided, this is a string that specifies the program to use. This corresponds to the `file` command. See 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.

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 File Options).

`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.

Next: JIT Interface, Previous: Annotations, Up: Top [Contents][Index]