// Description
CDT GDB debug adapter extension for Visual Studio Code
// Readme
Open VSX#CDT GDB Debug Adapter Extension for Visual Studio Code
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 (
attachuse case), or a suitable GDB server variant must be installed tolaunchand 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 |
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, neverDefault: 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:
###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: falseNotes:* Requires support for multiple connections to the same TCP port in connected GDB server.* Requires gdbAsync mode and cannot be used with gdbNonStop mode. |
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, neverDefault: 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, 8Default: 8 |
parity | x | x | string | The type of parity check enabled with the transmitted data.Supported values: none, odd, even, mark, spaceDefault: 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, 2Default: 1 |
handshakingMethod | x | x | string | The handshaking method used for flow control across the serial line.Supported values: none, XON/XOFF, RTS/CTSDefault: none - no handshaking |
eolCharacter | x | x | string | The EOL character used to parse the UART output line-by-line.Supported values: LF, CRLFDefault: 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.
// Install
Open this extension directly in your IDE — no CLI, no extra tools.
eclipse-cdt.cdt-gdb-vscodeIf your IDE doesn't open automatically, copy the ID above and paste it into the Extensions view (⌘P → ext install <id>).
// Source signals
Live from open-vsx.org. Refreshed hourly.
// Are you the author?
This listing is mirrored from Open VSX. Claim it to ship a native OXP build, customise the page, and respond to reviews.
Claim this listing// Package Info
- Version
- 2.7.0
- Owner
- @vsx-eclipse-cdt
- Downloads
- 780.6k
- Stars
- 0