To enable this option go into Tools->Options->Editor->Advanced->Unused Entities

Right now this only works for functions and variables. Let us know if you find it useful, and if there are other entities you want it added for.

Update April,26 2012 – I’ve made some extensive changes to this script to improve performance and remove repeated results

In order to use this,

1. Navigate to your build directory
2. Edit CMakeCache.txt and set CMAKE_EXPORT_COMPILE_COMMANDS to ON.
3. Run make again, you’ll see a file called compile_commands.json in your build directory.
4. 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

As an extra incentive, they are offering a free license to the first 3 Understand users who demo one of their tools and send an exported image such as the one below of any part of their code or an Open Source project. Just send it to hwsupport@headwaysoftware.com and tell them Kevin sent you

To be fair to another great partner, Lattix can also import your Understand projects and is a great tool for organizing and refactoring your code, so give them a look.

If your team uses CodeCheck heavily, you will definitely want to upgrade to this build since it fixes some related crashes.  

Build Notes

As always, let us know if you run into any questions or problems – support@scitools.com

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  

Where configuration.ini is my saved configuration file and the results are saved to the OutputDir. 

We are still in scenic St George, near Zion National Park and less than two hours from Vegas. If you are in the area feel free to stop by and visit us!

Our new address is:

Scientific Toolworks, Inc.
249 East Tabernacle, Suite 200
St George, UT 84770

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

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.

In India? Give them a ring:

Meteonic
www.meteonic.com
Tel: +91-9980070704, +91-080-40874900
moumita@meteonic.com

Set the Compiler

Under Project->Configure Project -> C++ Options there is a section that allows you to set your compiler and the location of your Compilers include files. Setting these two options to the correct settings will provide the default pragmas and macros as well as include files that your project needs. In many cases just performing this one step will be all you need to do to get the accuracy you are after.

Set Include Paths

Your project probably depends on header files from other places, both system header files, like time.h, and those to your own team’s libraries.  The easiest way to identify these header files is to expand the parse log while Understand is parsing, and hit the "Include Paths" button. This will open the Parse Improvement Tool that lets you search for and quickly find missing include paths. These include paths can also be specified in Project->Configure Project -> C++ -> Includes.

Found include files are not added to the project unless you specify the option to do so. Instead Understand will parse those files and record the Macro definitions, types, include paths, and other data that pertains to your projects source files. So when you view information on a class that is used in your project, but defined elsewhere, Understand can now answer questions about it.

Set Macros

While in the parse log, you can also add definitions for undefined macros which will completely change how the code is analyzed. You can define macros at the project level, folder level, or just for a particular file. The new tool for specifying macros makes it very easy to identify how often and where a macro is used. That will let you know which ones are most critical to define for an accurate parse. The macros can also be defined in the Project->Configure Project -> C++ -> Macros page.

Set File Types

If you have non standard file extensions, you will want to set them under Project->Configure Project->File Types screen. That will ensure that they get parsed correctly. Also, if your project is pure C, you may want to change the appropriate extensions to parse with C instead of C++. This can lead to a more accurate parse for C files.

Disable the Include Cache

Project->Configure Project->C++ Options has an option to "Use the Include Cache". This significantly speeds up parsing by caching the values of a file the first time it is looked at. In reality though, every time a file is parse by the compiler its contents can change dynamically based off the context it was included in. Disabling the include cache by unchecking the box will make the parse time slower, but will lead to a more accurate parse.

The ‘To Entities’ column shows the specific entities that depend on GetoptDemo.  So, expanding the tree on the right side of the Dependency Browser shows the 8 entities that GetoptDemo depends on in Getopt, and the 6 entities that GetoptDemo depends on in LongOpt.

The From Entities is the number of entities in GetoptDemo that have dependencies.  By going to the method GetoptDemo on the left side of the Dependency Browser, and expanding the dependencies on that method in the right side of the Browser, we see that there is 1 dependency in Getopt, and 1 dependency in LongOpt.

Now, continue to look at the ‘From Entities’ on the left side of the Dependency Browser by looking at Variable: g, expand the tree on the right and see that it depends on Getopt.  Which brings the number of From Entities for Getopt from 1 to 2.

Finally, look at the last entity for GetoptDemo on the left, ‘Variable: longopts’, expand the tree on the right and see that it Depends on LongOpt, which brings the number of From Entities from 1 to 2 for LongOpt.

Hopefully this sample clarifies the Class Dependencies csv report.

Getting Started

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.

Documentation

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.

Sample Scripts

The documentation includes some samples. More detailed example scripts are shipped with Understand in the SciTools/scripts/python folder.

Happy Scripting!

As with the dependency graphs, you can change what data these graphs display by using the graph customizer pane, to the right of the graphs. With this, you can show and hide nodes and edges, highlight nodes and edges of interest, and aggregate edges going into a file or architecture.

We hope this graph will provide a useful tool in helping you visual your code.

After the parse is complete the parse log will have a new button, Undefined Macros, that leads to this new tool. You can access the previous parse log from the View menu if you have already closed it.

And you get the Undefined Macros dialog, which lets you sort and filter the list of macros that are referenced in your project but not defined. It also shows the number of times that macro is used and the number of files it is used in. To give a macro a global definition, simply select it and enter the new value in the text box near the bottom.

If the macro needs to have different values in different folders or files, the Detail View button at the bottom will provide access to the the Override dialog that will let you specify the value for a macro for any file or folder.

Once you have sent the macro values you want, the save button will prompt you to reparse the project, and large swaths of inactive (pink) code will be activated and the results of the analysis will be even more accurate.

Interactive Mode

Interactive mode is not want you want to use for automating a process, but is useful for testing commands and quick tasks. Running through these commands in interactive mode is a good test to make sure everything is configured the way you want.

If you need to customize these commands more, und help and und help <command> provide thorough documentation. Or feel free to contact us at support@scitools.com

Batch Mode

Once you have identified the commands you want to run using interactive mode,  place those exact commands in a text file. No need to include the first und command and the quit command, those are handled automatically.

Then all you have to do is run:

und myCommands.txt

and all the commands in the file will be processed in order. In previous versions of und the project database was opened and closed between each command, when many commands were run on large projects, this could cause significant slowdown. In the new version of und the database stays opened in Interactive and Batch Mode leading to much quicker results.

Line Mode

Single line mode lets you run each command directly in the shell. The Understand database is opened and closed for each command and needs to be specified on each line. It can be specified with the –db parameter, or included as the last parameter. So doing the same thing in Single Line Mode would look like:

>und create -languages C++ c:\project.udb
>und add c:\path\to\src c:\project.udb
>und analyze c:\project.udb
>und settings -reportOutputDirectory c:\htmlDir c:\project.udb
>und report c:\project.udb
>und settings -metrics all c:\project.udb
>und settings -metricsOutputFile c:\metrics.csv c:\project.udb
>und metrics c:\project.udb

Again, this method is a little slower since it opens the database each command, but depending on your build process, it may be easier to implement.

Single Line Mode

The same commands can all be run on the same line if desired, which will only open the database once and will be faster, although harder to read. The commands will run in the order entered.

>und -db c:\project.udb create -languages C++ add c:\path\to\src analyze settings -reportOutputDirectory c:\htmlDir report settings -metrics all settings -metricsOutputFile c:\metrics.csv metrics

The commands have been standardized and the tool should be much easier to use. Because of the extensive changes, this new version is not backwards compatible with older versions of und. The old und will still ship and has been renamed ‘undlegacy’ – current users will need to change the name of the binary for scripts to continue to work.

In general the syntax for running commands are similar to Subversion and should be much more intuitive than previous versions.

The new version also includes a cool new interactive mode that lets you specify a database and then continually run commands in it, similar to MySQL.

The help documentation has been flushed out extensively and should be much more useful – just run und help for a complete overview of how to use this great new tool. Also this post steps through each different method of using und and demonstrates some of the most common commands: Integrate Understand with your build system.

The above dialog will appear on the parse log after analyzing your project, you can also access the log via View->Last Parse Log

Once you hit the Improve Parse button, you will be presented with a list of include files referenced but not found in the project:

Hit the Search button to begin finding those files. You will be presented with this dialog:

Where you can navigate to a directory where the missing files reside, or select a directory that contains header files and hit the large Search button to descend through it looking for missing include files.

Select the directories you want to add, and they will be added to the project include paths. When you are finished you can save those include paths and choose to reparse the entire project, or just the files that were parsed on the previous parse. That’s all there is to it. Let us know if you have have any questions, problems or feedback – support@scitools.com