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:

EZ Setup

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

penagos / vgdb

readme