Extension for Visual Studio Code - GDB Debug extension to make OiAK easier. In gdbserver mode, GDB is run locally, which connects to gdbserver on the remote system. In gdb mode, the Visual Studio debugger drives GDB on the remote system. This is a better option if the local version of GDB isn't compatible with the version installed on the target computer. This is the only mode that the Linux Console window supports.
Native VSCode debugger. Supports both GDB and LLDB.
- VisualGDB allows debugging code without creating Visual Studio projects. Simply open the Quick Debug window, point to a binary built with GNU tools and VisualGDB will start a debugging session. Your settings will be saved in a preset, so next time you could just select them from a list and start debugging with one mouse click.
- In this tutorial, you will configure Visual Studio Code to use the GCC C compiler (g) and GDB debugger on Linux. GCC stands for GNU Compiler Collection; GDB is the GNU debugger. After configuring VS Code, you will compile and debug a simple C program in VS Code. This tutorial does not teach you GCC, GDB, Ubuntu or the C language.
Installation
Press ctrl-p (cmd+p on OS X) and run
ext install webfreak.debug
in visual studio code and install GDB/LLDB. See Usage
for details on how to set it up.Usage
Or if you already have an existing debugger in your project setup you can click 'Create Configuration' or use the auto completion instead:
Open your project and click the debug button in your sidebar. At the top right pressthe little gear icon and select GDB or LLDB. It will automatically generate the configurationyou need.
Note: for LLDB you need to have
lldb-mi
in your PATHVisualgdb
If you are on OS X you can add
lldb-mi
to your path usingln -s /Applications/Xcode.app/Contents/Developer/usr/bin/lldb-mi /usr/local/bin/lldb-mi
if you have Xcode.Now you need to change
target
to the application you want to debug relativeto the cwd. (Which is the workspace root by default)Additionally you can set
terminal
if you want to run the program in a separate terminal withsupport for input. On Windows set it to an empty string ('
) to enable this feature. On linuxset it to an empty string ('
) to use the default terminal emulator specified with x-terminal-emulator
or specify a custom one. Note that it must support the -e
argument.Before debugging you need to compile your application first, then you can run it usingthe green start button in the debug sidebar. For this you could use the
preLaunchTask
argument vscode allows you to do. Debugging multithreaded applications is currently notimplemented. Adding breakpoints while the program runs will not interrupt it immediately.For that you need to pause & resume the program once first. However adding breakpointswhile its paused works as expected.Extending variables is very limited as it does not support child values of variables.Watching expressions works partially but the result does not get properly parsed andit shows the raw output of the command. It will run
data-evaluate-expression
to check for variables.While running you will get a console where you can manually type GDB/LLDB commands or MIcommands prepended with a hyphen
-
. The console shows all output separatedin stdout
for the application, stderr
for errors and log
for log messages.Some exceptions/signals like segmentation faults will be catched and displayed butit does not support for example most D exceptions.
Attaching to existing processes
Attaching to existing processes currently only works by specifying the PID in the
launch.json
and setting request
to 'attach'
. You also need to specify the executablepath for the debugger to find the debug symbols.This will attach to PID 4285 which should already run. GDB will pause the program on entering and LLDB will keep it running.
Using gdbserver
for remote debugging (GDB only)
You can also connect to a gdbserver instance and debug using that. For that modify the
launch.json
by setting request
to 'attach'
and remote
to true
and specifing theport and optionally hostname in target
.This will attach to the running process managed by gdbserver on localhost:2345. You mightneed to hit the start button in the debug bar at the top first to start the program.
Using ssh for remote debugging
Debugging using ssh automatically converts all paths between client & server and also optionallyredirects X11 output from the server to the client. Simply add a
ssh
object in your launch
request.cwd
will be used to trim off local paths and ssh.cwd
will map them to the server. This isrequired for basically everything except watched variables or user commands to work.For X11 forwarding to work you first need to enable it in your Display Manager and allow theconnections. To allow connections you can either add an entry for applications or run
xhost +
in the console while you are debugging and turn it off again when you are done using xhost -
.Because some builds requires one or more environment files to be sourced before running anycommand, you can use the
ssh.bootstrap
option to add some extra commands which will be prependedto the debugger call (using &&
to join both).Issues
After you have set up the basics of your debugging environment as specified in the configuration tutorials for each target compiler/platform, you can learn more details about debugging C/C++ in this section.
Visual Studio Gdb Commands
Visual Studio Code supports the following debuggers for C/C++ depending on the operating system you are using:
- Linux: GDB
- macOS: LLDB or GDB
- Windows: the Visual Studio Windows Debugger or GDB (using Cygwin or MinGW)
Windows debugging with GDB
You can debug Windows applications created using Cygwin or MinGW by using VS Code. To use Cygwin or MinGW debugging features, the debugger path must be set manually in the launch configuration (
launch.json
). To debug your Cygwin or MinGW application, add the miDebuggerPath
property and set its value to the location of the corresponding gdb.exe for your Cygwin or MinGW environment.For example:
Cygwin/MinGW debugging on Windows supports both attach and launch debugging scenarios.
To learn more, see Configuring C/C++ debugging.
If you are debugging with GDB on Windows, see Windows Debugging with MinGW64.
Conditional breakpoints
Conditional breakpoints enable you to break execution on a particular line of code only when the value of the condition is true. To set a conditional breakpoint, right-click on an existing breakpoint and select Edit Breakpoint. This opens a small peek window where you can enter the condition that must evaluate to true in order for the breakpoint to be hit during debugging.
In the editor, conditional breakpoints are indicated by a breakpoint symbol that has a black equals sign inside of it. You can place the cursor over a conditional breakpoint to show its condition.
Function breakpoints
Function breakpoints enable you to break execution at the beginning of a function instead of on a particular line of code. To set a function breakpoint, on the Run view right-click inside the Breakpoints section, then choose Add Function Breakpoint and enter the name of the function on which you want to break execution.
Expression evaluation
VS Code supports expression evaluation in several contexts:
- You can type an expression into the Watch section of the Run view and it will be evaluated each time a breakpoint is hit.
- You can type an expression into the Debug Console and it will be evaluated only once.
- You can evaluate any expression that appears in your code while you're stopped at a breakpoint.
Expressions in the Watch section take effect in the application being debugged; an expression that modifies the value of a variable will modify that variable for the duration of the program.
Sent when an incoming collider makes contact with this object's collider (2D physics only). Further information about the collision is reported in the Collision2D parameter passed during the call. If you don't need this information then you can declare OnCollisionEnter2D without the parameter. Sent when an incoming collider makes contact with this object's collider (2D physics only). Further information about the collision is reported in the Collision 2D parameter passed during the call. Notes: Collision events will be sent to disabled MonoBehaviours, to allow enabling Behaviours in response to collisions.
Multi-threaded debugging
The C/C++ extension for VS Code has the ability to debug multi-threaded programs. All threads and their call stacks appear in the Call Stack section:
Memory dump debugging
The C/C++ extension for VS Code also has the ability to debug memory dumps. To debug a memory dump, open your
launch.json
file and add the coreDumpPath
(for GDB or LLDB) or dumpPath
(for the Visual Studio Windows Debugger) property to the C++ Launch configuration, set its value to be a string containing the path to the memory dump. This will even work for x86 programs being debugged on an x64 machine.Additional symbols
If there are additional directories where the debugger can find symbol files (for example,
.pdb
files for the Visual Studio Windows Debugger), they can be specified by adding the additionalSOLibSearchPath
(for GDB or LLDB) or symbolSearchPath
(for the Visual Studio Windows Debugger).For example:
or
Locate source files
Vs Code Gdb
The source file location can be changed if the source files are not located in the compilation location. This is done by simple replacement pairs added in the
sourceFileMap
section. The first match in this list will be used.For example:
GDB, LLDB, and LLDB-MI Commands (GDB/LLDB)
For the
C++ (GDB/LLDB)
debugging environment, you can execute GDB, LLDB and LLDB-MI commands directly through the debug console with the -exec
command, but be careful, executing commands directly in the debug console is untested and might crash VS Code in some cases.Other debugging features
- Unconditional breakpoints
- Watch window
- Call stack
- Stepping
For more information on debugging with VS Code, see this introduction to debugging in VS Code.
For additional ways to configure the launch.json file so that you can debug your C/C++ app, see Configuring C/C++ debugging.
Natvis framework
You create custom views of C++ object in the debugger with the Natvis framework. You can read the Custom views for native objects topic for details on using Natvis with the C/C++ extension.
Debug remotely
For information about attaching to a remote process, such as debugging a process in a Docker container, see Pipe transport.
Debug the debugger
If you are experiencing a debugging problem with the extension that we can't diagnose based on information in your issue report, we might ask you to enable logging and send us your logs. See Enable logging for the debug adapter to learn how to get C/C++ extension logs.
Known limitations
Symbols and code navigation
All platforms:
- Because the extension doesn't parse function bodies, Peek Definition and Go to Definition don't work for symbols defined inside the body of a function.
Debugging
Windows:
- GDB on Cygwin and MinGW cannot break a running process. To set a breakpoint when the application is running (not stopped under the debugger), or to pause the application being debugged, press Ctrl-C in the application's terminal.
- GDB on Cygwin cannot open core dumps.
Linux:
- You may see an error saying:
ptrace: Operation not permitted
. This is due to GDB needing elevated permissions in order to attach to a process. This can be solved using the solutions below:- When using attach to process, you need to provide your password before the debugging session can begin.
- To disable this error temporarily, use the following command:
echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope
- To remove the error permanently, add a file called
10-ptrace.conf
to/etc/sysctl.d/
and add the followingkernel.yama.ptrace_scope = 0
.
macOS:
- LLDB:
- When debugging with LLDB, if the Terminal window is closed while in break mode, debugging does not stop. Debugging can be stopped by pressing the Stop button.
- When debugging is stopped the Terminal window is not closed.
- GDB:
- Additional manual install steps are required to use GDB on macOS. See Manual Installation of GDB for OS X in the README.
- When attaching to a process with GDB, the application being debugged cannot be interrupted. GDB will only bind breakpoints set while the application is not running (either before attaching to the application, or while the application is in a stopped state). This is due to a bug in GDB.
- Core dumps cannot be loaded when debugging with GDB because GDB does not support the core dump format used in macOS.
- When attached to a process with GDB, break-all will end the process.
Next steps
Read on to find out about:
- Configure C/C++ debugging - Learn about additional debugger configuration options.
- Basic Editing - Learn about the powerful Visual Studio Code editor.
- Code Navigation - Move quickly through your source code.
- Tasks - use tasks to build your project and more.
- Debugging - find out about the Visual Studio Code debugger.
If you have any other questions or run into any issues, please file an issue on GitHub.