C++ VS Code GCC CMake Setup

This page sets up a simple C++ project with GCC, CMake, GDB, Ninja, and VS Code. It is designed as a first working reference for compiling, building, debugging, and running a small C++ project from both VS Code and the terminal.

Overview

• Install the compiler, build tools, debugger, CMake, and Ninja.
• Verify each tool from the terminal.
• Create a small C++ project folder.
• Add CMakeLists.txt at the project root.
• Add main.cpp under src.
• Build from VS Code with the CMake extension.
• Build from the terminal as a fallback workflow.

Install required packages

Install the standard Ubuntu C++ development tools. build-essential provides GCC, G++, make, and related compiler tools. cmake handles project configuration, gdb handles debugging, and ninja-build provides a fast build backend.

sudo apt update
sudo apt install -y build-essential cmake gdb ninja-build

Verify installation

Check that the compiler, CMake, debugger, and Ninja are available from the shell.

g++ --version
cmake --version
gdb --version
ninja --version

Create project structure

Create a clean project folder. Keep CMakeLists.txt at the project root and source files under src.

mkdir -p ~/Projects/cpp/hello_cpp/src
cd ~/Projects/cpp/hello_cpp

Target structure:

hello_cpp/
  CMakeLists.txt
  src/
    main.cpp

Create CMakeLists.txt

CMakeLists.txt defines the project, C++ standard, executable target, source file path, and compiler warning flags.

nano CMakeLists.txt

Paste the following:

cmake_minimum_required(VERSION 3.16)

project(hello_cpp VERSION 1.0 LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_CXX_EXTENSIONS OFF)

add_executable(hello_cpp src/main.cpp)

target_compile_options(hello_cpp PRIVATE -Wall -Wextra -Wpedantic)

• CMAKE_CXX_STANDARD sets the language version.
• CMAKE_CXX_STANDARD_REQUIRED prevents silent downgrade to an older standard.
• CMAKE_CXX_EXTENSIONS OFF keeps the build closer to standard C++ instead of compiler-specific extensions.
• target_compile_options adds useful warning flags for daily development.

Create main.cpp

Create the first source file under src. This confirms that the compiler, CMake target, and build path work end to end.

nano src/main.cpp

Paste the following:

#include <iostream>

int main() {
    std::cout << "Hello from C++ on Ubuntu" << std::endl;
    return 0;
}

VS Code extensions

For the VS Code workflow, install the Microsoft C++ extension and the CMake Tools extension. The C++ extension provides language support and debugging. CMake Tools provides configure, build, kit selection, and target actions.

Open project in VS Code

Open the project root in VS Code. The project root is the folder that contains CMakeLists.txt.

cd ~/Projects/cpp/hello_cpp
code .

VS Code CMake workflow

Use the Command Palette to configure and build the project through CMake Tools.

• Open ~/Projects/cpp/hello_cpp in VS Code.
• Open the Command Palette.
• Run CMake: Select a Kit.
• Choose a GCC kit.
• Run CMake: Configure.
• Run CMake: Build.
• Run the compiled binary from the integrated terminal.

./build/hello_cpp

Terminal workflow

Use the terminal workflow when VS Code configuration is not needed or when checking whether the project builds outside the editor.

cd ~/Projects/cpp/hello_cpp

cmake -S . -B build
cmake --build build
./build/hello_cpp

Terminal workflow with Ninja

Ninja can be selected explicitly as the CMake generator. This keeps builds fast and makes the selected build backend clear.

cd ~/Projects/cpp/hello_cpp

cmake -S . -B build -G Ninja
cmake --build build
./build/hello_cpp

Clean and rebuild

Delete the build folder when CMake cache, compiler settings, or generator selection needs to be reset.

cd ~/Projects/cpp/hello_cpp

rm -rf build
cmake -S . -B build -G Ninja
cmake --build build
./build/hello_cpp

Debug build

Use Debug build type when stepping through the program with GDB or VS Code debugger.

cd ~/Projects/cpp/hello_cpp

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug
cmake --build build

Run with GDB

After building in Debug mode, open the compiled binary with GDB.

gdb ./build/hello_cpp

Common GDB commands for a first check:

break main
run
next
continue
quit

Expected output

A successful build and run should print the hello message from main.cpp.

Hello from C++ on Ubuntu

Common mistakes

• Opening the src folder in VS Code instead of the project root that contains CMakeLists.txt.
• Forgetting to run CMake: Select a Kit before configure.
• Running ./build/hello_cpp before building the target.
• Changing CMakeLists.txt but not reconfiguring the project.
• Expecting CMake to find a source file that is not listed in add_executable.
• Mixing old CMake cache files with a different generator. Remove build and configure again.

Daily reference commands

# verify tools
g++ --version
cmake --version
gdb --version
ninja --version

# configure
cmake -S . -B build -G Ninja

# build
cmake --build build

# run
./build/hello_cpp

# clean rebuild
rm -rf build
cmake -S . -B build -G Ninja
cmake --build build

# debug build
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug
cmake --build build

# run debugger
gdb ./build/hello_cpp