Skip to content

Repo sync for protected CLA branch #3633

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jan 4, 2022
Merged

Repo sync for protected CLA branch #3633

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9df7b1f
1/4/2022 AM Publish (#4019)
Taojunshen Jan 4, 2022
b72b146
Merging changes synced from https://github.com/MicrosoftDocs/cpp-docs…
opbld15 Jan 4, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 27 additions & 17 deletions docs/linux/cmake-linux-configure.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: "Configure a Linux CMake project in Visual Studio"
description: "How to configure Linux CMake settings in Visual Studio"
ms.date: "08/08/2020"
ms.date: 01/03/2022
---
# Configure a Linux CMake project in Visual Studio

Expand All @@ -10,11 +10,11 @@ Linux support is available in Visual Studio 2017 and later. To see the documenta
::: moniker-end

::: moniker range=">=msvc-150"
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)
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're using MSBuild, instead, see [Configure a Linux MSBuild Project in Visual Studio](configure-a-linux-project.md)

## Add a Linux configuration

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.
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 other properties that control the build settings on the remote Linux machine.
::: moniker-end

::: moniker range="msvc-150"
Expand All @@ -24,27 +24,36 @@ The default configuration for Linux-Debug in Visual Studio 2017 (and Visual Stud

```json
{
"configurations": [
{
"name": "Linux-Debug",
"generator": "Unix Makefiles",
"remoteMachineName": "${defaultRemoteMachineName}",
"configurationType": "Debug",
"remoteCMakeListsRoot": "/var/tmp/src/${workspaceHash}/${name}",
"cmakeExecutable": "/usr/local/bin/cmake",
"buildRoot": "${env.LOCALAPPDATA}\\CMakeBuilds\\${workspaceHash}\\build\\${name}",
"installRoot": "${env.LOCALAPPDATA}\\CMakeBuilds\\${workspaceHash}\\install\\${name}",
"buildRoot": "${env.USERPROFILE}\\CMakeBuilds\\${workspaceHash}\\build\\${name}",
"installRoot": "${env.USERPROFILE}\\CMakeBuilds\\${workspaceHash}\\install\\${name}",
"remoteBuildRoot": "/var/tmp/build/${workspaceHash}/build/${name}",
"remoteInstallRoot": "/var/tmp/build/${workspaceHash}/install/${name}",
"remoteCopySources": true,
"remoteCopySourcesOutputVerbosity": "Normal",
"remoteCopySourcesConcurrentCopies": "10",
"remoteCopySourcesMethod": "rsync",
"remoteCopySourcesExclusionList": [".vs", ".git"],
"rsyncCommandArgs" : "-t --delete --delete-excluded",
"remoteCopyBuildOutput" : "false",
"remoteCopySourcesExclusionList": [
".vs",
".git"
],
"rsyncCommandArgs": "-t --delete --delete-excluded",
"remoteCopyBuildOutput": false,
"cmakeCommandArgs": "",
"buildCommandArgs": "",
"ctestCommandArgs": "",
"inheritEnvironments": [ "linux-x64" ]
"inheritEnvironments": [
"linux_x64"
]
}
]
}
```

Expand All @@ -55,16 +64,18 @@ To change the default CMake settings in Visual Studio 2019 or later, from the ma

![Screenshot showing CMake Manage Configurations highlighted in the Configuration dropdown.](../build/media/vs2019-cmake-manage-configurations.png "CMake configurations drop-down")

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).
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 upper-right of the **CMake Settings** dialog. For more information, see [Customize CMake Settings](../build/customize-cmake-settings.md).

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

```json
{
"name": "Linux-Debug",
"generator": "Unix Makefiles",
"configurations": [
{
"name": "Linux-GCC-Debug",
"generator": "Ninja",
"configurationType": "Debug",
"cmakeExecutable": "/usr/bin/cmake",
"cmakeExecutable": "cmake",
"remoteCopySourcesExclusionList": [ ".vs", ".git", "out" ],
"cmakeCommandArgs": "",
"buildCommandArgs": "",
Expand All @@ -78,7 +89,6 @@ The default Linux-Debug configuration in Visual Studio 2019 version 16.1, and la
"rsyncCommandArgs": "-t --delete --delete-excluded",
"remoteCopyBuildOutput": false,
"remoteCopySourcesMethod": "rsync",
"addressSanitizerRuntimeFlags": "detect_leaks=0",
"variables": []
}
]
Expand All @@ -98,7 +108,7 @@ When you do a build:

## Choose a Linux target

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 based on your Linux compiler. For example, if you are using GCC on Linux and compiling with debug info, you'll chose: **Linux-GCC-Debug** or **Linux-GCC-Release**.
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 based on your Linux compiler. For example, if you're using GCC on Linux and compiling with debug info, choose: **Linux-GCC-Debug** or **Linux-GCC-Release**.

If you specify a remote Linux target, your source is copied to the remote system.

Expand All @@ -121,7 +131,7 @@ The **CMakeSettings.json** window appears.

![Add configuration.](media/cmake-linux-configurations.png "Add a configuration to CMake settings")

Press **Add Configuration** (the green '+' button) and then choose **Linux-GCC-Debug** or **Linux-GCC-Release** if using GCC. Use the Clang variants if you are using the Clang/LLVM toolset. Press **Select** and then **Ctrl+S** to save the configuration.
Press **Add Configuration** (the green '+' button) and then choose **Linux-GCC-Debug** or **Linux-GCC-Release** if using GCC. Use the Clang variants if you're using the Clang/LLVM toolset. Press **Select** and then **Ctrl+S** to save the configuration.

**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.
::: moniker-end
Expand All @@ -135,7 +145,7 @@ Accurate C++ IntelliSense requires access to the C++ headers referenced by your

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.

## Additional settings
## More settings

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.

Expand Down
Loading