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.

CMake is a cross-platform, open-source build system generator that produces native build files (Makefiles, Ninja files, Visual Studio solution files) from a single CMakeLists.txt description. It has become the de-facto standard for C++ projects that need to build on multiple operating systems and compilers. Visual Studio 2019 and later provide first-class CMake support — you can open any folder containing a CMakeLists.txt and Visual Studio automatically configures IntelliSense, discovers build targets, and lets you build and debug without creating any Visual Studio-specific project files. This tutorial walks through creating a CMake project from scratch, understanding the configuration files, and building and debugging a target.

​
Prerequisites

  • Visual Studio 2019 or 2022 with the Desktop development with C++ workload installed. C++ CMake tools for Windows is included in that workload by default in Visual Studio 2022.
  • If you are on Visual Studio 2019, verify that C++ CMake tools for Windows is checked in the installer’s Individual components tab.

​
What Visual Studio Does When You Open a CMake Folder

When you open a folder containing a CMakeLists.txt, Visual Studio:
  1. Detects the root CMakeLists.txt and enables CMake integration.
  2. Invokes cmake.exe to generate the CMake cache (CMakeCache.txt) for the default configuration.
  3. Displays the CMake output in the Output window (select CMake from the Show output from dropdown).
  4. Indexes source files in the background to power IntelliSense, Go to Definition, Find All References, and refactoring.
  5. Populates the Startup Item toolbar dropdown with all executable targets defined in your CMakeLists.txt.

​
Creating a CMake Project

1

Create a new project using the CMake template

On the Visual Studio Start Window, click Create a new project. Filter by C++, Windows, and search for CMake Project. Select the template and click Next.Name the project HelloCMake, choose a location, and click Create. Visual Studio creates a folder with this structure:
HelloCMake/
├── CMakeLists.txt
├── HelloCMake.cpp
└── CMakePresets.json
2

Review the generated CMakeLists.txt

Open CMakeLists.txt. The generated file looks like this:
cmake_minimum_required (VERSION 3.8)

# Enable Hot Reload for MSVC compilers if supported.
if (POLICY CMP0141)
  cmake_policy(SET CMP0141 NEW)
  set(CMAKE_MSVC_DEBUG_INFORMATION_FORMAT "$<IF:$<AND:$<C_COMPILER_ID:MSVC>,$<CXX_COMPILER_ID:MSVC>>,$<$<CONFIG:Debug,RelWithDebInfo>:EditAndContinue>,$<$<CONFIG:Debug,RelWithDebInfo>:ProgramDatabase>>")
endif()

project ("HelloCMake")

# Add source to this project's executable.
add_executable (HelloCMake "HelloCMake.cpp")

if (CMAKE_VERSION VERSION_GREATER 3.12)
  set_property(TARGET HelloCMake PROPERTY CXX_STANDARD 20)
endif()
Key CMake commands used here:
  • cmake_minimum_required — sets the oldest CMake version this file is compatible with.
  • project("HelloCMake") — names the project and enables C and C++ language support.
  • add_executable(HelloCMake "HelloCMake.cpp") — declares an executable target named HelloCMake built from HelloCMake.cpp.
  • set_property(TARGET ... CXX_STANDARD 20) — requests C++20 for the target.
3

Review the generated source file

Open HelloCMake.cpp:
// HelloCMake.cpp : Defines the entry point for the application.
//

#include <iostream>

int main()
{
    std::cout << "Hello CMake." << std::endl;
    return 0;
}
4

Wait for CMake configuration to complete

Visual Studio runs the CMake configure step automatically when the project opens. Watch the Output window (set to CMake). When you see:
CMake generation done.
IntelliSense is active and the build targets are available.

​
Understanding CMakeLists.txt Structure

A real-world CMakeLists.txt is more involved. Here is an annotated example for a project with a library and an executable: 
cmake_minimum_required(VERSION 3.20)
project(MyApp VERSION 1.0 LANGUAGES CXX)

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

# --- Static library target ---
add_library(MathLib STATIC
    src/math/Calculator.cpp
    src/math/Calculator.h
)

# The library's public include directory
target_include_directories(MathLib PUBLIC
    ${CMAKE_CURRENT_SOURCE_DIR}/src
)

# --- Executable target ---
add_executable(MyApp
    src/main.cpp
)

# Link the executable against the library
target_link_libraries(MyApp PRIVATE MathLib)
add_library(name [STATIC|SHARED|MODULE] sources...) creates a library target. STATIC produces a .lib file; SHARED produces a .dll and .lib import library. add_executable(name sources...) creates an executable target.
Specifies include paths for a target. PUBLIC means the paths are visible to this target AND any targets that link against it. PRIVATE means only this target sees the paths. INTERFACE means only consumers see the paths.

​
Open Folder Workflow (Existing Projects)

If you already have a CMake project on disk (or cloned from GitHub), use the Open Folder workflow instead of creating a new project:
1

Open the folder

From the Visual Studio Start Window, click Open a local folder (or go to File > Open > Folder). Navigate to the folder that contains your root CMakeLists.txt and click Select Folder.Visual Studio opens the folder and begins CMake configuration automatically.
2

Switch to CMake Targets View

In Solution Explorer, click the Solutions and Folders toggle button (the dropdown at the top of Solution Explorer) and select CMake Targets View. This shows your project organized by CMake targets (executables, libraries) rather than as raw folders and files.
3

Select a startup target

In the toolbar’s Startup Item dropdown, select the executable target you want to run. Only add_executable targets appear here.

​
Build Configurations and CMake Presets

Visual Studio 2019 16.10+ and 2022 use CMakePresets.json as the recommended way to define build configurations. Earlier versions use CMakeSettings.json. The toolbar configuration dropdown (e.g., x64-Debug) reflects the presets defined in this file. A minimal CMakePresets.json: 
{
  "version": 3,
  "configurePresets": [
    {
      "name": "windows-debug",
      "displayName": "Windows Debug",
      "generator": "Visual Studio 17 2022",
      "binaryDir": "${sourceDir}/build/debug",
      "cacheVariables": {
        "CMAKE_BUILD_TYPE": "Debug"
      }
    },
    {
      "name": "windows-release",
      "displayName": "Windows Release",
      "generator": "Ninja",
      "binaryDir": "${sourceDir}/build/release",
      "cacheVariables": {
        "CMAKE_BUILD_TYPE": "Release"
      }
    }
  ],
  "buildPresets": [
    {
      "name": "windows-debug-build",
      "configurePreset": "windows-debug"
    }
  ]
}
CMakePresets.json is understood by CMake itself (version 3.19+), Visual Studio, VS Code with the CMake Tools extension, and CI systems. Committing it to source control means every developer and every pipeline uses the same configuration.

​
Building CMake Projects

There are three ways to build a CMake project in Visual Studio:
Select your target in the Startup Item dropdown, then click the green Run button or press F5 (debug) / Ctrl+F5 (run). Visual Studio builds all required dependencies first, then launches the executable.
Build output appears in the Output window. Errors are shown in the Error List and double-clicking an error navigates to the offending source line.

​
Editing CMakeLists.txt

Visual Studio 2019 16.5+ provides language services for CMake scripts:
  • Syntax highlighting for CMake commands, variables, and string literals.
  • Go to Definition (F12) for CMake variables and functions.
  • Find All References for targets and variables across all CMakeLists.txt files.
  • IntelliSense completions for CMake commands and CMake module names.
When you save a modified CMakeLists.txt, a yellow notification bar appears at the top of the editor offering to re-run CMake configuration. Click Configure (or let it auto-configure) to regenerate the cache.
Starting in Visual Studio 2019 16.5+, you can add and remove source files from your CMake project directly in Solution Explorer. Visual Studio automatically edits the CMakeLists.txt to keep it in sync — no manual editing required for file additions and removals.

​
Debugging CMake Targets

Debugging CMake projects works the same as debugging MSBuild projects:
  1. Select your executable target in the Startup Item dropdown.
  2. Set breakpoints in any source file.
  3. Press F5 to build and launch under the debugger.
To pass command-line arguments or set environment variables for a specific target, create a launch.vs.json file: 
{
  "version": "0.2.1",
  "configurations": [
    {
      "type": "default",
      "project": "CMakeLists.txt",
      "projectTarget": "HelloCMake",
      "name": "HelloCMake with args",
      "args": ["--verbose", "inputfile.txt"],
      "env": {
        "MY_VAR": "hello"
      }
    }
  ]
}
Access this file via Debug > Debug and Launch Settings for <target>.

​
Enable Edit and Continue for CMake Projects

To enable Edit and Continue in a CMake project built with MSVC, add the following to your CMakeLists.txt: 
if(MSVC)
  target_compile_options(HelloCMake PUBLIC "/ZI")
  target_link_options(HelloCMake PUBLIC "/INCREMENTAL")
endif()
This sets the debug information format to “Edit and Continue” (/ZI) and enables incremental linking, which is required for Edit and Continue to apply code changes while debugging.

​
Next Steps

Now that you understand CMake projects in Visual Studio, explore how to use the same CMakeLists.txt to target Linux from Windows in the Linux Development Tutorial, or use vcpkg to add third-party library dependencies to your CMake project.

Build docs developers (and LLMs) love

Get started for freeTalk to us