Skip to content

Commit fb13037

Browse files
Tyler WhitneyTyler Whitney
Tyler Whitney
authored and
Tyler Whitney
committed
address tech feedback
1 parent 737116f commit fb13037

5 files changed

+34
-31
lines changed

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

+19-19
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ A configuration can be used to target different platforms (Windows, WSL, a remot
1818
::: moniker-end
1919

2020
::: moniker range="vs-2017"
21-
To change the default CMake settings in Visual Studio 2017, choose **CMake** > **Change CMake Settings** > **CMakeLists.txt** from the main menu. Or, right-click *CMakeSettings.txt* in **Solution Explorer** and choose **Change CMake Settings**. Visual Studio then creates a new *CMakeSettings.json* file in your root project folder. To make changes, open the file and modify it directly. For more information, see [Customize CMake settings](../build/customize-cmake-settings.md).
21+
To change the default CMake settings in Visual Studio 2017, choose **CMake** > **Change CMake Settings** > **CMakeLists.txt** from the main menu. Or, right-click *CMakeLists.txt* in **Solution Explorer** and choose **Change CMake Settings**. Visual Studio then creates a new *CMakeSettings.json* file in your root project folder. To make changes, open the file and modify it directly. For more information, see [Customize CMake settings](../build/customize-cmake-settings.md).
2222

2323
The default configuration for Linux-Debug in Visual Studio 2017 (and Visual Studio 2019 version 16.0) looks like this:
2424

@@ -54,7 +54,7 @@ To change the default CMake settings in Visual Studio 2019, from the main toolba
5454

5555
![CMake Manage Configurations](../build/media/vs2019-cmake-manage-configurations.png "CMake configurations drop-down")
5656

57-
This command opens the **CMake Settings Editor**, which you can use to edit the *CMakeSettings.json* file in your root project folder. You can also open the file directly by clicking the **Edit JSON** button in the editor. For more information, see [Customize CMake Settings](../build/customize-cmake-settings.md).
57+
This command opens the **CMake Settings Editor**, which you can use to edit the *CMakeSettings.json* file in your root project folder. You can also open the file with the JSON editor by clicking the **Edit JSON** button in the editor. For more information, see [Customize CMake Settings](../build/customize-cmake-settings.md).
5858

5959
The default Linux-Debug configuration in Visual Studio 2019 version 16.1, and later, looks like this:
6060

@@ -84,10 +84,22 @@ The default Linux-Debug configuration in Visual Studio 2019 version 16.1, and la
8484
}
8585
```
8686

87+
In Visual Studio 2019 version 16.6 or later, Ninja is the default generator for configurations targeting a remote system or WSL. For more information, see this post on the [C++ Team Blog](https://devblogs.microsoft.com/cppblog/linux-development-with-visual-studio-first-class-support-for-gdbserver-improved-build-times-with-ninja-and-updates-to-the-connection-manager/).
88+
8789
::: moniker-end
8890
::: moniker range=">=vs-2017"
8991
For more information about these settings, see [CMakeSettings.json reference](../build/cmakesettings-reference.md).
9092

93+
When you do a build:
94+
- If you're targeting a remote system, Visual Studio chooses the first remote system in the list under **Tools** > **Options** > **Cross Platform** > **Connection Manager** by default for remote targets.
95+
- If no remote connections are found, you're prompted to create one. For more information, see [Connect to your remote Linux computer](connect-to-your-remote-linux-computer.md).
96+
97+
If you specify a remote Linux target, your source is copied to the remote system.
98+
99+
After you select a target, CMake runs automatically on the Linux system to generate the CMake cache for your project:
100+
101+
![Generate CMake cache on Linux](media/cmake-linux-1.png "Generate the CMake cache on Linux")
102+
91103
## Choose a Linux target
92104

93105
When you open a CMake project folder, Visual Studio parses the *CMakeLists.txt* file and specifies a Windows target of **x86-Debug**. To target a remote Linux system, you'll change the project settings to **Linux-Debug** or **Linux-Release**.
@@ -97,29 +109,17 @@ When you open a CMake project folder, Visual Studio parses the *CMakeLists.txt*
97109

98110
### Target Windows Subsystem for Linux
99111

100-
To target Windows Subsystem for Linux (WSL), select **Manage Configurations** in the configuration dropdown in the main toolbar. Then press the **Add Configuration** button and choose **WSL-Debug** or **WSL-Release** if using GCC. Use the Clang variants if using the Clang/LLVM toolset.
112+
If you're targeting Windows Subsystem for Linux (WSL), you don't need to add a remote connection.
101113

102-
**Visual Studio 2019 version 16.1** When you target WSL, you don't need to copy sources or headers because the compiler on Linux has direct access to your source files in the Windows file system. (In Windows 10 version 1903 and later, Windows applications likewise can access the Linux header files directly. Visual Studio doesn't take advantage of this capability yet.)
114+
To target WSL, select **Manage Configurations** in the configuration dropdown in the main toolbar. Then press the **Add Configuration** button and choose **WSL-Debug** or **WSL-Release** if using GCC. Use the Clang variants if using the Clang/LLVM toolset.
115+
116+
**Visual Studio 2019 version 16.1** When you target WSL, Visual Studio doesn't need to copy source files and maintain two synchronous copies of your build tree because the compiler on Linux has direct access to your source files in the mounted Windows file system.
103117
::: moniker-end
104118
::: moniker range=">=vs-2017"
105119

106-
### Add a remote connection
107-
108-
If you're targeting WSL, you don't need to add a remote connection.
109-
110-
If you're targeting a remote system, Visual Studio chooses the first remote system in the list under **Tools** > **Options** > **Cross Platform** > **Connection Manager** by default for remote targets.
111-
112-
If no remote connections are found, you're prompted to create one. For more information, see [Connect to your remote Linux computer](connect-to-your-remote-linux-computer.md).
113-
114-
If you specify a remote Linux target, your source is copied to the remote system.
115-
116-
After you select a target, CMake runs automatically on the Linux system to generate the CMake cache for your project:
117-
118-
![Generate CMake cache on Linux](media/cmake-linux-1.png "Generate the CMake cache on Linux")
119-
120120
### IntelliSense
121121

122-
Accurate C++ IntelliSense requires access to the C++ headers referenced by your C++ source files. Visual Studio automatically copies the headers referenced by a CMake project from Linux to Windows to provide a full-fidelity IntelliSense experience. For more information, see [IntelliSense for remote headers](configure-a-linux-project.md#remote_intellisense).
122+
Accurate C++ IntelliSense requires access to the C++ headers referenced by your C++ source files. Visual Studio automatically uses the headers referenced by a CMake project from Linux to Windows to provide a full-fidelity IntelliSense experience. For more information, see [IntelliSense for remote headers](configure-a-linux-project.md#remote_intellisense).
123123

124124
### Locale setting
125125

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

+10-4
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ Linux support is available in Visual Studio 2017 and later. To see the documenta
1414

1515
::: moniker range=">=vs-2017"
1616

17-
We recommend you use CMake for projects that are cross-platform or you think you might make open-source. You can use CMake projects to build and debug the same source code on Windows, the Windows Subsystem for Linux (WSL), and remote systems.
17+
We recommend you use CMake for projects that are cross-platform or will be open-source. You can use CMake projects to build and debug the same source code on Windows, the Windows Subsystem for Linux (WSL), and remote systems.
1818

1919
## Before you begin
2020

@@ -40,7 +40,7 @@ Visual Studio 2017 can't create a CMake project from scratch, but you can open a
4040
::: moniker range=">=vs-2019"
4141
You can use Visual Studio 2019 to build and debug on a remote Linux system or WSL, and CMake will be invoked on that system. Cmake version 3.14 or later should be installed on the target machine.
4242

43-
Linux support for CMake projects requires that the target machine has a recent version of CMake. Often, the version offered by a distribution's default package manager isn't recent enough to support all the features required by Visual Studio. Visual Studio 2019 detects whether a recent version of CMake is installed on the Linux system. If none is found, Visual Studio shows an info-bar at the top of the editor pane. It offers to install CMake for you from [https://github.com/Microsoft/CMake/releases](https://github.com/Microsoft/CMake/releases).
43+
Make sure that the target machine has a recent version of CMake. Often, the version offered by a distribution's default package manager isn't recent enough to support all the features required by Visual Studio. Visual Studio 2019 detects whether a recent version of CMake is installed on the Linux system. If none is found, Visual Studio shows an info-bar at the top of the editor pane. It offers to install CMake for you from [https://github.com/Microsoft/CMake/releases](https://github.com/Microsoft/CMake/releases).
4444

4545
With Visual Studio 2019, you can create a CMake project from scratch, or open an existing CMake project. To create a new CMake project, follow the instructions below. Or skip ahead to [Open a CMake project folder](#open-a-cmake-project-folder) if you already have a CMake project.
4646

@@ -51,9 +51,15 @@ To create a new Linux CMake project in Visual Studio 2019:
5151
1. Select **File > New Project** in Visual Studio, or press **Ctrl + Shift + N**.
5252
1. Set the **Language** to **C++** and search for "CMake". Then choose **Next**. Enter a **Name** and **Location**, and choose **Create**.
5353

54-
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 in this file. Right-click on the root *CMakeLists.txt* file in **Solution Explorer** and choose **CMake settings for project**.
55-
5654
Alternatively, you can open your own CMake project in Visual Studio 2019. The following section explains how.
55+
56+
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.
57+
58+
To help you make sense of, edit, and author your CMake scripts in Visual Studio 2019, refer to the following resources:
59+
60+
- [In-editor documentation for CMake in Visual Studio](https://devblogs.microsoft.com/cppblog/in-editor-documentation-for-cmake-in-visual-studio/)
61+
- [Code navigation for CMake scripts](https://devblogs.microsoft.com/cppblog/code-navigation-for-cmake-scripts/)
62+
- [Easily Add, Remove, and Rename Files and Targets in CMake Projects](https://devblogs.microsoft.com/cppblog/easily-add-remove-and-rename-files-and-targets-in-cmake-projects/)
5763
::: moniker-end
5864

5965
::: moniker range=">=vs-2017"

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

+1-1
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ Linux support is available in Visual Studio 2017 and later.
1212

1313
::: moniker-end
1414

15-
This topic describes how to add a Linux configuration to a MSBuild project as described in [Create a Linux MSBuild C++ project in Visual Studio](create-a-new-linux-project.md). For Linux CMake projects, see [Configure a Linux CMake project](cmake-linux-project.md).
15+
This topic describes how to configure a MSBuild-based Linux project as described in [Create a Linux MSBuild C++ project in Visual Studio](create-a-new-linux-project.md). For Linux CMake projects, see [Configure a Linux CMake project](cmake-linux-project.md).
1616

1717
You can configure a Linux project to target a physical Linux machine, a virtual machine, or the [Windows Subsystem for Linux](/windows/wsl/about) (WSL).
1818

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

+2-7
Original file line numberDiff line numberDiff line change
@@ -88,17 +88,14 @@ There are several ways to interact with and debug your Linux project.
8888
## Configure other debugging options (MSBuild projects)
8989

9090
- Command-line arguments can be passed to the executable using the **Program Arguments** item in the project's **Debugging** property page.
91+
- 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`
9192

9293
![Program Arguments](media/settings_programarguments.png)
9394

9495
- 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:
9596

9697
`handle SIGILL nostop noprint`
9798

98-
## Configure other debugging options (CMake projects)
99-
100-
You can specify additional command-line arguments for a CMake project in the launch.vs.json file. [Configure CMake debugging sessions](../build/configure-cmake-debugging-sessions.md#launchvsjson-reference).
101-
10299
## Debug with Attach to Process
103100

104101
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:
@@ -122,12 +119,10 @@ The **AttachOptionsForConnection** has most of the attributes you might need. Th
122119

123120
::: moniker range="vs-2019"
124121

125-
## <a name="separate_build_debug"></a> Specify different machines for building and debugging
122+
## <a name="separate_build_debug"></a> Specify different machines for building and debugging in MSBuild-based Linux projects
126123

127124
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.
128125

129-
### MSBuild projects
130-
131126
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**.
132127

133128
![Linux remote debug machine](media/linux-remote-debug-machine.png)

‎docs/linux/toc.yml

+2
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,8 @@
4848
href: ../linux/cmake-linux-project.md
4949
- name: Configure a Linux CMake project
5050
href: ../linux/cmake-linux-configure.md
51+
- name: Configure CMake debugging sessions
52+
href: ../build/configure-cmake-debugging-sessions.md
5153
- name: "Tutorial: Create C++ cross-platform projects in Visual Studio"
5254
href: ../build/get-started-linux-cmake.md
5355
- name: Configure Linux projects to use Address Sanitizer

0 commit comments

Comments
 (0)