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/linux/deploy-run-and-debug-your-linux-project.md
+35-38Lines changed: 35 additions & 38 deletions
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,7 @@
1
1
---
2
2
title: "Deploy, run, and debug your Linux MSBuild C++ project in Visual Studio"
3
3
description: "Describes how to compile, execute, and debug code on the remote target from inside a MSBuild-based Linux C++ project in Visual Studio."
4
-
ms.date: "08/08/2020"
4
+
ms.date: 12/5/2024
5
5
ms.custom: intro-deployment
6
6
---
7
7
# Deploy, run, and debug your Linux MSBuild project
@@ -33,72 +33,67 @@ There are several ways to interact with and debug your Linux project.
33
33
GDB is used to debug applications running on Linux. When debugging on a remote system (not WSL) GDB can run in two different modes, which can be selected from the **Debugging Mode** option in the project's **Debugging** property page:
34
34
35
35
36
+
37
+
::: moniker-end
36
38
37
-
::: moniker-end
39
+
::: moniker range="msvc-150"
38
40
39
-
::: moniker range="msvc-150"
40
-
41
-
GDB is used to debug applications running on Linux. GDB can run in two different modes, which can be selected from the **Debugging Mode** option in the project's **Debugging** property page:
41
+
GDB is used to debug applications running on Linux. GDB can run in two different modes, which can be selected from the **Debugging Mode** option in the project's **Debugging** property page:
42
42
43
43
44
+
45
+
::: moniker-end
44
46
45
-
::: moniker-end
46
-
47
-
- In **gdbserver** mode, GDB is run locally, which connects to gdbserver on the remote system.
47
+
- In **gdbserver** mode, GDB is run locally, which connects to gdbserver on the remote system. To use this, you must provide a local Windows path to GDB under **Debugger Path** in **Visual Studio 2022 version 17.6** and later, or under **GDB Path** in **Visual Studio 2019 version 16.11** and earlier. For more information about where to provide the path to GDB for CMake projects, see [Additional options allowed with the gdbserver configuration (16.7 or later)](../build/configure-cmake-debugging-sessions.md#additional-options-allowed-with-the-gdbserver-configuration-167-or-later).
48
48
49
49
- In **gdb** mode, the Visual Studio debugger drives GDB on the remote system. This is a better option if the local version of GDB isn't compatible with the version installed on the target computer. This is the only mode that the Linux Console window supports.
50
50
51
-
> [!NOTE]
52
-
> If you are unable to hit breakpoints in gdbserver debugging mode, try gdb mode. gdb must first be [installed](download-install-and-setup-the-linux-development-workload.md) on the remote target.
51
+
> [!NOTE]
52
+
> If you are unable to hit breakpoints in gdbserver debugging mode, try gdb mode. gdb must first be [installed](download-install-and-setup-the-linux-development-workload.md) on the remote target.
53
53
54
54
1. Select the remote target using the standard **Debug** toolbar in Visual Studio.
55
55
56
-
When the remote target is available, you'll see it listed by either name or IP address.
56
+
When the remote target is available, you see it listed by name or IP address:
57
57
58
58
59
-
60
-
If you haven't connected to the remote target yet, you'll see an instruction to use [Linux Connection Manager](connect-to-your-remote-linux-computer.md) to connect to the remote target.
59
+
60
+
If you haven't connected to the remote target yet, you see instructions to use [Linux Connection Manager](connect-to-your-remote-linux-computer.md) to connect to the remote target:
61
61
62
62
63
-
64
-
1. Set a breakpoint by clicking in the left gutter of some code that you know will execute.
65
-
66
-
A red dot appears on the line of code where you set the breakpoint.
63
+
64
+
1. Set a breakpoint by clicking in the left gutter of some code that you know will execute. A red dot appears on the line of code where you set the breakpoint.
When you start debugging, the application is compiled on the remote target before it starts. Any compilation errors will appear in the **Error List** window.
68
+
When you start debugging, the application is compiled on the remote target before it starts. Any compilation errors appear in the **Error List** window.
71
69
72
-
If there are no errors, the app will start and the debugger will pause at the breakpoint.
70
+
If there are no errors, the app starts and the debugger pauses at the breakpoint:
73
71
74
72
75
-
76
-
Now, you can interact with the application in its current state, view variables, and step through code by pressing command keys such as **F10** or **F11**.
73
+
74
+
Now, you can interact with the application in its current state, view variables, and step through code by pressing command keys such as **F10** or **F11**.
77
75
78
76
1. If you want to use the Linux Console to interact with your app, select **Debug > Linux Console**.
79
77
80
78
81
-
82
-
This console will display any console output from the target computer and take input and send it to the target computer.
79
+
80
+
This console displays console output from the target computer and takes input and sends it to the target computer.
83
81
84
82
85
-
83
+
86
84
## Configure other debugging options (MSBuild projects)
87
85
88
86
- Command-line arguments can be passed to the executable using the **Program Arguments** item in the project's **Debugging** property page.
89
87
- You can export the `DISPLAY` environment variable by using the **Pre-Launch Command** in the project's **Debugging** property pages. For example: `export DISPLAY=:0.0`
90
88
91
89
92
-
93
-
- Specific debugger options can be passed to GDB using the **Additional Debugger Commands** entry. For example, you might want to ignore SIGILL (illegal instruction) signals. You could use the **handle** command to achieve this by adding the following to the **Additional Debugger Commands** entry as shown above:
94
-
95
-
`handle SIGILL nostop noprint`
96
-
97
-
- You can specify the path to the GDB used by Visual Studio using the **GDB Path** item in the project's **Debugging** property page. This property is available in Visual Studio 2019 version 16.9 and later.
90
+
91
+
- Specific debugger options can be passed to GDB using the **Additional Debugger Commands** entry. For example, you might want to ignore SIGILL (illegal instruction) signals. You could use the **handle** command to achieve this by adding the following to the **Additional Debugger Commands** entry shown above: `handle SIGILL nostop noprint`.
92
+
- Specify the path to the GDB used by Visual Studio using the **GDB Path** item in the project's **Debugging** property page. This property is available in Visual Studio 2019 version 16.9 and later.
98
93
99
94
## Debug with Attach to Process
100
95
101
-
The [Debugging](prop-pages/debugging-linux.md) property page for Visual Studio projects, and the **Launch.vs.json** settings for CMake projects, have settings that enable you to attach to a running process. If you require more control beyond what is provided in those settings, you can place a file named `Microsoft.MIEngine.Options.xml` in the root of your solution or workspace. Here is a simple example:
96
+
The [Debugging](prop-pages/debugging-linux.md) property page for Visual Studio projects, and the **Launch.vs.json** settings for CMake projects, have settings that enable you to attach to a running process. If you require more control beyond what is provided in those settings, you can place a file named `Microsoft.MIEngine.Options.xml` in the root of your solution or workspace. Here's a simple example:
The **AttachOptionsForConnection** has most of the attributes you might need. The example above shows how to specify a location to search for more .so libraries. The child element **ServerOptions** enables attaching to the remote process with gdbserver instead. To do that, you need to specify a local gdb client (the one shipped in Visual Studio 2017 is shown above) and a local copy of the binary with symbols. The **SetupCommands** element enables you to pass commands directly to gdb. You can find all the options available in the [LaunchOptions.xsd schema](https://github.com/Microsoft/MIEngine/blob/master/src/MICore/LaunchOptions.xsd) on GitHub.
113
+
The **AttachOptionsForConnection** has most of the attributes you might need. The example above shows how to specify a location to search for more `.so` libraries. The child element **ServerOptions** enables attaching to the remote process with gdbserver instead. To do that, you need to specify a local gdb client (the one shipped in Visual Studio 2017 is shown above) and a local copy of the binary with symbols. The **SetupCommands** element enables you to pass commands directly to gdb. You can find all the options available in the [LaunchOptions.xsd schema](https://github.com/Microsoft/MIEngine/blob/master/src/MICore/LaunchOptions.xsd) on GitHub.
119
114
120
115
::: moniker range=">=msvc-160"
121
116
122
117
## <aname="separate_build_debug"></a> Specify different machines for building and debugging in MSBuild-based Linux projects
123
118
124
119
You can separate your remote build machine from your remote debug machine for both MSBuild-based Linux projects and CMake projects that target a remote Linux machine. For example, you can now cross-compile on x64 and deploy to an ARM device when targeting IoT scenarios.
125
120
126
-
By default, the remote debug machine is the same as the remote build machine (**Configuration Properties** > **General** > **Remote Build Machine**). To specify a new remote debug machine, right-click on the project in **Solution Explorer** and go to **Configuration Properties** > **Debugging** > **Remote Debug Machine**.
121
+
By default, the remote debug machine is the same as the remote build machine (**Configuration Properties** > **General** > **Remote Build Machine**). To specify a new remote debug machine, right-click on the project in **Solution Explorer** and go to **Configuration Properties** > **Debugging** > **Remote Debug Machine**:
127
122
128
123
129
124
130
-
The drop-down menu for **Remote Debug Machine** is populated with all established remote connections. To add a new remote connection, navigate to **Tools** > **Options** > **Cross Platform** > **Connection Manager** or search for "Connection Manager" in **Quick Launch**. You can also specify a new remote deploy directory in the project's Property Pages (**Configuration Properties** > **General** > **Remote Deploy Directory**).
125
+
The drop-down menu for **Remote Debug Machine** is populated with all established remote connections.
126
+
127
+
To add a new remote connection, navigate to **Tools** > **Options** > **Cross Platform** > **Connection Manager** or search for "Connection Manager" in **Quick Launch**. You can also specify a new remote deploy directory in the project's Property Pages (**Configuration Properties** > **General** > **Remote Deploy Directory**).
131
128
132
-
By default, only the files necessary for the process to debug will be deployed to the remote debug machine. You can use **Solution Explorer** to configure which source files will be deployed to the remote debug machine. When you click on a source file, you'll see a preview of its File Properties directly below the Solution Explorer.
129
+
By default, only the files necessary for the process to debug are deployed to the remote debug machine. You can use **Solution Explorer** to configure which source files are deployed to the remote debug machine. When you click on a source file, you see a preview of its File Properties directly below the Solution Explorer:
133
130
134
131
135
132
@@ -156,11 +153,11 @@ In some cases, you may require more control over your project's deployment. For
156
153
157
154
### CMake projects
158
155
159
-
For CMake projects that target a remote Linux machine, you can specify a new remote debug machine in launch.vs.json. By default, the value of "remoteMachineName" is synchronized with the "remoteMachineName" property in CMakeSettings.json, which corresponds to your remote build machine. These properties no longer need to match, and the value of "remoteMachineName" in launch.vs.json will dictate which remote machine is used for deploy and debug.
156
+
For CMake projects that target a remote Linux machine, you can specify a new remote debug machine in launch.vs.json. By default, the value of `"remoteMachineName"` is synchronized with the `"remoteMachineName"` property in `CMakeSettings.json`, which corresponds to your remote build machine. These properties no longer need to match, and the value of `"remoteMachineName"` in `launch.vs.json` dictate which remote machine is used for deploy and debug.
160
157
161
158
162
159
163
-
IntelliSense will suggest all a list of all established remote connections. You can add a new remote connection by navigating to **Tools** > **Options** > **Cross Platform** > **Connection Manager** or searching for "Connection Manager" in **Quick Launch**.
160
+
IntelliSense suggests a list of all established remote connections. You can add a new remote connection by navigating to **Tools** > **Options** > **Cross Platform** > **Connection Manager** or searching for "Connection Manager" in **Quick Launch**.
164
161
165
162
If you want complete control over your deployment, you can append the following code block(s) to the launch.vs.json file. Remember to replace the placeholder values with real values:
166
163
@@ -186,4 +183,4 @@ If you want complete control over your deployment, you can append the following
![learn-build-service-prod[bot]](https://avatars.githubusercontent.com/in/237442?v=4&size=40){kind=avatar}
0 commit comments