CDT GDB Debug Adapter Extension for Visual Studio Code

July 2, 2026 · View on GitHub

This is a Visual Studio Code extension that supports debugging using GDB and the MI protocol. It is built by the experts that provide the GDB support in the Eclipse C/C++ IDE (CDT).

This extension provides a number of features that integrate into the Visual Studio Code debug environment. This includes launch types, support for the standard debug views as well as a custom viewer for memory browsing.

Prerequisites

External tools are expected to be present on your system depending on the intended use case.

Local GDB Debug: A GDB installation is required on your system.
Remote GDB Debug: A GDB installation is required on your system. In addition to that you must have either access to a running GDB server instance (attach use case), or a suitable GDB server variant must be installed to launch and connect to your debug target.

Launch Configurations

The Visual Studio Debug Extension for GDB contributes two debugger types:

gdb: Support for Local GDB Debug. Launch or attach to an already running application locally on your host machine using GDB.
gdbtarget: Support for Remote GDB Debug. Launch or attach to an already running remote GDB server using GDB.

Both come as launch and attach request types, each with a sophisticated set of configuration settings.

`gdb` Debugger Type

Launch and attach configuration settings that can be used with the gdb debugger type for local GDB debug.

Setting	`launch`	`attach`	Type	Description
`gdb`	x	x	`string`	Path to GDB. This can be an absolute path or the name of an executable on your PATH environment variable. Default: `gdb`
`cwd`	x	x	`string`	Current working directory for launching GDB. Default: Directory of the debugged `program`.
`environment`	x	x	`object`	Environment variables to use when launching GDB, defined as a key-value pairs. Use `null` value to remove variable. Example: "environment": { "VARNAME": "value", "PATH": "/new/item:${env:PATH}", "REMOVEME": null }
`program`	x	x	`string`	Path to the program to be debugged. For `launch` requests, this program is also launched. Default: `${workspaceFolder}/${command:askProgramPath}`, which allows to interactively enter the full program path.
`arguments`	x		`string`	Arguments for the program.
`processId`		x	`string`	Process ID to attach to.
`gdbAsync`	x	x	`boolean`	Use `mi-async` mode for communication with GDB. Always `true` if `gdbNonStop` is `true`. Default: `true`
`gdbNonStop`	x	x	`boolean`	Use `non-stop` mode for controlling multiple threads. Default: `false`
`run`	x	x	`string`	How much of the program to run/continue after starting the debug session. `all`: Launch: run the program. Attach: let all threads run. `preserve`: Launch: don’t run, allow interaction with GDB before it starts the program (use the Continue command to do so). Attach: keep stopped threads stopped. Default: `all`
`verbose`	x	x	`boolean`	Produce verbose log output.
`logFile`	x	x	`string`	Absolute path to the file to log interaction with GDB.
`openGdbConsole`	x	x	`boolean`	(UNIX-only) Open a GDB console in your IDE while debugging.
`preConnectCommands`	x	x	`string[]`	List of GDB commands sent before attaching to inferior.
`initCommands`	x	x	`string[]`	List of GDB commands sent after attaching to inferior before running/continuing.
`updateThreadInfo`	x	x	`string`	Controls when thread information is retrieved from GDB. See `updateThreadInfo` setting section for details. Supported values: `missing`, `when-requested`, `never` Default: `missing`

`updateThreadInfo` Setting

The updateThreadInfo setting controls when thread information is retrieved from GDB. This setting can be used with both gdb and gdbtarget debugger types.

Supported values:

never: Thread info is never retrieved, no thread names will be displayed. Good for slow links or targets that have no thread names or are single-threaded.
missing (default): Thread info is retrieved when target is stopped or when thread names are missing and GDB allows retrieval while running (when using async mode locally or non-stop mode). Good for targets whose thread names/details don't change.
when-requested: Thread info is retrieved every time the client requests it, as far as possible (when stopped or when GDB allows while running). Good when thread names/details do change.

`gdbtarget` Debugger Type

Launch and attach configuration settings that can be used with the gdbtarget debugger type for remote GDB debug connections.

Setting	`launch`	`attach`	Type	Description
`gdb`	x	x	`string`	Path to GDB. This can be an absolute path or the name of an executable on your PATH environment variable. Default: `gdb`
`cwd`	x	x	`string`	Current working directory for launching GDB. Default: Directory of the debugged `program`.
`environment`	x	x	`object`	Environment variables to use when launching GDB, defined as a key-value pairs. Use `null` value to remove variable. Example: "environment": { "VARNAME": "value", "PATH": "/new/item:${env:PATH}", "REMOVEME": null }
`program`	x	x	`string`	Path to the program to be debugged. For `launch` requests, this program is also launched. Default: `${workspaceFolder}/${command:askProgramPath}`, which allows to interactively enter the full program path. Note: While `program` is marked as required, the debug adapter launches anyway for remote GDB connections. For example to inspect an embedded target system's memory and other hardware resources without debugging a program.
`gdbAsync`	x	x	`boolean`	Use `mi-async` mode for communication with GDB. Always `true` if `gdbNonStop` is `true`. Default: `true`
`gdbNonStop`	x	x	`boolean`	Use `non-stop` mode for controlling multiple threads. Default: `false`
`auxiliaryGdb`	x	x	`boolean`	Creates an auxiliary GDB connection to the target TCP port to allow memory accesses and expression evaluation while the target is running. Default: `false` Notes: _ Requires support for multiple connections to the same TCP port in connected GDB server. _ Requires `gdbAsync` mode and cannot be used with `gdbNonStop` mode.
`run`	x	x	`string`	How much of the program to continue after attaching. `all`: Let all threads run. `preserve`: Keep stopped threads stopped. Default: `all`
`verbose`	x	x	`boolean`	Produce verbose log output.
`logFile`	x	x	`string`	Absolute path to the file to log interaction with GDB.
`openGdbConsole`	x	x	`boolean`	(UNIX-only) Open a GDB console in your IDE while debugging.
`preConnectCommands`	x	x	`string[]`	List of GDB commands sent to initialize GDB before attaching to target.
`initCommands`	x	x	`string[]`	List of GDB commands sent to initialize debug target after attaching to it but before loading image and symbols.
`preRunCommands`	x	x	`string[]`	List of GDB commands sent after loading image on target before resuming target.
`imageAndSymbols`	x	x	`object`	Additional settings for loading images to the target and symbols into the debugger. See section "`imageAndSymbols` object" for details.
`target`	x	x	`object`	Additional settings to configure the remote GDB target. See section "`target` object" for details.
`customResetCommands`	x	x	`string[]`	List of GDB commands to perform a RESET of the connected target, for example through `monitor ...` commands of the connected GDB server.
`updateThreadInfo`	x	x	`string`	Controls when thread information is retrieved from GDB. See `updateThreadInfo` setting section for details. Supported values: `missing`, `when-requested`, `never` Default: `missing`

`imageAndSymbols` Object

Additional settings for loading images to the target and symbols into the debugger. This object can be used in launch and attach configurations for the gdbtarget debugger type for remote GDB connections.

Setting	`launch`	`attach`	Type	Description
`symbolFileName`	x	x	`string`	If specified, a symbol file to load at the given (optional) offset. Also see `symbolOffset`.
`symbolOffset`	x	x	`string`	If `symbolFileName` is specified, the offset added to symbol addresses when loaded.
`imageFileName`	x	x	`string`	If specified, an image file to load at the given (optional) offset. Also see `imageOffset`.
`imageOffset`	x	x	`string`	If `imageFileName` is specified, the offset used to load the image.

`target` Object

Additional settings to configure the remote GDB target. This object can be used in launch and attach configurations for the gdbtarget debugger type for remote GDB connections.

Setting	`launch`	`attach`	Type	Description
`type`	x	x	`string`	The kind of target debugging to do. This is passed to `-target-select`. Default: `remote`
`parameters`	x	x	`string[]`	Target parameters for the type of target. Normally something like `localhost:12345`. Default: `${host}:${port}`.
`host`	x	x	`string`	Target host to connect to. Ignored if `parameters` is set. Default: `localhost`
`port`	x	x	`string`	Target port to connect to. Ignored if `parameters` is set. Default: Value captured by `serverPortRegExp`, otherwise defaults to `2331`
`cwd`	x		`string`	Specifies the working directory of the server. Default: Working directory of GDB
`environment`	x		`object`	Environment variables to use when launching server, defined as key-value pairs. Defaults to the environment used to launch GDB. Use `null` value to remove variable. Example: "environment": { "VARNAME": "value", "PATH": "/new/item:${env:PATH}", "REMOVEME": null }
`server`	x		`string`	The executable for the target server to launch (e.g. `gdbserver` or `JLinkGDBServerCLExe`). This can be an absolute path or the name of an executable on your PATH environment variable. Default: `gdbserver`
`serverParameters`	x		`string[]`	Command line arguments passed to server. Default: `--once :0 ${args.program}`
`serverPortRegExp`	x		`string`	Regular expression to extract `port` from by examining stdout/stderr of the GDB server. Once the server is launched, `port` will be set to this if unspecified. Defaults to matching a string like `Listening on port 41551` which is what `gdbserver` provides. Ignored if `port` or `parameters` is set.
`portDetectionTimeout`	x		`number`	Timeout for port detection based on `serverPortRegExp`. Default value is `10000` (ms).
`serverDisconnectTimeout`	x		`number`	Timeout for GDB server disconnect request. Default value is 1000 (ms).
`serverStartupDelay`	x		`number`	Delay, in milliseconds, after startup but before continuing launch. If `serverPortRegExp` is provided, it is the delay after that regexp is seen.
`automaticallyKillServer`	x		`boolean`	Automatically terminate the launched server when client issues a disconnect. Default: `true`
`watchServerProcess`	x		`boolean`	Watch server process and handle when it (unexpectedly) exits. Default: `true`
`uart`	x	x	`object`	Settings related to displaying UART output in the debug console.

`uart` object

Settings related to displaying UART output in the debug console. This object can be used in the target object of launch and attach configurations for the gdbtarget debugger type for remote GDB connections.

Setting	`launch`	`attach`	Type	Description
`serialPort`	x	x	`string`	Path to the serial port connected to the UART on the board.
`socketPort`	x	x	`string`	Target TCP port on the host machine to attach socket to print UART output. Default: `3456`
`baudRate`	x	x	`number`	Baud Rate (in bits/s) of the serial port to be opened. Default: `115200`.
`characterSize`	x	x	`number`	The number of bits in each character of data sent across the serial line. Supported values: `5`, `6`, `7`, `8` Default: `8`
`parity`	x	x	`string`	The type of parity check enabled with the transmitted data. Supported values: `none`, `odd`, `even`, `mark`, `space` Default: `none` - no parity bit sent
`stopBits`	x	x	`number`	The number of stop bits sent to allow the receiver to detect the end of characters and resynchronize with the character stream. Supported values: `1`, `1.5`, `2` Default: `1`
`handshakingMethod`	x	x	`string`	The handshaking method used for flow control across the serial line. Supported values: `none`, `XON/XOFF`, `RTS/CTS` Default: `none` - no handshaking
`eolCharacter`	x	x	`string`	The EOL character used to parse the UART output line-by-line. Supported values: `LF`, `CRLF` Default: `LF`

Memory Browser

The extension comes with a Memory Browser window. However, we have plans to deprecate and remove the window in favour of the Eclipse CDT Cloud Memory Inspector extension for Visual Studio Code which is available from the Visual Studio Code Marketplace and the Open VSX Registry.

Any feedback on these plans is welcomed in the discussion in GitHub issue #110.

Contributions

We welcome any feedback and contributions on GitHub.

Please raise GitHub issues to submit feedback, defect reports, and enhancement requests.

Check our contribution guidelines for more information on how to contribute changes. And our developer documentation for how to build and develop the extension.

This open-source project is part of Eclipse CDT Cloud.