Update C++ Settings doc #8310
Open
Update C++ Settings doc #8310
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
There was a problem hiding this comment.
Pull Request Overview
A documentation update for C++ settings that merges the old customization doc with the new c_cpp_properties.json reference, clarifying default settings and introducing a recursive include paths section.
- Removed the outdated "Customize default settings" document.
- Updated and merged C++ settings reference with revised metadata, improved descriptions, and added recursive include path properties.
Reviewed Changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| docs/cpp/customize-default-settings-cpp.md | Removed obsolete document; content now merged in the new settings reference. |
| docs/cpp/customize-cpp-settings-cpp.md | Updated metadata and documentation content; added new recursive include properties and editorial improvements. |
Co-authored-by: Copilot <[email protected]>
|
|
||
| - `intelliSenseMode` | ||
| The IntelliSense mode to use that maps to an architecture-specific variant of MSVC, gcc, or Clang. If not set or if set to `${default}`, the extension will choose the default for that platform. | ||
| The IntelliSense mode to use that maps to an architecture-specific variant of MSVC, gcc, or Clang. If not set or if set to `${default}`, the extension chooses the default for that platform. | ||
|
|
||
| Platform defaults: | ||
| - Windows: `windows-msvc-x64` |
There was a problem hiding this comment.
Is it listed somewhere the actual values for the triplets?
Might be nice to have at least the viable parts listed windows|macos|linux-msvc|clang|gcc-x86|x64|arm|arm64
There was a problem hiding this comment.
The values will appear in the IntelliSense for the config file. I would say that we can forego listing all the combinations here.
There was a problem hiding this comment.
I think we need to be consistent - then we would need to list all the options for every variable. But considering that cstandard, C++ standard, and IntelliSenseMode all have dropdowns available in the Config UI I think people can find this information very easily without us specifying.
|
|
||
| - `defines` | ||
| A list of preprocessor definitions for the IntelliSense engine to use while parsing files. Optionally, use `=` to set a value, for example `VERSION=1`. | ||
|
|
||
| - `cStandard` | ||
| The version of the C language standard to use for IntelliSense. For example, `c17`, `gnu23`, or `${default}`. Note that GNU standards are only used to query the set compiler to get GNU defines, and IntelliSense will emulate the equivalent C standard version. | ||
| The version of the C language standard to use for IntelliSense. For example, `c17`, `gnu23`, or `${default}`. Note: GNU standards are only used to query the set compiler to get GNU defines, and IntelliSense emulates the equivalent C standard version. |
There was a problem hiding this comment.
And again, are the supported values listed?
bobbrow
reviewed
Apr 24, 2025
bobbrow
reviewed
Apr 24, 2025
bobbrow
reviewed
Apr 24, 2025
format the configuration and update some descriptions
bobbrow
approved these changes
Apr 25, 2025
ntrogh
requested changes
Apr 25, 2025
| --- | ||
| # C++ extension settings reference | ||
|
|
||
| The C++ Extension settings are highly configurable. This article explains the schema for the `c_cpp_properties.json` file. For general information about settings in VS Code, refer to [User and workspace settings](/docs/configure/settings.md), as well as the [Variables reference](/docs/reference/variables-reference.md) and [Default VS Code Settings](/docs/reference/default-settings.md). |
There was a problem hiding this comment.
Suggested change
| The C++ Extension settings are highly configurable. This article explains the schema for the `c_cpp_properties.json` file. For general information about settings in VS Code, refer to [User and workspace settings](/docs/configure/settings.md), as well as the [Variables reference](/docs/reference/variables-reference.md) and [Default VS Code Settings](/docs/reference/default-settings.md). | |
| The C++ Extension settings are highly configurable. This article explains the schema for the `c_cpp_properties.json` file. For general information about settings in VS Code, refer to [Configure settings](/docs/getstarted/personalize-vscode.md#configure-settings), as well as the [Variables reference](/docs/reference/variables-reference.md) and [Default VS Code Settings](/docs/reference/default-settings.md). |
| The C++ Extension settings are highly configurable. This article explains the schema for the `c_cpp_properties.json` file. For general information about settings in VS Code, refer to [User and workspace settings](/docs/configure/settings.md), as well as the [Variables reference](/docs/reference/variables-reference.md) and [Default VS Code Settings](/docs/reference/default-settings.md). | ||
|
|
||
| Looking to get started with configuring your C++ project? Begin with [configure Intellisense](/docs/cpp/configure-intellisense.md). | ||
| ## Example of Variables |
There was a problem hiding this comment.
Suggested change
| ## Example of Variables | |
| ## Example of variables |
| Looking to get started with configuring your C++ project? Begin with [configure Intellisense](/docs/cpp/configure-intellisense.md). | ||
| ## Example of Variables | ||
|
|
||
| Note, this json is an example configuration for `c_cpp_properties.json`. You only need to include relevant variables in your json file, all missing fields will be filled in with default values by the C++ extension. |
There was a problem hiding this comment.
Suggested change
| Note, this json is an example configuration for `c_cpp_properties.json`. You only need to include relevant variables in your json file, all missing fields will be filled in with default values by the C++ extension. | |
| The following JSON snippet is an example configuration for `c_cpp_properties.json`. You only need to include relevant variables in your JSON file, and any missing fields are filled in with their default values by the C++ extension. |
| An array of configuration objects that provide the IntelliSense engine with information about your project and your preferences. By default, the extension creates a configuration for you based on your operating system. You can also add more configurations. | ||
|
|
||
| - `version` | ||
| We recommend you don't edit this field. It tracks the current version of the `c_cpp_properties.json` file so that the extension knows what properties and settings should be present and how to upgrade this file to the latest version. |
There was a problem hiding this comment.
Suggested change
| We recommend you don't edit this field. It tracks the current version of the `c_cpp_properties.json` file so that the extension knows what properties and settings should be present and how to upgrade this file to the latest version. | |
| We recommend that you don't edit this field. It tracks the current version of the `c_cpp_properties.json` file, so that the extension knows what properties and settings should be present and how to upgrade this file to the latest version. |
| ## Configuration properties | ||
|
|
||
| - `name` | ||
| A friendly name that identifies a configuration. `Linux`, `Mac`, and `Win32` are special identifiers for configurations that are autoselected on those platforms. The status bar in VS Code shows you which configuration is active. You can also select the label in the status bar to change the active configuration. |
There was a problem hiding this comment.
Suggested change
| A friendly name that identifies a configuration. `Linux`, `Mac`, and `Win32` are special identifiers for configurations that are autoselected on those platforms. The status bar in VS Code shows you which configuration is active. You can also select the label in the status bar to change the active configuration. | |
| A user-friendly name that identifies a configuration. `Linux`, `Mac`, and `Win32` are special identifiers for configurations that are autoselected on those platforms. The Status Bar in VS Code shows you which configuration is active. You can also select the label in the Status Bar to change the active configuration. |
| For more information about the file format, see the [Clang documentation](https://clang.llvm.org/docs/JSONCompilationDatabase.html). Some build systems, such as CMake, [simplify generating this file](https://cmake.org/cmake/help/v3.5/variable/CMAKE_EXPORT_COMPILE_COMMANDS.html). | ||
|
|
||
| - `dotConfig` | ||
| A path to a .config file created by the Kconfig system. The Kconfig system generates a file with all the defines needed to build a project. Examples of projects that use the Kconfig system are the Linux Kernel and NuttX RTOS. |
There was a problem hiding this comment.
Suggested change
| A path to a .config file created by the Kconfig system. The Kconfig system generates a file with all the defines needed to build a project. Examples of projects that use the Kconfig system are the Linux Kernel and NuttX RTOS. | |
| A path to a `.config` file, created by the Kconfig system. The Kconfig system generates a file with all the defines needed to build a project. Examples of projects that use the Kconfig system are the Linux Kernel and NuttX RTOS. |
| ### Browse properties | ||
|
|
||
| - `path` | ||
| A list of paths for the Tag Parser to search for headers included by your source files. If omitted, `includePath` is used as the `path`. Searching on these paths is recursive by default. Specify `*` to indicate nonrecursive search. For example: `${workspaceFolder}` searches through all subdirectories while `${workspaceFolder}/*` will not. |
There was a problem hiding this comment.
Suggested change
| A list of paths for the Tag Parser to search for headers included by your source files. If omitted, `includePath` is used as the `path`. Searching on these paths is recursive by default. Specify `*` to indicate nonrecursive search. For example: `${workspaceFolder}` searches through all subdirectories while `${workspaceFolder}/*` will not. | |
| A list of paths for the Tag Parser to search for headers included by your source files. If omitted, `includePath` is used as the `path`. Searching on these paths is recursive by default. Specify `*` to indicate nonrecursive search. For example, `${workspaceFolder}` searches through all subdirectories while `${workspaceFolder}/*` does not. |
|
|
||
| You can allow `tasks.json` or `launch.json` to query the current active configuration from `c_cpp_properties.json`. To do this, use the variable `${command:cpptools.activeConfigName}` as an argument in a `tasks.json` or `launch.json` script. | ||
|
|
||
| ### Default VS Code Settings |
There was a problem hiding this comment.
Suggested change
| ### Default VS Code Settings | |
| ### Default VS Code settings |
|
|
||
| ### Default VS Code Settings | ||
|
|
||
| All default VS Code settings, such as C_Cpp.default.includePath, are supported in c_cpp_properties.json. The only exception is |
There was a problem hiding this comment.
Suggested change
| All default VS Code settings, such as C_Cpp.default.includePath, are supported in c_cpp_properties.json. The only exception is | |
| All default VS Code settings, such as `C_Cpp.default.includePath`, are supported in `c_cpp_properties.json`. The only exception is: |
| C_Cpp.default.systemIncludePath : string[] | ||
| ``` | ||
|
|
||
| This setting allows you to specify the system include path separately from the include path. However, the selected system include path the C++ extension receives from the compiler is not passed to the IntelliSense process. This is only used in rare scenarios since it overwrites the standard compiler behavior, for example, if your compiler is not supported. Instead, use the setting `compilerArgs` and using the "-isystem" flag to specify system headers, which is a better solution in most scenarios. |
There was a problem hiding this comment.
Suggested change
| This setting allows you to specify the system include path separately from the include path. However, the selected system include path the C++ extension receives from the compiler is not passed to the IntelliSense process. This is only used in rare scenarios since it overwrites the standard compiler behavior, for example, if your compiler is not supported. Instead, use the setting `compilerArgs` and using the "-isystem" flag to specify system headers, which is a better solution in most scenarios. | |
| This setting allows you to specify the system include path separately from the include path. However, the selected system include path that the C++ extension receives from the compiler is not passed to the IntelliSense process. This is only used in rare scenarios since it overwrites the standard compiler behavior, for example, if your compiler is not supported. Instead, use the setting `compilerArgs` and using the "-isystem" flag to specify system headers, which is a better solution in most scenarios. |
sean-mcmanus
suggested changes
Apr 26, 2025
| --- | ||
| ContentId: 4E34F6AF-BFC6-4BBB-8464-2E50C85AE826 | ||
| DateApproved: 4/25/2025 | ||
| MetaDescription: How to customize the c_cpp_properties.json file for the C++ extension. |
There was a problem hiding this comment.
It seems like the "C++ extension" references should be changed to "C/C++ extension".
| --- | ||
| # C++ extension settings reference | ||
|
|
||
| The C++ Extension settings are highly configurable. This article explains the schema for the `c_cpp_properties.json` file. For general information about settings in VS Code, refer to [User and workspace settings](/docs/configure/settings.md), as well as the [Variables reference](/docs/reference/variables-reference.md) and [Default VS Code Settings](/docs/reference/default-settings.md). |
| - `compilerPath` | ||
| The full path to the compiler you use to build your project, for example `/usr/bin/gcc`, to enable more accurate IntelliSense. The extension queries the compiler to determine the system include paths and default defines to use for IntelliSense. | ||
|
|
||
| Putting `"compilerPath": ""` (empty string) skips querying a compiler. This is useful if your preferred compiler doesn't support the arguments that are used for the query, as the extension defaults to any compiler it can find (like Visual C). Leaving out the `compilerPath` property does not skip the query. |
There was a problem hiding this comment.
"Visual C" doesn't seem like a valid compiler?
| - `compilerPath` | ||
| The full path to the compiler you use to build your project, for example `/usr/bin/gcc`, to enable more accurate IntelliSense. The extension queries the compiler to determine the system include paths and default defines to use for IntelliSense. | ||
|
|
||
| Putting `"compilerPath": ""` (empty string) skips querying a compiler. This is useful if your preferred compiler doesn't support the arguments that are used for the query, as the extension defaults to any compiler it can find (like Visual C). Leaving out the `compilerPath` property does not skip the query. |
There was a problem hiding this comment.
The phrase "the extension defaults to any compiler it can find" may mislead users to believe the extension scans their machine for compilers to use. We don't just use "any" compiler. There's a specific list of compilers at specific locations.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
The current settings doc for C++ points to the C_Cpp.default settings and contains inaccurate and incomplete information. Default settings are described in the general VS Code docs and only need to be linked to, and one exception needs to be covered. Additionally, this settings doc contains no information on the c_cpp_properties .json schema, which is in a separate doc that does not even have a place in the TOC right now. These two docs have been merged under "Settings Reference" to match Python's layout and updated with the most recent information.