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
+30-26Lines changed: 30 additions & 26 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,12 +2,12 @@
2
2
title: "Tutorial: Run and debug a CMake project on a remote machine"
3
3
ms.date: "11/20/2020"
4
4
ms.topic: tutorial
5
-
description: "How to use Visual Studio C++ on Windows to create and build a CMake project than you can deploy and debug on an ARM64 device."
5
+
description: "How to use Visual Studio C++ on Windows to create and build a CMake project that you can deploy and debug on a remote ARM64 Windows machine."
6
6
---
7
7
8
8
# Tutorial: Run and debug a CMake project on a remote machine
9
9
10
-
This tutorial shows how to use Visual Studio C++ on Windows to create and build a CMake project than you can deploy and debug on an ARM64 device. The steps can be generalized to deploy and debug a CMake project that doesn't target ARM64.
10
+
This tutorial shows how to use Visual Studio C++ on Windows to create and build a CMake project than you can deploy and debug on a remote ARM64 Windows machine. The steps can be generalized to deploy and debug a CMake project that doesn't target ARM64.
11
11
12
12
This tutorial focuses on ARM64 because the default debugging experience for ARM64 is remote debugging. Attempting to debug ARM64 without configuring your CMake project as shown in this tutorial will result in an error that VS can't find the remote machine.
13
13
@@ -17,25 +17,28 @@ In this tutorial, you'll learn how to:
17
17
>
18
18
> * create a CMake project
19
19
> * configure a CMake project to build for ARM64
20
-
> * configure a CMake project to run on a remote ARM64 device
21
-
> * debug a CMake project running on a remote ARM64 device
20
+
> * configure a CMake project to run on a remote ARM64 Windows machine
21
+
> * debug a CMake project running on a remote ARM64 Windows machine
22
22
23
23
## Prerequisites
24
24
25
25
### On the host machine
26
26
27
-
Set up Visual Studio for cross-platform C++ development by installing the ARM64 build tools:
27
+
To set up Visual Studio for cross-platform C++ development, install the ARM64 build tools:
28
28
29
-
Todo! VS installer > Modify > Individual Components
30
-
In the **Compilers, build tools, and runtimes** section install
31
-
C++ ARM64 build tools (v14.28)
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?view=vs-2019#:~: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).
31
+
1. From the choices at the top, choose **Individual components**.
32
+
1. Scroll down to the **Compilers, build tools, and runtimes** section.
33
+
1. Ensure that the following are selected:
34
+
-**C++ Cmake tools for Windows**
35
+
-**MSVC v142 - VS 2019 C++ ARM64 build tools (v14.28)** (choose the latest version)
36
+
1. Select **Modify** to install the tools.
32
37
33
38
### On the remote machine
34
39
35
-
Install the remote debugging tools on the remote machine.
36
-
37
-
ToDo! This tutorial targets ARM64, so install the ARM64 version of the Visual Studio 2019 remote debugging tools.
38
-
[link to download](https://visualstudio.microsoft.com/downloads/#remote-tools-for-visual-studio-2019)
40
+
1. Install the ARM64 remote tools on the remote machine as described in [Download and Install the remote tools](https://docs.microsoft.com/visualstudio/debugger/remote-debugging-cpp?view=vs-2019&viewFallbackFrom=vs-2019%23download-and-install-the-remote-tools#download-and-install-the-remote-tools)
41
+
1. Follow the directions in [set up the remote debugger](https://docs.microsoft.com/visualstudio/debugger/remote-debugging-cpp?view=vs-2019&viewFallbackFrom=vs-2019%23download-and-install-the-remote-tools#BKMK_setup) on the remote ARM64 machine.
39
42
40
43
## Create a CMake project
41
44
@@ -46,7 +49,7 @@ Give Visual Studio a few moments to create the project and populate the **Soluti
46
49
47
50
## Change the configuration to target ARM64
48
51
49
-
Because you are targeting an ARM64 device, you need to use the ARM64 build tools. To select the ARM64 build tools, select the Visual Studio **Configuration** dropdown and select **Manage Configurations...**
52
+
Because you are targeting an ARM64 Windows machine, you need to use the ARM64 build tools. To select the ARM64 build tools, select the Visual Studio **Configuration** dropdown and select **Manage Configurations...**
50
53
51
54
52
55
@@ -59,6 +62,11 @@ Select the **Toolset** dropdown and from the list of build tools, choose **msvc_
59
62
> [!Note]
60
63
> In the **Toolset** dropdown, **msvc_arm64** builds for 64-bit ARM, and **msvc_arm64 x64** uses the 64-bit host tools to cross-compile for ARM64--which is what you will do in this tutorial.
61
64
65
+
Save the `CMakeSettings.json` file and ensure that your **arm64-debug** configuration is selected in the configuration dropdown:
66
+
67
+
68
+
69
+
62
70
## Add a debug configuration file
63
71
64
72
Next, add configuration information that tells Visual Studio where to find your remote machine, and other configuration details.
@@ -75,10 +83,10 @@ In the **Solution Explorer**, right-click the executable and select **Add Debug
75
83
76
84
This creates a `launch.vs.json` file in your project. Open it and change the following entries to enable remote debugging:
77
85
78
-
-`projectTarget` : set to the name of your executable; for example, `CMakeProject3`
86
+
-`projectTarget` : set to the name of your target, for example, `CMakeProject3.exe` You can check the
79
87
-`remoteMachineName` : set to the IP address of the remote ARM64 machine, or its machine name.
80
88
81
-
## Start the remote debugger monitor on the ARM64 device
89
+
## Start the remote debugger monitor on the ARM64 Windows machine
82
90
83
91
Before you run your CMake project, ensure that the Visual Studio 2019 remote debugger is running on the remote ARM64 machine. You may need to change the remote debugger options depending on your authentication situation.
84
92
@@ -98,7 +106,7 @@ If you choose **No Authentication**, update the `launch.vs.json` file in your pr
98
106
"windowsAuthenticationType": "Remote Windows with No authentication"
99
107
"name": "CMakeLists.txt",
100
108
"project": "CMakeLists.txt",
101
-
"projectTarget": "CMakeProject1",
109
+
"projectTarget": "CMakeProject3.exe",
102
110
"remoteMachineName": "<ip address goes here>",
103
111
"cwd": "${debugInfo.defaultWorkingDirectory}",
104
112
"program": "${debugInfo.fullTargetPath}",
@@ -126,28 +134,24 @@ The default CPP file is a simple hello world console app. Set a breakpoint on `r
126
134
127
135
On the Visual Studio toolbar, use the startup item dropdown to change the startup item to match the name you specified for `"name"` in the `launch.vs.json` file:
128
136
129
-
137
+
130
138
131
139
To start debugging, on the VS toolbar choose **Debug** > **Start Debugging** (or press **F5**).
132
140
133
141
If it doesn't start, ensure that the following are set correctly in the `launch.vs.json` file:
134
-
-`"remoteMachineName"` should be set to the IP address, or machine name, of the remote ARM64 device.
142
+
-`"remoteMachineName"` should be set to the IP address, or machine name, of the remote ARM64 Windows machine.
135
143
-`"name"` should match the selection in the VS startup item dropdown.
136
-
-`"projectTarget"` should be set to the name of the executable file.
137
-
-`"type"` should be set to `"remoteWindows"`
144
+
-`"projectTarget"` should match the name of the executable file.
145
+
-`"type"` should be `"remoteWindows"`
138
146
- 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.
139
147
140
148
After the project builds, the app should appear on the remote ARM64 machine:
143
151
144
152
## What you learned
145
153
146
-
In this tutorial, you created a CMake project, configured it to build for ARM64 and to run on a remote machine. Then you built, ran, and debugged it on a remote ARM64 device.
147
-
148
-
## Target other platforms.
149
-
150
-
154
+
In this tutorial, you created a CMake project, configured it to build for ARM64 and to run on a remote machine. Then you built, ran, and debugged it on a remote ARM64 Windows machine.
0 commit comments