Using Visual Studio Code and Building and Debugging with C++ on Mac OS X

Saturday, August 6th, 2016

By Michael Suodenjoki, August 2016.

I wanted to play with and test Visual Studio Code's (VSCode) features for doing C++ development on the Mac platform.

At work and in the past 20+ years I've mainly been using Windows, so this is somewhat different and new interesting territory for me. Previously I've used C++ on the Mac at a basic level, but do have *nix experience, e.g. working with GCC compiler, GDB debugger, NetBeans etc.

Nevertheless, this document contain my VSCode experience results, with small how-to guides for getting up and running.

To follow, I do expect that you have a minimal understanding of working with text editors, C++ build/compilation, C++ debugging and terminal shell commands.

Test machine and installed setup:

• Mac OS X Yosemite, version 10.10.5
• XCode 7.2.1, the official development tool for C++ on Mac OS X is assumed installed.
• Xcode Command Line Tools is assumed installed. This will include (Apple's) clang compiler and Standard C/C++ library.
• Visual Studio Code (VSCode) 1.4 is assumed installed.
• VSCode Extension(s):
  • Microsoft's C/C++ v0.8.1
  • Yasuaki MITANI's C/C++ Clang v0.2.1
  • xaver's Clang-Format v0.10.2

Sample C++ code

Let's take a simple Hello World program:

#include <iostream>
      
using namespace std;
      
int main()
{
  cout << "hello Michael. It works!" << endl;
}      

Create project folder structure

VSCode requires (or works best) when a project is residing in its own main folder. This also makes the VSCode EXPLORER pane work appropriately.

1. Create a folder e.g. test (use Finder or Terminal)
2. Start the VSCode application.
3. Create a new file using File, New or Command(⌘)+N.
4. Type in the above C++ source code into the new file and save it as a new file, e.g. test.cpp using File, Save As... or Shift(⇧)+Command(⌘)+S.

To get code completion etc. up and running

To setup include path to point to the Standard C++ headers, I've added a new path /Applications/... to the includePath setting in the c_cpp_properties.json file in the "Mac" configuration section.

  ...
"configurations": [
  {
    "name": "Mac",
    "includePath": ["/usr/include", 
                    "/Applications/XCode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.11.sdk/usr/include"],
    ...
  }
]
...

This is also where you would need to add the include path for/if you use a third-party library, e.g. boost.

Formatting your C++ source code with clang-format

To format C++ source code with clang-format, clang-format must be available (installed).

clang-format can most easily be installed by using the Homebrew package manager. See also http://macappstore.org/clang-format/

1. Activate Terminal with Command(⌘)+Space, type Terminal and press Enter.

2. Install Homebrew package manager (skip if already installed) by executing shell command:

   /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
             

3. Install clang-format using Homebrew by executing command:

   brew install clang-format

4. Verify by running command:

   clang-format --version
             

   Should output something like, e.g.:

   clang-format version 3.9.0 (tags/google/stable/2016-06-27)

To format your C++ source code file run Shift(⇧)+Alt(⌥)+F. Alternatively start the VSCode's View, Command Palette Shift(⇧)+Command(⌘)+P and search for and run Format Code command.

Tip. You can place your own .clang-format file specifying your own configuration file for the formatting. For options see Clang Format Style Options

Build (compile) your C++ file

As far as I understand there is, as of this writing (August 5, 2016), no such thing as an integrated build command for clang in VSCode. Perhaps it is possible to establish a task runner for it.

I can see several options - at least:

• Compile using clang or g++ on command line, e.g. using bash.
  • Example: Stackoverflow: How do I set up VSCode to compile C++ code
• Use CMake or alternative cross-platform build (generator) tools. A great advantage with this is that your project becomes a lot more platform independent.

Both of these options can be used with VSCode's integrated terminal.

Since, I could see that VSCode already have CMake extensions available and know that CMake is quite popular nowadays I though this could be interesting to use.

I'm not at all familiar with CMake, except at the most basic level. I understand what it is. I also know that some people believe it to be difficult to work with. Build tools usually are complex - particular in non-trivial, i.e. real development, environments. So this is not surprising.

Installing CMake

To install CMake:

1. Open Terminal, e.g. directly from within VSCode using View, Integrated Terminal to open lower terminal pane in VSCode.
2. Run command brew install cmake to install CMake via Homebrew.
3. Run command cmake --version to verify version installed. I worked with version 3.6.1.
4. Also consider to install the VSCode CMake extension, Shift(⇧)+Command(⌘)+X to open the extension view, search for CMake.

Build with CMake

1. Create a CMakeLists.txt file in the main project folder with the content of:

   cmake_minimum_required(VERSION 3.0)
   project(TEST)
   set(SOURCE test.cpp)
   add_executable(${PROJECT_NAME} ${SOURCE})

   Note: Above does not specify full debug symbols.

2. Open Terminal and execute:

   mkdir Debug
   cd Debug

   to create a new Debug sub-directory. This will eventually also contain a debug version of the executable. Source

3. Execute command:

   cmake -DCMAKE_BUILD_TYPE=Debug ..

   This will generate the Makefile which can build debug executable from the test.cpp C++ source file using XCode's C++ compiler (AppleClang).

4. Execute make to build the debug executable - named TEST.

   Output may look something like:

   $ make
   Scanning dependencies of target TEST
   [ 50%] Building CXX object CMakeFiles/TEST.dir/test.cpp.o
   [100%] Linking CXX executable TEST
   [100%] Built target TEST

5. Run the executable with ./TEST. You should see output like:

   hello Michael. It works!
             

Debug the program (with LLDB)

You can also debug your executable from within VSCode.

1. Start VSCode's debug mode using View, Debug or Shift(⇧)+Command(⌘)+D. You'll see that left pane changes to DEBUG and states C++ Launch.

2. Activate the settings (wheel) icon to open the launch.json file and ensure that the sections referencing "program" is specifying the main executable file TEST.

   "program": "${workspaceRoot}/Debug/TEST",
           

3. Save the launch.json file.

4. Select your test.cpp file and set a breakpoint in a interesting code line, e.g. line 7 where std::cout << ... is. You set a breakpoint on a line by either by double-clicking at the beginning of the line (left of line number) or placing the cursor at the line and hit fn 9 (F9). You should notice that the line is added to the lower BREAKPOINTS section in the DEBUG pane, e.g. showing "test.cpp 7" telling that you've set a breakpoint at line 7 in test.cpp file. There is even a checkbox there where you can disable/enable the breakpoint.

5. Start debugging using fn 5(F5) key. Hopefully you will see that system hits your breakpoint. Also you should see a small panel where you can control how to go along with execution, e.g.:

   • Continue fn 5(F5)
   • Step Over fn 10(F10)
   • Step Into fn 11(F11)
   • Step Out Shift(⇧)+fn 11(F11)
   • Restart Shift(⇧)+Command(⌘)+fn 5(F5)
   • Stop Shift(⇧)+fn 5(F5)

   If your code contains variables, the current values at the breakpoint is shown in the Local VARIABLES part of the DEBUG pane.

Conclusions

What I've got:

• C++ syntax coloring, symbol recognition, intellisense, code completion and code navigation.
• Integrated clang-format code formatting.
• Integrated terminal (command shell).
• CMake integration and build via terminal commands using the generated Makefile.
• Integrated LLDB debugging, with breakpoint, variables, watches fully integrated with source code. However it doesn't show complex structures in a nice way, e.g. the content of a std::string. This is perhaps caused by the debugger rather than vscode itself. See also this github issue.
• Integrated (built-in) markdown and preview support. This text was written in VSCode with Markdown syntax. Info...

It do take some time to setup the environment. It is not plug and play. All in all I have a good feeling about VSCode and want to learn more.

Could need (I will add to this list as I found more nice/need-to-have).

• Automatic spell checking (should in my view be an OS feature, so that you get everywhere). See also User Voice topic on the matter.