Skip to content

Commit 9551976

Browse files
Tyler WhitneyTyler Whitney
Tyler Whitney
authored and
Tyler Whitney
committed
refactoring doc
1 parent 20ec300 commit 9551976

4 files changed

Lines changed: 230 additions & 162 deletions

File tree

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

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
---
2+
title: "Configure CMake settings for Linux in Visual Studio"
3+
description: "How to configure Linux CMake project in Visual Studio"
4+
ms.date: "07/23/2020"
5+
---
6+
# Configure CMake settings for Linux 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 Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page.
10+
::: moniker-end
11+
12+
::: moniker range=">=vs-2017"
13+
This topic describes how to configure a C++ Linux project as described in [Create a Linux CMake project in Visual Studio](cmake-linux-project.md). For MSBuild Linux projects, see [Configure a Linux Project](configure-a-linux-project.md)
14+
15+
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.
16+
::: moniker-end
17+
18+
::: moniker range="vs-2019"
19+
To change the default CMake settings in Visual Studio 2019, from the main toolbar, open the **Configuration** dropdown and choose **Manage Configurations**.
20+
21+
![CMake Manage Configurations](../build/media/vs2019-cmake-manage-configurations.png "CMake configurations drop-down")
22+
23+
This command brings up 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).
24+
25+
The the default Linux-Debug configuration in Visual Studio 2019 version 16.1 and later is shown here:
26+
27+
```json
28+
{
29+
"name": "Linux-Debug",
30+
"generator": "Unix Makefiles",
31+
"configurationType": "Debug",
32+
"cmakeExecutable": "/usr/bin/cmake",
33+
"remoteCopySourcesExclusionList": [ ".vs", ".git", "out" ],
34+
"cmakeCommandArgs": "",
35+
"buildCommandArgs": "",
36+
"ctestCommandArgs": "",
37+
"inheritEnvironments": [ "linux_x64" ],
38+
"remoteMachineName": "${defaultRemoteMachineName}",
39+
"remoteCMakeListsRoot": "$HOME/.vs/${projectDirName}/${workspaceHash}/src",
40+
"remoteBuildRoot": "$HOME/.vs/${projectDirName}/${workspaceHash}/out/build/${name}",
41+
"remoteInstallRoot": "$HOME/.vs/${projectDirName}/${workspaceHash}/out/install/${name}",
42+
"remoteCopySources": true,
43+
"rsyncCommandArgs": "-t --delete --delete-excluded",
44+
"remoteCopyBuildOutput": false,
45+
"remoteCopySourcesMethod": "rsync",
46+
"addressSanitizerRuntimeFlags": "detect_leaks=0",
47+
"variables": []
48+
}
49+
]
50+
}
51+
```
52+
::: moniker-end
53+
::: moniker range="vs-2017"
54+
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. You can open the file using the **CMake Settings** editor or modify the file directly. For more information, see [Customize CMake settings](../build/customize-cmake-settings.md).
55+
56+
Given the following code and CMakeLists.txt file:
57+
58+
```cpp
59+
// hello.cpp
60+
61+
#include <iostream>
62+
63+
int main(int argc, char* argv[])
64+
{
65+
std::cout << "Hello from Linux CMake" << std::endl;
66+
}
67+
```
68+
69+
*CMakeLists.txt*:
70+
71+
```txt
72+
cmake_minimum_required(VERSION 3.8)
73+
project (hello-cmake)
74+
add_executable(hello-cmake hello.cpp)
75+
```
76+
77+
You would see something like this default configuration for Linux-Debug in Visual Studio 2017 (and Visual Studio 2019 version 16.0):
78+
79+
```json
80+
{
81+
"name": "Linux-Debug",
82+
"generator": "Unix Makefiles",
83+
"remoteMachineName": "${defaultRemoteMachineName}",
84+
"configurationType": "Debug",
85+
"remoteCMakeListsRoot": "/var/tmp/src/${workspaceHash}/${name}",
86+
"cmakeExecutable": "/usr/local/bin/cmake",
87+
"buildRoot": "${env.LOCALAPPDATA}\\CMakeBuilds\\${workspaceHash}\\build\\${name}",
88+
"installRoot": "${env.LOCALAPPDATA}\\CMakeBuilds\\${workspaceHash}\\install\\${name}",
89+
"remoteBuildRoot": "/var/tmp/build/${workspaceHash}/build/${name}",
90+
"remoteInstallRoot": "/var/tmp/build/${workspaceHash}/install/${name}",
91+
"remoteCopySources": true,
92+
"remoteCopySourcesOutputVerbosity": "Normal",
93+
"remoteCopySourcesConcurrentCopies": "10",
94+
"remoteCopySourcesMethod": "rsync",
95+
"remoteCopySourcesExclusionList": [".vs", ".git"],
96+
"rsyncCommandArgs" : "-t --delete --delete-excluded",
97+
"remoteCopyBuildOutput" : "false",
98+
"cmakeCommandArgs": "",
99+
"buildCommandArgs": "",
100+
"ctestCommandArgs": "",
101+
"inheritEnvironments": [ "linux-x64" ]
102+
}
103+
```
104+
105+
::: moniker-end
106+
::: moniker range=">=vs-2017"
107+
For more information about these settings, see [CMakeSettings.json reference](../build/cmakesettings-reference.md).
108+
109+
## Optional Settings
110+
111+
You can use the following optional settings for more control:
112+
113+
```json
114+
{
115+
"remotePrebuildCommand": "",
116+
"remotePreGenerateCommand": "",
117+
"remotePostbuildCommand": "",
118+
}
119+
```
120+
121+
These options allow you 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.
122+
123+
## Next step
124+
125+
[Debug a CMake Linux project](cmake-linux-debug.md)
126+
127+
## See also
128+
129+
[Working with Project Properties](../build/working-with-project-properties.md)<br/>
130+
[CMake Projects in Visual Studio](../build/cmake-projects-in-visual-studio.md)<br/>
131+
[Connect to your remote Linux computer](connect-to-your-remote-linux-computer.md)<br/>
132+
[Customize CMake settings](../build/customize-cmake-settings.md)
133+
<br/>
134+
[CMake predefined configuration reference](../build/cmake-predefined-configuration-reference.md)
135+
::: moniker-end

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

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
---
2+
title: "Debug a CMake Linux project in Visual Studio"
3+
description: "How to debug a Linux CMake project in Visual Studio"
4+
ms.date: "07/23/2020"
5+
---
6+
# Debug a CMake Linux 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 later versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page.
10+
::: moniker-end
11+
12+
::: moniker range=">=vs-2017"
13+
This topic describes how to debug a C++ Linux project as described in [Create a Linux CMake project in Visual Studio](cmake-linux-project.md).
14+
15+
Once you have created or opened a Linux C++ CMake project, you can compile, execute, and debug the code on the remote target.
16+
17+
(For MSBuild Linux projects, see [Deploy, run, and debug your Linux project](deploy-run-and-debug-your-linux-project.md))
18+
19+
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**.
20+
21+
## Choose a Linux target
22+
23+
::: moniker-end
24+
::: moniker range="vs-2019"
25+
### Windows Subsystem for Linux
26+
27+
If you are targeting 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.
28+
29+
**Visual Studio 2019 version 16.1** When targeting WSL, no copying of sources or headers is necessary. That's 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.)
30+
::: moniker-end
31+
32+
::: moniker range=">=vs-2017"
33+
### Add a remote connection
34+
35+
If you are targeting Windows Subsystem for Linux, you don't need to add a remote connection.
36+
37+
If you are 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.
38+
39+
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).
40+
41+
If you specify a remote Linux target, your source is copied to the remote system.
42+
43+
After you select a target, CMake runs automatically on the Linux system to generate the CMake cache for your project:
44+
45+
![Generate CMake cache on Linux](media/cmake-linux-1.png "Generate the CMake cache on Linux")
46+
47+
### Intellisense
48+
49+
To provide IntelliSense support for headers on remote Linux systems, Visual Studio automatically copies them from the Linux machine to a directory on your local Windows machine. For more information, see [IntelliSense for remote headers](configure-a-linux-project.md#remote_intellisense).
50+
51+
### Locale
52+
53+
For more information, see [Linux target locale](configure-a-linux-project.md#locale).
54+
55+
## Debug
56+
57+
To debug your code on the specified target system, set a breakpoint. Select the CMake target as the startup item in the toolbar menu next to the project setting. Then choose **&#x23f5; Start** on the toolbar, or press **F5**.
58+
59+
To customize your program's command-line arguments, press the **Switch Targets** button at the top of **Solution Explorer** and then choose **Targets View**. Then right-click on the target and select **Debug and Launch Settings**. This command opens or creates a *launch.vs.json* configuration file that contains information about your program. To specify the location for source files, add a **sourceFileMap** property to the file, as shown in this example:
60+
61+
```json
62+
"MIMode": "gdb",
63+
"externalConsole": true,
64+
"sourceFileMap": {
65+
"c/Users/USER/source/repos/CMAKEPROJECTNAME": "C:\\Users\\USER\\source\\repos\\CMAKEPROJECTNAME"
66+
},
67+
"remoteMachineName": "${debugInfo.remoteMachineName}",
68+
```
69+
70+
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).
71+
72+
## See also
73+
74+
[CMake Projects in Visual Studio](../build/cmake-projects-in-visual-studio.md)<br/>
75+
[Connect to your remote Linux computer](connect-to-your-remote-linux-computer.md)<br/>
76+
[Configure CMake debugging sessions](../build/configure-cmake-debugging-sessions.md)<br/>
77+
[Deploy, run, and debug your Linux project](deploy-run-and-debug-your-linux-project.md)
78+
79+
::: moniker-end

0 commit comments

Comments
 (0)