Understand 2.0: April 2008 Archives

• Fixed regression in syncing existing editors to a new project.
• Generate Detailed Metrics... button on project metrics browser now opens the new metrics export dialog.
• Bug fix: The cursor when hovered over the context browser splitter now changes to a resize cursor.
• Some UI changes to make snapshot creation more usable
• Added an HTML/text report for uninitialized items in a project.
• Find in files no longer uses case sensitive file matching on Windows - still case sensitive on other platforms
• Remember Snapshot Preview size and position.
• Added an unused variable and parameter report.

Of all the changes made last week – 3261 lines added, 934 removed, and 742 removed, just one enum changed…

I was curious…. What was it?  Well, that is pretty easy to find out.

Earlier, I showed you the Functional Decomposition architecture and used it and an about to be alpha tested tool called “Measure” to present measurements of the various parts of our source tree.  This was as a pre-cursor to doing weekly build size, complexity and change metrics reporting.

Today, I’ll show you the other architecure I’ll be using – Staff.  Using the Functional Decomposition architecture developed in about 45 minutes, I was able to create “Staff”, or who owns what, in about 15 minutes. This is what it looks like when seen in the Architect->Browse Architectures window:

 

Our engineers all use Understand 2.0 all day every day as they maintain it and also develop new features and tools.

Rob G. recently joined us from Utah State University. Because we already had a Rob, we call him [new]Rob. So far he has added the Contextual Information Sidebar, re-worked the Architecture mapper, and also helped in work on a new tool for software maintenance estimation (change scoping) that we intend to  incorporate into Understand 2.0. 

[new]Rob works with two monitors. The right monitor is flipped vertically, the left is the typical landscape (horizontal layout).

He writes:

I like the dock layout on my left monitor because it has everything that I use the most in one location.  I spend most of my time in the selector, especially when I have many editors open,  and the entity filter.  And having the docks on my other monitor gives me the most room to work in Understand.  I also keep the CIS sidebar located on the bottom of my editor, which can be moved around by right-clicking on the editor's tab or title bar, because of the limited horizontal room that I have on that monitor.

Click on the pic below to see [new]Rob’s

Understand’s Information Browser provides a one stop source for virtually all available information about a given piece of source code (entity).

So where is our new Architecture information in the Information Browser?

Well, one obvious place is the Architectures field, which tells you what part of a given architecture the entity is in. 

Here we can learn, quite quickly, that the class “GenericTree” is in the “guitrees” directory, was developed by Mark F., is part of the Scitools Specific Qt Enhancements, and was modified this month:

Hmmm… we learned a lot in just four lines… maybe this Architecture stuff could be useful (-:

We believe that if we use our own tools they will be better.

Hence, in the coming weeks, using just tools we sell or are about to introduce, I will be posting build metrics about each build we release. I will give static views of the size and scope of our various development efforts and on week two I’ll start showing change metrics describing what is new, changed and removed.

Today, I’ll start that off by showing you “Functional Decomposition”,  the first Architecture I will be using to organize future reports.

First off, Understand provides automatically a Filesystem architecture that is automatically derived from the directory structure of the project.

Understand’s Assistant, also suggests three that you can do by hand that will take you a long way.  They are “Functional Decomposition”, “Staff”, and “Requirements”.   Since we don’t deal with formal requirements here at Scitools, I’ll just be doing “Functional Decomposition” today and “Staff” tomorrow.

On the left is the basic Filesystem architecture I started with, and on the right one I whipped up in about 45 minutes:

 

I’m experimenting with Understand 2.0 to see how it behaves when references are limited to a particular kind.

I had Jason Madrid, one of our Understand database gurus, patch in a filter in a central spot that would limit all database references to just declares and defines.

He gave me a file, which didn’t work. So before I go bug him again, I’m going to try and sort this out on my own.

First off… what did he change?
Well, here TrackBack helps quite a bit. I just load it up in the TrackBack history by hitting the  icon.

This pops up the most recent current file and compares it to TrackBack’s last automatic backup made when I copied the new file in:

I was playing around with fonts while testing an issue, and ended up with a very hard to read cursive script. I could have went in and tried to find the original font, but I figured it would be easier to just revert Understand back to its initial settings.

There can be several good reasons for resetting any application to the default, freshly-installed settings. It could be you simply want to go back to the initial windows layout, or it may be something as ugly as a bad setting that causes the application to crash on startup. Whatever the reason, you can quickly clear your settings with these steps:

1. Close the application if it is running.

2. Navigate to where the settings files are stored.

• On Windows you may have to enable "Show Hidden Files and Folders"
• Windows 2000/XP – C:\Documents and Settings\USERID\Application Data\Scientific Toolworks, Inc
• Windows Vista –  C:\Users\USERID\AppData\Roaming\Scientific Toolworks, Inc
• On Linux/Unix – ~/.config/Scientific Toolworks, Inc.
• On Mac OS X – ~/Library/Preferences/com.scitools.Understand.plist

3. Rename/Delete the settings file.
There is a settings file for each of our installed products.e.g understand.conf, trackback.ini. Rename the file if there is any chance you want to revert to these settings again, otherwise delete the file associated with the application

4. Restart the application.
It should now be restored to it's pristine, freshly-installed state.

I usually don’t pay much attention to the parse log that comes up after I analyze changed files. I generally just hit close without looking at it.

But I noticed an oddity as I worked in some of our source code with Understand, and I though, hmmm what happened???

Fortunately, using   I can easily pull up the parse log from the last parsing and see what happened:

And sure enough…. ui_ExternalEditorDlg.h wasn’t found. “ui_” files are automatically generated files that Qt’s build system generates. We recently added a system that cleans them up. Now I’m wondering if that system is over doing it a bit. Anyway, I’m now off to Jim’s office to see about that (-:

 

 

One of the new features of 2.0 is “Architecture”. Loosely described Architecture is a mapping of any abstraction onto the source of a project.  The abstraction can be anything – Functional Decomposition, Requirements, Staff, Security Classification, Internal vs Externally Owned code - whatever you can dream up, Understand’s Architect component lets you map it onto our source. And as the source changes it keeps it mapped correctly, including adding/removing files and entities.

Over the next few weeks, I’ll be showing you all the places Architecture can be used.  Yesterday, for instance, I showed how the Calendar architecture can be used to limit where you search in Find in Files.

Today, I’ll explain a relatively new feature – the Architecture Dependence Graph Browser.  Basically, pick an architecture, right click on it, and choose ‘Dependence Graph”.

Something like this pops up (BTW: this is a broad overview of the products in our Maintain family at the source level):

Recently we added OS X support for Understand 2.0. I’m not a Mac user myself, but as the “Build Engineer” I’ve spent quite a bit of time on our Mac build machine lately getting the installer polished up and I have to admit that I like what I see.

I went to a couple of our resident macheads to find out how applications are normally installed on the Mac. I was going to just .tar.gz it like our linux builds, but they protested, wanting something with a little more flair. So I was able to bundle it into a dmg package, but they insisted I had the layout all wrong and it was just ugly  Ok, I admit I have no graphical design sense.

I needed an inspiration. Several of us here at the office are Geocachers, and Jim just downloaded MacCaching which not only provides useful geocaching information, but had a very nice OS X install package. I thought I would try for a similar affect with our installer.

It wasn’t easy. They had a nice background image in their folder, and we wanted one as well. After wasting almost an entire day on copying .DS_store files around and losing the image every time I moved the folder, I discovered this wonderful article, which quickly taught me all I needed. Thanks Peter!

So as of Build 441, when all you Mac Users download Understand 2.0, you will now see this beautiful install window.

Enjoy!

KevinG

 

Since I’m picking on Devin today, I’ll show you how I use Understand 2.0’s new Architecture feature and the Understand/Trackback integration to do quick reviews of changes he made this week.

Here is how Devin Pitcher, one of our engineers who sits on a Solaris Intel box all day, sets up his Understand.

He has two monitors. His left monitor is devoted to source code and information about where he is in the source code (the C.I.S.):

On his right monitor he has organized a set of undocked information palettes. He has the Project Browser available for quick traversing around the project tree. He has the Entity Filter up, set to filter on Functions. He has the Architecture browser setup to browse based on a Architecture it automatically derives while analyzing the source. And he has the Selector window up for quick access to any files he has open.  In the middle, with plenty of space to show full reference text he has an Information Browser setup to sync so that any entity he clicks on will have its information shown there.

This setup is pretty common among our engineers. Source on one big monitor (often vertically oriented) and information/navigational aids on another monitor.

Thanks for sharing Devin!

 

 

One of the most commonly asked questions of our support folks is “how can I share this Understand project” with somebody else.
In 1.4 this could be done in two ways – by having the same absolute paths (e.g. /sti/src ) or by using the relative project mode that located source files relative to the location of the project .udc file.

Understand 2.0 keeps those methods of portability but adds a new and more flexible method called called “Named Roots”.  I view “Named Roots” as pretty much like environment variables.  If I have a named root “STI” and it is set to “c:\sti\src” and I add a source folder c:\sti\src\maintain\ then when “Named Roots” are used my paths will show up as “STI:\maintain\”.

Read on to learn how to use them for fun and portability….

Understand 1.4 had two windowing modes – SDI and MDI. On X-Windows, it had only SDI.

One of the big design goals for 2.0 was what we call “Any DI”, which basically means, put windows where you want. In a container window (MDI), all alone (SDI), or docked together, so forth.

Read on to learn how you can put information windows (IB, ENtity Filter, so forth) – what we call Dock Windows anywhere on your screen and have Understand 2.0 remember where you put them next time you run it.

For a few years now we have been asked by users to add some “push” to Understand. “Don’t make me right click, show me what I need to know”, they ask.  In Understand 2.0 we have addressed that wish in two primary ways:

• Browse mode in the editor (I’ll write about that in a post soon)
• Contextual Information Sidebar (CIS)

Understand 2.0 has many more GUI layout options that Understand 1.4 did. It is also very smart about remembering the state, position and size of the various GUI components.  Furthermore, these states are saved by monitor setup, so you can easily switch between a single and multiple monitor setup and have appropriate/pleasant/efficient layouts.

Right now I use a single 24” monitor. Here is how I currently have Understand 2.0 setup when I’m reviewing checkins and looking at crashlog stacks that arrive via e-mail periodically.  Click to see it in its full beauty (-:

On the left I keep my Architecture browser, set to Calendar and File System architectures. These let me see what is changing and also browse. On the bottom I have the Locator Window (Project->Browse ENtities) which quickly lets me filter and find lots of interesting things. Notice the two “Command Window” tabs on the bottom?  These are commands I frequently use – making Understand itself. The left one does a SVN update and make, the right makes new tools “Measure” and “Impact”. I just sit in Understand all day, doing updates, visiting syntax errors (if any), doing most of my business right in Understand. On the right is the new “Context Information Browser” - see my next posting for info about it.

Over time, I’ll be asking all of our engineers to post up their setups (they vary greatly). 

 

Recently we switched our download system so that downloaders are offered the Understand 2.0 beta ahead of Understand 1.4.  This is because we feel that even though not 100% feature complete, the beta is a better tool for what most of our customers use Understand for than 1.4.

That download page change reflects how close we are to taking Understand 2.0 off beta.  Remaining features we want to add before doing that are:

• external editor integration (for instance using EMACS as the source editor)
• external application control of Understand (permitting other apps to launch Understand views/graphs)
• user tools (permitting users to integrate with make, CM and other external system commands)
• poster / n-page printing of graphics

All of these are 2–3 weeks away… so the time is approaching.

Naturally most of our development effort is directed at Understand 2.0, but Understand 1.4 will not be ignored:

• we will continue to release new builds of Understand 1.4 for 4–6 months. These builds will include:
• all parser changes
• crash fixes
• no new features will be added except for parser and things common to 2.0, like the PERL and C APIs
  
• after 4–6 months, we will stop making new builds of 1.4 weekly. However, we can and will make new builds as we encounter and fix critical errors reported by users still depending on it.

Note that all current Understand 1.4 licenses will operate 2.0 as well. If you are under maintenance, enjoy 2.0. If you aren’t, give it a try and see if coming back under maintenance is worth the money. If so, e-mail sales@scitools.com to ask for a maintenance renewal quotation.  As usual, it is an honor system. We hope you understand doing things like 2.0 (and 2.1, 2.2, so forth) takes money and we hope you feel Understand 2.0 and our support efforts are worth the cost.

I hope this plan seems reasonable to you. None of this is cast in stone, so feel free to send concerns, compliments or suggestions  to support@scitools.com.

Regards,

Ken Nelson
President
Scitools