Acrolinx fix followup for PR2784

Author: Colin Robertson

docs/build/configure-cmake-debugging-sessions.md

@@ -1,7 +1,7 @@
 ---
 title: "Configure CMake debugging sessions in Visual Studio"
-description: "Describes how to use Visual Studio to configure CMake debugger settings"
-ms.date: "01/13/2020"
+description: "Describes how to use Visual Studio to configure CMake debugger settings."
+ms.date: "04/02/2020"
 helpviewer_keywords: ["CMake debugging"]
 ---
 # Configure CMake debugging sessions
@@ -26,9 +26,9 @@ Then, right-click on an executable and select **Debug**. This command automatica
 
 ## Customize debugger settings
 
-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:
+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:
 
-- **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.
+- **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.
 
 ![Debug menu entry point](media/cmake-debug-menu.png "Debug menu entry point")
 
@@ -40,11 +40,11 @@ You can customize the debugger settings for any executable CMake target in your
 
 ![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.
+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.
 
 ## 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:
+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:
 
 ```json
 {
@@ -62,15 +62,15 @@ To reference any key in a *CMakeSettings.json* file, preface it with `cmake.` in
 }
 ```
 
-**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**.
+**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**.
 
 ## 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 the **Debug Menu** or **Targets View**. This value must match the name of an existing debug target listed in the **Startup Item** dropdown.
 
-- `env`: Additional environment variables to add with the syntax:
+- `env`: Additional environment variables to add using the syntax:
 
   ```json
   "env": {
@@ -83,56 +83,56 @@ There are many *launch.vs.json* properties to support all your debugging scenari
 
 ## Launch.vs.json reference for remote projects and WSL
 
-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.
+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.
 
 ### Configuration type `cppgdb`
 
 - `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. In Visual Studio 2019 version 16.6, the only valid option is **gdb**.
+- `project`: Specifies the relative path to the project file. Normally, you don't need to change this path 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 target 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. In Visual Studio 2019 version 16.6, the only valid option is `gdb`. Earlier versions also support `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).
 
-#### Additional options allowed with the `gdb` configuration
+#### Additional options for the `gdb` configuration
 
 - `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.
+- `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` doesn't start until the command completes. You can use the option to run a script before the execution of `gdb`.
 
 #### Deployment options
 
-Use the following options to separate your build machine (defined in CMakeSettings.json) from your remote debug machine. 
+Use the following options to separate your build machine (defined in CMakeSettings.json) from your remote debug machine.
 
 - `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.
+- `deployDirectory`: Full Unix path to the directory on `remoteMachineName` that the executable gets 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 get deployed to the remote debug machine.
+  - `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.
+  - `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.
   - `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
+### Execute custom `gdb` commands
 
-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)
+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).
 
 ### Enable logging
 
-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)
+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)
 
 ### Configuration type `cppdbg`
 
 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.
 
 - `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.
+- `project`: Specifies the relative path to the project file. Normally, you don't need to change this value 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.
 
@@ -161,7 +161,7 @@ The following options can be used when debugging on a remote system or WSL using
       ]
   ```
 
-- `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:
+- `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:
 
   - Export the value of the environment variable DISPLAY on your Linux system. In the following example, this value is `:1`.
 
@@ -177,7 +177,7 @@ The following options can be used when debugging on a remote system or WSL using
       ],
     ```
 
-  - Run a script before the execution of gdb. Ensure execute permissions are set on your script.
+  - Run a script before the execution of `gdb`. Ensure execute permissions are set on your script.
 
     ```json
     "pipeArgs": [
@@ -193,18 +193,19 @@ The following options can be used when debugging on a remote system or WSL using
 
 - `stopOnEntry`: A boolean that specifies whether to break as soon as the process is launched. The default is false.
 
-- `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.
+- `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.
 
 - `showDisplayString`: A boolean that enables the display string when a `visualizerFile` is specified. Setting this option to `true` can cause slower performance during debugging.
 
-- `setupCommands`: One or more gdb command(s) to execute, to set up the underlying debugger.
+- `setupCommands`: One or more `gdb` command(s) to execute, to set up the underlying debugger.
+
+- `miDebuggerPath`: The full path to `gdb`. When unspecified, Visual Studio searches PATH first for the debugger.
 
-- `miDebuggerPath`: The full path to gdb. When unspecified, Visual Studio searches PATH first for the debugger.
+- Finally, all of the deployment options defined for the `cppgdb` configuration type can be used by the `cppdbg` configuration type as well.
 
-- Finally, all of the deployment options defined for the `cppgdb` configuration type can be used with the `cppdbg` configuration type as well.
+### Debug using `gdbserver`
 
-### Debugging with gdbserver 
-You can configure the `cppdbg` configuration to debug with gdbserver. More details and a sample launch configuration can be found [here](https://devblogs.microsoft.com/cppblog/debugging-linux-cmake-projects-with-gdbserver/). 
+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/).
 
 ::: moniker-end