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
+37-33Lines changed: 37 additions & 33 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,53 +2,55 @@
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 setup, run, and debug a CMake project on a remote machine"
5
+
description: "How to set up, run, and debug a CMake project on a remote 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 for C++ on Windows to create and build a CMake project on x86 Windows, and then deploy it to run on an ARM device. In this tutorial, you'll deploy and run on an ARM device, but you could just as easily deploy and run on a Linux or other Windows device.
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 ARM device. The steps can be generalized to deploy and debug a CMake project on a remote Windows device.
11
11
12
-
In this tutorial, you learn how to:
12
+
In this tutorial, you'll learn how to:
13
13
14
14
> [!div class="checklist"]
15
15
>
16
16
> * create a CMake project
17
-
> * configure it to build for ARM
18
-
> * configure debugging for a remote ARM device
19
-
> *build and debug the target on a remote ARM device
17
+
> * configure a CMake project to build for ARM
18
+
> * configure a CMake project to run on a remote ARM device
19
+
> *debug a CMake project running on a remote ARM device
20
20
21
21
## Prerequisites
22
22
23
23
### On the host machine
24
24
25
-
Setup Visual Studio for cross-platform C++ development by installing the ARM build tools:
25
+
Set up Visual Studio for cross-platform C++ development by installing the ARM build tools:
26
26
27
-
VS installer > Modify > Individual Components
27
+
Todo! VS installer > Modify > Individual Components
28
28
In the **Compilers, build tools, and runtimes** section install
29
29
C++ ARM64 build tools (v14.28)
30
30
31
-
### On the target machine
31
+
### On the remote machine
32
32
33
-
Install the remote debugging tools on the remote machine. This tutorial targets ARM, so install the ARM version of the Visual Studio 2019 remote debugging tools.
33
+
Install the remote debugging tools on the remote machine.
34
+
35
+
ToDo! This tutorial targets ARM, so install the ARM version of the Visual Studio 2019 remote debugging tools.
34
36
[link to download](https://visualstudio.microsoft.com/downloads/#remote-tools-for-visual-studio-2019)
35
37
36
38
## Create a CMake project
37
39
38
40
On the Windows host machine, run Visual Studio and choose **Create new project** > **CMake Project** > **Next**
39
41
Give the project a name and choose a location. Then select **Create**.
40
42
41
-
Give Visual Studio a few moments to create the project and populate the Solution Explorer.
43
+
Give Visual Studio a few moments to create the project and populate the **Solution Explorer**.
42
44
43
45
## Change the configuration to target ARM
44
46
45
-
In the **Configuration** dropdown, choose**Manage Configurations...**
47
+
Because you are targeting an ARM device, you need to use the ARM build tools. To select the ARM build tools, select the Visual Studio **Configuration** dropdown and select**Manage Configurations...**
@@ -57,30 +59,32 @@ Change the **Toolset** dropdown to **msvc_arm64_x64**. Your settings should look
57
59
58
60
## Add a debug configuration file
59
61
60
-
To configure the project to debug remotely on another machine, first change the **Solution Explorer** view to targets view by selecting the **Switch Views** button in the **Solution Explorer**:
62
+
Next, add configuration information that tells Visual Studio where to find your remote machine, and other configuration details.
63
+
64
+
Change the **Solution Explorer** view to targets view by selecting the **Switch Views** button:
61
65
62
66
63
67
64
68
Then double-click **CMake Targets View**. The **CMake Targets View** appears.
65
69
66
-
In the **Solution Explorer**, right-click the executable and select **Add Debug Configuration**.
70
+
In the **Solution Explorer**, right-click the executable and select **Add Debug Configuration**:
67
71
68
-
This creates a `launch.vs.json` file. Change the following entries to enable remote debugging:
74
+
This creates a `launch.vs.json` file in your project. Open it and change the following entries to enable remote debugging:
71
75
72
-
`projectTarget` : set to the name of your executable, for example, `CMakeProject1`
73
-
`remoteMachineName` : set to either the IP address, or the machine name, of your remote ARM machine or ARM virtual machine.
76
+
-`projectTarget` : set to the name of your executable; for example, `CMakeProject3`
77
+
-`remoteMachineName` : set to the IP address of the remote ARM machine, or its machine name.
74
78
75
79
## Start the remote debugger monitor on the ARM device
76
80
77
-
Before you run your CMake project, ensure that the Visual Studio 2019 remote debugger is running on the remote ARM machine. You may need to change the options depending on your authentication situation.
81
+
Before you run your CMake project, ensure that the Visual Studio 2019 remote debugger is running on the remote ARM machine. You may need to change the remote debugger options depending on your authentication situation.
78
82
79
-
From the VS Remote Debugger, set authentication to match how your environment is setup:
83
+
From the VS Remote Debugger menu bar, select **Tools** > **Options**. Then set authentication to match how your environment is set up:
If you choose **No Authentication**, in the `launch.vs.json` file, add**"windowsAuthenticationType": "Remote Windows with No authentication"** to the `configurations` section `launch.vs.json`. For example:
87
+
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`. For example:
84
88
85
89
```XAML
86
90
{
@@ -114,22 +118,22 @@ Otherwise, `"windowsAuthenticationType"` defaults to `"Remote Windows authentica
114
118
115
119
## Debug the app
116
120
117
-
In the **Solution Explorer**, open the CPP file. If you are still in **CMake Targets View**, you'll need to open the **(executable)** node to see it.
121
+
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.
118
122
119
-
The default CPP file is a simple hello world console app. Set a breakpoint on the `return 0;` line so that the program doesn't quickly run and close on the remote machine.
123
+
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.
120
124
121
125
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:
122
126
123
127
124
128
125
-
From the VS toolbar, choose **Debug** > **Start Debugging** (or press **F5**)
129
+
To start debugging, on the VS toolbar choose **Debug** > **Start Debugging** (or press **F5**).
126
130
127
-
If it doesn't start, ensure that the following are set correctly in the launch.vs.json file:
128
-
-`"remoteMachineName"` set to the IP address or name of the remote machine
129
-
-`"name"`is what your startup item in Visual Studio is set to
130
-
-`"projectTarget"`is set to the name of the executable
131
-
-`"type"`is set to `"remoteWindows"`
132
-
- If your authentication type on the remote debugger is set to **No Authentication**, that you have `"windowsAuthenticationType": "Remote Windows with No authentication"` set in the `launch.vs.json` file.
131
+
If it doesn't start, ensure that the following are set correctly in the `launch.vs.json` file:
132
+
-`"remoteMachineName"`should be set to the IP address, or machine name, of the remote ARM device.
133
+
-`"name"`should match the selection in the VS startup item dropdown.
134
+
-`"projectTarget"`should be set to the name of the executable file.
135
+
-`"type"`should be set to `"remoteWindows"`
136
+
- 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.
133
137
134
138
After the project builds, the app should appear on the remote ARM machine:
0 commit comments