Using Visual Studio Code and Building and Debugging C++ on Mac OS X (2023)

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.

Create a folder e.g. test (use Finder or Terminal)
Start the VSCode application.
Create a new file using File, New or Command(⌘)+N.
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).

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.

Installing CMake

To install CMake:

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

Build with CMake

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.
Open Terminal and execute:
```
mkdir Debugcd Debug
```
to create a new Debug sub-directory. This will eventually also contain a debug version of the executable. Source
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).
Execute make to build the debug executable - named TEST.

Output may look something like:
See Also
Vad är CBD bra för? |15+ fördelar baserade på fakta 🥇43 Tips For Preparing To Move To Korea | 10 Magazine Korea Canada Visa from South Africa - How to Apply for Canada Visitor Visa Application And Requirements Guide - Visa Reservation 전국 전공의 실명 모두 밝힌 '젊은 의사들의 성명서' 주목
```
$ makeScanning dependencies of target TEST[ 50%] Building CXX object CMakeFiles/TEST.dir/test.cpp.o[100%] Linking CXX executable TEST[100%] Built target TEST
```
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.

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.
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", 
```
Save the launch.json file.
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.
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).