For Input you can chose to use the selected text, the text of the entire current file, or not to use any input. You can output your results into the command output window like previous versions allowed, discard it, copy it to the clipboard, or overwrite the current selected text or file.

For example, the following would replace the word int with float in the currently highlighted text:

Yes, Find & Replace would do the same thing, it’s just an example

An example of replacing an entire file would be when using astyle to format your code. In that blog posting we had to overwrite the current file, and then reload it. Now we can feed the file text straight into the command and then the editor contents get automatically overwritten. No need to confirm the file reload every time:

As with many new Understand features, this was requested by a cutomer, we thought it was a good idea and that other people would use it, so we implemented it. If you have a good idea don’t hesitate to let us know. Just drop us an email at support@scitools.com

We are also in the process of adding Snapshot support for the Perl API for build 476. Now you can access historical versions of the code through your scripts as well. For example you can compare versions of files or write a script to compare metrics between versions.

What does this mean to you as an Understand script user?
In addition to the new features, the main side effect might be that some scripts might no longer work.

If any of your scripts stop working, review this list of incompatabilites in the Perl delta document. You can also make sure the scripts are still valid syntax by running maintain_uperl -c myscipt.pl.

The new snapshot changes modify the API in a few different ways:

• Db::snapshots() to get a list of snapshots for the db.
• $snapshot->name() to get the name of a snapshot and
• $snapshot->open() to open the snapshot and return a $db variable that represents the snapshot.
• The $db object is now “live”. It never used to be and it was never important that a script pass around and use the correct object. It is now critical.
• Entity objects carry with them knowledge of the database/snapshot they belong to. Multiple databases/snapshots can be open and you can have entities from them all at once.
• Any scripts which used entity ids $ent->id() as keys in hashes must be updated – the $ent->id is no longer unique across snapshots and multiple databases
  • At the beginning of the script add:   use Tie::RefHash;
  • declare the hash with:  tie my %my_hash, ‘Tie::RefHash’;
  • use the actual entity object as the key $my_hash{$ent}, not the dereference of the entity $my_hash{$ent->id}.
  • Don’t use Understand::ent->new($id) to reconstruct an Ent object from the id.

If you run into any problems that you need help with, feel free to post a question on the scripting forum, or shoot us an email at support@scitools.com

UPDATE- We found some issues with the above approach to $ent->id and changed it with build 477. Using a Tie::RefHash for entities does not work as intended and is no longer recommended. We added a new call $db->ent_from_id($id), to reconstruct entity objects from ids.  To use entities as hash keys without later retrieving the entities from keys, it is sufficient to simply use $ent for the key. To later retrieve an entity from a key, instead, use the entity id as the key ($ent->id()), and retrieve the entity from the key with $db->ent_from_id($key). Note, it is not possible to safely store entities from different db’s into the same hash using this technique, since id’s are not unique across multiple open db’s.

We’ve had dependency analysis in Understand for many years.  With B471 of Understand 2.0 we have consolidated it into a functional area of the tool, improved what it does and also added a few new dependency views.

The Dependency Analysis capability provides these features:

• rapid browsing of dependencies for files and Understand architectures
• Dependents, Depends On, and Butterfly graphs for files and architectures
• Spreadsheet export of dependency relationships
• A new Dependency Browsing dock that shows all depedency information

Read on to learn more about the Dependency Analysis capability and what we plan for it.

Or watch the video here.

Lots of Data

To calculate dependency we have to examine every refererence in an Understand project. We then build up dependency data structures for every file and architecture. This includes the nature of the dependency and the references that caused the depedency.

Because this can be a lot of data, we don’t calculate this as you ask for a given dependency relationship. Instead, we calculate all dependency information, cache it, and this makes subsquent exploration and browsing quick.

So the first step is to tell Understand you want to explore dependency information, by choosing:

Note the Scitools Labs icon next to the menu. This means this is an early feature, so don’t depend on it and also send feedback if you have ideas about it.

Depending on the size of the project building this cache can take a while. On 2 million lines of code, it will take about 15 seconds, but the time will depend on the reference density of the code.

After reparsing the cache will still be used, you currently have to remember to update it, although in a build or two we will ask if you want to update it.

Exploring Dependencies

Once the cache is created, you can now explore dependencies using the Dependency Browser. To get it, right click on a file or an architecture and choose “View Dependencies”

The Dependency Browser then pops up, by default docked to the right side of the interface.

The browser shows that “adler32.c” depends on two other files (zconf.h and zlib.h).  Clicking on zconf.h shows the references that caused the dependence.   It also shows that adler.c is depended on by 3 files, to see them click on the tab.  Note that these references are hot, click on them to visit the source location.

The [x] Sync button at the top tells Understand to show dependency information for whatever entity you click on elsewhere in the interface.

Dependence Graphs

We provide, currently, three graphs for files and architectures:

• Dependency Graph – edges show that node a depends on node b
• Reverse Dependency Graph – edges show that node a is depended on by node b
• ButterFly  – shows dependence and dependency

To get a graph, just right click on the file or node in question, or choose the graph icon in the Dependency Browser:

Choosing the Dependency Graph for adler.c we get:

Adler.c depends on zlib.h twice in the code, and 4 times on zconf.h, and so on.

Data Export

You can export relationship information for a file or architecture to CSV format by clicking on the  icon. This will do output dependency relationships in matrix form for that entity. 

You can also get the matrix for all files or architectures by choosing the CSV export options from the main Dependency menu:

Our Intentions

We want your feedback on these features – both in how we implement them and also what else we should do.

Our plans currently include:

• Dependency information for Java, C#, C++ Classes  & Ada Packages
• Dependency Rules – a specification system indicating permited and non-permitted dependencies
• Dependency Corrections – system for correcting false positives dependencies
• Access to Dependency Information from the C++ and PERL APIs

Customers tell us frequently that they appreciate our weekly builds. They provide a constant stream of new features and bug fixes to Understand users. We like weekly builds because it means we don’t have to provide patch binaries to customers in dire need of an update and also because we hate the idea of a crash or bug existing in the wild longer than necessary.

But what do we do with new capabilities that we want feedback on, but aren’t quite “production ready”? We faced this with Understand 2.0, which had lots of new features/capabilities.  Frankly, I think we took too long getting feedback and had to redo more than we would have liked once we did get user experiences.

Going foward we have big plans for Understand and the core technology it is based on. And so that we can get rapid feedback, we will be exposing features much earlier than we have in the past using a vehicle called “Scitools Labs”.

Scitools Labs isn’t some effort to make us look bigger than we are. We are still the 20 something person company we’ve always been.  Instead, it is our way of asking… “this is where we are heading, what do you think?”.

Build 471, which will be released tomorrow, includes three Scitools Labs features:

• Dependence Analysis, Graphing and metrics for files and architectures
• Stack Analysis specific to Microchip Corporation’s compiler/micro-controllers
• UnderstandYourCode.Com – a website hosting free tools, online analysis and new web oriented features we are putting into Understand.

I’ll write more specifically about each new Scitools Labs technology in blog postings prefixed with “Scitools Labs:“.

And remember, your input is the whole idea, so don’t be shy – let us know what you think.

Build 470, released today, introduces beta support for VHDL.  E-mail support@scitools.com for instructions on how to enabble that support.

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!

Here is one of our own source code showing the top 50 most complex functions in source tree.

We thought doing Classes by lines of code, Classes by Sum Complexity and Architectures by the same might also be interesting.

Q: Worth adding to Understand?

BTW: The Cloud was generated by Wordle.net.  We wrote a script that generates output that can be pasted into its text box.   I’ve attached it in case you want to try it on your own code.
File Attachment: wordart.pl.zip

  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:

Understand 2.0 keeps the context menus, but also adds a new Graph Toolbar:

This toolbar item updates whenever you click on an entity anywhere in source or any of Understand’s graphical or other informational views.

To get a graph, just pull down the menu:

and the graph will pop right up.

For instance, here is a butterfly chart for a function (click on it to see it bigger):

The function queried was “add_data_in_datablock”. Note that it is in the middle, with calls it makes to the right, and those it is called-by to the left.

These graphs are available for every entity that we have hierarchical graphs for.

It controls workspace splitting. Here are some examples. Click on them to see them bigger.

Single document view workspace:

Split workspace – horizontal & vertical

I love this feature. For instance, in this one with the check  box checked in the upper right, I can walk the butterfly (calls and callbys on same graph) view of this function and visit source in the left pane. Handy.

Similarly, I can setup a class browser with lots of useful information about classes in like this:

Here I have the 4 graphs (Declaration, UML, Derivation and Derived From) up and synched. This means they follow whatever I click on. 

To move tabs from one workspace to the other, just right click on the tab. In the near future you will be able to drag tabs between the splits. We also intend to provide more than one workspace (that can then be split and moved to alternate monitors).

EMACS

Add the following lisp to your .emacs file to open the Understand right click menu when C-c u is pressed (thanks for the correction Guillaume):
Note: this assumes the understand executable is in your path

(defun understand-word-at-point ()
  "Run understand menu for the word at point."
  (interactive)
  (setq understand-command
        (concat
           "understand -existing -contextmenu " (buffer-file-name)
           "-text "(current-word)" -line "
           (number-to-string (count-lines (point-min) (point)))
           " -col " (number-to-string (current-column))
   )     )
  (shell-command understand-command)
)
(global-set-key "\C-cu" 'understand-word-at-point)

Visual Studio

Step 1: Add Understand to Visual Studio’s External Tools

• On the Tools menu, click External Tools
• Click Add
• Type "&Understand Menu" in the Title box
• Type "C:\Program Files\STI\bin\pc-win32\understand.exe" in the Command box
• Type "-existing -contextmenu $(TargetPath) -line $(CurLine) -col $(CurCol) -name $(CurText) in the Arguments box
• Click OK

Step 2: Add a keyboard shortcut to Visual Studio

• On the Tools menu, Click Options
• Expand the Environment Folder and select Keyboard
• Type "Tools.ExternalCommand" in the box labeled "Show commands containing"
• Select the ExternalCommand associated with the "&Understand Menu" External Tool. If "&Understand Menu" was 8th on the list (default) then select Tools.ExternalCommand8
• Click the box labeled "Press shortcut key(s)". Type in a keyboard combination such as Ctrl+U or Ctrl+`
• Click Assign
• Click Ok

Vi

Add the following to your vi startup file -.vimrc, _vimrc, etc. Note: this assumes the understand executable is in your path:

Linux/Unix courtesy of Devin)

:command! UMenu silent: exe "!understand -existing -contextmenu %:p -line " line(‘.’) " -col " col(‘.’) " -text <cword> &" | redraw!
map <C-u> :UMenu<CR>

Windows: (thanks for the help Ilguiz):

command UMenu silent: exe join(['!understand -existing -contextmenu "$(cygpath -w "%:p")" -line ', line('.'), ' -col ', col('.'), ' -text ', '<cword>', ' &']) | redraw!
map <C-u> :UMenu<CR>

Assuming you have had TrackBack B443 or later monitoring your source trees, you can recreate the state of any monitored directory at any time. This includes file modification, file existance, file renaming, everything.

The Problem – I don’t have a snapshot for the time period.

I’m trying to see if a bug reported has been fixed. I know the area and I know we made changes for a similar bug, I just need to see if the changes cover the situation the user reports. He is using B453… my source is at B456+local changes. I’d like to easily compare the area affected between B453 and now.

I will need to grab the source for B453, build a snapshot, and compare the “Managed DB API” architectural area for changes.

Getting The Source – Piece of Cake

First I choose “Change->Make a Snapshot->From Any Point in Time”

If this is your first snapshot of this project it will caution you that Project Portability settings cannot be changed after making a snapshot.  Don’t worry about that. Just click through it.

Now I’m basically asked “When”, using th the calendar pulldown I specify the 23rd at 1700 hours (end of programming day):

Understand and TrackBack then work together to build up a preview of what the new snapshot will contain:

The first box is files in common. The second is files that existed in B453 but not in the current source. The third is files that exist now but didn’t back then.

This looks right to me. I accept it.

It then grabs the source needed for the snapshot from the TrackBack history and starts parsing the snapshot:

 Elapsed time to start… about 1 second.  I didn’t have to use SVN, I didn’t have to make a directory, I just need to know what TIME I wanted to compare against.

Snapshot Made – now find the changes

I could, and usually would, just compare all of my current database against the snapshot I made for B453.  But in this case I know the area I want to check.

So I’ll choose “Change->Compare Snapshots”  and specify the particular area I want to search changes for:

I’m then presented with the changes to that area and I check them out:

After perusing them I decide the bug is not fixed and I make a note to talk to [new]Rob, the owner of that code,  tomorrow to make sure he gets this one fixed before the next build.

Launch an External Application

For example, suppose I want to open the current file in Notepad. First select Tools | Configure User Tools

Enter the name you want to appear for your tool, and the executable that is being launched:

The parameters section is a little more tricky. What you enter here will vary wildly based on what application you are launching. If you look at the arrow on the right of the parameters checkbox, you will see a list of variables that Understand can pass to another application.

In this case we want to pass Notepad the name of the current file, so we select $CurFile

If the application needs a working directory specified, you can set that, and if you would like to specify an icon for the tool, you can select something different than the application. These settings aren’t needed for this tool, so I leave them alone. Likewise there is no command line output and this is not an STI Perl script, so I’ll leave those checkboxes blank.

Finally we need to decide where we want the tool to appear inside of Understand. There are several option.

Pop up Menu Appears anywhere you right click	Main Menu Appears under Tools | User Tools	Toolbar Appears in the User Tools Toolbar

This tool will now open the current file in Notepad. Here are the complete settings.

Here are a couple more examples of some basic tools.

Launch Build System

In this sample I want to launch my Make script. Note the parameter. In this case I don’t want to send it a file name, I want it to ask me what to build. The $Prompt parameters will ask you for input. When I run this tool, it will ask me for my build target, which is what I wanted

Then the build output displays in the Understand command window. The great part of building in Understand is that if there are errors, you can simply click on the error message and Understand will jump straight to that line of code in the editor

Code Lookup

In this sample, I want to lookup the selected text in MSDN’s library.  There are many different ways to do this, but I think I’ll launch firefox with the following parameters:

http://www.google.com/search?q=$CurSelection site:msdn.microsoft.com+OR+site:support.microsoft.com

This will search for the current highlighted text with Google on the MSDN site and the support site.