Diving into the API documentation can be a little overwhelming, so here is a collection of tutorials to get you started.
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.
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:
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.
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)
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.
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.
We have added a new feature to this weekend’s build (623) of Understand called Buildspy that allows gcc/g++ users to create an Understand project during the build. Buildspy picks up files, includes, and macros from the compiler so you don’t have to enter them manually. This can save time and improve project accuracy.
To use Buildspy, you first need to change your compiler from gcc/g++ to gccwrapper/g++wrapper in your makefile or build system. Alternatively, it is possible to override these settings from the command line without having to touch the Makefile using the following command:
buildspy –db example.udb –cmd “make <additional_Make_Options>”
You may also need to add the /SciTools/bin/linux32/buildspy directory to your path.Then, starting with a clean build, run:
buildspy –db path/name.udb –cmd <command to compile project>
For example:
Or, to override the makefile settings:
This allows Buildspy to receive information from gccwrapper/g++wrapper to build a complete project. The wrappers will then call the corresponding compiler. To change the compiler edit the configuration file located at $HOME/.config/SciTools on Linux systems and $HOME/Library/Preferences on Mac.
The wrappers will work with any compiler that has gcc-like syntax. To finish, simply open the project in Understand and Analyze All. Those tedious includes and macros are now set.
Cygwin/Windows Users
We have added support for Buildspy on Windows using Cygwin as of build 633. However, when the buildspy command results in this error:
gcc – Process failed to start: Access is denied.
extra setup is required. Cygwin uses a symlink to access the gcc executable and the actual name of the executable is required in the configuration file. Trace the symlink until the executable is found in order to get the actual name. In my case, the executable was named gcc-3.
On Windows the configuration file is located in C:\Users\<USERNAME>\AppData\Roaming\SciTools and is called Buildspy.ini. Open the Buildspy.ini file and change the compiler name appropriately.
Once this is done, Buildspy should work as expected.
Any feedback on this new feature is welcome and appreciated.
Some customers have asked us to provide test files for validating the output of CodeCheck feature. For example, Avionics teams using DO-178B can use it for Tool Qualification. The attached file includes a test suite for each of the CodeCheck Checks, as well as a script that uses our Perl API to automatically run each of the Checks on the corresponding test suite. Before running the script, modify the paths at the beginning to point to the appropriate location, then simply run it from the command line with uperl codecheck_validation.pl
As always, let us know if you run into any questions or problems – support@scitools.com
Codecheck Validation Tests: DOWNLOAD (Updated Dec 7, 2012)
With build 596 we’ve added support to Understand for Objective-C and Objective-C++, and we would love your feedback on it. This support is added as part of the new strict analyzer, so make sure your project is fully configured to get an accurate parse. Please point Understand and your Objective-C code, and if you run into any problems or questions, shoot us an email – support@scitools.com
CodeCheck can be set up to run from the command line using Und if that is your preferred work environment, or if you are looking to automate the task. To see all of the options available in Und, run und help. For specific documentation on each option run und help optionName.
To run CodeCheck from the command line, first you will need to export the CodeCheck configuration file from the Understand GUI that has the checks you wish to run selected.
Once that is saved to a file, the command line option is
und codecheck C:\path\to\configuration.ini C:\path\to\OutputDir
–db C:\path\to\UnderstandProject.udb
Where configuration.ini is my saved configuration file, the results are saved to the OutputDir, and it is running the checks on UnderstandProject.udb.
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 support@scitools.com
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.
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.
![python-logo[1]](http://www.scitools.com/blog/wp-content/uploads/2011/08/pythonlogo1.gif "python-logo[1]")
Understand now fully supports Python access to its underlying database! The new Python API allows you to write your own scripts that can create custom reports, generate your own metrics and in general make Understand deliver exactly what you want it to.
The Python API runs on your 3.x installation of Python, you can grab it from here if you need to install it.
Once you have Python installed you need to tell it where the Understand module is. The easiest way to do that is to add/modify the PYTHONPATH environment variable to include the module location, which is SciTools/bin/<System>/python. Also if you did not add Understand to the Path variable during installation, you will need to add the SciTools/bin/<System> directory to PATH.
Finally, to use the API you will need to put ‘import Understand’ in your script.
The most up-to-date documentation will ship with Understand and can be accessed from the Python Console with:
import understand
help (understand)
A more readable version can be obtained with the python ‘pydoc’ command, which can generate an html version of the documentation. We also try to keep a current version of the Python documentation on the Manuals page.
The documentation includes some samples. More detailed example scripts are shipped with Understand in the SciTools/scripts/python folder.
Happy Scripting!
