CMake Projects in Visual Studio: Open Folder Guide

CMake is a cross-platform, open-source build description system that generates native build files — Makefiles, Ninja build files, or Visual Studio project files — from a high-level CMakeLists.txt description. Visual Studio 2019 and later provide first-class CMake support: you open a folder containing a CMakeLists.txt, and Visual Studio reads CMake directly for IntelliSense, browsing, configuration, and debugging without ever generating a .vcxproj. This makes it straightforward to share the same CMake project between Windows developers using Visual Studio, Linux developers using the command line, and CI pipelines running on any platform.

Installation

CMake support is included in the Desktop development with C++ workload. When installing via the Visual Studio Installer, make sure C++ CMake tools for Windows is checked. For cross-platform (Linux/WSL) development, also install the Linux Development with C++ workload, which adds C++ CMake tools for Linux.

CMake version 3.14 or later is recommended. CMake 3.20 or later is required when invoking CMake with --preset from the command line.

Opening a CMake Project

When you choose File → Open → Folder and select a directory that contains a CMakeLists.txt, Visual Studio:

Adds a CMake menu to the main menu bar.
Displays the folder structure in Solution Explorer.
Runs the CMake configure step and generates CMakeCache.txt for the default configuration.
Indexes source files in the background for IntelliSense, Go To Definition, and Find All References.

Once configuration succeeds, switch Solution Explorer to CMake Targets View to browse your project organized by target rather than by directory.

Minimal CMakeLists.txt

A minimal project that builds a console executable from a single source file:

cmake_minimum_required(VERSION 3.20)
project(HelloWorld LANGUAGES CXX)

# Require C++17
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

add_executable(hello hello.cpp)

# Enable Edit and Continue on MSVC
if(MSVC)
  target_compile_options(hello PUBLIC "/ZI")
  target_link_options(hello PUBLIC "/INCREMENTAL")
endif()

install(TARGETS hello DESTINATION bin)

A more complete project with a library and an executable:

cmake_minimum_required(VERSION 3.20)
project(MyApp VERSION 1.0 LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# Static library
add_library(mylib STATIC
    src/mylib.cpp
    include/mylib.h
)
target_include_directories(mylib PUBLIC include)

# Executable that links against the library
add_executable(myapp src/main.cpp)
target_link_libraries(myapp PRIVATE mylib)

# Preprocessor definitions
target_compile_definitions(myapp PRIVATE APP_VERSION="${PROJECT_VERSION}")

# MSVC-specific options
if(MSVC)
  target_compile_options(myapp PRIVATE /W4 /WX)
endif()

Configuring CMake Projects

Visual Studio drives CMake configuration through a CMake configuration file. Two formats are supported:

CMakePresets.json (Recommended)
CMakeSettings.json (Legacy)

CMakePresets.json is the recommended format for Visual Studio 2019 16.10 and later. It is also understood by VS Code, the command line, and CI systems, making it the most portable choice.Enable it in Tools → Options → CMake → General → Always use CMakePresets.json.Basic CMakePresets.json structure:

{
  "version": 3,
  "configurePresets": [
    {
      "name": "windows-debug",
      "displayName": "Windows x64 Debug",
      "description": "Debug build using Ninja generator",
      "generator": "Ninja",
      "binaryDir": "${sourceDir}/out/build/${presetName}",
      "architecture": {
        "value": "x64",
        "strategy": "external"
      },
      "cacheVariables": {
        "CMAKE_BUILD_TYPE": "Debug",
        "CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}"
      },
      "vendor": {
        "microsoft.com/VisualStudioSettings/CMake/1.0": {
          "hostOS": ["Windows"],
          "intelliSenseMode": "windows-msvc-x64"
        }
      }
    },
    {
      "name": "windows-release",
      "displayName": "Windows x64 Release",
      "description": "Release build with optimizations",
      "generator": "Ninja",
      "binaryDir": "${sourceDir}/out/build/${presetName}",
      "architecture": {
        "value": "x64",
        "strategy": "external"
      },
      "cacheVariables": {
        "CMAKE_BUILD_TYPE": "Release",
        "CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}"
      },
      "vendor": {
        "microsoft.com/VisualStudioSettings/CMake/1.0": {
          "hostOS": ["Windows"]
        }
      }
    },
    {
      "name": "linux-debug",
      "displayName": "Linux Debug",
      "description": "Debug build on Linux or WSL",
      "generator": "Ninja",
      "binaryDir": "${sourceDir}/out/build/${presetName}",
      "cacheVariables": {
        "CMAKE_BUILD_TYPE": "Debug",
        "CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}"
      },
      "vendor": {
        "microsoft.com/VisualStudioSettings/CMake/1.0": {
          "hostOS": ["Linux"]
        },
        "microsoft.com/VisualStudioRemoteSettings/CMake/1.0": {
          "sourceDir": "$env{HOME}/.vs/$ms{projectDirName}"
        }
      }
    }
  ],
  "buildPresets": [
    {
      "name": "windows-debug-build",
      "configurePreset": "windows-debug"
    },
    {
      "name": "windows-release-build",
      "configurePreset": "windows-release"
    }
  ],
  "testPresets": [
    {
      "name": "windows-debug-test",
      "configurePreset": "windows-debug",
      "output": { "outputOnFailure": true }
    }
  ]
}

The Visual Studio Settings vendor map (microsoft.com/VisualStudioSettings/CMake/1.0) controls IDE-specific behaviour like hostOS (which presets appear in the dropdown) and intelliSenseMode. These settings do not affect the CMake command line.

CMakeSettings.json is the older per-project configuration format used in Visual Studio 2017 and 2019 before 16.10. It is still supported but CMakePresets.json is preferred for new projects.

{
  "configurations": [
    {
      "name": "x64-Debug",
      "generator": "Ninja",
      "configurationType": "Debug",
      "buildRoot": "${projectDir}\\out\\build\\${name}",
      "installRoot": "${projectDir}\\out\\install\\${name}",
      "cmakeCommandArgs": "",
      "buildCommandArgs": "",
      "ctestCommandArgs": "",
      "intelliSenseMode": "windows-msvc-x64"
    }
  ]
}

Triggering Configuration

Visual Studio automatically re-runs the configure step when you edit CMakeLists.txt or the configuration file. To trigger it manually:

Project → Configure Cache from the main menu, or
Run cmake --preset <configurePreset> from the Developer Command Prompt.

To see verbose CMake output, enable Tools → Options → CMake → Enable verbose CMake diagnostic output.

Building CMake Projects

Select a Configure Preset

Use the Configure Preset dropdown in the toolbar to choose a preset (e.g., windows-debug). Visual Studio automatically invokes the configure step if the cache is out of date.

Select a Build Preset

The Build Preset dropdown controls build-specific options. If no build presets are defined, Visual Studio uses the default (equivalent to cmake --build with no extra arguments).

Build

Press F5 to build and run, or use Build → Build All. You can also right-click a target in CMake Targets View and choose Build. Build output appears in the Output Window and errors in the Error List.

From the command line with presets:

# Configure
cmake --preset windows-debug

# Build
cmake --build --preset windows-debug-build

# Run tests
ctest --preset windows-debug-test

Debugging CMake Projects

All executable CMake targets appear in the Startup Item dropdown in the toolbar. Select a target and press F5 or Debug → Start Debugging. Customize a debugging session by creating a launch.vs.json file:

{
  "version": "0.2.1",
  "defaults": {},
  "configurations": [
    {
      "type": "default",
      "project": "CMakeLists.txt",
      "projectTarget": "myapp",
      "name": "myapp with args",
      "args": ["--verbose", "--input", "data.txt"]
    }
  ]
}

Access Debug → Debug and Launch Settings for <target> to open and edit this file from the IDE.

Edit and Continue

Add the following to your CMakeLists.txt to enable Edit and Continue when building with MSVC on Windows:

if(MSVC)
  target_compile_options(<target> PUBLIC "/ZI")
  target_link_options(<target> PUBLIC "/INCREMENTAL")
endif()

vcpkg Integration

CMake projects opened in Visual Studio integrate with vcpkg after you run vcpkg integrate install. When CMakeSettings.json is the active configuration file, Visual Studio automatically passes the vcpkg toolchain file to CMake. For CMakePresets.json, set the toolchain file explicitly using the VCPKG_ROOT environment variable:

{
  "configurePresets": [
    {
      "name": "windows-debug",
      "toolchainFile": "$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake",
      "cacheVariables": {
        "CMAKE_BUILD_TYPE": "Debug"
      }
    }
  ]
}

Use the VCPKG_ROOT environment variable instead of a hard-coded path so that CMakePresets.json can be shared across machines with different vcpkg installation directories.

IntelliSense and Language Services

Visual Studio uses the compiler and target architecture defined in the active Configure Preset to power IntelliSense. With CMakePresets.json, you can override this using intelliSenseMode in the Visual Studio Settings vendor map:

"vendor": {
  "microsoft.com/VisualStudioSettings/CMake/1.0": {
    "intelliSenseMode": "windows-msvc-x64"
  }
}

CMake language services (available in Visual Studio 2019 16.5+) support Go To Definition, Peek Definition, and Find All References for CMake variables, functions, and targets.

Troubleshooting

CMake cache errors

Open the Project menu (or right-click CMakeLists.txt in Solution Explorer) and choose:

View CMakeCache.txt — inspect the current cache values.
Delete Cache and Reconfigure — wipe the build directory and start fresh.
Configure Cache — force a re-run of the configure step.

IntelliSense not updating

Save CMakeLists.txt to trigger a re-configure. If the issue persists, select Project → Configure Cache to manually regenerate the CMake cache.

CMake partial activation (Visual Studio 2022 17.1+)

If your root folder does not contain a CMakeLists.txt, Visual Studio prompts whether to enable CMake integration. Accept and edit CMakeWorkspaceSettings.json (in the .vs directory) to specify which sub-folders contain CMake roots:

{
  "enableCMake": true,
  "sourceDirectory": ["${workspaceRoot}/engine", "${workspaceRoot}/tools"]
}

Running CMake from CI

With CMakePresets.json, your local workflow maps directly to CI:

# Set up the MSVC environment (from Developer Command Prompt or vcvarsall.bat)
call "C:\Program Files\Microsoft Visual Studio\2022\Enterprise\VC\Auxiliary\Build\vcvarsall.bat" x64

# Configure and build
cmake --preset windows-release
cmake --build --preset windows-release-build

# Test
ctest --preset windows-debug-test

CMake 3.20 or later is required when using --preset from the command line. Inside Visual Studio, any version from 3.14 is supported because the IDE evaluates presets directly.

Build Systems

Compiler & Linker

Code Quality

Cross-Platform Development

CMake Projects in Visual Studio: Open Folder Guide

Installation

Opening a CMake Project

Minimal CMakeLists.txt

Configuring CMake Projects

Triggering Configuration

Building CMake Projects

Debugging CMake Projects

Edit and Continue

vcpkg Integration

IntelliSense and Language Services

Troubleshooting

Running CMake from CI

Build docs developers (and LLMs) love

Build Systems

Compiler & Linker

Code Quality

Cross-Platform Development

Documentation Index

​Installation

​Opening a CMake Project

​Minimal CMakeLists.txt

​Configuring CMake Projects

​Triggering Configuration

​Building CMake Projects

​Debugging CMake Projects

​Edit and Continue

​vcpkg Integration

​IntelliSense and Language Services

​Troubleshooting

​Running CMake from CI

Build docs developers (and LLMs) love

Installation

Opening a CMake Project

Minimal CMakeLists.txt

Configuring CMake Projects

Triggering Configuration

Building CMake Projects

Debugging CMake Projects

Edit and Continue

vcpkg Integration

IntelliSense and Language Services

Troubleshooting

Running CMake from CI