Skip to content

Commit b22ae9d

Browse files
author
mikeblome
committed
edits per tech review by Erika
1 parent f0570fa commit b22ae9d

10 files changed

+156
-30
lines changed

‎docs/linux/cmake-linux-project.md‎

Lines changed: 17 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
2-
title: "Configure a Linux CMake project in Visual Studio"
3-
description: "How to configure, edit and compile a Linux CMake project in Visual Studio"
2+
title: "Create and configure a Linux CMake project in Visual Studio"
3+
description: "How to create, configure, edit and compile a Linux CMake project in Visual Studio"
44
ms.date: "06/07/2019"
55
ms.assetid: f8707b32-f90d-494d-ae0b-1d44425fdc25
66
---
@@ -13,7 +13,18 @@ Linux support is available in Visual Studio 2017 and later.
1313

1414
::: moniker-end
1515

16-
When you open a folder that contains a CMake project, Visual Studio uses the metadata that CMake produces to configure IntelliSense and builds automatically. Local configuration and debugging settings are stored in JSON files that can optionally be shared with others who are using Visual Studio.
16+
::: moniker range="vs-2019"
17+
18+
To create a new Linux CMake project in Visual Studio 2019:
19+
20+
1. Select **File > New Project** in Visual Studio, or press **Ctrl + Shift + N**.
21+
1. Set the **Language** to **C++** and search for "CMake". Then choose **Next**. Enter a **Name** and **Location**, and choose **Create**.
22+
23+
Visual Studio creates a minimal CMakeLists.txt file with only the name of the executable and the minimum CMake version required. You can manually edit this file however you like; Visual Studio will never overwrite your changes. You can specify CMake command-line arguments and environment variables by right-clicking on the CMakeLists.txt file in **Solution Explorer** and choosing **CMake settings for project**. To specify options for debugging, right-click on the project node and choose **Debug and launch settings**.
24+
25+
::: moniker-end
26+
27+
When you open a folder that contains an existing CMake project, Visual Studio uses the metadata that CMake produces to configure IntelliSense and builds automatically. Local configuration and debugging settings are stored in JSON files that can optionally be shared with others who are using Visual Studio.
1728

1829
Visual Studio does not modify the CMakeLists.txt files or the original CMake cache, so that others working on the same project can continue to use whatever tools they are already using.
1930

@@ -69,13 +80,13 @@ add_executable(hello-cmake hello.cpp)
6980

7081
## Choose a Linux target
7182

72-
As soon as you open the folder, Visual Studio parses the CMakeLists.txt file and specifies a Windows target of **x86-Debug**. To target a remote Linux system, change the project settings to **Linux-Debug** or **Linux-Release**.
83+
As soon as you open the folder, Visual Studio parses the CMakeLists.txt file and specifies a Windows target of **x86-Debug**. To target a remote Linux system, change the project settings to **Linux-Debug** or **Linux-Release**. (See [Configure CMake settings for Linux](#configure_cmake_linux) below.)
7384

7485
::: moniker range="vs-2019"
7586

7687
To target Windows Subsystem for Linux, choose **WSL-Debug** or **WSL-Release** if using GCC, or the Clang variants if using the Clang/LLVM toolset.
7788

78-
**Visual Studio 2019 version 16.1** When targeting WSL, no copying or sources or headers is necessary because the compiler on Linux has direct access to the Windows file system where your source files are located, and Visual Studio likewise can access the Linux header files directly.
89+
**Visual Studio 2019 version 16.1** When targeting WSL, no copying or sources or headers is necessary because the compiler on Linux has direct access to the Windows file system where your source files are located. (In Windows version 1903 and later, Windows applications likewise can access the Linux header files directly, but Visual Studio does not yet take advantage of this capability).
7990

8091
::: moniker-end
8192

@@ -95,7 +106,7 @@ To debug your code on the specified debug target system, set a breakpoint, selec
95106

96107
To customize your program’s command line arguments, right-click on the executable in **Solution Explorer** and select **Debug and Launch Settings**. This opens or creates a launch.vs.json configuration file that contains information about your program. To specify additional arguments, add them in the `args` JSON array. For more information, see [Open Folder projects for C++](../build/open-folder-projects-cpp.md) and [Configure CMake debugging sessions](../build/configure-cmake-debugging-sessions.md).
97108

98-
## Configure CMake settings for Linux
109+
## <a name="configure_cmake_linux"></a> Configure CMake settings for Linux
99110

100111
A CMakeSettings.json file in a CMake Linux project can specify all the properties listed in [Customize CMake settings](../build/customize-cmake-settings.md), plus additional properties that control the build settings on the remote Linux machine.
101112

‎docs/linux/configure-a-linux-project.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: "Configure a C++ Linux project in Visual Studio"
3-
ms.date: "06/07/2019"
3+
ms.date: "06/11/2019"
44
ms.assetid: 4d7c6adf-54b9-4b23-bd23-5de0c825b768
55
---
66
# Configure a Linux project
@@ -31,7 +31,7 @@ To view configuration options, select the **Project > Properties** menu, or righ
3131

3232
![General configuration](media/settings_general.png)
3333

34-
By default, an executable (.out) is built with the tool. To build a static or dynamic library, or to use an existing Makefile, use the **Configuration Type** setting.
34+
By default, an executable (.out) is built. To build a static or dynamic library, or to use an existing Makefile, use the **Configuration Type** setting.
3535

3636
For more information about the settings in the property pages, see [Linux Project Property Page Reference](prop-pages-linux.md).
3737

‎docs/linux/connect-to-your-remote-linux-computer.md‎

Lines changed: 50 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,27 @@
11
---
2-
title: "Connect to your remote Linux computer in Visual Studio"
3-
description: "How to connect to a remote Linux machine from inside a Visual Studio C++ project."
4-
ms.date: "06/07/2019"
2+
title: "Connect to your target Linux system in Visual Studio"
3+
description: "How to connect to a remote Linux machine or WSL from inside a Visual Studio C++ project."
4+
ms.date: "06/11/2019"
55
ms.assetid: 5eeaa683-4e63-4c46-99ef-2d5f294040d4
66
---
77

8-
# Connect to your remote Linux computer
8+
# Connect to your target Linux system in Visual Studio
99

1010
::: moniker range="vs-2015"
1111

1212
Linux support is available in Visual Studio 2017 and later.
1313

1414
::: moniker-end
1515

16-
::: moniker range="vs-2019"
16+
::: moniker range=">=vs-2017"
1717

18-
When you target Windows Subsystem for Linux (WSL) Visual Studio interacts with your Linux distro directly through the file system; no remote connection is necessary.
18+
You can configure a Linux project to target a remote machine or to Windows Subsystem for Linux (WSL).
1919

20-
::: moniker-end
20+
## Connect to a remote Linux computer
21+
22+
When building a C++ Linux project for a remote Linux system (VM or physical machine), Linux code is copied to your remote Linux computer and then compiled based on Visual Studio settings. (In Visual Studio 2017, use these instructions to connect to WSL also. Use **localhost** for the **Host Name**.)
2123

22-
When building a C++ Linux project for a remote Linux system (VM or physical machine), Linux code is copied to your remote Linux computer and then compiled based on Visual Studio settings. To set up this remote connection:
24+
To set up this remote connection:
2325

2426
1. Build the project for the first time or manually create a new entry by selecting **Tools > Options** and then open the **Cross Platform > Connection Manager** node and click the **Add** button.
2527

@@ -41,6 +43,44 @@ When building a C++ Linux project for a remote Linux system (VM or physical mach
4143
| **Private key file** | Private key file created for ssh connection
4244
| **Passphrase** | Passphrase used with private key selected above
4345

44-
1. Click the **Connect** button to attempt a connection to the remote computer. If the connection fails, the entry boxes which need to be changed will be outlined in red.
46+
1. Click the **Connect** button to attempt a connection to the remote computer.
47+
48+
If the connection succeeds, Visual Studio will begin configuring IntelliSense to use the remote headers. For more information, see [IntelliSense for headers on remote systems](configure-a-linux-project.md#remote_intellisense).
49+
50+
If the connection fails, the entry boxes which need to be changed will be outlined in red.
51+
52+
![Connection Manager Error](media/settings_connectionmanagererror.png)
53+
54+
::: moniker range="vs-2019"
55+
56+
Go to **Tools > Options > Cross Platform > Logging** to enable logging to help troubleshoot connection problems:
57+
58+
![Remote Logging](media/remote-logging-vs2019.png)
59+
60+
Logs include connections, all commands sent to the remote machine (their text, exit code and execution time), and all writes from Visual Studio to the shell. Logging works for any cross-platform CMake project or MSBuild-based Linux project in Visual Studio.
61+
62+
You can configure the output to go to a file or to the **Cross Platform Logging** pane in the Output Window. For MSBuild-based Linux projects, commands issued to the remote machine by MSBuild are not routed to the **Output Window** because they are emitted out-of-process. Instead, they are logged to a file with the "msbuild_" prefix.
63+
64+
## Connect to WSL
65+
66+
In Visual Studio 2019 version 16.1, it is not necessary to add a remote connection or configure SSH when targeting WSL. All that is required on the Linux system is gcc, gdb, make, rsync, and zip. Visual Studio requires rsync and zip only to extract header files on first use from your WSL instance to the Windows filesystem to use for IntelliSense. In Visual Studio 2019 version 16.1, WSL support is based on Windows version 1809. You can be running a later version of Windows, but Visual Studio does not yet take advantage of new WSL capabilities.
67+
68+
If your distro supports apt, you can install the required packages with this command:
69+
70+
```bash
71+
sudo apt install g++ gdb make rsync zip
72+
```
73+
74+
To configure your project for WSL, see [Configure a Linux project](configure-a-linux-project.md) or [Configure a Linux CMake project](cmake-linux-project.md) depending on which kind of project you have.
75+
76+
::: moniker-end
77+
78+
## See Also
79+
80+
[Configure a Linux project](configure-a-linux-project.md)
81+
[Configure a Linux CMake project](cmake-linux-project.md)
82+
[Deply, run and debug your Linux project](deploy-run-and-debug-your-linux-project.md)
83+
84+
85+
4586

46-
![Connection Manager Error](media/settings_connectionmanagererror.png)

‎docs/linux/create-a-new-linux-project.md‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: "Create a new C++ Linux project in Visual Studio"
3-
ms.date: "06/07/2019"
3+
ms.date: "06/11/2019"
44
ms.assetid: 5d7c1d67-bc31-4f96-8622-2b4cf91372fd
55
---
66

@@ -14,7 +14,7 @@ Linux projects are available in Visual Studio 2017 and later.
1414

1515
First, make sure you have the **Linux Development Workload** for Visual Studio installed. For more information, see [Download, install, and setup the Linux workload](download-install-and-setup-the-linux-development-workload.md).
1616

17-
When you create a new C++ project for Linux in Visual Studio, you can choose to create a Visual Studio project or a CMake project. This article describes how to create a Visual Studio project. For information about how to create and work with existing CMake Projects, see [Configure a Linux CMake Project ](cmake-linux-project.md).
17+
When you create a new C++ project for Linux in Visual Studio, you can choose to create a Visual Studio project or a CMake project. This article describes how to create a Visual Studio project. For information about how to create and work with existing CMake Projects, see [Create and configure a Linux CMake Project ](cmake-linux-project.md).
1818

1919
## To create a new Linux project
2020

@@ -45,6 +45,12 @@ To create a new Linux project in Visual Studio, follow these steps:
4545
| **Empty Project (Linux)** | Project targeted for any Linux computer, with no sample code |
4646
| **Makefile Project (Linux)** | Project targeted for any Linux computer, built using a standard Makefile build system |
4747

48+
::: moniker range="vs-2019"
49+
50+
Visual Studio 2019 enables you to create a new CMake project. For more information, see [Create and configure a Linux CMake Project ](cmake-linux-project.md).
51+
52+
::: moniker-end
53+
4854
## Next Steps
4955

5056
[Configure a Linux project](configure-a-linux-project.md)

‎docs/linux/deploy-run-and-debug-your-linux-project.md‎

Lines changed: 73 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ Once you have created a Linux C++ project in Visual Studio and you have connecte
1616

1717
::: moniker range="vs-2019"
1818

19-
**Visual Studio 2019 version 16.1** You can target different Linux systems for debugging and building. Specify the build machine on the **General** property page and the debug machine on the **Debugging** property page.
19+
**Visual Studio 2019 version 16.1** 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](#separate_build_debug) later in this article.
2020

2121
::: moniker-end
2222

@@ -29,8 +29,6 @@ There are several ways to interact with and debug your Linux project.
2929
## Debug your Linux project
3030

3131
1. Select debugging mode in the **Debugging** property page.
32-
33-
3432

3533
::: moniker range="vs-2019"
3634

@@ -88,16 +86,20 @@ There are several ways to interact with and debug your Linux project.
8886

8987
![Linux Console window](media/consolewindow.png)
9088

91-
## Configure other debugging options
89+
## Configure other debugging options (MSBuild-based projects)
9290

9391
- Command-line arguments can be passed to the executable using the **Program Arguments** item in the project's **Debugging** property page.
9492

9593
![Program Arguments](media/settings_programarguments.png)
9694

97-
- 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:
95+
- 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:
9896

9997
`handle SIGILL nostop noprint`
10098

99+
## Configure other debugging options (CMake projects)
100+
101+
You can specify additional command-line arguments for a CMake project in the launch.vs.json file. For more information, see [Debug the CMake project](cmake-linux-project.md#debug_cmake_project)
102+
101103
## Debug with Attach to Process
102104

103105
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 additional 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:
@@ -119,6 +121,72 @@ ExePath="C:\temp\ConsoleApplication17\ConsoleApplication17\bin\x64\Debug\Console
119121

120122
The **AttachOptionsForConnection** has most of the attributes you might need. The example above shows how to specify a location to search for additional .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.
121123

124+
::: moniker range="vs-2019"
125+
126+
## <a name="separate_build_debug"></a> Specify different machines for building and debugging
127+
128+
In Visual Studio 2019 version 16.1 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.
129+
130+
### MSBuild-based projects
131+
132+
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**.
133+
134+
![Linux remote debug machine](media/linux-remote-debug-machine.png)
135+
136+
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**).
137+
138+
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 will see a preview of its File Properties directly below the Solution Explorer.
139+
140+
![Linux deployable files](media/linux-deployable-content.png)
141+
142+
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.
143+
144+
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 ordirectory. In these cases, append the following code block(s) to your .vcxproj file and replace "example.cpp" with the actual file names:
145+
146+
```xml
147+
148+
<ItemGroup>
149+
<RemoteDeploy Include="__example.cpp">
150+
<!-- This is the source Linux machine, can be empty if DeploymentType is LocalRemote -->
151+
<SourceMachine>$(RemoteTarget)</SourceMachine>
152+
<TargetMachine>$(RemoteDebuggingTarget)</TargetMachine>
153+
<SourcePath>~/example.cpp</SourcePath>
154+
<TargetPath>~/example.cpp</TargetPath>
155+
<!-- DeploymentType can be LocalRemote, in which case SourceMachine will be empty and SourcePath is a local file on Windows -->
156+
<DeploymentType>RemoteRemote</DeploymentType>
157+
<!-- Indicates whether the deployment contains executables -->
158+
<Executable>true</Executable>
159+
</RemoteDeploy>
160+
</ItemGroup>
161+
```
162+
163+
### CMake projects
164+
165+
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.
166+
167+
![CMake remote debug machine](media/cmake-remote-debug-machine.png)
168+
169+
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**.
170+
171+
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:
172+
173+
```json
174+
175+
"disableDeploy": false,
176+
"deployDirectory": "~\foo",
177+
"deploy" : [
178+
{
179+
"sourceMachine": "127.0.0.1 (username=example1, port=22, authentication=Password)",
180+
"targetMachine": "192.0.0.1 (username=example2, port=22, authentication=Password)",
181+
"sourcePath": "~/example.cpp",
182+
"targetPath": "~/example.cpp",
183+
"executable": "false"
184+
}
185+
]
186+
187+
```
188+
::: moniker-end
189+
122190
## Next steps
123191

124192
- To debug ARM devices on Linux, see this blog post: [Debugging an embedded ARM device in Visual Studio](https://blogs.msdn.microsoft.com/vcblog/2018/01/10/debugging-an-embedded-arm-device-in-visual-studio/).

0 commit comments

Comments
 (0)