Why do I care?
The more information Understand has about include paths and macro configuration, the more closely your Understand project will match your compiled code. In most cases, Understand does a great job of parsing the code and figuring out what goes where, but sometimes there are things you don’t expect in your project. This article show several different approaches to enhancing the accuracy of your projects. Our partner, Emenda, has also written an article that walks through setting up a project you can read here.
Some symptoms the project configuration may need to be improved:
- Chunks of inactive (pink) code that should be getting parsed but are not:
- The same entity shows up multiple times, with some of those definitions unresolved(gray)
- Missing entities in graphs
Potential Solutions
Strict or Fuzzy Parsing
Understand lets you chose between two different types of parsing when creating C/C++ projects. The fuzzy parse is not as accurate but is great if the code doesn’t compile or for making an initial pass of the project with Understand. The strict parser requires that the include paths and macros be setup correctly, as outlined below, but in return will provide a very accurate parse. Objective-C and Objective-C++ both require use of the strict parser. Also if your project makes heavy use of Templates or Overloaded functions, you will want to use the Strict Parser.
Choose Compiler Options
It’s important to set the Compiler Options correctly. By configuring the right Compiler details, many Macros, Pragmas and Include Paths are automatically added to the project and increase the accuracy. It is important to note that not all environments will be supported with the strict parser, so look closely at the settings that are accessed under Project->Configure Project->C++ or C++(Strict) to see if your environment is supported.
Setting up Strict
In most situations, OS and Env should be set to the target machine, but there are certain assumptions that go along with this idea. If the user is developing on a Windows system, but they are building a program for a Linux operating system using GNU, Understand assumes the appropriate libraries are available on the Windows system. If the user selects Linux and GNU, Understand is going to look for library files in a different location than if the user selected Windows and MSVC. If Understand can’t find the correct header files, then the analysis will generate errors and those errors will disrupt the behavior of Understand.
There is a different selection of header files available for GCC and MSVC, but many of the headers are the same across different platforms. So long as compiler specific MACROs and headers aren’t being used, there shouldn’t be any harm in using the header files available on the development system to increase project accuracy. If compiler specific headers and MACROs are to be used, then the appropriate dependencies need to be installed on the user’s machine before the analysis errors can be resolved.
One thing to always adhere to is that the strict project must be setup and analyzed with zero errors. If a strict project analysis results with errors and they are referencing files that you aren’t looking into, it doesn’t mean that they are not important to the results. It is pertinent that the errors not be ignored as it likely has a very significant impact on the entire project. File not found errors are fatal (subsequent errors are not reported) and they frequently obscure more fundamental issues.
Setting up Fuzzy
Fuzzy is much simpler to set up, but as mentioned earlier, not as accurate. Simply specify which compiler you would like to use and the compiler include paths. If your compiler is not shown, email us at [email protected] and we’ll see what we can do.
Visual Studio
If you use Visual Studio, you can specify the Visual Studio solution or project files directly and Understand will gather all the information from them. Those files can be specified during the Project Creation wizard or in Project->Configure Project->Visual Studio. It can also help to launch Understand from the Visual Studio command prompt so it will look for the right include files. Start->Microsoft Visual Studio->Tools->Command Prompt then just type “understand” to launch it if it’s on your PATH.
Here is a short video on creating a new Visual Studio project with the New Project Wizard:
GCC/G++
If your project builds with GCC or G++, you can use the new Buildspy feature to hook into the build system and gather the correct data for the Understand project. More details on configuring Buildspy here.
CMake
If your team uses the cross-platform build system, CMake, follow the directions here to create an Understand project as it compiles.
Or, watch this short video on how to create a new CMake project with the New Project Wizard:
JSON and BEAR
Understand projects can also be created by using .json files. CMake and BEAR can be used to create accurate projects from compile commands. More information can be found here and an article showing an example of one of our engineers using BEAR to create an Understand project can be found here.
Import a log file
If your compiler can generate a log file, it can be imported into an understand project via the command line tool und. A log file is recognized by the extension “log” and has two available switches.
-cc specifies the c compiler
-cxx specifies the c++ compiler
So the command to create a new project, import the log file and analyze it would be:
> und create -languages C++ add mybuildlogfile.log -cc /usr/gcc -cxx /usr/g++ analyze myUnderstandProj.und
Manually Setting Includes and Macros
If your project doesn’t support any of the above options, you can manually configure the Includes and Macros for the project. We’ve added a couple of new tools to identify the missing bits and make this process more intuitive.
Missing Includes
Missing include directories can be added in Project->Configure Project->C++ ->Includes. The new “Search” button opens a dialog that let’s you quickly identify where the missing search files are and add those directories to the include paths for your project.
Missing Macros
Similarly, Missing Macros can be added via Project->Configure Project->C++ ->Macros. The new “Undefined Macros” button opens a dialog that will let you quickly identify macros that may be missing from the project and you can specify their definitions. To manually add a macro select Project->Configure Project->C++ ->Macros and select ‘New’. In the dialog put the name of the macro without spaces, and the definition, if there is one. The Definition can be left blank to define compiler dependencies and to set a macro to “true”.
Overrides
In some cases, individual files or directories have their own macros and include paths that are different from other parts of the project. These can be specified by going to the file or folder in question in
Project->Configure Project->Files. Right click on it, and select Configure override settings. From that dialog you can add the specifics.
Conclusion
Understand does a great job of parsing projects “out of the box” but if the project is more complex, there are a lot of options for adding more detail to the project configuration and ending up with a perfect analysis.