You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/linux/cmake-linux-project.md
+21-19Lines changed: 21 additions & 19 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,24 +1,25 @@
1
1
---
2
2
title: "Create and configure a Linux CMake project in Visual Studio"
3
3
description: "How to create, configure, edit, and compile a Linux CMake project in Visual Studio"
4
-
ms.date: "06/22/2020"
4
+
ms.date: "07/22/2020"
5
5
ms.assetid: f8707b32-f90d-494d-ae0b-1d44425fdc25
6
6
---
7
7
# Create and configure a Linux CMake project
8
8
9
-
::: moniker range="vs-2015"
9
+
We recommend that you use CMake for projects that are cross-platform or that 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.
10
+
11
+
This article describes how to create a new CMake project and configure it to build and debug on a remote Linux system or WSL.
10
12
13
+
::: moniker range="vs-2015"
11
14
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.
12
15
13
16
::: moniker-end
14
-
15
17
::: moniker range=">=vs-2017"
16
-
17
18
## Before you begin
18
19
19
-
First, make sure you have the **Linux development with C++** workload installed, including the CMake component. See [Install the C++ Linux workload in Visual Studio](download-install-and-setup-the-linux-development-workload.md).
20
+
First, make sure you have the Visual Studio Linux workload installed, including the CMake component. That's the **Linux development with C++** workload in the Visual Studio installer. See [Install the C++ Linux workload in Visual Studio](download-install-and-setup-the-linux-development-workload.md) if you aren't sure that you have that installed.
20
21
21
-
On the Linux system, make sure that the following are installed:
22
+
Also, make sure the following are installed on the remote machine:
22
23
23
24
- gcc
24
25
- gdb
@@ -27,23 +28,19 @@ On the Linux system, make sure that the following are installed:
27
28
- ninja-build
28
29
29
30
::: moniker-end
30
-
31
-
::: moniker range="vs-2019"
32
-
33
-
Linux support for CMake projects requires the target machine to have 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).
34
-
35
-
The CMake support in Visual Studio requires the server mode support that was introduced in CMake 3.8. In Visual Studio 2019, version 3.14 or later is recommended.
36
-
37
-
::: moniker-end
38
-
39
31
::: moniker range="vs-2017"
40
32
41
33
The CMake support in Visual Studio requires the server mode support that was introduced in CMake 3.8. For a Microsoft-provided CMake variant, download the latest prebuilt binaries at [https://github.com/Microsoft/CMake/releases](https://github.com/Microsoft/CMake/releases).
42
34
43
35
The binaries are installed in `~/.vs/cmake`. After deploying the binaries, your project automatically regenerates. If the CMake specified by the `cmakeExecutable` field in *CMakeSettings.json* is invalid (it doesn't exist or is an unsupported version), and the prebuilt binaries are present, Visual Studio ignores `cmakeExecutable` and uses the prebuilt binaries.
36
+
::: moniker-end
37
+
::: moniker range=">=vs-2019"
44
38
45
-
:::moniker-end
39
+
Linux support for CMake projects requires that the target machine have 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).
46
40
41
+
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.
42
+
43
+
::: moniker-end
47
44
::: moniker range="vs-2019"
48
45
49
46
## Create a new Linux CMake project
@@ -55,12 +52,15 @@ To create a new Linux CMake project in Visual Studio 2019:
55
52
56
53
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**. To specify options for debugging, right-click on the project node and choose **Debug and launch settings**.
57
54
55
+
Alternatively, you can bring your own CMake project to Visual Studio 2019 by opening any folder containing a root `CMakeLists.txt` directly in Visual Studio. The following section explains how to use "Open Folder" to open an existing repo.
58
56
::: moniker-end
59
57
60
58
::: moniker range=">=vs-2017"
61
59
62
60
## Open a CMake project folder
63
61
62
+
You can bring your own CMake project to Visual Studio by opening any folder containing a root `CMakeLists.txt`.
63
+
64
64
When you open a folder that contains an existing CMake project, Visual Studio uses variables in the CMake cache to automatically configure IntelliSense and builds. Local configuration and debugging settings get stored in JSON files. You can optionally share these files with others who are using Visual Studio.
65
65
66
66
Visual Studio doesn't modify the *CMakeLists.txt* files. It's left alone so that others working on the same project can continue to use their existing tools. Visual Studio does regenerate the cache when you save edits to *CMakeLists.txt* or in some cases to *CMakeSettings.json*. But if you're using an **Existing Cache** configuration, then Visual Studio doesn't modify the cache.
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.)
95
+
After 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.)
96
96
97
97
::: moniker-end
98
98
@@ -106,7 +106,9 @@ To target Windows Subsystem for Linux, click on **Manage Configurations** in the
106
106
107
107
::: moniker range=">=vs-2017"
108
108
109
-
Visual Studio chooses the first remote system in the list under **Tools** > **Options** > **Cross Platform** > **Connection Manager** by default for remote targets. 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).
109
+
Visual Studio chooses the first remote system in the list under **Tools** > **Options** > **Cross Platform** > **Connection Manager** by default for remote targets.
110
+
111
+
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).
110
112
111
113
If you specify a remote Linux target, your source is copied to the remote system.
112
114
@@ -126,7 +128,7 @@ For more information, see [Linux target locale](configure-a-linux-project.md#loc
126
128
127
129
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 **⏵ Start** on the toolbar, or press **F5**.
128
130
129
-
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:
131
+
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:
0 commit comments