Deploy, run, and debug your Linux MSBuild project Linux support is available in Visual Studio 2017 and later. To see the documentation for these versions, set the Version drop-down located above the table of contents to Visual Studio 2017 or Visual Studio 2019 .
Once you’ve created a MSBuild-based Linux C++ project in Visual Studio and you’ve connected to the project using the Linux Connection Manager, you can run and debug the project. You compile, execute, and debug the code on the remote target.
Visual Studio 2019 version 16.1 and later: You can target different Linux systems for debugging and building. For example, you can cross-compile on x64 and deploy to an ARM device when targeting IoT scenarios. For more information, see Specify different machines for building and debugging later in this article.
There are several ways to interact with and debug your Linux project.
Debug using traditional Visual Studio features, such as breakpoints, watch windows, and hovering over a variable. Using these methods, you may debug as you normally would for other project types. View output from the target computer in the Linux Console window. You can also use the console to send input to the target computer. Debug your Linux project 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. Press F5 (or Debug > Start Debugging ) to start debugging. 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. If there are no errors, the app will start and the debugger will pause at the breakpoint. F10 or F11 . If you want to use the Linux Console to interact with your app, select Debug > Linux Console .
Command-line arguments can be passed to the executable using the Program Arguments item in the project’s Debugging property page. 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 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: handle SIGILL nostop noprint 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. Debug with Attach to Process The Debugging 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:
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 on GitHub.
Specify different machines for building and debugging in MSBuild-based Linux projects 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.
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 .
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 ).
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.
The Content property specifies whether the file will be deployed to the remote debug machine. You can disable deployment entirely by navigating to Property Pages > Configuration Manager and unchecking Deploy for the desired configuration.
In some cases, you may require more control over your project’s deployment. For example, some files that you want to deploy might be outside of your solution or you want to customize your remote deploy directory per file or directory. In these cases, append the following code block(s) to your .vcxproj file and replace «example.cpp» with the actual file names:
$(RemoteTarget) $(RemoteDebuggingTarget) ~/example.cpp ~/example.cpp RemoteRemote true CMake projects 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.
Next steps Create a Linux MSBuild C++ project in Visual Studio Linux projects are available in Visual Studio 2017 and later.
First, make sure you have the Linux Development Workload for Visual Studio installed. For more information, see Download, install, and setup the Linux workload.
For cross-platform compilation, we recommend using CMake. CMake support is more complete in Visual Studio 2019. If CMake isn’t an option, and you have an existing Windows Visual Studio solution that you would like to extend to compile for Linux, you can add a Visual Studio Linux project to the Windows solution, along with a Shared Items project. Put the code that is shared between both platforms in the Shared Items project, and add a reference to that project from the Windows and Linux projects.
To create a new Linux project To create a new Linux project in Visual Studio 2017, follow these steps:
Select File > New Project in Visual Studio, or press Ctrl + Shift + N . Select the Visual C++ > Cross Platform > Linux node, and then select the project type to create. Enter a Name and Location , and choose OK .
