Create a CMake Linux project in Visual Studio

We recommend you use CMake for projects that are cross-platform or will be made open-source. You can use CMake projects to build and debug the same source code on Windows, the Windows Subsystem for Linux (WSL), and remote systems.

Before you begin

First, make sure you have the Visual Studio Linux workload installed, including the CMake component. That's the Linux development with C++ workload in the Visual Studio installer. See Install the C++ Linux workload in Visual Studio if you aren't sure you have that installed.

Also, make sure the following are installed on the remote machine:

• gcc
• gdb
• rsync
• zip
• ninja-build (Visual Studio 2019 or above)

You can use Visual Studio 2019 to build and debug on a remote Linux system or WSL, and CMake will be invoked on that system. Cmake version 3.14 or later should be installed on the target machine.

Make sure that the target machine has a recent version of CMake. Often, the version offered by a distribution's default package manager isn't recent enough to support all the features required by Visual Studio. Visual Studio 2019 detects whether a recent version of CMake is installed on the Linux system. If none is found, Visual Studio shows an info-bar at the top of the editor pane. It offers to install CMake for you from https://github.com/Microsoft/CMake/releases.

With Visual Studio 2019, you can create a CMake project from scratch, or open an existing CMake project. To create a new CMake project, follow the instructions below. Or skip ahead to Open a CMake project folder if you already have a CMake project.

Create a new Linux CMake project

To create a new Linux CMake project in Visual Studio 2019:

1. Select File > New Project in Visual Studio, or press Ctrl + Shift + N.
2. Set the Language to C++ and search for "CMake". Then choose Next. Enter a Name and Location, and choose Create.

Alternatively, you can open your own CMake project in Visual Studio 2019. The following section explains how.

Visual Studio creates a minimal CMakeLists.txt file with only the name of the executable and the minimum CMake version required. You can manually edit this file however you like; Visual Studio will never overwrite your changes.

To help you make sense of, edit, and author your CMake scripts in Visual Studio 2019, refer to the following resources:

• In-editor documentation for CMake in Visual Studio
• Code navigation for CMake scripts
• Easily Add, Remove, and Rename Files and Targets in CMake Projects

Open a CMake project folder

When you open a folder that contains an existing CMake project, Visual Studio uses variables in the CMake cache to automatically configure IntelliSense and builds. Local configuration and debugging settings get stored in JSON files. You can optionally share these files with others who are using Visual Studio.

Visual Studio doesn't modify the CMakeLists.txt files. This allows others working on the same project to continue to use their existing tools. Visual Studio does regenerate the cache when you save edits to CMakeLists.txt, or in some cases, to CMakeSettings.json. If you're using an Existing Cache configuration, then Visual Studio doesn't modify the cache.

For general information about CMake support in Visual Studio, see CMake projects in Visual Studio. Read that before continuing here.

To get started, choose File > Open > Folder from the main menu or else type devenv.exe <foldername> in a developer command prompt window. The folder you open should have a CMakeLists.txt file in it, along with your source code.

The following example shows a simple CMakeLists.txt file and .cpp file:

// hello.cpp

#include <iostream>

int main(int argc, char* argv[])
{
    std::cout << "Hello from Linux CMake \n";
}

CMakeLists.txt:

cmake_minimum_required(VERSION 3.8)
project (hello-cmake)
add_executable(hello-cmake hello.cpp)

Next steps

Configure a Linux CMake project

See also

CMake Projects in Visual Studio