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/10/2020"
4
5
helpviewer_keywords: ["CMake debugging"]
5
6
---
6
7
# Configure CMake debugging sessions
@@ -17,13 +18,15 @@ Then, right-click on any executable and select **Debug** or **Debug and Launch S
17
18
18
19
## Customize debugger settings
19
20
20
-
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:
21
+
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:
21
22
22
-
- 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 do not have an active target selected, this option will be grayed out.
23
-
- Navigate to **Targets View** in the Solution Explorer, right-click on a debug target and select **Debug and Launch Settings** to edit the debug configuration specific to your selected target.
24
-
- Right-click on a root CMakeLists.txt and select **Debug and Launch Settings** to open the “Select a Debugger” dialogue. This will allow you to add any debug configuration, but you will need to manually specify the CMake target to invoke via the `projectTarget` property.
23
+
- 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.
25
24
26
-
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:
25
+
- 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.
26
+
27
+
- 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.
28
+
29
+
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:
27
30
28
31
```json
29
32
{
@@ -40,93 +43,118 @@ To reference any key in a **CMakeSettings.json** file, preface it with `cmake.`
40
43
]
41
44
}
42
45
```
43
-
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.
46
+
47
+
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.
44
48
45
49
## Launch.vs.json reference
46
50
47
-
There are many launch.vs.json properties to help support different debugging scenarios. The following properties are **common to all debug configurations** (remote and local):
51
+
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:
52
+
53
+
-`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**.
48
54
49
-
-`projectTarget`: specifies the CMake target to invoke when building the project. This property is auto-populated if you enter launch.vs.json from **Debug > Debug and Launch Settings for ${activeDebugTarget}** or **Targets View**.
50
-
-`program`: full path to the program executable on the remote system. The macro `${debugInfo.fullTargetPath}` can be used.
51
-
-`args`: command line arguments passed to the program to debug
55
+
-`program`: Full path to the program executable on the remote system. You can use the macro `${debugInfo.fullTargetPath}` here.
56
+
57
+
-`args`: Command-line arguments passed to the program to debug.
52
58
53
59
## Launch.vs.json reference for remote Linux projects
54
60
55
-
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) to see what commands we are sending to gdb, what output gdb is returning, and how long each command took.
61
+
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.
62
+
63
+
-`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.
64
+
65
+
-`environment`: Additional environment variables to add to the environment for the program with this syntax:
56
66
57
-
-`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.
58
-
-`environment`: additional environment variables to add to the environment for the program with syntax:
59
67
```json
60
-
"environment": [
61
-
{
62
-
"name": "ENV1",
63
-
"value": "envvalue1"
64
-
},
65
-
{
66
-
"name": "ENV2",
67
-
"value": "envvalue2"
68
-
}
69
-
]
68
+
"environment": [
69
+
{
70
+
"name": "ENV1",
71
+
"value": "envvalue1"
72
+
},
73
+
{
74
+
"name": "ENV2",
75
+
"value": "envvalue2"
76
+
}
77
+
]
70
78
```
71
79
72
-
-`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:
73
-
- Export the value of the environment variable DISPLAY on your Linux system. In the following example this value is :1.
80
+
-`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:
81
+
82
+
- Export the value of the environment variable DISPLAY on your Linux system. In the following example, this value is `:1`.
83
+
74
84
```json
75
85
"pipeArgs": [
76
-
"/s",
77
-
"${debugInfo.remoteMachineId}",
78
-
"/p",
79
-
"${debugInfo.parentProcessId}",
80
-
"/c",
81
-
"export DISPLAY=:1;${debuggerCommand}",
82
-
"--tty=${debugInfo.tty}"
83
-
],
86
+
"/s",
87
+
"${debugInfo.remoteMachineId}",
88
+
"/p",
89
+
"${debugInfo.parentProcessId}",
90
+
"/c",
91
+
"export DISPLAY=:1;${debuggerCommand}",
92
+
"--tty=${debugInfo.tty}"
93
+
],
84
94
```
85
-
- Run a script before the execution of gdb. Ensure execute permissions are set on your script.
95
+
96
+
- Run a script before the execution of gdb. Ensure execute permissions are set on your script.
97
+
86
98
```json
87
99
"pipeArgs": [
88
-
"/s",
89
-
"${debugInfo.remoteMachineId}",
90
-
"/p",
91
-
"${debugInfo.parentProcessId}",
92
-
"/c",
93
-
"/path/to/script.sh;${debuggerCommand}",
94
-
"--tty=${debugInfo.tty}"
95
-
],
100
+
"/s",
101
+
"${debugInfo.remoteMachineId}",
102
+
"/p",
103
+
"${debugInfo.parentProcessId}",
104
+
"/c",
105
+
"/path/to/script.sh;${debuggerCommand}",
106
+
"--tty=${debugInfo.tty}"
107
+
],
96
108
```
97
109
98
-
- `stopOnEntry`: a boolean that specifies whether to break as soon as the process is launched. The default is false.
99
-
- `visualizerFile`: a [.natvis file](https://docs.microsoft.com/en-us/visualstudio/debugger/create-custom-views-of-native-objects?view=vs-2019) to be used when debugging this process. This option is not compatible with gdb pretty printing. Please also see showDisplayString when using this property.
100
-
- `showDisplayString`: a boolean that enables the display string when a visualizerFile is specified. Setting this option to true can cause slower performance during debugging.
101
-
- `setupCommands`: one or more gdb command(s) to execute in order to set-up the underlying debugger.
102
-
- `externalConsole`: a boolean that specifies whether a console is launched for the debugee.
103
-
- `miDebuggerPath`: the full path to gdb. When unspecified, Visual Studio will search PATH first for the debugger.
104
-
105
-
The following properties can be used to **separate your remote build system from your remote debug system**.
106
-
107
-
- `remoteMachineName`: the remote Linux system which hosts gdb and the program to debug. This does not 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).
108
-
- `disableDeploy`: indicates whether build/debug separation is disabled. When enabled, this feature allows build and debug to occur on two separate machines.
109
-
- `deployDirectory`: directory on the remote debug machine (specified by `remoteMachineName`) that the executable will be copied to.
110
-
- `deploy`: an array of advanced deployment settings. These settings only need to be configured 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.
111
-
- `sourceMachine`: the machine from which the file or directory will be copied. Press cntrl+space to view a list of all the remote connections stored in the Connection Manager.
112
-
- `targetMachine`: the machine to which the file or directory will be copied. Press cntrl+space to view a list of all the remote connections stored in the Connection Manager.
113
-
- `sourcePath`: file or directory location on `sourceMachine`
114
-
- `targetPath`: file or directory location on `targetMachine`
115
-
- `deploymentType`: 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.
116
-
- `executable`: indicates whether the deployed file is an executable
117
-
118
-
## Attach to a remote process
119
-
You can **attach to a process running on your Linux system** by manipulating `processId`: the Process ID to attach the debugger to. See [troubleshoot attaching to processes using GDB](https://github.com/Microsoft/MIEngine/wiki/Troubleshoot-attaching-to-processes-using-GDB) for more information.
110
+
- `stopOnEntry`: A boolean that specifies whether to break as soon as the process is launched. The default is false.
111
+
112
+
- `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.
113
+
114
+
- `showDisplayString`: A boolean that enables the display string when a `visualizerFile` is specified. Setting this option to `true` can cause slower performance during debugging.
115
+
116
+
- `setupCommands`: One or more gdb command(s) to execute, to set up the underlying debugger.
117
+
118
+
- `externalConsole`: A boolean that specifies whether a console is launched for the debuggee.
119
+
120
+
- `miDebuggerPath`: The full path to gdb. When unspecified, Visual Studio searches PATH first for the debugger.
121
+
122
+
The following properties can be used to separate your **remote build system** from your **remote debug system**.
123
+
124
+
- `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).
125
+
126
+
- `disableDeploy`: Indicates whether build/debug separation is disabled. When enabled, this feature allows build and debug to occur on two separate machines.
127
+
128
+
- `deployDirectory`: The directory on the remote debug machine (specified by `remoteMachineName`) that the executable will be copied to.
129
+
130
+
- `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.
131
+
132
+
- `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.
133
+
134
+
- `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.
135
+
136
+
- `sourcePath`: The file or directory location on `sourceMachine`.
137
+
138
+
- `targetPath`: The file or directory location on `targetMachine`.
139
+
140
+
- `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*.
141
+
142
+
- `executable`: Indicates whether the deployed file is an executable.
143
+
144
+
## Attach to a remote process
145
+
146
+
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).
120
147
121
148
## Debug on Linux using gdbserver
122
-
Visual Studio 2019 version 16.5 Preview 1 or later supports the remote debugging of CMake projects with gdbserver. See [debugging Linux CMake projects with gdbserver](https://devblogs.microsoft.com/cppblog/debugging-linux-cmake-projects-with-gdbserver/) for more information.
149
+
150
+
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/).
123
151
124
152
## See also
125
153
126
-
[CMake Projects in Visual Studio](cmake-projects-in-visual-studio.md)<br/>
127
-
[Configure a Linux CMake project](../linux/cmake-linux-project.md)<br/>
128
-
[Connect to your remote Linux computer](../linux/connect-to-your-remote-linux-computer.md)<br/>
0 commit comments