Configuring C++ IntelliSense and Browsing
Whether you are creating a new (or modifying an existing) C++ project using a Wizard, or importing an project into Visual Studio from another IDE, it’s important to configure the project correctly for the IntelliSense and Browsing features to provide accurate information. This article provides some tips on configuring the projects and describes a few ways that you can investigate configuration problems.
Include Paths and Preprocessor Macros
The two settings that have the greatest effect on the accuracy of IntelliSense and Browsing operations are the Include Paths and the Preprocessor macros. This is especially important for projects that are built outside of Visual Studio: such a project may build without any errors, but show squiggles in Visual Studio IDE.
To check the project’s configuration, open the Properties for your project. By default, All Configurations and All Platforms will be selected, so that the changes will be applied to all build configurations:
If some configurations do not have the same values as the rest, then you will see <different options>. If your project is a Makefile project, then you will see the following properties dialog. In this case, the settings controlling IntelliSense and Browsing will be under NMake property page, IntelliSense category:
Error List
If IntelliSense is showing incorrect information (or fails to show anything at all), the first place to check is the Error List window. It could happen that earlier errors are preventing IntelliSense from working correctly. To see all the errors for the current source file together with all included header files, enable showing IntelliSense Errors in the Error List Window by making this selection in the dropdown:
IntelliSense limits the number of errors it produces to 1000. If there are over 1000 errors in the header files included by a source file, then the source file will show only a single error squiggle at the very start of the source file.
Validating Project Settings via Diagnostic Logging
To check whether IntelliSense compiler is using correct compiler options, including Include Paths and Preprocessor macros, turn on Diagnostic Logging of IntelliSense command lines in Tools > Options > Text Editor > C/C++ > Advanced > Diagnostic Logging. Set Enable Logging to True, Logging Level to 5 (most verbose), and Logging Filter to 8 (IntelliSense logging):
The Output Window will now show the command lines that are passed to the IntelliSense compiler. Here is a sample output that you may see:
[IntelliSense] Configuration Name: Debug|Win32 [IntelliSense] Toolset IntelliSense Identifier: [IntelliSense] command line options: /c /I. /IC:\Repo\Includes /DWIN32 /DDEBUG /D_DEBUG /Zc:wchar_t- /Zc:forScope /Yustdafx.h
This information may be useful in understanding why IntelliSense is providing inaccurate information. One example is unevaluated project properties. If your project’s Include directory contains $(MyVariable)\Include, and the diagnostic log shows /I\Include as an Include path, it means that $(MyVariable) wasn’t evaluated, and was removed from the final include path.
IntelliSense Build
In order to evaluate the command lines used by the IntelliSense compiler, Visual Studio launches an IntelliSense-only build of each project in the solution. MSBuild performs the same steps as the project build, but stops short of executing any of the build commands: it only collects the full command line.
If your project contains some custom .props or .targets files, it’s possible for the IntelliSense-only build to fail before it finishes computing the command lines. Starting with Visual Studio 2017 15.6, errors with IntelliSense-only build are logged to the Output window, Solution Pane.
An example error you may see is: error: Designtime build failed for project 'E:\src\MyProject\MyProject.vcxproj', configuration 'Debug|x64'. IntelliSense might be unavailable. Set environment variable TRACEDESIGNTIME=true and restart Visual Studio to investigate.
If you set the environment variable TRACEDESIGNTIME to true and restart Visual Studio, you will see a log file in the %TEMP% directory which will help diagnose this error:
C:\Users\me\AppData\Local\Temp\MyProject.designtime.log : error : Designtime build failed for project 'E:\src\MyProject\MyProject.vcxproj', configuration 'Debug|x64'. IntelliSense might be unavailable.
To learn more about TRACEDESIGNTIME environment variable, please see the articles from the Roslyn and Common Project System projects. C++ Project System is based on the Common Project System, so the information from the articles is applicable to all C++ projects.
Single File IntelliSense
Visual Studio allows you to take advantage of IntelliSense and Browsing support of files that are not part of any existing projects. By default, files opened in this mode will not display any error squiggles but will still provide IntelliSense; so if you don’t see any error squiggles under incorrect code, or if some expected preprocessor macros are not defined, check whether a file is opened in Single-File mode. To do so, look at the Project node in the Navigation Bar: the project name will be Miscellaneous Files:
Investigating Open Folder Issues
Open Folder is a new command in Visual Studio 2017 that allows you to open a collection of source files that doesn’t contain any Project or Solution files recognized by Visual Studio. To help configure IntelliSense and browsing for code opened in this mode, we’ve introduced a configuration file CppProperties.json. Please refer to this article for more information.
CppProperties.json Syntax Error
If you mistakenly introduce a syntax error into the CppProperties.json file, IntelliSense in the affected files will be incorrect. Visual Studio will display the error in the Output Window, so be sure to check there.
Project Configurations
In Open Folder mode, different configurations may be selected using the Project Configurations toolbar.
Please note that if multiple CppProperties.json files provide differently-named configurations, then the selected configuration may not be applicable to the currently-opened source file. To check which configuration is being used, turn on Diagnostic Logging to check for IntelliSense switches.
Single-File IntelliSense
When a solution is open, Visual Studio will provide IntelliSense for files that are not part of the solution using the Single-File mode. Similarly, in Open Folder mode, Single-File IntelliSense will be used for all files outside of the directory cone. Check the Project name in the Navigation Bar to see whether the Single-File mode is used instead of CppProperties.json to provide IntelliSense for your source code.
Investigating Tag Parser Issues
Tag Parser is a ‘fuzzy’ parser of C++ code, used for Browsing and Navigation. (Please check out this blog post for more information.)
Because Tag Parser doesn’t evaluate preprocessor macros, it may stumble while time parsing code that makes heavy use of them. When the Tag Parser encounters an unfamiliar code construct, it may skip a large region of code.
There are two common ways for this problem to manifest itself in Visual Studio. The first way is by affecting the results shown in the Navigation Bar. If instead of the enclosing function, the Navigation Bar shows an innermost macro, then the current function definition was skipped:
The second way the problem manifests is by showing a suggestion to create a function definition for a function that is already defined:
In order to help the parser understand the content of macros, we have introduced the concept of hint files. (Please see the documentation for more information.) Place a file named cpp.hint to the root of your solution directory, add to it all the code-altering preprocessor definitions (i.e. #define do_if(condition) if(condition)) and invoke the Rescan Solution command, as shown below, to help the Tag Parser correctly understand your code.
Coming soon: Tag Parser errors will start to appear in the Error List window. Stay tuned!
Scanning for Library Updates
Visual Studio periodically checks whether files in the solution have been changed on disk by other programs. As an example, when a ‘git pull’ or ‘git checkout’ command completes, it may take up to an hour before Visual Studio becomes aware of any new files and starts providing up-to-date information. In order to force a rescan of all the files in the solution, select the Rescan Solution command from the context menu:
The Rescan File command, seen in the screenshot above, should be used as the last diagnostic step. In the rare instance that the IntelliSense engine loses track of changes and stops providing correct information, the Rescan File command will restart the engine for the current file.
Send us Feedback!
We hope that these starting points will help you diagnose any issues you encounter with IntelliSense and Browsing operations with Visual Studio. For all issues you discover, please report them by using the Help > Send Feedback> Report A Problem command. All reported issues can be viewed at the Developer Community.
Light
Dark
0 comments