Configure CMake debugging sessions

All executable CMake targets are shown in the Startup Item dropdown in the General toolbar. To start a debugging session, just select one and launch the debugger.

CMake startup item dropdown

You can also start a debug session from Solution Explorer. First, switch to CMake Targets View in the Solution Explorer window.

CMake targets view button

Then, right-click on any executable and select Debug or Debug and Launch Settings. Debug automatically starts debugging the selected target, based on your active configuration. Debug and Launch Settings opens the launch.vs.json file and adds a new debug configuration for the selected target.

Customize debugger settings

To customize the debugger settings for any executable CMake target in your project, right-click on the specific CMakeLists.txt file and select Debug and Launch Settings. (Or select a target in Targets View in Solution Explorer.) When you select a CMake target in the submenu, a file called launch.vs.json is created. This file is pre-populated with information about the CMake target you have selected and allows you to specify additional parameters such as program arguments or debugger type. To reference any key in a CMakeSettings.json file, preface it with cmake. in launch.vs.json. The following example shows a simple launch.vs.json file that pulls in the value of the remoteCopySources key in the CMakeSettings.json file for the currently selected configuration:

  "version": "0.2.1",
  "defaults": {},
  "configurations": [
      "type": "default",
      "project": "CMakeLists.txt",
      "projectTarget": "CMakeHelloWorld.exe (Debug\\CMakeHelloWorld.exe)",
      "name": "CMakeHelloWorld.exe (Debug\\CMakeHelloWorld.exe)",
      "args": ["${cmake.remoteCopySources}"]

As soon as you save the launch.vs.json file, an entry is created in the Startup Item dropdown with the new name. By editing the launch.vs.json file, you can create as many debug configurations as you like for any number of CMake targets.

Support for CMakeSettings variables

Launch.vs.json supports variables that are declared in CMakeSettings.json (see below) and that are applicable to the currently-selected configuration. It also has a key named currentDir, which sets the current directory of the launching app for a local project:

  "type": "default",
  "project": "CMakeLists.txt",
  "projectTarget": "CMakeHelloWorld1.exe (C:\\Users\\satyan\\CMakeBuilds\\Test\\Debug\\CMakeHelloWorld1.exe)",
  "name": "CMakeHelloWorld1.exe (C:\\Users\\satyan\\CMakeBuilds\\Test\\Debug\\CMakeHelloWorld1.exe)",
  "currentDir": "${env.USERPROFILE}\\CMakeBuilds\\${workspaceHash}"

When you run the app, the value of currentDir is something similar to


The key 'cwd' sets the current directory of the launching app for a remote project. The default value is '${debugInfo.defaultWorkingDirectory}' which evaluates to


See also

CMake Projects in Visual Studio
Configure a Linux CMake project
Connect to your remote Linux computer
Customize CMake build settings
Configure CMake debugging sessions
Deploy, run, and debug your Linux project
CMake predefined configuration reference