Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/MicrosoftDocs/cpp-docs/llms.txt

Use this file to discover all available pages before exploring further.

Visual Studio brings the full power of its IDE — IntelliSense, the debugger, and the project system — to Linux C++ development. You write and debug code on Windows while compiling and running it on a remote Linux machine, a Linux VM, or the Windows Subsystem for Linux (WSL). Linux header files are automatically synchronized to your Windows machine so IntelliSense works without leaving the IDE.

​
Installing the Linux Development Workload

1

Open Visual Studio Installer

Type Visual Studio Installer in the Windows search box and open it. Click Modify next to your Visual Studio installation.
2

Select the workload

On the Workloads tab, scroll to Other toolsets and select Linux and embedded development with C++. This workload includes:
  • Visual C++ for Linux development
  • CMake support for Linux
  • Embedded and IoT tooling (optional components)
3

Install

Click Modify to begin the installation. No restart is required for the core workload.
CMake support for Linux is selected by default within the workload. If you plan to use MSBuild-based Linux projects instead of CMake, the workload installs those templates as well.

​
Setting Up Your Linux Machine

Visual Studio communicates with remote Linux machines over SSH and uses rsync/zip to synchronize header files. Install the required packages on your Linux target: 
sudo apt-get install openssh-server g++ gdb make ninja-build rsync zip
sudo service ssh start

​
Connecting to a Remote Linux Machine via SSH

1

Open Connection Manager

In Visual Studio, go to Tools → Options → Cross Platform → Connection Manager.
2

Add a new connection

Click Add. The Connect to Remote System dialog appears.Fill in:
  • Host name: IP address or hostname of the Linux machine (e.g., 192.168.1.100)
  • Port: 22 (default SSH port)
  • User name: Your Linux account username
  • Authentication type: Password or Private Key
  • Password / Private key file: Credentials for the account
3

Connect

Click Connect. Visual Studio establishes the SSH session and automatically downloads headers from the remote include directories to your local machine for IntelliSense.
Use Private Key authentication for CI/CD scenarios. Generate a key pair with ssh-keygen -t ed25519 and copy the public key to ~/.ssh/authorized_keys on the Linux machine.

​
Creating a Linux Project

​
Option A: MSBuild Linux Project

  1. File → New Project, search for Linux in the template filter.
  2. Select Console Application (Linux) and click Next.
  3. Enter a project name and location, then click Create.
  4. In Project Properties → General → Remote Build Machine, select your SSH connection.
Available project templates:
TemplateDescription
Console ApplicationStandard main() program targeting any Linux machine
Empty ProjectBlank project, no sample code
Makefile ProjectWraps an existing Makefile-based build
CMake ProjectCMake-driven build, recommended for cross-platform work
Open a folder containing a CMakeLists.txt. Visual Studio detects it automatically and offers Linux configurations. See the CMake Cross-Platform guide for a full CMakeLists.txt example.

​
A Simple Linux CMakeLists.txt

cmake_minimum_required(VERSION 3.16)
project(HelloLinux CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

add_executable(hello_linux
    src/main.cpp
    src/utils.cpp
)

# Include directories
target_include_directories(hello_linux PRIVATE include)

# Linux-specific compiler flags
if(CMAKE_SYSTEM_NAME STREQUAL "Linux")
    target_compile_options(hello_linux PRIVATE
        -Wall
        -Wextra
        -Wpedantic
        -g          # Debug symbols for GDB
    )
    target_link_libraries(hello_linux PRIVATE pthread)
endif()

# Install target
install(TARGETS hello_linux DESTINATION bin)

​
Building with GCC or Clang Remotely

Once your connection and project are configured, building works identically to a local project:
  • Press Ctrl+Shift+B or go to Build → Build Solution.
  • Visual Studio copies source files to the remote machine via rsync, runs the remote compiler (GCC or Clang), and retrieves error output back to the IDE Error List.
To change the compiler, open Project Properties → C/C++ General → C++ Compiler and specify the path (e.g., /usr/bin/clang++).
Visual Studio 2019 and later support both GCC and Clang for remote Linux builds. You can specify a specific version such as /usr/bin/g++-12 or /usr/bin/clang++-16 in the compiler path.

​
Debugging with GDB

Visual Studio uses GDB on the remote Linux machine as the debug backend, with the Visual Studio debugger UI as the front end. You get breakpoints, watch windows, call stacks, and variable inspection — all targeting the remote process.
1

Set breakpoints

Click in the left gutter of any source file to set a red-dot breakpoint, just as you would for a Windows project.
2

Start debugging

Press F5 (or Debug → Start Debugging). Visual Studio compiles on the remote machine, deploys the binary, and launches gdb remotely.
3

Choose GDB mode

In Project Properties → Debugging, the Debugging Mode option selects between:
  • gdb mode — Visual Studio drives GDB directly on the remote machine. Best compatibility.
  • gdbserver mode — a local GDB client connects to gdbserver on the remote. Faster for large binaries.
4

Inspect state

When the breakpoint is hit, use Locals, Watch, Call Stack, and Memory windows normally. The Linux Console window (Debug → Linux Console) shows stdout/stderr from the remote process and accepts stdin.

​
Separate Build and Debug Machines

You can cross-compile on an x64 Linux machine and deploy to an ARM device (e.g., a Raspberry Pi) for IoT scenarios:
  1. Set the Remote Build Machine in Configuration Properties → General.
  2. Set a separate Remote Debug Machine in Configuration Properties → Debugging.
  3. Visual Studio copies only the necessary binaries to the debug target.

​
IntelliSense for Linux Headers

When you add or modify a connection, Visual Studio automatically extracts the remote compiler’s system headers (/usr/include, /usr/lib/gcc/...) to a local cache using rsync and zip. These headers power IntelliSense features (completions, Go to Definition, error squiggles) without requiring a local Linux installation. To update the cache after installing new packages on the remote: Tools → Options → Cross Platform → Connection Manager → select your connection → Update.

WSL Setup

Install WSL with wsl --install and target it from Visual Studio with zero SSH configuration needed.

CMake Linux Projects

Use CMake with Linux-Debug presets to share a single CMakeLists.txt across Windows and Linux builds.

Remote ARM Debugging

Cross-compile for ARM on an x64 host and deploy to Raspberry Pi or similar embedded Linux boards.

GDB Documentation

Reference for GDB commands available in the Additional Debugger Commands project property.

Build docs developers (and LLMs) love

Get started for freeTalk to us