diff --git a/docs/build/configure-cmake-debugging-sessions.md b/docs/build/configure-cmake-debugging-sessions.md index 0f5d061c87a..94e141677f5 100644 --- a/docs/build/configure-cmake-debugging-sessions.md +++ b/docs/build/configure-cmake-debugging-sessions.md @@ -14,7 +14,7 @@ Native CMake support is available in Visual Studio 2017 and later. ::: moniker range=">=vs-2017" -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. +All executable CMake targets are shown in the **Startup Item** dropdown in the **General** toolbar. Select one to start a debugging session and launch the debugger. ![CMake startup item dropdown](media/cmake-startup-item-dropdown.png "CMake startup item dropdown") @@ -22,17 +22,27 @@ You can also start a debug session from Solution Explorer. First, switch to **CM ![CMake targets view button](media/cmake-targets-view.png "CMake Targets View menu item") -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. +Then, right-click on an executable and select **Debug**. This command automatically starts debugging the selected target based on your active configuration. ## Customize debugger settings -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: +You can customize the debugger settings for any executable CMake target in your project 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: -- 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. +- **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. -- 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. +![Debug menu entry point](media/cmake-debug-menu.png "Debug menu entry point") -- 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. +- **Targets View:** Navigate to **Targets View** in Solution Explorer. Then, right-click on a debug target and select **Add Debug Configuration** to customize the debug configuration specific to the selected target. + +![Targets view entry point](media/cmake-targets-add-debug.png "Targets view entry point") + +- **Root CMakeLists.txt:** Right-click on a root *CMakeLists.txt* and select **Add Debug Configuration** to open the **Select a Debugger** dialog box. The dialog allows you to add *any* type of debug configuration, but you must manually specify the CMake target to invoke via the `projectTarget` property. + +![Select a debugger dialog box](media/cmake-select-a-debugger.png "Select a debugger dialog box") + +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. + +## Reference keys in CMakeSettings.json 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: @@ -52,128 +62,155 @@ To reference any key in a *CMakeSettings.json* file, preface it with `cmake.` in } ``` -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. +**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**. ## Launch.vs.json reference 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: -- `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**. - -- `program`: Full path to the program executable on the remote system. You can use the macro `${debugInfo.fullTargetPath}` here. - -- `args`: Command-line arguments passed to the program to debug. - -## Launch.vs.json reference for remote Linux projects - -The following properties are specific to **remote debug configurations**. You can also [execute custom gdb commands](https://github.com/microsoft/MIEngine/wiki/Executing-custom-gdb-lldb-commands) to send commands directly to the underlying debugger, and [enable MIEngine logging](https://github.com/microsoft/MIEngine/wiki/Logging) to see what commands get sent to gdb, what output gdb returns, and how long each command takes. - -- `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. +- `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. -- `environment`: Additional environment variables to add to the environment for the program with this syntax: +- `env`: Additional environment variables to add with the syntax: -```json - "environment": [ - { - "name": "ENV1", - "value": "envvalue1" - }, - { - "name": "ENV2", - "value": "envvalue2" + ```json + "env": { + "DEBUG_LOGGING_LEVEL": "trace;info", + "ENABLE_TRACING": "true" } - ] -``` - -- `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`. +- `args`: Command-line arguments passed to the program to debug. - ```json - "pipeArgs": [ - "/s", - "${debugInfo.remoteMachineId}", - "/p", - "${debugInfo.parentProcessId}", - "/c", - "export DISPLAY=:1;${debuggerCommand}", - "--tty=${debugInfo.tty}" - ], - ``` +## Launch.vs.json reference for remote projects and WSL - - Run a script before the execution of gdb. Ensure execute permissions are set on your script. +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. - ```json - "pipeArgs": [ - "/s", - "${debugInfo.remoteMachineId}", - "/p", - "${debugInfo.parentProcessId}", - "/c", - "/path/to/script.sh;${debuggerCommand}", - "--tty=${debugInfo.tty}" - ], - ``` +### Configuration type `cppgdb` -- `stopOnEntry`: A boolean that specifies whether to break as soon as the process is launched. The default is false. +- `name`: A friendly name to identify the configuration in the **Startup Item** dropdown. +- `project`: Specifies the relative path to the project file. You shouldn't need to change this when debugging a CMake project. +- `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. +- `debuggerConfiguration`: Indicates which set of debugging default values to use. Valid options are **gdb** and **gdbserver**. +- `args`: Command-line arguments passed on startup to the program being debugged. +- `env`: Additional environment variables passed to the program being debugged. For example, `{"DISPLAY": "0.0"}`. +- `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). -- `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. +#### Additional options allowed with the `gdb` configuration -- `showDisplayString`: A boolean that enables the display string when a `visualizerFile` is specified. Setting this option to `true` can cause slower performance during debugging. +- `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. +- `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. +- `cwd`: Defaults to `"${debugInfo.defaultWorkingDirectory}"`. The Unix path to the directory on the remote system where `program` is run. The directory must exist. +- `gdbpath`: Defaults to `/usr/bin/gdb`. Full Unix path to the gdb used to debug. Only required if using a custom version of gdb. +- `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. -- `setupCommands`: One or more gdb command(s) to execute, to set up the underlying debugger. +#### Additional options allowed with the `gdbserver` configuration -- `externalConsole`: A boolean that specifies whether a console is launched for the debuggee. +- `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. +- `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. +- `cwd`: Defaults to `"${debugInfo.defaultWorkingDirectory}"`. Full Unix path to the directory on the remote system where `program` is run. The directory must exist. +- `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. +- `gdbserverPath`: Defaults to `usr/bin/gdbserver`. Full Unix path to the gdbserver used to debug. +- `preDebugCommand`: A Linux command to run immediately before starting gdbserver. Gdbserver will not start until it completes. -- `miDebuggerPath`: The full path to gdb. When unspecified, Visual Studio searches PATH first for the debugger. +#### Deployment options -::: moniker-end +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. -::: moniker range="vs-2017" +- `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. +- `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. +- `deployDirectory`: Full Unix path to the directory on `remoteMachineName` that the executable will be copied to. +- `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. + - `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. + - `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. + - `sourcePath`: The file or directory location on `sourceMachine`. + - `targetPath`: The file or directory location on `targetMachine`. + - `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*. + - `executable`: Indicates whether the deployed file is an executable. + +### Execute custom gdb commands -- `remoteMachineName`: The remote Linux system that hosts gdb and the program to debug. +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) -::: moniker-end +### Enable logging -::: moniker range="vs-2019" +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) -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). +### Configuration type `cppdbg` -- `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). +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. -- `disableDeploy`: Indicates whether build/debug separation is disabled. When enabled, this feature allows build and debug to occur on two separate machines. +- `name`: A friendly name to identify the configuration in the **Startup Item** dropdown. -- `deployDirectory`: The directory on the remote debug machine (specified by `remoteMachineName`) that the executable will be copied to. +- `project`: Specifies the relative path to the project file. You shouldn't need to change this when debugging a CMake project. -- `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. +- `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. - - `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. +- `args`: Command-line arguments passed on startup to the program being debugged. - - `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. +- `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). - - `sourcePath`: The file or directory location on `sourceMachine`. +- `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. - - `targetPath`: The file or directory location on `targetMachine`. +- `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. - - `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*. +- `cwd`: Defaults to `"${debugInfo.defaultWorkingDirectory}"`. Full Unix path to the directory on the remote system where `program` is run. The directory must exist. - - `executable`: Indicates whether the deployed file is an executable. +- `environment`: Additional environment variables passed to the program being debugged. For example, -::: moniker-end + ```json + "environment": [ + { + "name": "ENV1", + "value": "envvalue1" + }, + { + "name": "ENV2", + "value": "envvalue2" + } + ] + ``` + +- `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: -::: moniker range=">=vs-2017" + - Export the value of the environment variable DISPLAY on your Linux system. In the following example, this value is `:1`. -## Attach to a remote process + ```json + "pipeArgs": [ + "/s", + "${debugInfo.remoteMachineId}", + "/p", + "${debugInfo.parentProcessId}", + "/c", + "export DISPLAY=:1;${debuggerCommand}", + "--tty=${debugInfo.tty}" + ], + ``` + + - Run a script before the execution of gdb. Ensure execute permissions are set on your script. + + ```json + "pipeArgs": [ + "/s", + "${debugInfo.remoteMachineId}", + "/p", + "${debugInfo.parentProcessId}", + "/c", + "/path/to/script.sh;${debuggerCommand}", + "--tty=${debugInfo.tty}" + ], + ``` + +- `stopOnEntry`: A boolean that specifies whether to break as soon as the process is launched. The default is false. -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). +- `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. -::: moniker-end +- `showDisplayString`: A boolean that enables the display string when a `visualizerFile` is specified. Setting this option to `true` can cause slower performance during debugging. -::: moniker range="vs-2019" +- `setupCommands`: One or more gdb command(s) to execute, to set up the underlying debugger. -## Debug on Linux using gdbserver +- `miDebuggerPath`: The full path to gdb. When unspecified, Visual Studio searches PATH first for the debugger. -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/). +- Finally, all of the deployment options defined for the `cppgdb` configuration type can be used with the `cppdbg` configuration type as well. ::: moniker-end diff --git a/docs/build/media/cmake-debug-menu.png b/docs/build/media/cmake-debug-menu.png new file mode 100644 index 00000000000..5b634d15479 Binary files /dev/null and b/docs/build/media/cmake-debug-menu.png differ diff --git a/docs/build/media/cmake-select-a-debugger.png b/docs/build/media/cmake-select-a-debugger.png new file mode 100644 index 00000000000..3efa18ca0e1 Binary files /dev/null and b/docs/build/media/cmake-select-a-debugger.png differ diff --git a/docs/build/media/cmake-targets-add-debug.PNG b/docs/build/media/cmake-targets-add-debug.PNG new file mode 100644 index 00000000000..38762cfc427 Binary files /dev/null and b/docs/build/media/cmake-targets-add-debug.PNG differ diff --git a/docs/build/media/cmake-targets-add-debug.png b/docs/build/media/cmake-targets-add-debug.png new file mode 100644 index 00000000000..38762cfc427 Binary files /dev/null and b/docs/build/media/cmake-targets-add-debug.png differ