You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
title: "Configure CMake debugging sessions in Visual Studio"
3
-
ms.date: "03/21/2019"
3
+
description: "Describes how to use Visual Studio to configure CMake debugger settings"
4
+
ms.date: "01/13/2020"
4
5
helpviewer_keywords: ["CMake debugging"]
5
6
---
6
7
# Configure CMake debugging sessions
7
8
9
+
::: moniker range="vs-2015"
10
+
11
+
Native CMake support is available in Visual Studio 2017 and later.
12
+
13
+
::: moniker-end
14
+
15
+
::: moniker range=">=vs-2017"
16
+
8
17
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.
@@ -17,7 +26,15 @@ Then, right-click on any executable and select **Debug** or **Debug and Launch S
17
26
18
27
## Customize debugger settings
19
28
20
-
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:
29
+
You can customize the debugger settings for any executable CMake target in your project in a file called *launch.vs.json*. There are three entry points to this file:
30
+
31
+
- Select **Debug > Debug and Launch Settings for ${activeDebugTarget}** from the main menu to edit the debug configuration specific to your active debug target. If you don't have an active target selected, this option will be grayed out.
32
+
33
+
- Navigate to **Targets View** in Solution Explorer. Then, right-click on a debug target and select **Debug and Launch Settings** to edit the debug configuration specific to your selected target.
34
+
35
+
- Right-click on a root CMakeLists.txt and select **Debug and Launch Settings** to open the **Select a Debugger** dialog box. The dialog allows you to add any debug configuration, but you must manually specify the CMake target to invoke via the `projectTarget` property.
36
+
37
+
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:
21
38
22
39
```json
23
40
{
@@ -35,40 +52,141 @@ To customize the debugger settings for any executable CMake target in your proje
35
52
}
36
53
```
37
54
38
-
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.
55
+
When you save the *launch.vs.json* file, Visual Studio creates an entry for the new name in the **Startup Item** dropdown. You can edit the *launch.vs.json* file to create multiple debug configurations, for any number of CMake targets.
56
+
57
+
## Launch.vs.json reference
58
+
59
+
There are many *launch.vs.json* properties to support all your debugging scenarios. The following properties are common to all debug configurations, both remote and local:
60
+
61
+
-`projectTarget`: Specifies the CMake target to invoke when building the project. Visual Studio autopopulates this property if you enter *launch.vs.json* from **Debug > Debug and Launch Settings for ${activeDebugTarget}** or **Targets View**.
62
+
63
+
-`program`: Full path to the program executable on the remote system. You can use the macro `${debugInfo.fullTargetPath}` here.
64
+
65
+
-`args`: Command-line arguments passed to the program to debug.
66
+
67
+
## Launch.vs.json reference for remote Linux projects
39
68
40
-
## Support for CMakeSettings variables
69
+
The following properties are specific to **remote debug configurations**. You can also [send commands directly to gdb](https://github.com/microsoft/MIEngine/wiki/Executing-custom-gdb-lldb-commands) and [enable MIEngine logging](https://github.com/microsoft/MIEngine/wiki/Logging). These properties let you see what commands get sent to gdb, what output gdb returns, and how long each command takes.
41
70
42
-
**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:
71
+
-`cwd`: Current working directory for finding dependencies and other files on the remote machine. The macro `${debugInfo.defaultWorkingDirectory}` can be used. The default value is the remote workspace root unless overridden in *CMakeLists.txt*. This property is only used for remote configurations; `currentDir` is used to set the current directory of the launching app for a local project.
72
+
73
+
-`environment`: Additional environment variables to add to the environment for the program with this syntax:
When you run the app, the value of `currentDir` is something similar to
88
+
-`pipeArgs`: Command-line arguments passed to the pipe program to configure the connection. The pipe program is used to relay standard input/output between Visual Studio and gdb. The command `${debuggerCommand}` launches gdb on the remote system, and can be modified to:
- Export the value of the environment variable DISPLAY on your Linux system. In the following example, this value is `:1`.
59
91
60
-
The key 'cwd' sets the current directory of the launching app for a remote project. The default value is '${debugInfo.defaultWorkingDirectory}' which evaluates to
- Run a script before the execution of gdb. Ensure execute permissions are set on your script.
105
+
106
+
```json
107
+
"pipeArgs": [
108
+
"/s",
109
+
"${debugInfo.remoteMachineId}",
110
+
"/p",
111
+
"${debugInfo.parentProcessId}",
112
+
"/c",
113
+
"/path/to/script.sh;${debuggerCommand}",
114
+
"--tty=${debugInfo.tty}"
115
+
],
116
+
```
117
+
118
+
- `stopOnEntry`: A boolean that specifies whether to break as soon as the process is launched. The default is false.
119
+
120
+
- `visualizerFile`: A [.natvis file](/visualstudio/debugger/create-custom-views-of-native-objects) to use when debugging this process. This option is incompatible with gdb pretty printing. Also set `showDisplayString` when you set this property.
121
+
122
+
- `showDisplayString`: A boolean that enables the display string when a `visualizerFile` is specified. Setting this option to `true` can cause slower performance during debugging.
123
+
124
+
- `setupCommands`: One or more gdb command(s) to execute, to set up the underlying debugger.
125
+
126
+
- `externalConsole`: A boolean that specifies whether a console is launched for the debuggee.
127
+
128
+
- `miDebuggerPath`: The full path to gdb. When unspecified, Visual Studio searches PATH first for the debugger.
129
+
130
+
::: moniker-end
131
+
132
+
::: moniker range="vs-2017"
133
+
134
+
- `remoteMachineName`: The remote Linux system that hosts gdb and the program to debug.
135
+
136
+
::: moniker-end
137
+
138
+
::: moniker range="vs-2019"
139
+
140
+
The following properties can be used to separate your **remote build system** from your **remote debug system**. For more information, see [Specify different machines for building and debugging](../linux/deploy-run-and-debug-your-linux-project.md#cmake-projects).
141
+
142
+
- `remoteMachineName`: The remote Linux system that hosts gdb and the program to debug. This entry doesn't need to match the remote Linux system used for build specified in *CMakeSettings.json*. Press **Ctrl+Space** to view a list of all remote connections stored in the [Connection Manager](../linux/connect-to-your-remote-linux-computer.md).
143
+
144
+
- `disableDeploy`: Indicates whether build/debug separation is disabled. When enabled, this feature allows build and debug to occur on two separate machines.
145
+
146
+
- `deployDirectory`: The directory on the remote debug machine (specified by `remoteMachineName`) that the executable will be copied to.
147
+
148
+
- `deploy`: An array of advanced deployment settings. You only need to configure these settings when you want more granular control over the deployment process. By default, only the files necessary for the process to debug will be deployed to the remote debug machine.
149
+
150
+
- `sourceMachine`: The machine from which the file or directory will be copied. Press **Ctrl+Space** to view a list of all the remote connections stored in the Connection Manager.
151
+
152
+
- `targetMachine`: The machine to which the file or directory will be copied. Press **Ctrl+Space** to view a list of all the remote connections stored in the Connection Manager.
153
+
154
+
- `sourcePath`: The file or directory location on `sourceMachine`.
155
+
156
+
- `targetPath`: The file or directory location on `targetMachine`.
157
+
158
+
- `deploymentType`: A description of the deployment type. `LocalRemote` and `RemoteRemote` are supported. `LocalRemote` means copying from the local file system to the remote system specified by `remoteMachineName` in *launch.vs.json*. `RemoteRemote` means copying from the remote build system specified in *CMakeSettings.json* to the different remote system specified in *launch.vs.json*.
159
+
160
+
- `executable`: Indicates whether the deployed file is an executable.
161
+
162
+
::: moniker-end
163
+
164
+
::: moniker range=">=vs-2017"
165
+
166
+
## Attach to a remote process
167
+
168
+
You can attach to a process running on your Linux system by setting `processId` to the Process ID to attach the debugger to. For more information, see [Troubleshoot attaching to processes using GDB](https://github.com/Microsoft/MIEngine/wiki/Troubleshoot-attaching-to-processes-using-GDB).
169
+
170
+
::: moniker-end
171
+
172
+
::: moniker range="vs-2019"
173
+
174
+
## Debug on Linux using gdbserver
175
+
176
+
Visual Studio 2019 version 16.5 Preview 1 or later supports the remote debugging of CMake projects with gdbserver. For more information, see [debugging Linux CMake projects with gdbserver](https://devblogs.microsoft.com/cppblog/debugging-linux-cmake-projects-with-gdbserver/).
177
+
178
+
::: moniker-end
179
+
180
+
::: moniker range=">=vs-2017"
65
181
66
182
## See also
67
183
68
-
[CMake Projects in Visual Studio](cmake-projects-in-visual-studio.md)<br/>
69
-
[Configure a Linux CMake project](../linux/cmake-linux-project.md)<br/>
70
-
[Connect to your remote Linux computer](../linux/connect-to-your-remote-linux-computer.md)<br/>
0 commit comments