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.