Creating Accurate C/C++ Projects
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.
Some symptoms the project configuration may need to be improved:
1. Chunks of inactive (pink) code that should be getting parsed but are not:
2. The same entity shows up multiple times, with some of those definitions unresolved(gray)
3. Missing entities in graphs
Strict or Fuzzy Parsing
Understand now let’s 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 the strict parser. Also if your project makes heavy use of C++ or Overloaded functions you will want to use the Strict Parser.
Choose Compiler Options
It’s important to double check the Compiler Options and make sure they are set 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 know 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).
Automatically Set Includes and Macros
Depending on your build system, Understand may be able to extrapolate the Include and Macro information automatically.
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.
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, or there is a video here to get you started.
If your team uses the cross-platform build system, CMake, follow the directions here to create an Understand project as it compiles.
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.udb
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 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.
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.
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.
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.