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/cmake-remote-debugging.md
+27-22Lines changed: 27 additions & 22 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
1
---
2
2
title: "Tutorial: Debug a CMake project on a remote Windows machine"
3
-
ms.date: "12/2/2020"
3
+
ms.date: "12/4/2020"
4
4
ms.topic: tutorial
5
5
description: "How to use Visual Studio C++ on Windows to create and build a CMake project. You'll then deploy and debug it on a remote Windows machine."
6
6
---
@@ -24,51 +24,55 @@ In this tutorial, you'll learn how to:
24
24
25
25
### On the host machine
26
26
27
-
To set up Visual Studio for cross-platform C++ development, install the build tools for the target architecture. For this tutorial, install the ARM64 build tools by following these steps:
27
+
To set up Visual Studio for cross-platform C++ development, install the build tools for the target architecture. For this tutorial, install the ARM64 build tools by doing the following:
28
28
29
29
1. Run the Visual Studio Installer. If you haven't installed Visual Studio yet, see [Install Visual Studio](https://docs.microsoft.com/visualstudio/install/install-visual-studio#:~:text=Install%20Visual%20Studio%201%20Make%20sure%20your%20computer,...%204%20Choose%20workloads.%20...%20More%20items...%20)
30
-
1. On the Visual Studio Installer home screen, choose **Modify** (look under **More** if you don't see it).
30
+
1. On the Visual Studio Installer home screen, choose **Modify**.
31
31
1. From the choices at the top, choose **Individual components**.
32
32
1. Scroll down to the **Compilers, build tools, and runtimes** section.
33
33
1. Ensure that the following are selected:
34
34
-**C++ CMake tools for Windows**
35
-
-**MSVC v142 - VS 2019 C++ ARM64 build tools (v14.28)**(choose the latest version)
35
+
-**MSVC v142 - VS 2019 C++ ARM64 build tools (Latest)**It's important that you choose the `ARM64` build tools and not the `ARM` build tools (look for the 64) and that you choose the version that goes with `VS 2019`.
36
36
1. Select **Modify** to install the tools.
37
37
38
38
### On the remote machine
39
39
40
-
1. Install the remote tools on the remote machine. For this tutorial, install the ARM64 tools as described in [Download and Install the remote tools](https://docs.microsoft.com/visualstudio/debugger/remote-debugging-cpp?%23download-and-install-the-remote-tools#download-and-install-the-remote-tools).
41
-
1.Install a remote debugger on the remote machine. For this tutorial, follow the directions in [set up the remote debugger](https://docs.microsoft.com/visualstudio/debugger/remote-debugging-cpp?%23download-and-install-the-remote-tools#BKMK_setup) on the remote Windows machine.
40
+
1. Install the remote tools on the remote machine. For this tutorial, install the ARM64 tools by following the instructions in [Download and Install the remote tools](https://docs.microsoft.com/visualstudio/debugger/remote-debugging-cpp?%23download-and-install-the-remote-tools#download-and-install-the-remote-tools).
41
+
1.Start and configure the remote debugger on the remote machine. For this tutorial, do so by following the directions in [set up the remote debugger](https://docs.microsoft.com/visualstudio/debugger/remote-debugging-cpp?%23download-and-install-the-remote-tools#BKMK_setup) on the remote Windows machine.
42
42
43
43
## Create a CMake project
44
44
45
45
On the Windows host machine:
46
46
1. Run Visual Studio
47
-
1. From the main menu, select **Create new project** > **CMake Project** > **Next**
47
+
1. From the main menu, select **File** > **New** > **Project**.
48
+
1. Select **CMake Project** > **Next**
48
49
1. Give the project a name and choose a location. Then select **Create**.
49
50
50
51
Give Visual Studio a few moments to create the project and populate the **Solution Explorer**.
51
52
52
53
## Change the configuration to target ARM64
53
54
54
-
To target an ARM64 Windows machine, you need to build with ARM64 build tools. Select the Visual Studio **Configuration** dropdown and select **Manage Configurations...**
55
+
To target an ARM64 Windows machine, you need to build using ARM64 build tools.
56
+
57
+
Select the Visual Studio **Configuration** dropdown and select **Manage Configurations**.
55
58
56
59
57
60
58
-
Add a new configuration by selecting the green **+** button. Choose **arm64-debug** in the dialog that appears and press the **Select** button:
61
+
Add a new configuration by selecting **Add a new configuration** (the green **+** button).\
62
+
In the **CMakeSettings** dialog that appears, select **arm64-debug**, and then press **Select**:
This will add a debug configuration named **arm64-Debug** to the*`CmakeSettings.json`* file. This configuration name is a unique, friendly name to make it easier for you to identify these settings in the **Configuration** dropdown.
66
+
This adds a debug configuration named **arm64-Debug** to your*`CmakeSettings.json`* file. This configuration name is a unique, friendly name that makes it easier for you to identify these settings in the **Configuration** dropdown.
63
67
64
68
The **Toolset** dropdown will be set to **msvc_arm64_x64**. Your settings should now look something like this:
> In the **Toolset** dropdown, **msvc_arm64**uses 32-bit host tools to cross-compile to ARM64, whereas **msvc_arm64 x64**uses 64-bit host tools to cross-compile to ARM64--which is what you will do in this tutorial.
73
+
> In the **Toolset** dropdown, **msvc_arm64**selects 32-bit host tools to cross-compile to ARM64, whereas **msvc_arm64 x64**selects 64-bit host tools to cross-compile to ARM64--which is what you will do in this tutorial.
70
74
71
-
Save the `CMakeSettings.json` file and ensure that your **arm64-debug**configuration is selected in the configuration dropdown:
75
+
Save the `CMakeSettings.json` file. In the configuration dropdown, select **arm64-debug**(it may take a moment after saving the `CMakeSettings.json` file for it to appear in the list):
72
76
73
77
74
78
@@ -80,34 +84,34 @@ Change the **Solution Explorer** view to targets view by selecting the **Switch
80
84
81
85
82
86
83
-
Then double-click **CMake Targets View**. The**CMake Targets View**appears.
87
+
Then, in the **Solution Explorer**, double-click**CMake Targets View**to see the project.
84
88
85
-
In the **Solution Explorer**, open the project folder, **CMakeProject3 Project**, this example, and then right-click the executable and select **Add Debug Configuration**:
89
+
Open the project folder (in this example, **CMakeProject3 Project**), and then right-click the executable and select **Add Debug Configuration**:
This creates a `launch.vs.json` file in your project. Open it and change the following entries to enable remote debugging:
90
94
91
-
-`projectTarget` : this is set for you if you added the debug configuration file from the **Solution Explorer** targets view.
95
+
-`projectTarget` : this is set for you if you added the debug configuration file from the **Solution Explorer** targets view per the instructions above.
92
96
-`remoteMachineName` : set to the IP address of the remote ARM64 machine, or its machine name.
93
97
94
-
For more information about these, and other `launch.vs.json` settings, see [launch.vs.json schema reference](launch-vs-schema-reference-cpp.md).
98
+
For more information about `launch.vs.json` settings, see [launch.vs.json schema reference](launch-vs-schema-reference-cpp.md).
95
99
96
100
> [!Note]
97
101
> If you are using the folder view instead of the targets view in **Solution Explorer**, right-click the `CMakeLists.txt` file and select **Add Debug Configuration**. This experience differs from adding the debug configuration from the targets view in the following ways:
98
-
> - You'll be asked to select a debugger (select **C/C++ Remote Windows Debug** in this case).
99
-
> - Visual Studio will provide less configuration template information in the `launch.vs.json` file so you'll need to add it yourself, such as the `remoteMachineName` and `projectTarget` entries. Alternatively, when you add the configuration from the targets view, you only need to specify `remoteMachineName`.
100
-
> - For the `projectTarget` setting value, check the startup item dropdown to get the unique name of your target, for example, `CMakeProject3.exe', in this tutorial.
102
+
> - You'll be asked to select a debugger (select **C/C++ Remote Windows Debug**).
103
+
> - Visual Studio will provide less configuration template information in the `launch.vs.json` file so you'll need to add it yourself. You'll need to provide the `remoteMachineName` and `projectTarget` entries. When you add the configuration from the targets view, you only need to specify `remoteMachineName`.
104
+
> - For the `projectTarget` setting value, check the startup item dropdown to get the unique name of your target, for example, in this tutorial it is `CMakeProject3.exe'.
101
105
102
106
## Start the remote debugger monitor on the remote Windows machine
103
107
104
108
Before you run your CMake project, ensure that the Visual Studio 2019 remote debugger is running on the remote Windows machine. You may need to change the remote debugger options depending on your authentication situation.
105
109
106
-
From the Visual Studio Remote Debugger menu bar, select **Tools** > **Options**. Then set authentication to match how your environment is set up:
110
+
For example, on the remote machine, from the Visual Studio Remote Debugger menu bar, select **Tools** > **Options**. Set the **authentication mode** to match how your environment is set up:
If you choose **No Authentication**, update the `launch.vs.json` file in your project by adding **"windowsAuthenticationType": "Remote Windows with No authentication"** to the `configurations` section `launch.vs.json`. Otherwise, `"windowsAuthenticationType"` defaults to `"Remote Windows authentication"` and doesn't need to be explicitly stated. For example:
114
+
Then, in Visual Studio on the host machine, update the `launch.vs.json` file to match. For example, if you choose **No Authentication** on the remote debugger, update the `launch.vs.json` file in your project by adding **"windowsAuthenticationType": "Remote Windows with No authentication"** to the `configurations` section `launch.vs.json`. Otherwise, `"windowsAuthenticationType"` defaults to `"Remote Windows authentication"` and doesn't need to be explicitly stated. This example is the `launch.vs.json` file, configured for no authentication:
111
115
112
116
```XAML
113
117
{
@@ -141,7 +145,7 @@ If you choose **No Authentication**, update the `launch.vs.json` file in your pr
141
145
142
146
On the host machine, in the Visual Studio **Solution Explorer**, open the CPP file for your CMake project. If you're still in **CMake Targets View**, you'll need to open the **(executable)** node to see it.
143
147
144
-
The default CPP file is a simple hello world console app. Set a breakpoint on `return 0;` so that the program doesn't quickly run and close on the remote machine.
148
+
The default CPP file is a simple hello world console app. Set a breakpoint on `return 0;` so that the program doesn't close on the remote machine.
145
149
146
150
On the Visual Studio toolbar, use the **Startup Item** dropdown to select the name you specified for `"name"` in your `launch.vs.json` file:
147
151
@@ -155,6 +159,7 @@ If it doesn't start, ensure that the following are set correctly in the `launch.
155
159
-`"projectTarget"` should match the name of the CMake target you want to debug.
156
160
-`"type"` should be `"remoteWindows"`
157
161
- If the authentication type on the remote debugger is set to **No Authentication**, you should have `"windowsAuthenticationType": "Remote Windows with No authentication"` set in the `launch.vs.json` file.
162
+
- If you are using Windows authentication, sign in when prompted using an account recognized by the remote machine.
158
163
159
164
After the project builds, the app should appear on the remote ARM64 Windows machine:
Copy file name to clipboardExpand all lines: docs/build/launch-vs-schema-reference-cpp.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -69,7 +69,7 @@ Used when debugging and deploying an app on a remote machine.
69
69
|`deployRuntimeLibraries`|string|Specifies to deploy the runtime libraries for the active platform. Defaults to `"true"` if the active configurationType is `"MinSizeRel"`, `"RelWithDebInfo"`, or `"Release"`.|
70
70
|`disableDeploy`| boolean | Specifies whether any files should be deployed. |
71
71
|`remoteMachineName`|string|Specifies the name of the remote ARM64 Windows machine where the program is launched. May be the server name or the remote machine's IP address|
72
-
|`windowsAuthenticationType`|string|Specifies the type of remote connection. Possible values are `"Remote Windows authentication"` and `"Remote Windows with No authentication"`. The default is `"Remote Windows authentication"`. This should match the authentication setting specified on the remote debugger running on the remote macihne.|
72
+
|`windowsAuthenticationType`|string|Specifies the type of remote connection. Possible values are `"Remote Windows authentication"` and `"Remote Windows with No authentication"`. The default is `"Remote Windows authentication"`. This should match the authentication setting specified on the remote debugger running on the remote machine.|
0 commit comments