Setting Up a C/C++ Development Environment in VS Code on Windows 10

As one of the most popular lightweight code editors among programmers, VS Code offers unmatched flexibility and advantages in daily use. But precisely because it is lightweight and flexible, many aspects of the development environment must be configured manually, unlike its bloated sibling Visual Studio (noting that VS Code and Visual Studio are similar only in name and because both are Microsoft products), which makes many operations “foolproof.” For beginners, such foolproof tools are certainly convenient, but by skipping the configuration process, many people can write code that runs under Visual Studio without ever understanding how a program is compiled, linked, and executed.

The official VS Code documentation provides detailed instructions on configuring environments for a variety of languages. On Windows, when doing C/C++ development, the official docs describe three approaches: using Microsoft’s C compiler, using GCC on Windows, and using GCC within the Windows 10 WSL (Windows Subsystem for Linux). This article demonstrates and explains only the latter two approaches.

1. Preparation

• After installing Visual Studio Code, you must first install the C/C++ extension before doing C/C++ development.

• Create an empty folder and then create a demo project inside it. From the command line, you can do this in order as follows:

mkdir projects
cd projects
mkdir helloworld
cd helloworld
code .

The last command, code ., opens the current folder in VS Code from the command line, which is very convenient in practice.

Add a helloworld.cpp file in the folder (you can create it via VS Code) and put the following content in it (code from the official VS Code site):

#include <iostream>
#include <vector>
#include <string>

using namespace std;

int main()
{
    vector<string> msg { "Hello", "C++", "World", "from", "VS Code", "and the C++ extension!" };

    for (const string& word : msg)
    {
        cout << word << " ";
    }
    cout << endl;
}

2. Configuring C++ with GCC on Windows

2.1 Installing MSYS2, GCC, GDB

Download the MSYS2 .exe installer from the official MSYS2 website and install it. It is generally recommended to install it directly under C:/msys2. After installation, locate and edit the following files in that directory to use Tsinghua University’s open-source mirror in place of the default overseas repositories:

Edit /etc/pacman.d/mirrorlist.mingw32 and add the following at the top of the file:

Server = https://mirrors.tuna.tsinghua.edu.cn/msys2/mingw/i686

Edit /etc/pacman.d/mirrorlist.mingw64 and add the following at the top:

Server = https://mirrors.tuna.tsinghua.edu.cn/msys2/mingw/x86_64

Edit /etc/pacman.d/mirrorlist.msys and add the following at the top:

Server = https://mirrors.tuna.tsinghua.edu.cn/msys2/msys/$arch

Then open the msys2.exe shell and run pacman -Sy in the terminal to refresh the package database.

pacman is the package manager used in Arch Linux, similar to yum on CentOS or apt on Ubuntu. To search for and install Linux-compatible packages under MSYS2, you use pacman.

2.2 Installing Packages with pacman

Common pacman commands include:

pacman -Sy      # Update package databases
pacman -R pkg   # Remove package
pacman -S pkg   # Install package
pacman -Syu     # Upgrade everything
pacman -Ss xx   # Search for package info about "xx"

Install gcc and gdb. You can choose either the 32-bit or 64-bit builds depending on your needs.

To install 32-bit packages:

pacman -S mingw32/mingw-w64-i686-gcc
pacman -S mingw32/mingw-w64-i686-gdb

To install 64-bit packages, change to something like mingw64/mingw-w64-x86_64-gcc, etc. You can also replace gcc with toolchain to install the entire toolchain.

2.3 Setting Environment Variables

After installation, add the corresponding c:/msys2/mingw32/bin or c:/msys2/mingw64/bin directory to the Windows system Path.

Steps:

1. Press Win+R, type control to open Control Panel → System → Advanced system settings.
2. In the pop-up window select Advanced → Environment Variables.
3. In the System variables section, find Path and double-click it.
4. Click New and add the path mentioned above (the actual MSYS2 and package install locations).

Open a command prompt and run the commands below. If you see version information, installation and path configuration are successful.

C:\Users\weizy>g++ --version
g++ (Rev1, Built by MSYS2 project) 9.3.0
Copyright (C) 2019 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

C:\Users\weizy>gdb --version
GNU gdb (GDB) 9.1
Copyright (C) 2020 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

2.4 Configuring tasks.json

Go back to the directory containing helloworld.cpp and open the folder with VS Code. Choose Terminal → Configure Default Build Task, then select C/C++: g++.exe build active file. VS Code will create a new tasks.json. Edit it based on the official sample as follows:

{
  "version": "2.0.0",
  "tasks": [
    {
      "type": "shell",
      "label": "g++.exe build active file",
      "command": "C:\\msys2\\mingw32\\bin\\g++.exe",
      "args": [
        "-g",
        "${file}",
        "-o",
        "${fileDirname}\\${fileBasenameNoExtension}.exe"
      ],
      "options": {
        "cwd": "C:\\msys2\\mingw32\\bin"
      },
      "problemMatcher": [
        "$gcc"
      ],
      "group": {
        "kind": "build",
        "isDefault": true
      }
    }
  ]
}

This configuration file uses VS Code’s built-in variables to make it more flexible. ${fileBasenameNoExtension} is the file name without its extension; adding the .exe suffix produces the executable (in this example, helloworld.exe). ${fileDirname} is the directory containing the file.

The official documentation lists all built-in variables for reference. Ensure that the command and cwd paths match your actual installation directories and that paths use double backslashes. Given its generality, you can reuse this tasks.json for future projects.

2.5 Building the Program

Close tasks.json and switch back to helloworld.cpp (otherwise VS Code may think tasks.json is the file to compile). Choose Terminal → Run Build Task, or use the shortcut Ctrl+Shift+B (in my case this conflicts with my IME emoji shortcut, so I changed it).

If everything is correct, the build will finish quickly and helloworld.exe will be generated in the same directory. Run it in the integrated terminal with:

.\helloworld.exe

You should see the program’s output.

3. Configuring C++ Development with GCC in the Windows WSL Subsystem

3.1 Installing the Ubuntu Linux Subsystem

Refer to Microsoft’s official WSL installation documentation and install a distribution either from the Microsoft Store or via the command line. Windows Server also supports downloading, manually unpacking, and installing distros. Here, we’ll search for and install Ubuntu 18.04 from the Microsoft Store.

Two common installation errors and solutions:

• Installation fails with error 0x80070003
  Windows Subsystem for Linux can only run on the system drive (usually the C: drive). Make sure the distribution is stored on the system drive: open Settings → Storage → More storage settings: Change where new content is saved.

• WslRegisterDistribution fails with error 0x8007019e
  The “Windows Subsystem for Linux” optional component is not enabled: open Control Panel → Programs and Features → Turn Windows features on or off → check “Windows Subsystem for Linux”, or open Windows PowerShell and run:

  Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux
  

After installation, you can launch the Ubuntu environment from the Start menu by searching for “Ubuntu”. You can also type bash in a command prompt to enter the Ubuntu bash environment. The first time you enter the WSL subsystem you’ll be prompted to set a Linux username and password.

To improve access speed, we again switch to Tsinghua University’s mirror for Ubuntu. Edit /etc/apt/sources.list inside the Ubuntu subsystem (back this file up first), replace its contents with the following, save, then run sudo apt-get update to update packages via the Tsinghua mirror:

# The source mirrors are commented out by default to speed up `apt update`.
# Uncomment them yourself if needed.

deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ bionic main restricted universe multiverse
# deb-src https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ bionic main restricted universe multiverse

deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ bionic-updates main restricted universe multiverse
# deb-src https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ bionic-updates main restricted universe multiverse

deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ bionic-backports main restricted universe multiverse
# deb-src https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ bionic-backports main restricted universe multiverse

deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ bionic-security main restricted universe multiverse
# deb-src https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ bionic-security main restricted universe multiverse

# Pre-release repositories, not recommended to enable
# deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ bionic-proposed main restricted universe multiverse
# deb-src https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ bionic-proposed main restricted universe multiverse

3.2 Installing the Build Environment

In the WSL subsystem, run the following command to install the build environment:

sudo apt-get install build-essential gdb

After installation, run these commands to verify:

whereis g++
whereis gdb

3.3 Opening WSL in VS Code and Configuring C++ Builds

After installing the Remote - WSL extension for VS Code, you can open the WSL subsystem from VS Code in several ways (for example, via the green “><” remote button in the lower-left corner and choosing “Remote-WSL: New Window”).

Once connected to WSL from VS Code, you must also install the C/C++ extension in the WSL environment to enable debugging and other features. Search for “C/C++” in the Extensions view and install it (inside the WSL environment).

As before, create a helloworld folder in WSL and add a helloworld.cpp file. Configure tasks.json based on the official documentation:

{
  "version": "2.0.0",
  "tasks": [
    {
      "type": "shell",
      "label": "g++ build active file",
      "command": "/usr/bin/g++",
      "args": [
        "-g",
        "${file}",
        "-o",
        "${fileDirname}/${fileBasenameNoExtension}"
      ],
      "options": {
        "cwd": "/usr/bin"
      },
      "problemMatcher": [
        "$gcc"
      ],
      "group": {
        "kind": "build",
        "isDefault": true
      }
    }
  ]
}

Notes:

• In Linux, executability is not determined by file extension, so .exe is unnecessary. As long as the file has the execute (x) permission, it can be run. After building, an executable named helloworld will be generated; run it in the terminal to see the output.

• In WSL, the original Windows drive letters are mapped under /mnt, for example the C drive is /mnt/c and the D drive is /mnt/d. To make files more easily shared between the two systems, I created a wsl directory on the D drive and then created a symbolic link to it in the WSL home directory. This way, files in that folder are easily accessible from both systems. The Linux commands are:

  mkdir /mnt/d/wsl
  ln -s /mnt/d/wsl ~/wsl
  

4. Debugging Programs

4.1 Configuration

In general, programs rarely compile successfully on the first try. Before a successful build, you may need extensive debugging. As with building, debugging must also be configured in VS Code.

Choose Run → Add Configuration…, then select C++ (GDB/LLDB) (if it does not appear, click More at the bottom and install the appropriate extensions). From the dropdown, select the compiler that matches your environment: choose g++.exe when using GCC on Windows, and g++ build and debug active file when using the WSL subsystem. Screenshots differ but the idea is the same.

This will generate a launch.json file. For GCC on Windows, launch.json looks like this (paths adjusted to match the example):

{
  // Use IntelliSense to learn about possible attributes.
  // Hover to view descriptions of existing attributes.
  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
  "version": "0.2.0",
  "configurations": [
    {
      "name": "g++.exe build and debug active file",
      "type": "cppdbg",
      "request": "launch",
      "program": "${fileDirname}\\${fileBasenameNoExtension}.exe",
      "args": [],
      "stopAtEntry": false,
      "cwd": "${workspaceFolder}",
      "environment": [],
      "externalConsole": false,
      "MIMode": "gdb",
      "miDebuggerPath": "C:\\msys2\\mingw32\\bin\\gdb.exe",
      "setupCommands": [
        {
          "description": "Enable pretty-printing for gdb",
          "text": "-enable-pretty-printing",
          "ignoreFailures": true
        }
      ],
      "preLaunchTask": "g++.exe build active file"
    }
  ]
}

In the WSL subsystem, the launch.json configuration looks like this:

{
  // Use IntelliSense to learn about possible attributes.
  // Hover to view descriptions of existing attributes.
  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
  "version": "0.2.0",
  "configurations": [
    {
      "name": "g++ build and debug active file",
      "type": "cppdbg",
      "request": "launch",
      "program": "${fileDirname}/${fileBasenameNoExtension}",
      "args": [],
      "stopAtEntry": false,
      "cwd": "${workspaceFolder}",
      "environment": [],
      "externalConsole": false,
      "MIMode": "gdb",
      "miDebuggerPath": "/usr/bin/gdb",
      "setupCommands": [
        {
          "description": "Enable pretty-printing for gdb",
          "text": "-enable-pretty-printing",
          "ignoreFailures": true
        }
      ],
      "preLaunchTask": "g++ build active file"
    }
  ]
}

With both tasks.json and launch.json properly configured, you can set breakpoints in helloworld.cpp, press F5 or use Run → Start Debugging, and step through the program in either the native Windows GCC environment or within WSL.