From c449bf30b4c00493436a60cee5aa0947eba9c6da Mon Sep 17 00:00:00 2001 From: Greg Van Liew Date: Mon, 6 Nov 2023 14:17:36 -0800 Subject: [PATCH 1/2] Update links, edit/formatting pass for C++ IntelliSense --- build/sitemap.xml | 5 ++ docs/cpp/configure-intellisense.md | 125 ++++++++++++++++------------- 2 files changed, 72 insertions(+), 58 deletions(-) diff --git a/build/sitemap.xml b/build/sitemap.xml index 207e16d023..2a60a0c431 100644 --- a/build/sitemap.xml +++ b/build/sitemap.xml @@ -815,6 +815,11 @@ weekly 0.8 + + https://code.visualstudio.com/docs/cpp/configure-intellisense + weekly + 0.8 + https://code.visualstudio.com/docs/cpp/configure-intellisense-crosscompilation weekly diff --git a/docs/cpp/configure-intellisense.md b/docs/cpp/configure-intellisense.md index 47ee46c9a8..823a781d37 100644 --- a/docs/cpp/configure-intellisense.md +++ b/docs/cpp/configure-intellisense.md @@ -4,63 +4,67 @@ Area: cpp TOCTitle: Configure IntelliSense ContentId: bf494c65-12b4-4506-ab6c-1fad76d7ccf1 PageTitle: Configure C/C++ IntelliSense -DateApproved: 10/31/2023 -MetaDescription: Configure Visual Studio Code IntelliSense in the C/C++ Extension +DateApproved: 11/6/2023 +MetaDescription: Configure Visual Studio Code IntelliSense in the C/C++ extension --- # Configure C/C++ IntelliSense -This article is about configuring the C/C++ extension to provide C++ specific [IntelliSense](/docs/editor/intellisense.md) suggestions in VS Code. IntelliSense is a helpful tool built into VS Code that provides various code editing features that help you code faster and more efficiently. For example, code completion, parameter info, syntax highlighting, code actions (light bulbs), and member lists are all generated using IntelliSense. +This article is about configuring the [C/C++](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools) extension to provide C++ specific [IntelliSense](/docs/editor/intellisense.md) suggestions in Visual Studio Code. IntelliSense is a helpful tool built into VS Code that provides various code editing features to help you code faster and more efficiently. For example, code completion, parameter info, syntax highlighting, Code Actions (light bulbs), and member lists are all generated using IntelliSense. -C/C++ IntelliSense only requires a C/C++ compiler to be installed on your system. The C/C++ compiler provides C++ specific information to IntelliSense, such as the locations of system include paths and other settings. For project level configurations, reference [Project level IntelliSense Configuration](/docs/cpp/configure-intellisense.md#_Project-Level-IntelliSense-Configuration) section. +C/C++ IntelliSense only requires a C/C++ compiler to be installed on your system. The C/C++ compiler provides C++ specific information to IntelliSense, such as the locations of system include paths and other settings. For project level configurations, reference [Project level IntelliSense configuration](#project-level-intellisense-configuration) section. -## When will the C/C++ Extension configure core IntelliSense features for me? +## When will the C/C++ extension configure core IntelliSense features for me? -A compiler is the only requirement to configure core Intellisense functionality. To identify a compiler for IntelliSense, the C/C++ Extension scans common paths on your machine for compilers such as clang, GCC, MinGW, cygwin, cygwin64, and MSVC. If any of these compilers are identified and in a secure location, they are automatically configured for IntelliSense. Otherwise, a notification is displayed asking you to confirm that this compiler should be configured for IntelliSense. In either of these scenarios, the compiler selected is also set as the default compiler. +A compiler is the only requirement to configure core IntelliSense functionality. To identify a compiler for IntelliSense, the C/C++ extension scans common paths on your machine for compilers such as Clang, GCC, MinGW, cygwin, cygwin64, and MSVC. If any of these compilers are identified and in a secure location, they are automatically configured for IntelliSense. Otherwise, a notification is displayed asking you to confirm that this compiler should be configured for IntelliSense. In either of these scenarios, the compiler selected is also set as the default compiler. ## How to check whether IntelliSense is configured -If you don't have IntelliSense configured, the C/C++ Extension shows a yellow indicator in the status bar with a warning sign labeled **Configure IntelliSense**. +If you don't have IntelliSense configured, the C/C++ extension shows a yellow indicator in the status bar with a warning sign labeled **Configure IntelliSense**. -![configure-intelliSense-indicator-status-bar](images/intellisense/configure-intellisense-indicator.png) +![Configure IntelliSense indicator in the status bar](images/intellisense/configure-intellisense-indicator.png) -To configure, select the status bar indicator, which navigates you to the [configuration quick pick](/docs/cpp/configure-intellisense.md#_Option-1.-Select-a-configuration-option-through-the-configuration-quick-pick). The quick pick can help you select or install a C/C++ compiler. +To configure, select the status bar indicator, which brings up the [configuration Quick Pick](#option-1-select-a-configuration-option-through-the-configuration-quick-pick). The Quick Pick can help you select or install a C/C++ compiler. -If you do not see a status bar indicator, you can also check your project's `c_cpp_properties.json` file. This file stores all of your IntelliSense configuration settings. Navigate to this file by selecting **C/C++: Edit Configurations (UI)** from the Command Palette (`kb(workbench.action.showCommands)`). Check the `IntelliSense mode` to find your configuration. To learn more about the `c_cpp_properties.json` file, see the [schema reference](/docs/cpp/c-cpp-properties-schema-reference.md). +If you do not see a status bar indicator, you can also check your project's `c_cpp_properties.json` file. This file stores all of your IntelliSense configuration settings. Navigate to this file by selecting **C/C++: Edit Configurations (UI)** from the Command Palette (`kb(workbench.action.showCommands)`). Check the `IntelliSense mode` to find your configuration. To learn more about the `c_cpp_properties.json` file, you can review the [schema reference](/docs/cpp/c-cpp-properties-schema-reference.md). -![Command Palette](images/cpp/command-palette.png) +![Command Palette filtered on C/C++ extension commands](images/cpp/command-palette.png) ## How to configure IntelliSense IntelliSense configuration is stored in the `c_cpp_properties.json` file, which is automatically created in your workspace. All three of the following options are different ways of editing the `c_cpp_properties.json` file: -### Option 1. Select a configuration option through the configuration quick pick +### Option 1. Select a configuration option through the configuration Quick Pick -Open the quick pick by entering **Select IntelliSense Configuration** in the Command Palette (`kb(workbench.action.showCommands)`), which shows you a dropdown with all of the configuration options found by the C/C++ Extension on your machine. +Open the Quick Pick by entering **Select IntelliSense Configuration** in the Command Palette (`kb(workbench.action.showCommands)`), which shows you a dropdown with all of the configuration options found by the C/C++ extension on your machine. -![Compiler Quick Pick](images/intellisense/compiler-quick-pick.png) +![Select a compiler to configure for IntelliSense Quick Pick](images/intellisense/compiler-quick-pick.png) -Select one of the options available. If you select a compiler, this compiler is used by IntelliSense by default. You can return to the Configuration quick pick at any point to change which option is used to configure IntelliSense. +Select one of the options available. If you select a compiler, this compiler is used by IntelliSense by default. You can return to the **IntelliSense Configuration** Quick Pick at any point to change which option is used to configure IntelliSense. -If no options are available in the quick pick, no compiler could be identified in your system. You can browse your machine manually or install a C/C++ compiler. To install on a Windows machine, select the **Help me install a compiler** option, which redirects you to the step-by-step walkthrough of how to install a C/C++ compiler. On a Mac or Linux machine, select **Install a compiler** and navigate through the prompts to have a C++ compiler installed on your machine. +If no options are available in the Quick Pick, no compiler could be identified in your system. You can browse your machine manually or install a C/C++ compiler. To install on a Windows machine, select the **Help me install a compiler** option that redirects you to the step-by-step walkthrough of how to install a C/C++ compiler. On a macOS or Linux machine, select **Install a compiler** and navigate through the prompts to have a C++ compiler installed on your machine. ### Option 2. Edit your IntelliSense configurations through the UI -Open your IntelliSense configuration by selecting **C/C++: Edit Configurations (UI)** from the Command Palette (`kb(workbench.action.showCommands)`). This view is an interface of the `c_cpp_properties.json` file. +Open your IntelliSense configuration by selecting **C/C++: Edit Configurations (UI)** from the Command Palette (`kb(workbench.action.showCommands)`). This view is a user interface for the `c_cpp_properties.json` file. Set the **Compiler path** field to the full path of the compiler you're using to build your project. For example, when using the default install path for GCC on Linux, the compiler path is `/usr/bin/gcc`. Set the **IntelliSense mode** to the architecture-specific variant of the compiler you're using. -### Option 3. Edit the `c_cpp_properties.json` file directly +### Option 3. Edit the c_cpp_properties.json file directly You can edit the `c_cpp_properties.json` file directly to customize your configuration. Use the **C/C++ Edit Configurations (JSON)** command from the Command Palette (`kb(workbench.action.showCommands)`), then the `c_cpp_properties.json` file is created in the `.vscode` folder of your workspace. + Use the `compilerPath` variable to add a compiler. This variable is the full path of the compiler you're using to build your project. For example, when using the default install path for GCC on Linux, the compiler path is `/usr/bin/gcc`. -For more information about the `c_cpp_properties.json` file, view the [schema reference](/docs/cpp/c-cpp-properties-schema-reference.md). +For more information about the `c_cpp_properties.json` file, review the [schema reference](/docs/cpp/c-cpp-properties-schema-reference.md). + +Select the sample below based on your operating system for a `c_cpp_configuration.json` file: -Select a tab to see some samples of a `c_cpp_configuration.json` file based on your operating system: +
+> Sample c_cpp_configuration.json on Windows +
+ +Using the default install path for MinGW: -Sample c_cpp_configuration.json on Windows -
-

Using the default install path for MinGW: ```json { "configurations": [ @@ -84,13 +88,14 @@ Select a tab to see some samples of a `c_cpp_configuration.json` file based on y "version": 4 } ``` -

-
-
-Sample c_cpp_configuration.json on Mac -
-

Using the default install path for clang: +

+
+
+> Sample c_cpp_configuration.json on macOS +
+Using the default install path for Clang: + ```json { "configurations": [ @@ -112,13 +117,14 @@ Select a tab to see some samples of a `c_cpp_configuration.json` file based on y "version": 4 } ``` -

- - -Sample c_cpp_configuration.json on Linux -
-

Using the default install path for GCC: +

+
+
+> Sample c_cpp_configuration.json on Linux +
+Using the default install path for GCC: + ```json { "configurations": [ @@ -144,49 +150,52 @@ Select a tab to see some samples of a `c_cpp_configuration.json` file based on y "version": 4 } ``` -

- - -## Project Level IntelliSense Configuration +
+ +## Project level IntelliSense configuration + +Configuring IntelliSense with a compiler provides you with core IntelliSense features. This setup is called the base configuration. For more complex usage scenarios, such as setting up a project that requires: -Configuring IntelliSense with a compiler provides you with core IntelliSense features. This steup is called the base configuration. For more complex usage scenarios, such as setting up a project that requires: +* Additional include paths, such as references to one or multiple different libraries +* Specific compiler arguments that influence the behavior of the language(and therefore IntelliSense) -- additional include paths, such as references to one or multiple different libraries -- specific compiler arguments that influence the behavior of the language(and therefore IntelliSense) +There are multiple other ways to configure IntelliSense. You can provide these additional configurations either through: -There are multiple other ways to configure IntelliSense. You can provide these additional configurations either through the `c_cpp_properties.json` file and related settings, a custom configuration provider in the form of another VS Code extension (for example, the [Makefile Tools](https://marketplace.visualstudio.com/items?itemName=ms-vscode.makefile-tools) or [CMake Tools](/docs/cpp/CMake-linux.md) extension), or a `compile_commands.json` file. +* The `c_cpp_properties.json` file and related settings +* A custom configuration provider in the form of another VS Code extension (for example, the [Makefile Tools](https://marketplace.visualstudio.com/items?itemName=ms-vscode.makefile-tools) or [CMake Tools](/docs/cpp/cmake-linux.md) extensions) +* A `compile_commands.json` file -### Configuration Providers +### Configuration providers -A custom configuration provider is another extension in VS Code which can potentially provide more accurate C++ IntelliSense configuration than the C/C++ Extension. For example, for the CMake or Make build systems, where the [Makefile Tools](https://marketplace.visualstudio.com/items?itemName=ms-vscode.makefile-tools) or [CMake Tools](/docs/cpp/CMake-linux.md) extensions can be configuration providers. To add an extension as a configuration provider, either select the extension through the configuration quick pick, add it to configuration UI by editing the **Configuration provider** field under **Advanced Settings**, or add the `configurationProvider` field to your `c_cpp_properties.json` file. For example, for the CMake extension, the path to add would be `ms-vscode.cmake-tools`. +A custom configuration provider is another extension in VS Code that can potentially provide more accurate C++ IntelliSense configuration than the C/C++ extension. For example, for the CMake or Make build systems, where the [Makefile Tools](https://marketplace.visualstudio.com/items?itemName=ms-vscode.makefile-tools) or [CMake Tools](/docs/cpp/cmake-linux.md) extensions can be configuration providers. To add an extension as a configuration provider, either select the extension through the configuration Quick Pick, add it to configuration UI by editing the **Configuration provider** field under **Advanced Settings**, or add the `configurationProvider` field to your `c_cpp_properties.json` file. For example, for the CMake extension, the path to add would be `ms-vscode.cmake-tools`. -The C/C++ Extension scans your system for custom configuration providers. If it identifies only one custom configuration provider, this configuration provider is automatically configured for IntelliSense. If there are multiple configuration providers identified, you need to select which the Extension should use by opening [the configuration quick pick](/docs/cpp/configure-intellisense.md#_Option-1.-Select-a-configuration-option-through-the-configuration-quick-pick). +The C/C++ extension scans your system for custom configuration providers. If it identifies only one custom configuration provider, this configuration provider is automatically configured for IntelliSense. If there are multiple configuration providers identified, you need to select which the extension should use by opening the [configuration Quick Pick](#option-1-select-a-configuration-option-through-the-configuration-quick-pick). -### `compile_commands.json` File +### compile_commands.json file -Another option to provide intelliSense configuration is a [`compile_commands.json` file](https://clang.llvm.org/docs/HowToSetupToolingForLLVM.html), which describes the exact compile commands used for every file in a project. This file is often generated by a build system, such as CMake or Bazel, by setting command line arguments when configuring your project. A `compile_commands.json` file can be selected for configuration through the same methods as discussed in the [How to configure IntelliSense section](/docs/cpp/configure-intellisense.md#_How-to-configure-IntelliSense): through the configuration quick pick, editing configurations through the UI, or editing the `c_cpp_properties.json` file directly. In the configuration UI, the file can be added under Advanced Configurations and the **Compile commands** field. For example, if your `compile_commands.json` file is in the root of your workspace, enter `${workspaceFolder}/compile_commands.json` in the **Compile commands** field. Otherwise, it can be added to the `c_cpp_properties.json` file directly using the `compileCommands` configuration property. +Another option to provide IntelliSense configuration is a [compile_commands.json](https://clang.llvm.org/docs/HowToSetupToolingForLLVM.html) file, which describes the exact compile commands used for every file in a project. This file is often generated by a build system, such as CMake or Bazel, by setting command line arguments when configuring your project. A `compile_commands.json` file can be selected for configuration through the same methods as discussed in the [How to configure IntelliSense](#how-to-configure-intellisense) section via the configuration Quick Pick, editing configurations through the UI, or editing the `c_cpp_properties.json` file directly. In the configuration UI, the file can be added under **Advanced Configurations** and the **Compile commands** field. For example, if your `compile_commands.json` file is in the root of your workspace, enter `${workspaceFolder}/compile_commands.json` in the **Compile commands** field. Otherwise, it can be added to the `c_cpp_properties.json` file directly using the `compileCommands` configuration property. -If the compile commands database does not contain an entry for the translation unit that corresponds to the file you opened in the editor, your base configuration (found in `c_cpp_properties.json`) is used instead (such as your `includePath` and `defines`). If the C/C++ Extension is reverting to the base configuration, the [language status bar indicator](/docs/cpp/configure-intellisense.md#_Option-1:-Check-for-a-status-bar-indicator) will show you the label **Configure IntelliSense** in the status bar. +If the compile commands database does not contain an entry for the translation unit that corresponds to the file you opened in the editor, your base configuration (found in `c_cpp_properties.json`) is used instead (such as your `includePath` and `defines`). If the C/C++ extension reverts to the base configuration, the [language status bar indicator](#check-intellisense-activity-using-the-language-status-bar) shows you the label **Configure IntelliSense** in the status bar. If you specified a custom configuration provider and a `compile_commands.json` file, the custom configuration provider is queried first for an IntelliSense configuration. If your program includes header files that aren't in your workspace or that aren't in the standard library path, you can modify the **Include Path**. The C/C++ extension populates the include path by querying the compiler specified by **Compiler path**. If the extension can't find the path for the target system libraries, you can enter the include path manually. -### Checking IntelliSense activity using the language status bar +### Check IntelliSense activity using the language status bar -You can determine if IntelliSense is actively working on your file using the language status bar. To invoke the language status bar, open a C++ file. Note that the status bar shows the text **{} C++**. Hover over the **{}** symbol to open the language status bar flyout. The top item in the flyout indicates the IntelliSense status. Here are the different statuses and their meanings: +You can determine if IntelliSense is actively working on your file using the language status bar. To invoke the language status bar, open a C++ file. The status bar shows the text **{} C++**. Hover over the **{}** symbol to open the language status bar flyout. The top item in the flyout indicates the IntelliSense status. Here are the different statuses and their meanings: -- **IntelliSense: Ready** = IntelliSense is configured for the C/C++ Extension and automatically activates if you interact with the editor, for example, by writing code. -- **IntelliSense: Updating** = IntelliSense is actively working to determine any code completions, syntax highlighting, etc. based on changes you're making to your code. +* **IntelliSense: Ready** = IntelliSense is configured for the C/C++ extension and automatically activates if you interact with the editor, for example, by writing code. +* **IntelliSense: Updating** = IntelliSense is actively working to determine any code completions, syntax highlighting, etc. based on changes you're making to your code. -![language-status-bar](images/intellisense/language-status-bar.png) +![C++ extension language status bar flyout](images/intellisense/language-status-bar.png) You can select the pin icon on the right of any item in the language status bar flyout to permanently pin it to your status bar. ## Next steps -- For more information about IntelliSense configuration, see [Customizing default settings](/docs/cpp/customize-default-settings-cpp.md). -- If you have trouble configuring the settings, please start a discussion at [GitHub discussions](https://github.com/microsoft/vscode-cpptools/discussions), or if you find an issue that needs to be fixed, file an issue at [GitHub issues](https://github.com/microsoft/vscode-cpptools/issues). -- Explore the [c_cpp_properties schema](/docs/cpp/c-cpp-properties-schema-reference.md). -- Review the [Overview of the C++ extension](/docs/languages/cpp.md). +* For more information about IntelliSense configuration, see [Customizing default settings](/docs/cpp/customize-default-settings-cpp.md). +* If you have trouble configuring the settings, please start a discussion at [GitHub discussions](https://github.com/microsoft/vscode-cpptools/discussions), or if you find an issue that needs to be fixed, file an issue at [GitHub issues](https://github.com/microsoft/vscode-cpptools/issues). +* Explore the [c_cpp_properties schema](/docs/cpp/c-cpp-properties-schema-reference.md). +* Review the [Overview of the C++ extension](/docs/languages/cpp.md). From ebdaea2c84b1f7e5b2e4bc7c1b15345c87da2eb5 Mon Sep 17 00:00:00 2001 From: Greg Van Liew Date: Mon, 6 Nov 2023 14:23:18 -0800 Subject: [PATCH 2/2] reverse order of UI text --- docs/cpp/configure-intellisense.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cpp/configure-intellisense.md b/docs/cpp/configure-intellisense.md index 823a781d37..c4c816e2e7 100644 --- a/docs/cpp/configure-intellisense.md +++ b/docs/cpp/configure-intellisense.md @@ -39,7 +39,7 @@ Open the Quick Pick by entering **Select IntelliSense Configuration** in the Com ![Select a compiler to configure for IntelliSense Quick Pick](images/intellisense/compiler-quick-pick.png) -Select one of the options available. If you select a compiler, this compiler is used by IntelliSense by default. You can return to the **IntelliSense Configuration** Quick Pick at any point to change which option is used to configure IntelliSense. +Select one of the options available. If you select a compiler, this compiler is used by IntelliSense by default. You can return to the **Configure IntelliSense** Quick Pick at any point to change which option is used to configure IntelliSense. If no options are available in the Quick Pick, no compiler could be identified in your system. You can browse your machine manually or install a C/C++ compiler. To install on a Windows machine, select the **Help me install a compiler** option that redirects you to the step-by-step walkthrough of how to install a C/C++ compiler. On a macOS or Linux machine, select **Install a compiler** and navigate through the prompts to have a C++ compiler installed on your machine.