C/C++ extension for Visual Studio Code

Today is an exciting day for all of us on the C++ team here at Microsoft! We love that we offer the great development experience C and C++ developers enjoy in Visual Studio on Windows, but at the same time we realize that some of you, for your own reasons, have chosen Linux or OS/X as your primary development platform, so you cannot utilize Visual Studio for your development needs. Today we are announcing a Preview of a product for your C/C++ editing and debugging needs on Linux and OS/X: the C/C++ extension to Visual Studio Code.

For those of you who are not aware of Visual Studio Code, Visual Studio Code is a new choice of tool in the Visual Studio family of products which combines the simplicity of a code editor with what developers need for their code-edit-debug cycle. The current Visual Studio Code experience only provides basic syntax highlighting support via the C/C++ text made bundle, this preview version of the C/C++ extension introduces a better language service experience with support for code-navigation and the ability to debug C/C++ applications but given this is a preview release there are a few caveats to this experience!

In the rest of this post I will assume that you have downloaded and configured Visual Studio Code, and also the preview of the C/C++ extension that we are announcing here.  I will walk you through the editing experience, the debugging experience, and options for compiling/building your code. I will close by sharing some useful links on how to report issues, make requests, and in general how to give us feedback on our current plans.

Using the C/C++ code-editing aids in Visual Studio Code

As soon as a folder containing C/C++ sources is loaded into Visual Studio Code the language service engine kicks in and the tag-parser starts parsing the source directory generating an offline database to store symbol information (browse.VC.db file). Look for the C_Cpp:Parsing notification on the Visual Studio Code status bar.

Once the symbol data base population is complete (C_Cpp:Ready notification) you are ready to try out the preview experience of the language services portion of this extension. The preview experience for the language service experience currently introduces support for code navigation through the following feature set.

Navigate to a particular symbol within the same source file (Cntrl + P, @Symbol Name)

Navigate to a particular symbol across source files (Cntrl + P, #Symbol Name)

Go to definition (F12)

Peek definition (Alt + F12)

Cntrl + Hover

Given that this is indeed a preview experience there are a few caveats. While Go to definition and Peek definition will work for most part it’s currently not wired up to work for locals. This is primarily because the tag-parser currently does not parse function bodies. Also given there is currently no semantic analysis that is performed, Go to definition and Peek definition as  only some-what accurate as they are based upon text parsing and matching of symbols. We are working hard to make this happen.

While the current language service experience is designed to provide you value out-of-the-box, one can further improve the experience by  providing a little more information about include paths not in your working directory opened in Visual Studio Code. In the future we will use the same mechanism to ask for more details to drive other language service features such as Auto-Complete.

As you traverse through your source code you will notice some headers are squiggled. The reason why these headers are squiggled is because we were not able to find them in the current source or sub source folders opened in Visual Studio Code. Hovering over these squiggles a light bulb action will appear which will allow you to specify the path on disk for these headers in a properties file known as the ‘c_cpp_properties.json’ file as shown in the figure below.

Adding your include directories to the “includePath” property in this file for the specific configuration you are interested in will help drive a more complete and accurate language service experience.

Debugging your C/C++ application in Visual Studio Code

This extension also introduces great support for debugging your C++ program with Visual Studio Code. You’ll be able to use all of the standard debugging capabilities that you’re familiar with, including setting and hitting breakpoints, stepping, inspecting variables, and viewing the call stack. Beyond that, you’ll also able to take advantage of some advanced debugging capabilities, including function breakpoints, expression evaluation, conditional breakpoints, and core dump debugging.

The debugging experience currently only works out-of-the-box for Linux – Ubuntu 14.04 (x64). We are working on OS X support as well, the current experience requires manual installation steps and has some limitations. Debugging on windows with VSCode for C/C++ code is currently not supported.

Getting set up

Before you can get started debugging C++ code in Visual Studio Code, you’ll need to set a few things up. Navigate to the Debug View by clicking on the debug icon on far left toolbar. Hit the “Settings” gear icon in the debug pane and select “C++ Launch (GDB).” This will bring up the launch.json file.

The launch.json file defines a set of configurations that tell the debugger how to interact with your built application. We include two configurations by default—one which shows the properties necessary for launching the application from VS Code, and the other which shows the properties necessary for attaching to an already running process. Hovering over a property name will show a tooltip that describes the property and possible values, but minimally you will need to update the “program” property to have the program name and path. You can learn more about the properties in the launch.json file and how to use them by reading the VS Code debugging documentation.

Once your launch.json file is properly configured, you’re ready to debug a C++ program. Note that VS Code will not build your program (but simply debug the built program) unless you also create a task.json file and set it to the preLaunchTask property in the launch.json file.

Function Breakpoints

Function breakpoints enable you to break execution at the beginning of a function rather than on a particular line of code. To set a function breakpoint in VS Code, right click in the breakpoints pane and click “Add Function Breakpoint,” then type the name of the function on which you’d like to break.

Expression Evaluation

Debugging C++ code often requires more than simply viewing the value of variables at a breakpoint. The C++ extension for VS Code has support for evaluating expressions in several spaces. You can type an expression into the Watch pane, and it will be evaluated when a breakpoint is hit. Note that this has side effects—an expression that modifies the value of a variable will modify that value for the duration of program execution. If you’d like to view the value of an expression that is a part of your code, you can hover over any expression in the editor while stopped at a breakpoint and the data tip will show the evaluated expression. If you only want to evaluate an expression once (rather than having it in the Watch pane), you can simply type the expression in the Debug Console.

Conditional Breakpoints

Right clicking on a breakpoint and selecting “Edit breakpoint” will open a peak window in your editor. Type a condition (eg. “i > 15”) and that breakpoint will only activate and break execution when that condition evaluates to true. Conditional breakpoints are indicated by a breakpoint symbol that has the black equals sign. Hovering over a conditional breakpoint will show its value.

Core Dump Debugging

The extension also offers the ability to debug using a memory dump. To do this, add the “coreDumpPath” property to the C++ Launch configuration in your launch.json file and set it to the path to your core dump. This will even work for multi-threaded programs and x86 programs being debugged on a x64 machine.

GDB and MI commands

You can also use the debug console with the “-exec” command to execute GDB commands directly (be careful though—executing GDB commands directly in the debug console is untested and may crash VS Code in some cases). A full introduction to debugging in VS Code is available here.

A quick demo demonstrating  the C/C++ experience:

Let us know what you think!

This particular release of the C/C++ extension for Visual Studio Code is a start and we’ll need your help to make this a full experience. If you’d like to help us build the best C/C++ experience on any platform, you can join our Cross-Platform C++ Insiders group where you’ll be able to talk directly to the product team and influence our investment in this area. We also recognize that there are some immediate asks you’re likely to have, so please go ahead and add them to  Visual Studio Code user-voice and we would love your help in prioritizing them just right.

Thank you for reading to the end, I look forward to seeing the bugs you report, and the requests you want us to consider. If you have any questions or comments that don’t fit a bug or a feature request, please drop me a comment below – our team is monitoring this blog comments and of-course don’t forget to go download the C/C++ extension for VS Code.