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.

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.

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

These instructions may vary slightly depending on your version of Windows, but in general the concept is the same.  I will register .cpp files for this example. When I’m done, whenever I double click on a C++ file, it will open in Understand by default.

First find a .cpp file in explorer, right click on it and select Open with –> Choose default Program

Click the Browse Button and navigate to the Understand executable, select it and click “Open”, by default it is at C:\Program Files\SciTools\bin\pc-win32\understand.exe

Understand will now show up in the list of programs available to open this file. Select Understand and make sure the checkbox is checked that says: “Always use the selected program to open this kind of file”. Then click ok

That’s it. Now Understand will handle those files everytime.

More details

Refactoring is a disciplined technique for restructuring an existing body of code, altering its internal structure without changing its external behavior. Its heart is a series of small behavior preserving transformations. Each transformation (called a ‘refactoring’) does little, but a sequence of transformations can produce a significant restructuring. Since each refactoring is small, it’s less likely to go wrong. The system is also kept fully working after each small refactoring, reducing the chances that a system can get seriously broken during the restructuring.  — Martin Fowler  http://www.refactoring.com/

In other words, refactoring is making your code cleaner, safer, and easier to use. Understand can be a very powerful tool in your re-factoring arsenal. Here are a few ways you can use Understand in your refactoring process.

Quickly Identify References

In the long list of refactorings, many of the suggested refactorings involve replacing one data type with another. In many cases that can involve changing the calls to that data type as well. Understand can instantly show you everywhere that that entity is used, called, referenced, modified or typed. Just right click on the entity, select View Information, and expand the references section.

Identify Complex Functions

Many overly-complex functions can be refactored into smaller, more maintainable units. Knowing the McCabe Cyclomatic complexity can help you quickly identify functions and methods that are overly complicated and may be good candidates for refactoring. You can quickly find the complexity of every function in an Understand project by selecting Metrics –> Export Metrics. If you’re just looking for a quick list of complex functions, this plugin will show you the most complex functions in your project.

Download it from our Plugin page and you’ll see a list of the most complex functions in your project.

Reformat your code

If you have ugly code, you can beautify it quickly with the the tip reported in this entry:

Tip – Beautify your code

With one button press, turn a file that looks like this:

into this:

Rename Entities

Sometimes renaming an entity can go a long way towards making the code readable, perhaps a missed name class or method.

Download rename.zip for a user tool to quickly rename entities in Understand – it goes through the references and replaces each instance of the class or object with the new name.

Save the .pl script to your hard drive, and then in Understand under Tools | User Tools| Configure select Import to load the .ini file. Change the path to the location of the .pl file. Then to use it, right click on any entity in Understand and select User Tools | Replace. You’ll be prompted for the new text, and then all references to that entity will be renamed. You’ll want to reparse the changed files after each rename so that the database stays up to date (Ctrl+R by default).

Follow Dependencies

Understand’s new Dependency features can help you to quickly get a handle on what parts of the code are dependant on other parts of the code, letting you define what logical lines to divide your code into. Dependency Browser Dependency Graphs Exporting Dependencies

The short C/C++ example below shows how each line and statement contribute to these metrics in Understand. You can view the larger version here.

We have made a lot of changes to the licensing in Understand 2.5. How does this affect you?

1. These changes require a new license key.
2. All Understand features are now available to all users

As always, as long as your maintenance is up-to-date, there is no cost for the new version of Understand, we just need to generate a new license for you. The dialog that pops up when you start Understand has three options for getting that new license, whichever you choose, we will get the license to you quickly and without any hassle.

What if your maintenance is not current? You can still use any of these options, and we will get you a quote for getting back up-to-date. Also, the 2.5 install does not overwrite your previous version, so you can continue to use Understand 2.0 with your previous license.

We have a philosophy here that licensing should never get in the way of engineers using our tools. Over time this philosophy has resulted in many different experiments as we have tried to simplify licensing and added different ways for people to access Understand. As we prepared to release Understand 2.5 we realized there were now 36 different license types. As you might imagine that resulted in some very messy code, this feature is only available for these 16 license types, etc.

It was getting hard to maintain and we were seeing more and more licensing related issues. We decided to make a clean break, and created a new license that supports all features, thus bypassing the complicated licensing logic and we hope providing the best possible experience to our customers.

On Linux and the Mac it is quite common to have command line GDB session in use for debugging and to need to inspect or walk a call stack from the “where” command.  It is a bit of a pain to have these separated from Understand. And we may (if we can figure out the Windows side) add debugging support directly into Understand, but until here is a tip that makes working with GDB a bit easier.

With B465 you paste any text into a command result window (get one by choosing “Options->Run a command”).  Once pasted, we analyze it for file, line and entity names and it becomes clickable for Understand events and menus.

Here is a GDB call stack pasted in:

Files and lines are identified so I can visit them in Understand, or right click and get information and graphs.

Also, with B465 we have made file detection much smarter. It will recognize short, relative and full path names and associate line numbers with them in any fashion a compiler or other tool can think to spit them out.

So I’m quite happy to report that Understand 2.0 Build 466 has searching in graphs. To search in a graph just hit the binocular button and enter in the search text. It is incremental. As you type, it matches. Hit return to move to the next, or use the green arrows. The graph will center to the next match. Searches will find on node labels and edge labels (if the graph has them).

Here I search a large call tree for “inflate”:

So you can quickly turn this:

Into this:

We plan on implementing astyle into the editor at some point in the future, but I’m not so patient, and I decided to use our plugin mechanism to do it now, and will show you how.

There are two ways to run astyle from inside Understand, as an Interactive Report plugin, or as a custom user tool. Either way, first you’ll need to install or build astyle you can download it from here.

Interactive Report

The Interactive report integrates directly with the file context menu in Understand. Download the plugin from here(right click and save as). To install it, just move the file to SciTools\conf\plugin\User\IReport\ and restart Understand.
To run the plugin, right click on a File, select Interactive Reports and Beautify

At which point you’ll be presented with the options window:

The first field is pretty straight forward, just navigate to where the astyle executable is installed.

The rest of the dialog may seem overwhelming, but the tricky part is figuring out what your “style” is. Astyle has 5 predefined styles, and chances are that one of them will be pretty close to what you like.

Astyle’s documentation goes into more detail about each of these styles, but here is a rough overview:

namespace foospace
{
int Foo()
{
if (isBar)
{
bar();
return 1;
}
else
return 0;
}
}

namespace foospace
{
int Foo()
{
if (isBar)
{
bar();
return 1;
}
else
return 0;
}
}

namespace foospace {
int Foo() {
if (isBar) {
bar();
return 1;
} else
return 0;
}
}

namespace foospace
{
int Foo()
{
if (isBar) {
bar();
return 1;
} else
return 0;
}
}

class foospace {
int Foo() {
if (isBar) {
bar();
return 1;
} else
return 0;
}
}

If one of these appeals to you as is, just select it from the “Predefined Style” section. If you want to modify one, select it and the other options in the dialog will allow you to override the default settings for a style. For more details about what the command does, select “Display the help text” in the Action section:

When you are ready to run it, you can either preview the changes in a separate window, or apply them directly to the source code. Of course I would suggest previewing the changes until you figure out exactly what your style is. Note that if your project uses relative paths or named roots, only the preview will work right now since the file naming is different, but you can still copy and paste

User Tool

If you already know what astyle command line options you want to use, you can setup a user tool  to quickly transform a file. Again, this only works for projects with absolute paths.

So here are the command line options I want to use with astyle:

astyle –style=ansi -t -B -w

To implement these as a user tool, I select Tools | User Tools | Configure

Then I create a new tool. I name it and provide the path to the astyle executable. Then I provide the parameters. The lipstick icon is optional

I also decided to bind this to a keyboard shortcut (Ctrl Shift B). You can set the keyboard shortcuts in Tool | Options | Key Bindings.

Now if I run into an ugly file, I can just hit Ctrl Shift B, and bam, pretty code!

  61 lines of code, pretty small, keeping functionality nice and modular. Good.

  Cyclomatic complexity of 30. Highly complex, but within the acceptable range. Good.

  CountPath metric 536,870,912. What is this? 536 Million paths in 61 lines of code, that can’t be right, can it?!?

The CountPath metric counts the number of unique paths though a body of code. It’s pretty common to have a huge count path metric, even in a small body of code.

In this example, I pull up the code and it looks like this:

29 IF statements in a row. That’s all, logically quite simple code:

But the fun thing about IF statements, is every one doubles the number of potential paths in your code(2ⁿ) – and as we all remember from our algebra days, exponential growth happens very fast.

So 2 IF statements makes 4 paths. 2³ is 8 paths. let me demonstrate:

So for the 3 IF statements here, n=3 and 2ⁿ= 8 possible paths:

ACE
ACF
ADE
ADF
BCE
BCF
BDE
BDF

And any guesses what 2²⁹ is? Yep, 29 IF statements make 536,870,912 paths. Because this metric can grow so large, we do truncate it at 1 Trillion, actually 999,999,999. If we see that many paths, we give up and stop counting. I don’t envy the QA team if they have to test every possible permutation of this, but at least you can believe Understand when it tells you that there are that many paths

Scheduled Activity

The quickest way to automatically get metrics is as a scheduled activity. For example I could setup Understand so that every Friday night it reparses my project and generates the current metrics. I can set it up to save the metrics as a comma delimited file and/or as an html report. This is all configured from Tools | Scheduled Activities.

Command Line

Another way to automate the metrics is using the command line tool und. For a list of the commands available from und, simply run und –help. For more advanced help on a specific command, run und –help command. For example run –help rescan will show the advanced help for the rescan command.

It most cases the first thing you’ll want to do is update your project by rescanning and analyzing. This can be done with:

und –db c:\project\pixie.udb –rescan – analyzeAll

Und lets you dynamically specify the parameters for the metrics exports. Simply look at the commands that start –metrics_* for additional options.

For example metrics_sel lets you specify which metrics you want to report on, so if you just wanted the cyclomatic complexity and the lines of code, first you would need to clear the current metrics and then you would set the option as:

und –db c:\project\pixie.udb –metrics_sel none AvgCyclomatic CountLineCode

Then to actually generate the metrics file, use the –metrics command, you can specify the filename for the csv export, or if none is specified it will default to the last used filed location. You can see the available metrics at http://scitools.com/documents/metrics.php

und –db c:\project\pixie.udb –metrics “c:\temp\Pixie Metrics\metrics.csv”

You can set the parameters and generate the metrics with the same command, so:

und –db c:\project\pixie.udb –metrics_sel none AvgCyclomatic CountLineCode –metrics "c:\temp\Pixie Metrics\metrics 10-13-2008.csv"

You now have a comma delimited text file that you can open in your favorite spreadsheet editor, or parse however you want:

If you would rather see your metrics as an html report, use the –metrics_htmlReport command instead of the –metrics command:

und –db c:\project\pixie.udb –metrics_htmlReport current –dir "c:\temp\Pixie Metrics\html metrics 10-13-2008"

The html reports let you browse by architecture, so you can look at the metrics by filesystem, staff, or whatever architectures you have setup:

In short…. use the entity filter window to filter on “unused functions”, turn entity->long names on, then type in the name of the class. Done. 

Here are the steps….  First select the “Unused Functions” filter in the Entity Filter window:

Now, turn on Full Entity Names by clicking on the dimple to the right of the Show: field:

The names now have :: in their full name if they are from a class:

I’m looking to see if class GameBoard has any unused functions, I type “GameBoar” into the Filter: and find the methods of GameBoard that are not called anywhere in this project:

So take for instance this section of code:

procedure Buffer_Demo is
   EOL  : Character renames ASCII.LF;
   Text : constant String
     := “Four score and seven years ago our fathers brought forth,” & EOL &
        “upon this continent, a new nation, conceived in liberty,” & EOL &
        “and dedicated to the proposition that `all men are created equal’.”;

I’ve got to make it look like this:

procedure Buffer_Demo is
   EOL  : Character renames ASCII.LF;
   Text : constant String
     := tr(“Four score and seven years ago our fathers brought forth,”) & EOL &
        tr(“upon this continent, a new nation, conceived in liberty,”) & EOL &
        tr(“and dedicated to the proposition that `all men are created equal’.”);

Fortunately, Understand 2.0 can record editor macros that make repeated tasks easy and possibly fun.

Here is how…

Ctrl-Alt-M toggles recording on / off. This is also available from the Tools-> menu.
Ctrl-M       plays the recorded macro.  Also available from the Tools-> menu.

I start recording:

Ctrl-Alt-M

The first thing I do is use the editors fast find to find the “.  I do this with:

ctrl-f “  ESC  <-

Or, in English… Control-F, double quotation mark, Escape, left arrow.This places me to the left of a “

I then add my function text:

tr(

Now I need to find my closing quotation mark:

Ctrl-F “  Ctrl-F  ESC ->

Or, in English… Control–F, double quotation mark, Control-F, Escape, Right Arrow. This places me to the right of the closing quotation. 

I then close out the function and stop recording:

) CTRL-ALT-M

Now anytime I hit “Ctrl-M” it will find a left quotation mark and put tr() around the string.

Note: For a simple one like this I could probably also use Search->Find and Replace.

Favorites can be “project favorites”, where they are only applicable to the .udb file open when you made them, or “all project favorites”, which are available no matter what project you have loaded.  The “All Projects” variety is useful to me since I have dozens of projects of largely the same source that I use for different testing/evaluation purposes.

Favorites are shown in the “Favorites” window, which you can show by clicking on the  toolbar (or by Windows->Favorites).

I have my favorites organized into three folders:

I give a lot of web and in-person demos of Understand, “Good Demos” is where I store classes, functions, and files that help me simply explain the kinds of things Understand does. For instance, here I have classes and functions and a “butterfly” view with the [x] Sync box checked. In a demo, I can just click on the favorite and see the graph update auto-magically.

“Interfaces” provides a handy spot to stash a quick way to see the API’s we often work against here. For instance, the “Understand database API (udb)” or “Change API”.  If I need to know the UDB API details, I just click on it and up comes the source:

“ToDo” stores places I want to take a peek at again later. Often this is when I find a spot, or a user reports a spot, where a  crash or bug can be replicated.  It is empty now, but let’s pretend I want to come back and look at a spot here in the UDB interface.

First I just click in the editor where I want to remember. Then pull down the Favorites toolbar menu:

It asks me to place the favorite, and I specify “All Projects” and put it inside “ToDo”:

It is now in my Favorites and I can visit it just by double clicking on it: