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

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.

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.

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

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.

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.

In both 1.4 and 2.0 the usual way of exploring/learning about code in the editor is via the Right Click context menu. For instance, if I want to learn about allocstrAppend() I right click on it:

However, the 2.0 has a new “Browse” mode that makes all entities behave like hyperlinks in a web browser.

Turn it on selectively by holding down the “CTRL” key.  Or toggle between normal mode and browse mode by toggling the browse mode icon in the toolbar:

Once in the browse mode, whenever you hover over an entity it is underlined:

When you click on the underlined entity two things will happen:

1. The Information Browser will update about that entity
2. The entities definition will be visited

You can control what happens on the Browse mode click via the Tools->Options->Editor dialog, and the Browse tab:

Note that you can still edit while in the Browse mode.  If  you don’t want to visit somewhere just click in white space.

To see the options, just start Understand with “-help”:

%understand -help

Here are the current options (updated 24 July 2008):

Understand file1 file2 file3 etc [options]

Open a list of files by including the list after the application name.

Options:

-existing

Use this option to pas arguments to an existing instance of Understand. If more than one exists, the one with the lowest PID will get the commands.Will start new one if none exist.

-cwd path

Set the current working directory to ”path”. Doesn’t change the cwd if path doesn’t exist.

-lastproject_cwd

Use the path to the last opened project as the cwd.

-db filename

Open the project file ”filename”. Does not assume .udb extension.

-lastproject

Open the last project opened by the application.

-noproject )

Do not open a project. This overrides -project, -lastproject, and also (more usefully) automatic settings to load projects on startup.It also clears any automatic settings so they will not happen until set again in the GUI.

-visit filename [line-number column-number]

Open the file ”filename” in an editor window. Path is relative to CWD of Understand instance doing the visit. Optionally position caret at line-number and column-number

-contextmenu filename [-line number -col number -text number]

Show the context-menu for ”filename” at the current global mouse coordinates. For better accuracy as to what entity the menu acts on specify more information with -line, -col and -text. This is useful for integrating Understand context menus into other editors, debuggers and other applications. See Using Understand with an External Editor for an example of using this menu in SlickEdit.

Examples:

Startup understand and load a database:

understand -db foo.udb

Load file foo.cpp existing Understand 2.0 instance.

understand foo.cpp -existing

Open the Understand and automatically open the last project:

understand -lastproject

Visit line 22, column 3 of file foo.cpp in an existing instance of Understand 2.0

understand -existing -visit foo.cpp 22 3

Bring up the context menu for an function named “foo” in file foo.cpp

understand -existing -contextmenu foo.cpp -text foo

]]> http://scitools.com/blog/2008/07/documentation-understand-20-gui-command-line.html/feed 0 http://scitools.com/blog/2008/07/faq-snapshots-what-are-they-and-working-them-into-your-workflow.html http://scitools.com/blog/2008/07/faq-snapshots-what-are-they-and-working-them-into-your-workflow.html#comments Fri, 25 Jul 2008 00:22:35 +0000 ken http://scitools.com/blog/http:/scitools.com/blog/archives/2008/07/faq-snapshots-what-are-they-and-working-them-into-your-workflow.html

I’ve just realized that while I’ve written a bunch of posts referring to snapshots and using snapshots, I’ve never explained what they are and how they can fit into a software engineer’s workflow. Hence the “missing piece of the puzzle” clip art above.

Q: What are snapshots?

A: A snapshot is a binary store included within an Understand database. A database can hold be any number of snapshots. Each contains three things:

1. a complete Understand database containing analysis (parse) information
2. all source, including any include files, needed to rebuild that analysis
3. certain cached information used to speed up working with them (metrics and file information)

Q: What are snapshots used for?

A: They are used throughout Understand 2.0 to provide details and metrics about what has changed in source code between two points of time.  The “Change”, “Metrics”, and “Estimate” menus all use snapshots intensively.

“Change” will tell you what has changed at the semantic level. For instance, what classes or types changed, versus just what files/lines changed.

“Metrics” can tell you the number of semantic changes – classes removed, changed, added, so forth.

Q: How is a “diff”  better when using snapshots than Understand 2.0’s text differencing capabilities?

A:

• Easy. Using a snapshot means you don’t have to keep different versions of source lying around. Snapshots are easy to make. Just click a button and you’ve got one.
  
• Compares using snapshots use semantic differencing.  That means, for instance,  that no matter how much a function changes or moves around in a file you can easily isolate just changes inside the function, class or other logical / semantic unit in code.   Differences shown are specific to the entities you are concerned about.
  
• Find Changes by type of entity changed.  You can just look at class or type changes, or functions.  You can find changes in classes with high complexity. You can find classes that had the most changes. So on.
  
• Find changes in dependency trees. Semantic differencing also permits exploring changes in dependency trees. For instance you can ask “Change” to find changes in code that is depended on by, or depends on, a region of code.  This helps you know what changes have affected a piece you are working on, or what pieces are affected by what you changed.   The classic question is “this function is broke, what changed that affected it”?  Semantic differencing answers that question directly.
  

Q: What kind of snapshots are there?

A: All snapshots contain the same kind of information. But we divide them up into kinds more on how they are made and what you can do with them in Understand 2.0.

There are three kinds:

1. Automatic – these are made with the project scheduler (Project->Configure->Schedule).  At the same time each day you can tell Understand 2.0 to update, parse and make a snapshot. These are labeled by the name of the day (e.g. Monday, Tuesday, Wednesday, …)
2. Scratch – there is only one “scratch” snapshot. You can make it from the current database in a single button click or keystroke.  Use it for snapshots you want to have but not long term. For instance, to save a key point, prior to moving ahead.
3. Named – these snapshots have a name / date that you set. For instance “B452” or “Before I started messing with the interface”.  There can be any number of these.

Q: Hey… I could use this stuff… but how do I make a snapshot?

A: Oh let me count the ways…

• Via button on the Parse Log…

  

• Via the Change->Make A Snapshot Menu

  

• Via the Project Scheduler…  (Configure from Change->Scheduled Activities dialog)

  

• Via the command line tool “und”

  und -db foo.udb -snapshot “Src-13–Jul-2008”

Q: It does seem easy to make one from source I have in an Understand project now, but what about source versions from before I heard about this?

A: We call these “Historical Snapshots”.  Basically, you need to get the old source and make a snapshot out of it.  We provide two ways to do this:

1. Do it from TrackBack.  If you have been using Trackback, getting old source is easy. Just choose “Change->Make a Snapshot->From any point in time” and specify TrackBack and a time:

   

2. Copy or checkout the desired source to an alternate location. Then choose “Make a Snapshot->Named from an Alternate Location”.

   

   For a detailed look at making a snapshot this way see “Tip: Making a Snapshot from an alternate source directory”.

Q: So how do you use snapshots?

A: Well,lets ignore me using them soley for testing of the snapshot function. How do I use them in my “real” day to day work?

I usually need to see what happened since the last build and since yesterday. I sometimes need to see what happened since a special time (usually same day).

I have have automatic snapshot building turned on. I do this with the automatic scheduler. Hence I always have snapshots of the last 7 days readily available.

I also make snapshots of recent builds. I keep the last 3 or 4.  I do this manually at the time the build is frozen (I’m involved in the freeze decision).   If I forget, I make them with TrackBack.

If somebody tells me they are about to check in something I want to examine. I’ll make a scratch snapshot, update, parse and then quickly compare/see what changed and what the changes were.

I’m a bit more organized than most (my wife may disagree).  Many of our engineers use only the Scratch snapshot facility. They “snap a scratch” and they can easily see what has changed since it.  When happy with what they are working on, they make another and move along.

Nifty!

The metrics capabilities vary depending on what version of Understand you are using: Understand Engineer provides high level project metrics, Understand Pro lets you explore and export project and entity level metrics, and Understand Analyst lets you do all that, create custom graphs, and even compare how metrics are changing over time (trend analysis). 

All of this Metrics capability is accessed through the new Metrics menu.

Engineer	Pro	Analyst

Basic and Advanced Metrics

We’ve noticed that some basic metrics are more useful to engineers then others, such as number of lines of code, number of classes etc. while other metrics are usually more helpful for management and code analysis. Since Understand Engineer and Pro target programmers, these Basic metrics are available in all versions, while the advanced metrics are partially available in Pro and fully available in Analyst.  Though which metrics are displayed depends on what languages are being analyzed, here is a list of what you can expect:

Understand Engineer

Metrics Summary The metrics summary provides an overview of the basic project metrics. For example I can quickly see how large my codebase is or how well I do at commenting my code. If there are snapshots in the project, you can also view the same metrics for those snapshots.

Code Volume Graph	File Volume Graph
This graph gives a quick view of what percentage of the source is executable code, declarative code, comments, and blank lines.	And this provides an overview of how many files are in your project and their breakout.

Understand Pro

Metrics Browser

The metrics browser is an efficient way to access all of your available metrics. With the metrics browser you quickly see the high level project overview metrics from Understand Engineer. You can also drill down through your file structure or other architectures to quickly see the basic metrics for any subset of your code. For example, in this case I can quickly see how many lines of code Mark owns and the breakout of that code.

If I drill down to the file level, I can actually get the Advanced metrics for any particular file I’m interested in as well.

Export Metrics Understand Pro let’s you select and export metrics to csv files, which you can then slice and dice with your favorite spreadsheet editor. The metrics you select are exported for files and all Major Language Elements e.g. class, function, methods, structs etc.

Average Complexity	Sum Complexity
< a href="http://scitools.com/blog/wp-content/uploads/mt-old/WindowsLiveWriter/MetricsGalore_A26B/image_27.png">
This graph shows how complex your code is on average using the cyclomatic complexity metric and also how deeply nested your code is.	And this shows the total number of paths through your code, the cumulative cyclomatic complexity, and essential complexity.

Understand Analyst

Metrics Browser In addition to the Metrics Browser functionality in Understand Pro, Understand Analyst provides Advanced metrics for any level of an Architecture tree, so if I wanted to know the average complexity of Mark’s code, that information is right there.

Export to HTML

The entire set of Advanced Metrics in the Metrics Browser can be exported to HTML using Analyst. This report is perfect for posting on the team intranet and provides quick access to a very wide range of information.

Browse Metrics Graphs This feature is where Understand Analyst really shows its strength as a premium metrics tool. This window gives you the capability to generate an unlimited number of metrics graphs. There are two major report categories here, Project metrics and Change Metrics. Project metrics are based on the snapshot you are looking at. Change metrics let you see how those project metrics have changed between different points in time. For example I can graph how many lines of code each engineer owns in my current database using project metrics. Using the change metrics I can see how many lines of code each engineer added, changed and removed since the last build.

The examples below are just a few reports generated almost instantly using Understand Analyst.

Code volume by Staff – Go Mark!	Code Breakdown by Language
Classes Modified between builds by Staff	Files Changed between builds by staff