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
Copy file name to clipboardExpand all lines: docs/build/configure-cmake-debugging-sessions.md
+35-40Lines changed: 35 additions & 40 deletions
Original file line number
Diff line number
Diff line change
@@ -1,14 +1,14 @@
1
1
---
2
2
title: "Configure CMake debugging sessions in Visual Studio"
3
-
description: "Describes how to use Visual Studio to configure CMake debugger settings"
4
-
ms.date: "01/13/2020"
3
+
description: "Describes how to use Visual Studio to configure CMake debugger settings."
4
+
ms.date: "04/02/2020"
5
5
helpviewer_keywords: ["CMake debugging"]
6
6
---
7
7
# Configure CMake debugging sessions
8
8
9
9
::: moniker range="vs-2015"
10
10
11
-
Native CMake support is available in Visual Studio 2017 and later.
11
+
Native CMake support is available in Visual Studio 2017 and later. To see the documentation for those versions, use the **Version** selector on this page and choose Visual Studio 2017 or 2019.
12
12
13
13
::: moniker-end
14
14
@@ -26,9 +26,9 @@ Then, right-click on an executable and select **Debug**. This command automatica
26
26
27
27
## Customize debugger settings
28
28
29
-
You can customize the debugger settings for any executable CMake target in your projectin a configuration file called *launch.vs.json*, located in a *.vs* folder in your project root. A launch configuration file is useful in most debugging scenarios, because you can configure and save your debugging setup details. There are three entry points to this file:
29
+
You can customize the debugger settings for any executable CMake target in your project. They're found in a configuration file called *launch.vs.json*, located in a *`.vs`* folder in your project root. A launch configuration file is useful in most debugging scenarios, because you can configure and save your debugging setup details. There are three entry points to this file:
30
30
31
-
-**Debug Menu:** Select **Debug > Debug and Launch Settings for ${activeDebugTarget}** from the main menu to customize the debug configuration specific to your active debug target. If you don't have a debug target selected, this option will be grayed out.
31
+
-**Debug Menu:** Select **Debug > Debug and Launch Settings for ${activeDebugTarget}** from the main menu to customize the debug configuration specific to your active debug target. If you don't have a debug target selected, this option is grayed out.
32
32
33
33
![Debug menu entry point](media/cmake-debug-menu.png"Debug menu entry point")
34
34
@@ -40,11 +40,11 @@ You can customize the debugger settings for any executable CMake target in your
40
40
41
41
![Select a debugger dialog box](media/cmake-select-a-debugger.png"Select a debugger dialog box")
42
42
43
-
When you save the *launch.vs.json* file, Visual Studio creates an entry for the new configuration in the **Startup Item** dropdown. You can edit the *launch.vs.json* file to create multiple debug configurations, for any number of CMake targets.
43
+
You can edit the *launch.vs.json* file to create debug configurations for any number of CMake targets. When you save the file, Visual Studio creates an entry for each new configuration in the **Startup Item** dropdown.
44
44
45
45
## Reference keys in CMakeSettings.json
46
46
47
-
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:
47
+
To reference any key in a *CMakeSettings.json* file, prepend `cmake.` to it 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:
48
48
49
49
```json
50
50
{
@@ -62,15 +62,15 @@ To reference any key in a *CMakeSettings.json* file, preface it with `cmake.` in
62
62
}
63
63
```
64
64
65
-
**Environment variables** defined in CMakeSettings.json can also be used in launch.vs.json using the syntax `${env.VARIABLE_NAME}`. In Visual Studio 2019 version 16.4 and later, debug targets are automatically launched with the environment you specify in CMakeSettings.json. You can unset an environment variable by setting it to **null**.
65
+
**Environment variables** defined in *CMakeSettings.json* can also be used in launch.vs.json using the syntax `${env.VARIABLE_NAME}`. In Visual Studio 2019 version 16.4 and later, debug targets are automatically launched using the environment you specify in *CMakeSettings.json*. You can unset an environment variable by setting it to **null**.
66
66
67
67
## Launch.vs.json reference
68
68
69
69
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:
70
70
71
71
-`projectTarget`: Specifies the CMake target to invoke when building the project. Visual Studio autopopulates this property if you enter *launch.vs.json* from the **Debug Menu** or **Targets View**. This value must match the name of an existing debug target listed in the **Startup Item** dropdown.
72
72
73
-
-`env`: Additional environment variables to add with the syntax:
73
+
-`env`: Additional environment variables to add using the syntax:
74
74
75
75
```json
76
76
"env": {
@@ -83,65 +83,56 @@ There are many *launch.vs.json* properties to support all your debugging scenari
83
83
84
84
## Launch.vs.json reference for remote projects and WSL
85
85
86
-
In Visual Studio 2019 version 16.6 we added a new debug configuration of `type: cppgdb` to simplify debugging with **gdb** and **gdbserver** on remote systems and WSL. Old debug configurations of `type: cppdbg` are still supported.
86
+
In Visual Studio 2019 version 16.6, we added a new debug configuration of `type: cppgdb` to simplify debugging on remote systems and WSL. Old debug configurations of `type: cppdbg` are still supported.
87
87
88
88
### Configuration type `cppgdb`
89
89
90
90
-`name`: A friendly name to identify the configuration in the **Startup Item** dropdown.
91
-
-`project`: Specifies the relative path to the project file. You shouldn't need to change this when debugging a CMake project.
92
-
-`projectTarget`: Specifies the CMake target to invoke when building the project. Visual Studio autopopulates this property if you enter *launch.vs.json* from the **Debug Menu** or **Targets View**. This value must match the name of an existing debug target listed in the **Startup Item** dropdown.
93
-
-`debuggerConfiguration`: Indicates which set of debugging default values to use. Valid options are **gdb** and **gdbserver**.
91
+
-`project`: Specifies the relative path to the project file. Normally, you don't need to change this path when debugging a CMake project.
92
+
-`projectTarget`: Specifies the CMake target to invoke when building the project. Visual Studio autopopulates this property if you enter *launch.vs.json* from the **Debug Menu** or **Targets View**. This target value must match the name of an existing debug target listed in the **Startup Item** dropdown.
93
+
-`debuggerConfiguration`: Indicates which set of debugging default values to use. In Visual Studio 2019 version 16.6, the only valid option is `gdb`. Earlier versions also support `gdbserver`.
94
94
-`args`: Command-line arguments passed on startup to the program being debugged.
95
95
-`env`: Additional environment variables passed to the program being debugged. For example, `{"DISPLAY": "0.0"}`.
96
96
-`processID`: Linux process ID to attach to. Only used when attaching to a remote process. For more information, see [Troubleshoot attaching to processes using GDB](https://github.com/Microsoft/MIEngine/wiki/Troubleshoot-attaching-to-processes-using-GDB).
97
97
98
-
#### Additional options allowed with the `gdb` configuration
98
+
#### Additional options for the `gdb` configuration
99
99
100
100
-`program`: Defaults to `"${debugInfo.fullTargetPath}"`. The Unix path to the application to debug. Only required if different than the target executable in the build or deploy location.
101
101
-`remoteMachineName`: Defaults to `"${debugInfo.remoteMachineName}"`. Name of the remote system that hosts the program to debug. Only required if different than the build system. Must have an existing entry in the [Connection Manager](../linux/connect-to-your-remote-linux-computer.md). Press **Ctrl+Space** to view a list of all existing remote connections.
102
102
-`cwd`: Defaults to `"${debugInfo.defaultWorkingDirectory}"`. The Unix path to the directory on the remote system where `program` is run. The directory must exist.
103
-
-`gdbpath`: Defaults to `/usr/bin/gdb`. Full Unix path to the gdb used to debug. Only required if using a custom version of gdb.
104
-
-`preDebugCommand`: A Linux command to run immediately before invoking gdb. Gdb will not start until it completes. You can use this to run a script before the execution of gdb.
105
-
106
-
#### Additional options allowed with the `gdbserver` configuration
107
-
108
-
-`program`: Defaults to `"${debugInfo.fullTargetPath}"`. The Unix path to the application to debug. Only required if different than the target executable in the build or deploy location.
109
-
-`remoteMachineName`: Defaults to `"${debugInfo.remoteMachineName}"`. Name of the remote system that hosts the program to debug. Only required if different than the build system. Must have an existing entry in the [Connection Manager](../linux/connect-to-your-remote-linux-computer.md). Press **Ctrl+Space** to view a list of all existing remote connections.
110
-
-`cwd`: Defaults to `"${debugInfo.defaultWorkingDirectory}"`. Full Unix path to the directory on the remote system where `program` is run. The directory must exist.
111
-
-`gdbPath`: Defaults to `${debugInfo.vsInstalledGdb}`. Full Windows path to the gdb used to debug. Defaults to the gdb installed with the Linux development with C/C++ workload.
112
-
-`gdbserverPath`: Defaults to `usr/bin/gdbserver`. Full Unix path to the gdbserver used to debug.
113
-
-`preDebugCommand`: A Linux command to run immediately before starting gdbserver. Gdbserver will not start until it completes.
103
+
-`gdbpath`: Defaults to `/usr/bin/gdb`. Full Unix path to the `gdb` used to debug. Only required if using a custom version of `gdb`.
104
+
-`preDebugCommand`: A Linux command to run immediately before invoking `gdb`. `gdb` doesn't start until the command completes. You can use the option to run a script before the execution of `gdb`.
114
105
115
106
#### Deployment options
116
107
117
-
Use the following options to separate your build machine (defined in CMakeSettings.json) from your remote debug machine. These options apply to both `gdb` and `gdbserver` configurations.
108
+
Use the following options to separate your build machine (defined in CMakeSettings.json) from your remote debug machine.
118
109
119
110
-`remoteMachineName`: Remote debug machine. Only required if different than the build machine. Must have an existing entry in the [Connection Manager](../linux/connect-to-your-remote-linux-computer.md). Press **Ctrl+Space** to view a list of all existing remote connections.
120
111
-`disableDeploy`: Defaults to `false`. Indicates whether build/debug separation is disabled. When `false`, this option allows build and debug to occur on two separate machines.
121
-
-`deployDirectory`: Full Unix path to the directory on `remoteMachineName` that the executable will be copied to.
122
-
-`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.
123
-
-`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. When building natively on WSL this option will be ignored.
124
-
-`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.
112
+
-`deployDirectory`: Full Unix path to the directory on `remoteMachineName` that the executable gets copied to.
113
+
-`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 get deployed to the remote debug machine.
114
+
-`sourceMachine`: The machine from which the file or directory is copied. Press **Ctrl+Space** to view a list of all the remote connections stored in the Connection Manager. When building natively on WSL, this option is ignored.
115
+
-`targetMachine`: The machine to which the file or directory is copied. Press **Ctrl+Space** to view a list of all the remote connections stored in the Connection Manager.
125
116
-`sourcePath`: The file or directory location on `sourceMachine`.
126
117
-`targetPath`: The file or directory location on `targetMachine`.
127
118
-`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*.
128
119
-`executable`: Indicates whether the deployed file is an executable.
129
120
130
-
### Execute custom gdb commands
121
+
### Execute custom `gdb` commands
131
122
132
-
Visual Studio supports executing custom gdb commands to interact directly with the underlying debugger. [Learn more](https://github.com/microsoft/MIEngine/wiki/Executing-custom-gdb-lldb-commands)
123
+
Visual Studio supports executing custom `gdb` commands to interact with the underlying debugger directly. For more information, see [Executing custom `gdb` lldb commands](https://github.com/microsoft/MIEngine/wiki/Executing-custom-gdb-lldb-commands).
133
124
134
125
### Enable logging
135
126
136
-
Enable MIEngine logging to see what commands get sent to gdb, what output gdb returns, and how long each command takes. [Learn more](https://github.com/microsoft/MIEngine/wiki/Logging)
127
+
Enable MIEngine logging to see what commands get sent to `gdb`, what output `gdb` returns, and how long each command takes. [Learn more](https://github.com/microsoft/MIEngine/wiki/Logging)
137
128
138
129
### Configuration type `cppdbg`
139
130
140
131
The following options can be used when debugging on a remote system or WSL using the `cppdbg` configuration type. In Visual Studio 2019 version 16.6 or later, configuration type `cppgdb` is recommended.
141
132
142
133
-`name`: A friendly name to identify the configuration in the **Startup Item** dropdown.
143
134
144
-
-`project`: Specifies the relative path to the project file. You shouldn't need to change this when debugging a CMake project.
135
+
-`project`: Specifies the relative path to the project file. Normally, you don't need to change this value when debugging a CMake project.
145
136
146
137
-`projectTarget`: Specifies the CMake target to invoke when building the project. Visual Studio autopopulates this property if you enter *launch.vs.json* from the **Debug Menu** or **Targets View**. This value must match the name of an existing debug target listed in the **Startup Item** dropdown.
147
138
@@ -170,7 +161,7 @@ The following options can be used when debugging on a remote system or WSL using
170
161
]
171
162
```
172
163
173
-
-`pipeArgs`: An array of 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. Most of this array **does not need to be customized** when debugging CMake projects. The exception is the `${debuggerCommand}`. which launches gdb on the remote system and can be modified to:
164
+
-`pipeArgs`: An array of 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`. Most of this array **doesn't need to be customized** when debugging CMake projects. The exception is the `${debuggerCommand}`, which launches `gdb` on the remote system. It can be modified to:
174
165
175
166
- Export the value of the environment variable DISPLAY on your Linux system. In the following example, this value is `:1`.
176
167
@@ -186,7 +177,7 @@ The following options can be used when debugging on a remote system or WSL using
186
177
],
187
178
```
188
179
189
-
- Run a script before the execution of gdb. Ensure execute permissions are set on your script.
180
+
- Run a script before the execution of `gdb`. Ensure execute permissions are set on your script.
190
181
191
182
```json
192
183
"pipeArgs": [
@@ -202,15 +193,19 @@ The following options can be used when debugging on a remote system or WSL using
202
193
203
194
- `stopOnEntry`: A boolean that specifies whether to break as soon as the process is launched. The default is false.
204
195
205
-
- `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.
196
+
- `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.
206
197
207
198
- `showDisplayString`: A boolean that enables the display string when a `visualizerFile` is specified. Setting this option to `true` can cause slower performance during debugging.
208
199
209
-
- `setupCommands`: One or more gdb command(s) to execute, to set up the underlying debugger.
200
+
- `setupCommands`: One or more `gdb` command(s) to execute, to set up the underlying debugger.
201
+
202
+
- `miDebuggerPath`: The full path to `gdb`. When unspecified, Visual Studio searches PATH first for the debugger.
203
+
204
+
- Finally, all of the deployment options defined for the `cppgdb` configuration type can be used by the `cppdbg` configuration type as well.
210
205
211
-
- `miDebuggerPath`: The full path to gdb. When unspecified, Visual Studio searches PATH first for the debugger.
206
+
### Debug using `gdbserver`
212
207
213
-
- Finally, all of the deployment options defined for the `cppgdb` configuration type can be used with the `cppdbg` configuration type as well.
208
+
You can configure the `cppdbg` configuration to debug using `gdbserver`. You can find more details and a sample launch configuration in the Microsoft C++ Team Blog post [Debugging Linux CMake Projects with `gdbserver`](https://devblogs.microsoft.com/cppblog/debugging-linux-cmake-projects-with-gdbserver/).
[ActivatableClass](activatableclass-macros.md) | Populates an internal cache that contains a factory that can create an instance of the specified class. This macro specifies default factory and group ID parameters.
90
90
[ActivatableClassWithFactory](activatableclass-macros.md) | Populates an internal cache that contains a factory that can create an instance of the specified class. This macro enables you to specify a particular factory parameter.
91
91
[ActivatableClassWithFactoryEx](activatableclass-macros.md) | Populates an internal cache that contains a factory that can create an instance of the specified class. This macro enables you to specify particular factory and group ID parameters.
0 commit comments