Archive for the ‘Tips’ Category
Last year I posted about Improving Project Accuracy for C/C++ projects. Since then, we have released several new features that make it easier to get accurate project definitions.
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. These settings 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.
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.
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.
If your team uses cmake to build your projects, you can use it to generate your Understand project. It will add all of the files, setup the correct macro definitions for each file, and setup the correct include files for each file in the project. The advantage of creating an Understand project like this is that the project will be much more accurate than can be created by hand, allowing you to have easier access to all the features of our new strict parser.
In order to use this,
- Navigate to your build directory
- Edit CMakeCache.txt and set CMAKE_EXPORT_COMPILE_COMMANDS to ON.
- Run make again, you’ll see a file called compile_commands.json in your build directory.
- To import into an understand project run the following from the command line (skip the red part for existing projects):
und -db path/to/db.udb create -languages C++ add path/to/build/dir/compile_commands.json settings -c++AddFoundFilesToProject on analyze
Update – On Windows you must use the NMake Makefiles generator. For example:
cmake -G "NMake Makefiles" -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
Many users have asked us in the past if Understand could have better support for Templates and Overloaded functions. We are excited to announce that this is now a reality. Our engineers have worked hard to add a completely new C++ parser to Understand, which is available for Beta testing in build 586.
Our current C++ parser was written with the goal of being able to use fuzzy logic to handle incomplete, non-compiling code gracefully and as accurately as possible. It does a great job at that and will continue to be an important part of our toolset. Unfortunately that same feature caused severe difficulties in parsing templates and recognizing overloaded functions. The new parser is more strict than the old parser and requires a more accurate project definition. If you plan on using it, please follow the instructions from this post to ensure your project is as correct as possible: Improving Project Accuracy (C/C++)
To access the new parser, just check the new checkbox on the Languages screen when creating a new project or in the Project Configuration dialog.
We welcome and appreciate your feedback and comments on this new parser – please send it to us at firstname.lastname@example.org
We’ve made a few changes to how keyboard shortcuts are managed with build 586.
Key Bindings can still be accessed via Tools->Options->Key Bindings but this page now lets you search for key binding, either by name or by the actual keystrokes. This page also has all of the key bindings in one place for easy browsing. The other change was to add a separate page for each Component(Category) of key bindings in the navigation pane.
While these are relatively small changes, we hope they will make life easier for those who rely heavily on keyboard navigation.
Usually just identifying the root of your source tree and saying "Analyze" will provide you with a accurate, useful Understand project. Sometimes, however, you need a more accurate representation of your project. Maybe you have large swaths of inactive code that should be enabled, maybe there are grayed out (unresolved) entities that do exist in the source code, or maybe the metrics don’t seem to line up. In cases like this, you will want to use some of the advanced C++ options to fine tune the parse. Here are some things that will improve the parse accuracy.
After printing the Class Dependencies Report (Reports->Dependency->Class Dependencies), we see some headers, with relating numbers that might be confusing as to what exactly they mean. The Dependency Browser can be very useful in seeing the actual dependencies and what they relate to, so I am going to use the Java sample project (getopt) that comes with Understand, the csv file, and the Dependency Browser, to explain the dependencies shown.
The Dependency Browser shows the Class: GetoptDemo on the left side, and it depends on Getopt and LongOpt (shown on the right of the Dependency Browser, and also in the ‘To Class’ column of the csv file). In Getopt there are 13 References, and LongOpt there are 12 References. Both of which are shown in the References column and on the right side of the Dependency Browser.
Many teams want to quickly generate Understand’s HTML reports and metrics as part of their regular build process. The new version of the command line tool ‘und’ provides a lot of options for doing exactly this. In this case, I am going to create an Understand project from the latest version of my source code, and generate the html reports and metrics for that version of the code. Since the new version of und has several different modes, I will show how this would be done in each mode.
As of build 523, the .udb extension on Windows is associated with Understand and when a .udb file is double clicked it will open the Understand Project. Some users have asked for similar functionality with code files. In the past if you setup Understand to open a code file, by default it would open a new instance of Understand. As of build 525 it will open up in the existing instance of Understand instead of a new one. Keep reading for instructions on registering Understand to open code files.