[Updated: January 14, 2019]
As a software engineer, a great editor or IDE helps improve productivity. I have used many IDEs and editors to write the code for many years. About a couple of years ago, Microsoft introduced a brand new cross-platform code editor called Visual Studio Code (VS Code) which is a lightweight and cross-platform version of Visual Studio. It supports several programming languages and many features to help programmers. In 2018, it has become the most popular editor. VS Code also becomes my favorite editor for Windows and Linux.
Microsoft has posted a lot of fantastic documents of Visual Studio Code. However, most of these documents are written for the general purpose of Visual Studio Code. It took me a while to figure out how to configure VS Code to work with C++ in Linux. Therefore, the purpose of this article is to help C++ programmer, like me, who want to use VS Code for C++ programming in Linux. By providing step by step guideline, hopefully, this article can help C++ programmers spend as little effort as possible to start using VS Code in Linux environment. The Quick Start includes two parts:
- Use VS Code to build C++ code with CMake and Make
- Use VS Code to do run time debugging.
The Quick Start is based on the following environment:
- Ubuntu 18.04
- Visual Studio Code 1.30.2
- Visual Studio Code Extensions:
- C/C++ for Visual Studio Code 0.20.1
- CMake 0.0.17
- CMake Tools 1.1.3
Installation of Visual Studio Code
First of all, download Visual Studio Code from https://code.visualstudio.com/Download. Several options are available: .deb for Debian and Ubuntu, and .rpm for Red Hat, Fedora, and SUSE. Here, we download the .deb package (code_1.30.2-1546901646_amd64.deb).
Then, we use dpkg command to install it.
sudo dpkg -i code_1.30.2-1546901646_amd64.deb(This command installs VS Code into /usr/bin/code.)
Install C/C++ and CMake Extensions
Once VS Code is installed, we can install C/C++ and CMake Extensions. To install the extensions, click the Extensions icon on the left side of VS Code and type C++ for C/C++ extension and install it.
Repeat the steps for CMake and CMake Tools extensions. After the installations, VS Code should look like the picture below.
A Simple C++ Example
The sample code includes a QuickStart library which provides a very simple function, add, and a unit test which leverages the power of Boost Unit Test Framework. We need to install CMake and Boost Library onto the Linux system if they are not already installed. Use the following commands to install CMake and Boost Library.
sudo apt install cmake
sudo apt install libboost-all-dev(Source code can be found here)
Sample Code
The sample code has the following hierarchy.
include/QuickStart.hpp
class QuickStart {
public:
int add(int, int);
};src/QuickStart.cpp
#include "QuickStart.hpp"
int QuickStart::add(int a, int b) {
return (a + b);
}test/QuickStartTest.cpp
#define BOOST_TEST_MODULE QuickStartTest
#include "QuickStart.hpp"
#define BOOST_TEST_DYN_LINK
#include <boost/test/unit_test.hpp>
BOOST_AUTO_TEST_SUITE(QuickStartSuite)
BOOST_AUTO_TEST_CASE(AdditionTest)
{
QuickStart quickStart;
BOOST_CHECK_EQUAL(quickStart.add(1, 1), 2);
}
BOOST_AUTO_TEST_SUITE_END()Build with CMake
CMake is a very popular tool for building, testing, and packaging C++ code. It supports directory hierarchy and uses a compiler-independent approach. CMake is also much easier to use than Make. There are few CMake extensions available for Visual Studio Code. For this example, we use CMake and CMake Tools.
- CMake provides the language service support for CMake.
- CMake Tools gives the ability to build CMake targets.
To have the best CMake experience, install both extensions is recommended.
Assume there are CMakeLists.txt files in QuickStart Project, and the hierarchy is as follows.
Top level CMakeLists.txt
cmake_minimum_required (VERSION 3.5)
project(QuickStart)
set(QUICK_START_VERSION_MAJOR 1)
set(QUICK_START_VERSION_MINOR 0)
set(SOURCES ${PROJECT_SOURCE_DIR}/src/QuickStart.cpp)
include_directories("${PROJECT_SOURCE_DIR}/include")
add_library(QuickStart STATIC ${SOURCES})
enable_testing()
add_subdirectory(test)test/CMakeLists.txt
find_package(Boost REQUIRED COMPONENTS unit_test_framework)
include_directories("${PROJECT_SOURCE_DIR}/include")
set(TEST_SOURCES ${PROJECT_SOURCE_DIR}/test/QuickStartTest.cpp)
set(TEST_LIBS QuickStart)
add_executable(test_main ${TEST_SOURCES})
target_link_libraries(test_main ${TEST_LIBS} ${Boost_LIBRARIES})
add_test(QuickStartTest test_main COMMAND test_main)First of all, type Ctrl+Shift+P to enable ‘’Command Palette’’ and type cmake, Command Palette will display a list of available commands that we can execute from here. In this case, it shows all commands related to cmake.
Choose CMake
Click ‘’Scan for kits’’. The CMake Tool, then, scans the system to find available kits. For example, my system has the following options.
After we choose one tool kit (e.g., GCC 7.3.0), CMake Tools automatically setup the configurations for us.
Now, VS Code is ready to use. Type Ctrl+Shift+P to enter Command Palette and type cmake, and choose CMake:Build.
VS Code starts building the code.
We can also choose CMake: Clean to clean the code.
VS Code cleans the build folder and built files.
To run the test cases, use CMake: Run.
In addition to using Command Palette, CMake Tools provides a quick and convenient way to trigger most common actions via Side Bar.
It shows all the available build targets such as:
Other Configurations
All available CMake configurations can be found at settings. To enable settings, from the menu bar do [File->Preference->Settings]. VS Code has the ability for users to modify nearly every part of Visual Studio Code. In the search bar, type
Modification of these options is straightforward. One option worth mentioning is ‘’cmake.preferredGenertors.’’
Ninja Build
Ninja is a small build system with a focus on speed. CMake Tools provides several code generators. Ninja is the default option. When a project gets bigger, the longer time to build the project. Ninja build system performs faster on build than GNU Make. Using Ninja to build the code is highly recommended, i.e., the default option of ‘’
Debug
One important reason to use IDE is its debugging support. VS Code has great debugging support.
To start debugging, click the debug icon in the Activity Bar.
For the very first time, we need to add a configuration.
Then, choose the debugger, C++ (GDB/LLDB), for Linux environment.
Visual Studio Code generates a configuration file, launch.json, for debugging. This configuration file provides variety options to modify. The most important option is to tell VS Code which binary to debug. In this example, we debug the unit test binary, test_main, which is located at ${workspaceRoot}/build/test/.
Now, Visual Studio Code is ready to debug.
Build with Make
Although CMake is easier to use than GNU Make, GNU Make is used by many people. This section demonstrates how to configure VS Code to build the code with GNU Make.
Assume there is a Makefile in QuickStart Project, and the hierarchy is as the
Makefile
BUILDDIR = build
INCDIRS = include
SRCDIR = src
TESTDIR = test
OBJS = $(addprefix $(BUILDDIR)/, $(patsubst %.cpp, %.o, $(notdir $(wildcard $(SRCDIR)/*.cpp))))
TESTOBJS = $(addprefix $(BUILDDIR)/, $(patsubst %.cpp, %.o, $(notdir $(wildcard $(TESTDIR)/*.cpp))))
LIBQUICKSTART_FNAME = $(BUILDDIR)/libQuickStart.a
TEST_FNAME = $(BUILDDIR)/test_main
CXXFLAGS += $(INCDIRS:%=-I%) -std=c++1y
LDFLAGS += $(LIBQUICKSTART_FNAME) -lboost_unit_test_framework
.PHONY: all clean
all: $(LIBQUICKSTART_FNAME) $(TEST_FNAME)
$(LIBQUICKSTART_FNAME): $(OBJS)
$(AR) $(ARFLAGS) $@ $^
$(TEST_FNAME): $(TESTOBJS) $(LIBQUICKSTART_FNAME)
$(CXX) -o $(TEST_FNAME) $^ $(LDFLAGS)
$(BUILDDIR)/%.o:$(SRCDIR)/%.cpp | $(BUILDDIR)
$(COMPILE.cc) $< $(OUTPUT_OPTION)
$(COMPILE.cc) -MM -MP -MT $@ $< -o $(BUILDDIR)/$*.d
$(BUILDDIR):
@mkdir $(BUILDDIR)
$(BUILDDIR)/%.o:$(TESTDIR)/%.cpp | $(BUILDDIR)
$(COMPILE.cc) $< $(OUTPUT_OPTION)
$(COMPILE.cc) -MM -MP -MT $@ $< -o $(BUILDDIR)/$*.d
run_test:
$(TEST_FNAME)
clean:
$(RM) $(BUILDDIR)/*.d $(BUILDDIR)/*.o $(LIBQUICKSTART_FNAME) $(TEST_FNAME)VS Code provides a feature, Tasks, to integrate with external tools, including Make.
First, type Ctrl+Shift+P to enable Command Palette and type tasks, Command Palette displays a list of available commands that we can execute from here. In this case, it shows all commands related to Tasks.
In the very first time, choose Tasks: Configure Task. And, then, click Create tasks.json file from template.
A new list bumps up; the list has all available configurations.
To use Make, choose Others, and then VS Code generates a configuration file, tasks.json. This file is where users can set up Tasks with external tools.
Change “command”: “echo Hello” to ‘’command’’: “make,” and change ‘’label’’: ‘’echo’’ to ‘’label’’: ‘’all’’. In the Makefile of Quick Start example, there are three build targets: all, run_test, and clean. Add the other two as below.
Now, VS Code is ready to run these tasks that we just defined. Type Ctrl+Shift+P to enable Command Palette and type tasks, it shows all the available Tasks options. Choose Tasks: Run Task.
Now, it shows all three tasks that we just added: all, clean, and run tests.
