Skip to content

Commit 8007e64

Browse files
author
mikeblome
committed
updates to cppproperties reference topic
1 parent d439f33 commit 8007e64

1 file changed

Lines changed: 64 additions & 217 deletions

File tree

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

Lines changed: 64 additions & 217 deletions
Original file line numberDiff line numberDiff line change
@@ -1,146 +1,68 @@
11
---
22
title: "CppProperties.json schema reference"
3-
ms.date: "05/16/2019"
3+
ms.date: "08/07/2019"
44
helpviewer_keywords: ["CMake in Visual Studio"]
55
---
66

77
# CppProperties.json schema reference
88

9-
Open Folder projects that don't use CMake can store project configuration settings in a `CppProperties.json` file. (CMake projects use a [CMakeSettings.json](customize-cmake-settings.md) file.) The Visual Studio IDE uses `CppProperties.json` for IntelliSense and code navigation. A configuration consists of name/value pairs and defines #include paths, compiler switches, and other parameters.
10-
11-
12-
## Default configurations
13-
14-
Visual Studio provides predefined configurations for x86 and x64 Debug and Release. By default, your project has an x86-Debug configuration in `CppProperties.json`. To add a new configuration, right-click on the `CppProperties.json` file in **Solution Explorer** and choose **Add Configuration**:
15-
16-
![Open Folder - add new configuration](media/open-folder-add-config.png "Open Folder add new configuration")
17-
18-
The default configurations are shown here:
19-
20-
```json
21-
{
22-
"configurations": [
23-
{
24-
"inheritEnvironments": [
25-
"msvc_x86"
26-
],
27-
"name": "x86-Debug",
28-
"includePath": [
29-
"${env.INCLUDE}",
30-
"${workspaceRoot}\\**"
31-
],
32-
"defines": [
33-
"WIN32",
34-
"_DEBUG",
35-
"UNICODE",
36-
"_UNICODE"
37-
],
38-
"intelliSenseMode": "windows-msvc-x86"
39-
},
40-
{
41-
"inheritEnvironments": [
42-
"msvc_x86"
43-
],
44-
"name": "x86-Release",
45-
"includePath": [
46-
"${env.INCLUDE}",
47-
"${workspaceRoot}\\**"
48-
],
49-
"defines": [
50-
"WIN32",
51-
"NDEBUG",
52-
"UNICODE",
53-
"_UNICODE"
54-
],
55-
"intelliSenseMode": "windows-msvc-x86"
56-
},
57-
{
58-
"inheritEnvironments": [
59-
"msvc_x64"
60-
],
61-
"name": "x64-Debug",
62-
"includePath": [
63-
"${env.INCLUDE}",
64-
"${workspaceRoot}\\**"
65-
],
66-
"defines": [
67-
"WIN32",
68-
"_DEBUG",
69-
"UNICODE",
70-
"_UNICODE"
71-
],
72-
"intelliSenseMode": "windows-msvc-x64"
73-
},
74-
{
75-
"inheritEnvironments": [
76-
"msvc_x64"
77-
],
78-
"name": "x64-Release",
79-
"includePath": [
80-
"${env.INCLUDE}",
81-
"${workspaceRoot}\\**"
82-
],
83-
"defines": [
84-
"WIN32",
85-
"NDEBUG",
86-
"UNICODE",
87-
"_UNICODE"
88-
],
89-
"intelliSenseMode": "windows-msvc-x64"
90-
}
91-
]
92-
}
93-
```
94-
For properties that have a set of allowable values, the code editor shows the available options when you start to type:
95-
96-
![Open Folder IntelliSense](media/open-folder-intellisense-mode.png "Open Folder IntelliSense")
97-
98-
9+
Open Folder projects that don't use CMake can store project configuration settings for IntelliSense in a `CppProperties.json` file. (CMake projects use a [CMakeSettings.json](customize-cmake-settings.md) file.) A configuration consists of name/value pairs and defines #include paths, compiler switches, and other parameters. See [Open Folder projects for C++](open-folder-projects-cpp.md) for more information about how to add configurations in an Open Folder project.
9910

10011
## Configuration properties
10112

10213
A configuration may have any of the following properties:
10314

10415
|||
10516
|-|-|
106-
|`name`|The configuration name that appears in the C++ configuration dropdown|
107-
|`includePath`|The list of folders that should be specified in the include path (maps to /I for most compilers)|
17+
|`inheritEnvironments`| Specifies which environments apply to this configuration.|
18+
|`name`|The configuration name that will appear in the C++ configuration dropdown|
19+
|`includePath`|A comma-separated list of folders that should be specified in the include path (maps to /I for most compilers)|
10820
|`defines`|The list of macros that should be defined (maps to /D for most compilers)|
10921
|`compilerSwitches`|One or more additional switches that can influence IntelliSense behavior|
11022
|`forcedInclude`|Header to be automatically included in every compilation unit (maps to /FI for MSVC or -include for clang)|
11123
|`undefines`|The list of macros to be undefined (maps to /U for MSVC)|
112-
|`intelliSenseMode`|The IntelliSense engine to be used. You can specify the architecture-specific variants for MSVC, gcc, or Clang:<br/><br/>- windows-msvc-x86 (default)<br/>- windows-msvc-x64<br/>- msvc-arm<br/>- windows-clang-x86<br/>- windows-clang-x64<br/>- windows-clang-arm<br/>- Linux-x64<br/>- Linux-x86<br/>- Linux-arm<br/>- gccarm|
24+
|`intelliSenseMode`|The IntelliSense engine to be used. You can specify one of the predefined architecture-specific variants for MSVC, gcc, or Clang.|
25+
|`environments`|User-defined sets of variables that behave like environment variables in a command prompt and are accessed with the ${env.<VARIABLE>} macro.|
11326

114-
Note: The values `msvc-x86` and `msvc-x64` are supported for legacy reasons only. Use the `windows-msvc-*` variants instead.
27+
### intelliSenseMode values
11528

116-
## Custom configurations
29+
The code editor shows the available options when you start to type:
11730

31+
![Open Folder IntelliSense](media/open-folder-intellisense-mode.png "Open Folder IntelliSense")
11832

119-
You can customize any of the default configurations in `CppProperties.json`, or create new configurations. Each will appear in the configuration dropdown:
33+
These are the supported values:
34+
35+
- windows-msvc-x86
36+
- windows-msvc-x64
37+
- windows-msvc-arm
38+
- windows-msvc-arm64
39+
- android-clang-x86
40+
- android-clang-x64
41+
- android-clang-arm
42+
- android-clang-arm64
43+
- ios-clang-x86
44+
- ios-clang-x64
45+
- ios-clang-arm
46+
- ios-clang-arm64
47+
- windows-clang-x86
48+
- windows-clang-x64
49+
- windows-clang-arm
50+
- windows-clang-arm64
51+
- linux-gcc-x86
52+
- linux-gcc-x64
53+
- linux-gcc-arm
12054

121-
```json
122-
{
123-
"configurations": [
124-
{
125-
"name": "Windows",
126-
...
127-
},
128-
{
129-
"name": "with EXTERNAL_CODECS",
130-
...
131-
}
132-
]
133-
}
134-
```
55+
Note: The values `msvc-x86` and `msvc-x64` are supported for legacy reasons only. Use the `windows-msvc-*` variants instead.
13556

136-
## Toolset environments
57+
## Pre-defined Environments
13758

138-
Use the following system-defined variables to specify which toolset you are compiling with:
59+
Visual Studio provides the following predefined environments for Microsoft C++ which map to the corresponding Developer Command Prompt. When you inherit one of these environments, you can refer to any of the environment variables by using ${env.\<VARIABLE>}.
13960

14061
|Variable Name|Description|
14162
|-----------|-----------------|
14263
|vsdev|The default Visual Studio environment|
14364
|msvc_x86|Compile for x86 using x86 tools|
65+
|msvc_x64|Compile for AMD64 using 64-bit tools|
14466
|msvc_arm|Compile for ARM using x86 tools|
14567
|msvc_arm64|Compile for ARM64 using x86 tools|
14668
|msvc_x86_x64|Compile for AMD64 using x86 tools|
@@ -155,133 +77,52 @@ When the Linux workload is installed, the following environments are available f
15577
|linux_x86|Target x86 Linux remotely|
15678
|linux_x64|Target x64 Linux remotely|
15779
|linux_arm|Target ARM Linux remotely|
158-
"windows-msvc-x86",
159-
"windows-msvc-x64",
160-
"windows-msvc-arm",
161-
"windows-msvc-arm64",
162-
"android-clang-x86",
163-
"android-clang-x64",
164-
"android-clang-arm",
165-
"android-clang-arm64",
166-
"ios-clang-x86",
167-
"ios-clang-x64",
168-
"ios-clang-arm",
169-
"ios-clang-arm64",
170-
"windows-clang-x86",
171-
"windows-clang-x64",
172-
"windows-clang-arm",
173-
"windows-clang-arm64",
174-
"linux-gcc-x86",
175-
"linux-gcc-x64",
176-
"linux-gcc-arm"
177-
178-
## System environment variables
179-
180-
`CppProperties.json` supports system environment variable expansion for include paths and other property values. The syntax is `${env.FOODIR}` to expand an environment variable `%FOODIR%`.
181-
182-
## Custom environment variables
183-
184-
You can define custom environment variables in `CppProperties.json` either globally or per-configuration. The following example shows how default and custom environment variables can be declared and used. The global **environments** property declares a variable named **INCLUDE** that can be used by any configuration:
18580

186-
```json
187-
{
188-
// The "environments" property is an array of key value pairs of the form
189-
// { "EnvVar1": "Value1", "EnvVar2": "Value2" }
190-
"environments": [
191-
{
192-
"INCLUDE": "${workspaceRoot}\src\includes"
193-
}
194-
],
81+
## User-defined environments
19582

196-
"configurations": [
197-
{
198-
"inheritEnvironments": [
199-
// Inherit the MSVC 32-bit environment and toolchain.
200-
"msvc_x86"
201-
],
202-
"name": "x86",
203-
"includePath": [
204-
// Use the include path defined above.
205-
"${env.INCLUDE}"
206-
],
207-
"defines": [ "WIN32", "_DEBUG", "UNICODE", "_UNICODE" ],
208-
"intelliSenseMode": "windows-msvc-x86"
209-
},
210-
{
211-
"inheritEnvironments": [
212-
// Inherit the MSVC 64-bit environment and toolchain.
213-
"msvc_x64"
214-
],
215-
"name": "x64",
216-
"includePath": [
217-
// Use the include path defined above.
218-
"${env.INCLUDE}"
219-
],
220-
"defines": [ "WIN32", "_DEBUG", "UNICODE", "_UNICODE" ],
221-
"intelliSenseMode": "windows-msvc-x64"
222-
}
223-
]
224-
}
225-
```
226-
## Per-configuration environment variables
83+
You can optionally use the `environments` property to define sets of variables in `CppProperties.json` either globally or per-configuration. These variables behave like environment variables in the context of an Open Folder project and can be accessed from *tasks.vs.json* and *launch.vs.json* after they are defined here. However, they are not necessarily set as actual environment variables in any command prompt that Visual Studio uses internally.
22784

228-
You can also define an **environments** property inside a configuration. It applies only to that configuration, and overrides any global variables of the same name. In the following example, the x64 configuration defines a local **INCLUDE** variable that overrides the global value:
85+
When you consume an environment, then you have to specify it in the `inheritsEnvironments` property even if the environment is defined as part of the same configuration; the `environment` property specifies the name of the environment. The following example shows a sample configuration for enabling IntelliSense for GCC in an MSYS2 installation. Note how the configuration both defines and inherits the `mingw_64` environment, and how the `includePath` property can access the `INCLUDE` variable.
22986

23087
```json
231-
{
232-
"environments": [
88+
"configurations": [
23389
{
234-
"INCLUDE": "${workspaceRoot}\src\includes"
235-
}
236-
],
23790

238-
"configurations": [
239-
{
24091
"inheritEnvironments": [
241-
"msvc_x86"
92+
"mingw_64"
24293
],
243-
"name": "x86",
244-
"includePath": [
245-
// Use the include path defined in the global environments property.
246-
"${env.INCLUDE}"
94+
"name": "Mingw64",
95+
"includePath ,": [
96+
"${env.INCLUDE}",
97+
"${workspaceRoot}\\**",
24798
],
248-
"defines": [ "WIN32", "_DEBUG", "UNICODE", "_UNICODE" ],
249-
"intelliSenseMode": "windows-msvc-x86"
250-
},
251-
{
99+
"intelliSenseMode": "linux-gcc-x64",
252100
"environments": [
253101
{
254-
// Append 64-bit specific include path to env.INCLUDE.
255-
"INCLUDE": "${env.INCLUDE};${workspaceRoot}\src\includes64"
102+
"MINGW64_ROOT": "C:\\msys64\\mingw64",
103+
"BIN_ROOT": "${env.MINGW64_ROOT}\\bin",
104+
"FLAVOR": "x86_64-w64-mingw32",
105+
"TOOLSET_VERSION": "9.1.0",
106+
"PATH": "${env.MINGW64_ROOT}\\bin;${env.MINGW64_ROOT}\\..\\usr\\local\\bin;${env.MINGW64_ROOT}\\..\\usr\\bin;${env.MINGW64_ROOT}\\..\\bin;${env.PATH}",
107+
"INCLUDE": "${env.MINGW64_ROOT}\\include\\c++\\${env.TOOLSET_VERSION};${env.MINGW64_ROOT}\\include\\c++\\${env.TOOLSET_VERSION}\\tr1;${env.MINGW64_ROOT}\\include\\c++\\${env.TOOLSET_VERSION}\\${env.FLAVOR};",
108+
"environment": "mingw_64"
256109
}
257-
],
258-
259-
"inheritEnvironments": [
260-
"msvc_x64"
261-
],
262-
"name": "x64",
263-
"includePath": [
264-
// Use the include path defined in the local environments property.
265-
"${env.INCLUDE}"
266-
],
267-
"defines": [ "WIN32", "_DEBUG", "UNICODE", "_UNICODE" ],
268-
"intelliSenseMode": "windows-msvc-x64"
110+
]
269111
}
270112
]
271-
}
272113
```
273114

274-
All custom and default environment variables are also available in `tasks.vs.json` and `launch.vs.json`.
115+
When you define an **environments** property inside a configuration, it overrides any global variables of the same name.
275116

276-
#### Build-in macros
117+
## Built-in macros
277118

278119
You have access to the following built-in macros inside `CppProperties.json`:
279120

280121
|||
281122
|-|-|
282-
|`${workspaceRoot}`| the full path to the workspace folder|
283-
|`${projectRoot}`| the full path to the folder where `CppProperties.json` is placed|
284-
|`${env.vsInstallDir}`| the full path to the folder where the running instance of Visual Studio is installed|
123+
|`${workspaceRoot}`| The full path to the workspace folder|
124+
|`${projectRoot}`| The full path to the folder where `CppProperties.json` is placed|
125+
|`${env.vsInstallDir}`| The full path to the folder where the running instance of Visual Studio is installed|
285126

286127
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:
287128

@@ -310,4 +151,10 @@ For example, if your project has an include folder and also includes windows.h a
310151
311152
## Troubleshoot IntelliSense errors
312153

154+
If you are not seeing the IntelliSense that you expect, you can troubleshoot by going to **Tools** > **Options** > **Text Editor** > **C/C++** > **Advanced** and setting **Enable Logging** to **true**. To start with, try setting **Logging Level** to 5, and **Logging Filters** to 8.
155+
156+
![Diagnostic logging](media/diagnostic-logging.png)
157+
158+
Output is piped to the **Output Window** and is visible when you choose **Show Output From: Visual C++ Log*. The output contains, among other things, the list of actual include paths that IntelliSense is trying to use. If the paths do not match the ones in *cppproperties.json*, try closing the folder and deleting the *.vs* sub-folder which contains cached browsing data.
159+
313160
To troubleshoot IntelliSense errors caused by missing include paths, open the **Error List** and filter its output to "IntelliSense only" and error code E1696 "cannot open source file ...".

0 commit comments

Comments
 (0)