vGDB | Visual Studio Code GDB Debug Adapter

A native typescript implementation of a debug adapter for GDB for use in Visual Studio Code. Tested on Linux, Windows support is untested. This extension is under active development

Features

• Debugging on Linux (Windows and Mac support untested)
• Launch target in integrated Visual Studio Code terminal or external terminal
• Conditional breakpoints (break on condition and hit count)
• Disassembly viewing and stepping
• Command completion
• Reverse debugging (on supported CPUs / kernels)
• Variable watches
• Viewing of register values
• Debug Console prompt accepts native GDB commands (as well as MI commands)
• Commands issued in the debug console will automatically pause and resume inferior process
• Honors deferred symbol loading settings in .gdbinit
• Support for lazy (deferred) symbol loading
• Environment variables
• Attach requests
• Works with remoteSSH
• Small and written in Typescript only

Installation

You can either download vGDB from within VSCode's Extensions pane (recommended), get it from the Extension marketplace, download the latest bundled VSIX package from the releases section on GitHub or build from source (instructions below).

Quick Start

vGDB ships with a sample launch configuration snippet you can use to quickly get started. Assuming your executable is named a.out, getting started is as easy as:

There is also a snippet for an attach request.

Configuration

These are all of the settings currently supported:

Launch Requests

Configuration Option	Required	Description
program	Yes	Path to program to debug "path/to/executable"
request	Yes	Set this to launch
args	No	Array of arguments to pass to debuggee ["arg1", "arg2", "arg3"]
cwd	No	The directory in which to start GDB "someOptionalDirectory"
debug	No	Verbosity of logging. "off"|"basic"|"verbose"
debugger	No	Path to GDB executable "/absolute/path/to/gdb"
debuggerArgs	No	Array of arguments to pass to debugger ["arg1", "arg2", "arg3"]
env	No	Key value pairs of environment variables to set in debugging shell {"name1": "value1", "name2": "value2"}
externalConsole	No	If set to false, debuggee will launch in Visual Studio Code terminal true|false
sharedLibraries	No	Array of shared library names to load, disregards all other libraries ["solib1.so", "solib2.so"]
startupCmds	No	Array of GDB commands to run at start ["gdb_command", "gdb_command2"]
useAbsoluteFilePaths	No	If true (default), full filepaths will be used when setting breakpoints true|false

Additional Notes

• When using the sharedLibraries configuration setting, your .gdbinit setting for auto-solib-add will be overwritten to be false. The debug adapter will listen for shared library load events and only proceed to sharedlibrary <name> if that file is in your whitelist.
• When setting the externalConsole setting to true, hitting CTRL+C in the integrated terminal will not abort the debug target.
• The startupCmds commands will run after those in your .gdbinit file have run.
• Environment variables are available to both the debugger and inferior process

Attach Requests

Configuration Option	Required	Description
program	Yes	Path to program to debug
request	Yes	Set this to attach
debug	No	Verbosity of logging. Values are off, basic or verbose
debugger	No	Path to GDB executable
useAbsoluteFilePaths	No	If true (default), full filepaths will be used when setting breakpoints

Building from Source

It's recommended that you use one of the published VSIX files on the releases tab, but you can also build the extension from source. To compile/package the extension yourself, you'll need to run the following commands:

npm install
vsce package

If you do not already have the vsce NodeJS CLI tool installed, please see https://code.visualstudio.com/api/working-with-extensions/publishing-extension