Skip to content

Commit 4e68093

Browse files
ttorblettorble
authored
Merge pull request #3030 from TylerMSFT/twhitney-cmakelinux
Twhitney cmakelinux
2 parents 43abb6d + aece87f commit 4e68093

7 files changed

+215
-217
lines changed

‎docs/build/media/vs2019-choose-console-app.png

5.48 KB
Loading

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

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
---
2+
title: "Configure a Linux CMake project in Visual Studio"
3+
description: "How to configure Linux CMake settings in Visual Studio"
4+
ms.date: "08/08/2020"
5+
---
6+
# Configure a Linux CMake project in Visual Studio
7+
8+
::: moniker range="vs-2015"
9+
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**.
10+
::: moniker-end
11+
12+
::: moniker range=">=vs-2017"
13+
This topic describes how to add a Linux configuration to a CMake project that targets either a remote Linux system or Windows Subsystem for Linux (WSL). It continues the series that began with [Create a Linux CMake project in Visual Studio](cmake-linux-project.md). If you are using MSBuild, instead, see [Configure a Linux MSBuild Project in Visual Studio](configure-a-linux-project.md)
14+
15+
## Add a Linux configuration
16+
17+
A configuration can be used to target different platforms (Windows, WSL, a remote system) with the same source code. A configuration is also used to set your compilers, pass environment variables, and customize how CMake is invoked. The *CMakeSettings.json* file specifies some or all of 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.
18+
::: moniker-end
19+
20+
::: 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 *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).
22+
23+
The default configuration for Linux-Debug in Visual Studio 2017 (and Visual Studio 2019 version 16.0) looks like this:
24+
25+
```json
26+
{
27+
"name": "Linux-Debug",
28+
"generator": "Unix Makefiles",
29+
"remoteMachineName": "${defaultRemoteMachineName}",
30+
"configurationType": "Debug",
31+
"remoteCMakeListsRoot": "/var/tmp/src/${workspaceHash}/${name}",
32+
"cmakeExecutable": "/usr/local/bin/cmake",
33+
"buildRoot": "${env.LOCALAPPDATA}\\CMakeBuilds\\${workspaceHash}\\build\\${name}",
34+
"installRoot": "${env.LOCALAPPDATA}\\CMakeBuilds\\${workspaceHash}\\install\\${name}",
35+
"remoteBuildRoot": "/var/tmp/build/${workspaceHash}/build/${name}",
36+
"remoteInstallRoot": "/var/tmp/build/${workspaceHash}/install/${name}",
37+
"remoteCopySources": true,
38+
"remoteCopySourcesOutputVerbosity": "Normal",
39+
"remoteCopySourcesConcurrentCopies": "10",
40+
"remoteCopySourcesMethod": "rsync",
41+
"remoteCopySourcesExclusionList": [".vs", ".git"],
42+
"rsyncCommandArgs" : "-t --delete --delete-excluded",
43+
"remoteCopyBuildOutput" : "false",
44+
"cmakeCommandArgs": "",
45+
"buildCommandArgs": "",
46+
"ctestCommandArgs": "",
47+
"inheritEnvironments": [ "linux-x64" ]
48+
}
49+
```
50+
::: moniker-end
51+
52+
::: moniker range="vs-2019"
53+
To change the default CMake settings in Visual Studio 2019, from the main toolbar, open the **Configuration** dropdown and choose **Manage Configurations**.
54+
55+
![CMake Manage Configurations](../build/media/vs2019-cmake-manage-configurations.png "CMake configurations drop-down")
56+
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).
58+
59+
The default Linux-Debug configuration in Visual Studio 2019 version 16.1, and later, looks like this:
60+
61+
```json
62+
{
63+
"name": "Linux-Debug",
64+
"generator": "Unix Makefiles",
65+
"configurationType": "Debug",
66+
"cmakeExecutable": "/usr/bin/cmake",
67+
"remoteCopySourcesExclusionList": [ ".vs", ".git", "out" ],
68+
"cmakeCommandArgs": "",
69+
"buildCommandArgs": "",
70+
"ctestCommandArgs": "",
71+
"inheritEnvironments": [ "linux_x64" ],
72+
"remoteMachineName": "${defaultRemoteMachineName}",
73+
"remoteCMakeListsRoot": "$HOME/.vs/${projectDirName}/${workspaceHash}/src",
74+
"remoteBuildRoot": "$HOME/.vs/${projectDirName}/${workspaceHash}/out/build/${name}",
75+
"remoteInstallRoot": "$HOME/.vs/${projectDirName}/${workspaceHash}/out/install/${name}",
76+
"remoteCopySources": true,
77+
"rsyncCommandArgs": "-t --delete --delete-excluded",
78+
"remoteCopyBuildOutput": false,
79+
"remoteCopySourcesMethod": "rsync",
80+
"addressSanitizerRuntimeFlags": "detect_leaks=0",
81+
"variables": []
82+
}
83+
]
84+
}
85+
```
86+
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+
89+
::: moniker-end
90+
::: moniker range=">=vs-2017"
91+
For more information about these settings, see [CMakeSettings.json reference](../build/cmakesettings-reference.md).
92+
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+
## Choose a Linux target
98+
99+
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**.
100+
101+
If you specify a remote Linux target, your source is copied to the remote system.
102+
103+
After you select a target, CMake runs automatically on the Linux system to generate the CMake cache for your project:
104+
105+
![Generate CMake cache on Linux](media/cmake-linux-1.png "Generate the CMake cache on Linux")
106+
107+
::: moniker-end
108+
::: moniker range="vs-2019"
109+
110+
### Target Windows Subsystem for Linux
111+
112+
If you're targeting Windows Subsystem for Linux (WSL), you don't need to add a remote connection.
113+
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.
117+
::: moniker-end
118+
::: moniker range=">=vs-2017"
119+
120+
### IntelliSense
121+
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).
123+
124+
### Locale setting
125+
126+
Visual Studio language settings aren't propagated to Linux targets because Visual Studio doesn't manage or configure installed packages. Messages shown in the Output window, such as build errors, are shown using the language and locale of the Linux target. You'll need to configure your Linux targets for the desired locale.
127+
128+
## Additional settings
129+
130+
Use the following settings to run commands on the Linux system before and after building, and before CMake generation. The values can be any command that is valid on the remote system. The output is piped back to Visual Studio.
131+
132+
```json
133+
{
134+
"remotePrebuildCommand": "",
135+
"remotePreGenerateCommand": "",
136+
"remotePostbuildCommand": "",
137+
}
138+
```
139+
140+
## Next steps
141+
142+
[Configure CMake debugging sessions](../build/configure-cmake-debugging-sessions.md)
143+
144+
## See also
145+
146+
[Working with project properties](../build/working-with-project-properties.md)<br/>
147+
[Customize CMake settings](../build/customize-cmake-settings.md)<br/>
148+
[CMake predefined configuration reference](../build/cmake-predefined-configuration-reference.md)
149+
150+
::: moniker-end

0 commit comments

Comments
 (0)