Skip to content

Commit 6e5d4dc

Browse files
authored
Merge pull request MicrosoftDocs#2092 from mikeblome/mb-clang
new content and graphics for Clang/LLVM in CMake projects
2 parents 5bc3058 + 614868e commit 6e5d4dc

10 files changed

Lines changed: 85 additions & 2 deletions

‎docs/build/clang-support-cmake.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
---
2+
title: "Clang/LLVM support in Visual Studio CMake projects"
3+
ms.date: "07/01/2019"
4+
ms.description: "Configure a CMake project in Visual Studio to use the Clang/LLVM toolchain."
5+
helpviewer_keywords: ["Clang support for C++"]
6+
---
7+
8+
# Clang/LLVM support in Visual Studio CMake projects
9+
10+
::: moniker range="<=vs-2017"
11+
12+
Clang support is available in Visual Studio 2019.
13+
14+
::: moniker-end
15+
16+
::: moniker range="vs-2019"
17+
18+
You can use Visual Studio with Clang to edit and debug C++ CMake projects that target Windows or Linux.
19+
20+
**Windows**: Visual Studio 2019 version 16.1 includes support for editing, building, and debugging with Clang/LLVM in CMake projects targeting Windows.
21+
22+
**Linux**: For Linux CMake projects, no special Visual Studio support is required. You can install Clang using your distro's package manager, and add the appropriate commands in the CMakeLists.txt file.
23+
24+
## Install
25+
26+
For best IDE support in Visual Studio, we recommend using the latest Clang compiler tools for Windows. If you don't already have those, you can install them by opening the Visual Studio Installer and choosing **Clang compiler for Windows** under **Desktop development with C++** optional components.
27+
28+
![Clang component installation](media/clang-install-vs2019.png)
29+
30+
## Create a new configuration
31+
32+
To add a new Clang configuration to a CMake project:
33+
34+
1. Right-click on CMakeLists.txt in **Solution Explorer** and choose **CMake settings for project**.
35+
36+
1. Under **Configurations**, press the **Add Configuration** button:
37+
38+
![Add configuration](media/cmake-add-config-icon.png)
39+
40+
1. Choose the desired Clang configuration (note that separate Clang configurations are provided for Windows and Linux), then press **Select**:
41+
42+
![CMake Clang configuration](media/cmake-clang-configuration.png)
43+
44+
1. To make modifications to this configuration, use the **CMake Settings Editor**. For more information, see [Customize CMake build settings in Visual Studio](customize-cmake-settings.md).
45+
46+
## Modify an existing configuration to use Clang
47+
48+
To modify an existing configuration to use Clang, follow these steps:
49+
50+
1. Right-click on CMakeLists.txt in **Solution Explorer** and choose **CMake settings for project**.
51+
52+
1. Under **General** select the **Toolset** dropdown and choose the desired Clang toolset:
53+
54+
![CMake Clang toolset](media/cmake-clang-toolset.png)
55+
56+
## Custom Clang locations
57+
58+
By default, Visual Studio looks for Clang in two places:
59+
60+
- (Windows) The internally installed copy of Clang/LLVM that comes with the Visual Studio installer.
61+
- (Windows and Linux) The PATH environment variable.
62+
63+
You can specify another location by setting the **CMAKE_C_COMPILER** and **CMAKE_CXX_COMPILER** CMake variables in **CMake Settings**:
64+
65+
![CMake Clang toolset](media/clang-location-cmake.png)
66+
67+
## Clang compatibility modes
68+
69+
For Windows configurations, CMake by default invokes Clang in [clang-cl](https://llvm.org/devmtg/2014-04/PDFs/Talks/clang-cl.pdf) mode and links with the Microsoft implementation of the Standard Library. By default, **clang-cl.exe** is located in `C:\Program Files (x86)\Microsoft Visual Studio\2019\Common7\IDE\CommonExtensions\Microsoft\Llvm\bin`.
70+
71+
You can modify these values in **CMake Settings** under **CMake variables and cache**. Click **Show advanced variables**. Scroll down to find **CMAKE_CXX_COMPILER**, then click the **Browse** button to specify a different compiler path.
72+
73+
## Edit, build, and debug
74+
75+
After you have set up a Clang configuration, you can build and debug the project. Visual Studio detects that you are using the Clang compiler and provides IntelliSense, highlighting, navigation, and other editing features. Errors and warnings are displayed in the **Output Window**.
76+
77+
When debugging, you can use breakpoints, memory and data visualization, and most other debugging features. Some compiler-dependent features such as Edit and Continue are not available for Clang configurations.
78+
79+
![CMake Clang debugging](media/clang-debug-visualize.png)
80+
81+
::: moniker-end

‎docs/build/cmakesettings-reference.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ ms.assetid: 444d50df-215e-4d31-933a-b41841f186f8
66
---
77
# CMakeSettings.json schema reference
88

9-
The **cmakesettings.json**` file contains information that specifies how Visual Studio should interact with CMake to build a project for a specified platform. The file stores information such as environment variables or arguments for the cmake.exe environment. You can edit directly or use the **CMake Settings editor** (Visual Studio 2019 and later). See [Customize CMake build settings in Visual Studio](customize-cmake-settings.md) for more information about the editor.
9+
The **cmakesettings.json** file contains information that specifies how Visual Studio should interact with CMake to build a project for a specified platform. The file stores information such as environment variables or arguments for the cmake.exe environment. You can edit directly or use the **CMake Settings editor** (Visual Studio 2019 and later). See [Customize CMake build settings in Visual Studio](customize-cmake-settings.md) for more information about the editor.
1010

1111
## Environments
1212

‎docs/build/cppproperties-schema-reference.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -258,7 +258,7 @@ You have access to the following built-in macros inside `CppProperties.json`:
258258
|-|-|
259259
|`${workspaceRoot}`| the full path to the workspace folder|
260260
|`${projectRoot}`| the full path to the folder where `CppProperties.json` is placed|
261-
|`${vsInstallDir}`| the full path to the folder where the running instance of Visual Studio is installed|
261+
|`${env.vsInstallDir}`| the full path to the folder where the running instance of Visual Studio is installed|
262262

263263
For example, if your project has an include folder and also includes windows.h and other common headers from the Windows SDK, you may want to update your `CppProperties.json` configuration file with the following includes:
264264

86.5 KB
Loading
29.1 KB
Loading
25.4 KB
Loading
4.39 KB
Loading
23.6 KB
Loading
16.9 KB
Loading

‎docs/toc.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -93,6 +93,8 @@
9393
href: build/cmake-projects-in-visual-studio.md
9494
- name: "Tutorial: Create C++ cross-platform projects in Visual Studio"
9595
href: build/get-started-linux-cmake.md
96+
- name: Clang/LLVM in CMake projects
97+
href: build/clang-support-cmake.md
9698
- name: Configure a Linux CMake project
9799
href: build/../linux/cmake-linux-project.md
98100
- name: Customize CMake build settings

0 commit comments

Comments
 (0)