Understand takes about 100-200MB of installation space, depending on which OS it is installed on and will run on Windows, Linux, Solaris (Sparc and Intel) and OSX(Intel). It will run on just about any system (our Solaris 8 box only has 256MB of RAM and it runs fine). However, for larger code bases the more RAM the better. We recommend 1GB / Million lines of code, it will run on less, but it is much slower.

You can reset Understand to its initial Settings by exiting the program and then renaming or deleting the configuration file. On Windows you may have to enable “Show Hidden Files and Folders” first. The configuration file can be found in the following location:

• Windows 2000/XP - C:\Documents and Settings\USERID\Application Data\SciTools\Understand.ini
• Windows Vista/7 - C:\Users\USERID\AppData\Roaming\SciTools\Understand.ini
• Linux/Unix - ~/.config/SciTools/Understand.conf
• Mac OS X - ~/Library/Preferences/com.scitools.Understand.plist

• Windows 2000/XP - C:\Documents and Settings\USERID\Application Data\Scientific Toolworks, Inc\Understand.ini
• Windows Vista/7 - C:\Users\USERID\AppData\Roaming\Scientific Toolworks, Inc\Understand.ini
• Linux/Unix - ~/.config/Scientific Toolworks, Inc./Understand.conf
• Mac OS X - ~/Library/Preferences/com.scitools.Understand.plist

Yes you can. Most platforms have a 64bit specific build, but the 32bit Understand should run fine on all 64bit Operating Systems as well.

On Linux/Unix you will probably need to install your system's 32-bit compatibility libraries.

On Debian based systems (including Ubuntu) the IA32 package will provide everything you need. The command sudo apt-get install ia-32-libs should be all you need to run. Then Understand should launch with no problems.

I don't have a Redhat/Fedora 64bit machine to test this on, but from what I've read the following commands will install the necessary libraries.

# up2date -i "@Compatibility Arch Development Support"
# up2date -i "@Compatibility Arch Support"

I actually couldn't find much information about running 32bit apps on Fedora or Redhat other than this forum post. If you know or find a better way to do this, let me know and I will update these instructions.

KevinG

We plan on adding support for several different Version Control Systems directly into Understand in the future, but right now Understand's User Tools give you the capability to quickly integrate them yourself.

In this blog post Ken shares the SVN tools he made:
http://scitools.com/blog/2008/06/tip-se ... s-for.html
and in this post I show how to add your own user tools:
http://scitools.com/blog/2008/07/tip-ma ... -tool.html

We'd be happy to help if you run into any problems, and happy to host any tools you make for a specific VCS. The main reason we haven't added them ourselves is because we aren't familiar enough with all the different flavors of Version Control :-)

• More RAM is useful. 1GB or better
• Source can be on a network, the database should be local. The database is the .udb file.
• If the system is gigantic (say > 8 MSLOC) you might want to use the 'und' command line parser to do it in batch or in chunks. The manual covers "und".
• Report generation on really big projects can be done, but... you probably shouldn't generate the invocation trees. Instead do this via scripts on important routines. www.scitools.com/plugins/scripts.php has scripts.
• Consider very closely what reports you want to generate and what are not needed. In particular, avoid the Invocation Tree report if not needed. It takes a lot of memory and time to generate if the system is really large.
• You can automate report generation with "und". Do it overnight when your computer isn't busy.
• You can get a lot of information without all of the source. For C/C++, consider providing just header files in some areas where detailed implementation analysis resolution isn't needed. For Ada, consider only providing Specs for some areas.
• Did we mention... More RAM is handy...

Exactly like a C/C++ compiler with one addition.

Include paths are specified either in the Project->Configure dialog, Includes tab, or on the command line of the 'undc' parser "undc -l foo". See Chapter 7 of the manual for more information about using the command line.

When looking for an include file Understand for C++ uses this search precedence:

1. absolute name
2. relative to parent dir
3. in project include list
4. in system specific (compiler) dir (same as compiler to this point) 5. in project files (we added to help typical users)

Steps 1 and 4 are identical to a C/C++ compiler. Step 5 is an additional search we provide for cases where code (or compile macros) are incomplete.

More on step 5, which internally we call "lazy include"... this is there as an aid, but it can lead to incorrect parsing. For instance if your tree has these files:

include/foo.h
util/foo.h
main.cpp
and main.cpp includes "foo.h" but there is no path then it will pick one of the two foo.h's in the project.
Perhaps the wrong one... the correct thing to do is to specify "include" ahead of "util" on your include path - if that is the precedence you prefer.

Understand supports K&R C, ANSI C, and ANSI C++.
It supports language extensions by VAX C, Visual C++, and GCC compilers. It also has support for a variety of embedded compiler language extensions from popular compiler vendors (IAR, Keilly, Greenhills, Diab, among others).

In addition, Understand for C++ supports the full C pre-processor specification + GCC extensions.

All of these languages can be analyzed together.

We normally do not suggest a change in code to accommodate Understand. We are working on a solution that does not require code changes. Until then, this workaround can help:

In Managed C++ code, a "public ref" is appended in front of the class definition, though this is not standard C++ syntax. The extra two words cause parsing problems, and Understand does not properly scope the following member variables/functions, causing various problems.

Workaround (thanks to Grady at Rathyeon):

The MSVC Compiler predefines a macro called "_MANAGED" that can be used to work-around this problem (you may need to set the /clr argument in the compiler). This Macro is not passed into Understandsince it is dynamic, so by modifying the class definition, as follows, Understand will recognize the rest of the code correctly:

CODE:
// FILE: STI.h ... #ifdef _MANAGED
public ref class STI
#else
class STI
#endif
{
...
};

Note that MSVC does not work correctly unless the "class WES" is on the same line as the "public ref".

Another note is that MSVC accepts a liberal sprinkling of the keywords "public", "private" and "protected" in the header file. i.e. In front of enum's definition in a namespace definition (but not within a class definition). The GNU compiler will not allow this nor does Understand for C++. The three keywords should only be used in class and struct definitions as the C++ standard directs.

A similar solution is to do this with the __UNDC__ macro provided by Understand. This macro is automatically defined in Understand, and instructs code to act in a certain way in Understand.

Function pointers will befuddle pretty much any static analysis tool. With Understand, we associate dependence between the function and where its address is taken. This can work pretty well in some types of code, but not so well in others (for instance table/array driven setups where the taking of the address is well away from where it is actually used).

So we do what we can automatically. And in the case where we can't sort it out, we are looking into adding a persistent linkage via manual annotations of the code.

As an alternative, you can modify your code to display function calls in Understand, but actually compile with function pointers. To do this use the __UNDC__ macro which is automatically defined in Understand, but not in the compiler>

So in your top level include file add something like:

CODE:
//Enable tracking pointers with Understand_C
#ifdef __UNDC__
#define func_pointer(x) x()
#else
#define func_pointer(x)
#endif

Then change your function pointer calls from:
CODE:
(*foo)();

to
CODE:
func_pointer(foo);

You can use the same concept to trace a function call in Understand that is not being directly made in the code, e.g. made with tables etc.

CODE:
#ifdef __UNDC__
#define undcforcecall(x) x();
#endif

then simply add the following wherever you want to track a call to foo();

CODE:
undcforcecall(foo);

DO-178B, Software Considerations in Airborne Systems and Equipment Certification, is a standard published by RTCA, Inc that the FAA accepts for certifying software in avionics.

Understand is used by quite a number of people developing to this standard. We don't have a specific DO-178B "solution", but the tool helps in quite a few parts:

• The HTML reports generated by Understand can act as "as built" Software Detailed Design (SDD) documents.
• Additional SDD information such as globals used and globals cross reference can be done by our SourcePublisher tool or via Understand scripts (see http://www.scitools.com/plugins/index.php).
• Certain coding standards, such as "no interrupt handler can be in the call chain of another interrupt handler" can be implemented as Understand scripts, permitting automatic re-checking as the code changes.
• If requirements are embedded in source as comments, Understand scripts can do requirements tracing and impact assessments. Using this capability you readily track changes in requirements as to where they affect code, and vice versa.
• When doing DO-178B mandated code reviews, Understand is very useful. It isn't a requirement for doing DO-178B code reviews, but it makes code reviews more useful, efficient and accurate - the main intention of the standard.

So Understand can satisfy some portions of the standard, help you be better at doing other parts, and also is a generally useful tool to the practice engineer to minimize mistakes and understand what they are doing in the code.

Understand can create several different types of project-wide diagrams. The Dependency Graphs can help explore the relationships between different parts of the code base. The UML class diagram will show the inheritance relationships between the classes in the project. There is also a plugin that provides a project wide call-tree display. All of these graphs can be accessed through the "Graphs" top level menu in Understand.

Since the graphs were designed first for Understand, exporting them to Visio involved some compromises. We ended up doing mostly custom placement and drawing of individual elements, instead of using standard Visio objects. Below are answers to specific questions about the Visio graphs, and workarounds where appropriate.

How do I specify the font size and text box spacing before Understand does the actual export? This would make the initial Visio drawing much less "spread out".

The problem is that Visio seems to lay out its own character placement in a way that does not match our own kerning and layouts. So the algorithm we have ened up with is a compromise, that most closely resembles our own layout, yet doesn't break the display in visio. When we try to be more accurate we end up with unexpected text wrapping in nodes and other unplanned results which ruin the layout. Unfortunately the only option available now is to do a global font size change and then manually resize each box.

How do I edit the text in an exported Visio node?

It's not as convenient as 'normal' Visio text, but you should be able to double click on text lines to select them, then press F2 to edit them.

How can I copy the text from an exported node into a new Visio node?

Same trick as above. Double-click select, then F2 makes it so you can copy/paste, as usual.

Shouldn't Comment Lines + Blank Lines + Code Lines = Total Lines?
And shouldn't declarative statements and executable statements add up to the total number of statements as well?

That is a common assumption, however, any given line can actually count towards multiple metrics, so the numbers are not necessarily unique.

For example:
CODE:
int deltaChange = 5; //Delta needs a minimum variant of 5

This line is a code line and a comment line, and counts as both. Likewise the statement is both declarative and executable, so would count in each of those metrics.

Since inactive regions of the code can contain just about anything, by default the code is completely skipped by the parser.

The most common reason to want to analyze inactive code is for metrics calculations, i.e. wanting the total number of Lines of Code instead of just the active lines of code. The metrics that begin with "Alt" contain the inactive lines as well as active, so in this case the metric AltCountLineCode would return the desired result. If your primary interest in inactive code is the metrics, than the Alt metrics should suffice.

Alternatively, the option "Create references in inactive code" in Project->Configure-> C++ Options causes the parser to do a text only search of the inactive code and tries to find matches to existing objects. No parsing occurs, simply a text match. If the object is not used previously in active code, then there will be no existing object to match against, so the reference will not be recorded. Additionally, if a reference is found, it won't show up as a declare or define, it will show up as an "inactive use". Make sure you have this option turned on, and see if it meets your needs, since it is much safer.

Finally, there is a hidden option to activate all code, but since treating all code as active can quickly lead to improperly parsed code and lots of problems, we keep that option hidden. For example, consider the following code:

#ifdef MACRO1
void somefunction(int a){
#else
int somefunction(varchar b){
#endif
 int c=1;
}

which would yield the following (very invalid) code:

void somefunction(int a){
int somefunctions(varchar b){
 int c=1;
}

This is a very trivial example, but you end up with an improperly formatted function with two conflicting header definitions, which will cause parsing problems and invalid metrics as well as navigation problems when you try to jump to the source definition, etc.

To enable this (risky) option use the following syntax from the command line:

und -db myproject.udb settings -c++IgnorePreprocessorConditionals on analyze

This will reparse the project with inactive references enabled. To disable, run the same command with the off parameter. With the older version of und (build 570 or earlier) the syntax is

und -db myproject.udb -reference_inactive on -analyzeAll

We often get asked for a list that compares Understand with other similar products, but this is harder to do than you might think. To our knowledge we have no direct competitors. We have taken a unique approach with Understand, focusing on helping you maintain your code. We do that through metrics, graphs, code standards checking, plugins, and many other ways. If you are strictly after a metrics tool, there are definitely other options, but Understand will do a great job at providing you with what you need, along with a ton of other features. So, without making a list of literally hundreds of features, in dozens of different products, here is a diagram that compares Understand with some of the other major tools in the software development market.

Single Developer License

If you have a single developer license, simply download Understand from www.getunderstand.com and enter the Single Developer code after the installation. No other steps are needed. If you have lost your code, you can send an email to keys@scitools.com to have us resend your code.

Floating License

If you have a new client, simply install Understand from www.getunderstand.com and point it to the license server when prompted. If you are moving the license server itself, follow the instructions at www.scitools.com/floating.php to get the almhostid for the new server. Then send that id to keys@scitools.com along with the license.dat file from the old license server, and we will send a license file for the new server.

If all licenses are in use and you need to free one, follow these steps:

• First run almstatus to see which licenses are checked out.
• Note the key of the license you wish to free.
• Next run almfree with the key you wish to release.

That's all it takes to release a checked out license.

Automation

If you want to take this a step further, even automating it, here is a perl script that should help. Give it the number of hours you would like checkouts limited to, and it will free any licenses checked out longer than that. For example, you could create a job to run the script twice a day and free any license in use for more than 12 hours. That would prevent users from going home and leaving Understand running. Use at your own risk though, if they are running a huge report that takes three days to run, they won't be happy with you. :-)

CODE:

#!/usr/bin/perl -w

# almtimeout
# Synopsis: Free floating licenses that have been checked out too long.

use Getopt::Long;
use strict;

sub usage($) {
return shift(@_) . <<"END_USAGE";
Usage: $0 -t [timeout]
-tltime [timeout] Timeout - Req. Hours that the key can be checkedout
-v Verbose - Optional

END_USAGE
}

my $timeout;
my $help;
my $verbose;
GetOptions(
"help" => $help,
"t|time=s" => $timeout,
"v" => $verbose,
);

# help message
die usage("Remove licenses that have passed the timeout thresholdn") if ($help);
die usage("Timeout requiredn") if ! $timeout;

# Run almstatus
my $status = `almstatus`;

#Parse output
my @statlines = split(/n/,$status);
my $checktime = localtime;
my $output ="";
print "Checking keys at $checktimen" if ($verbose);
foreach my $line(@statlines){
my @sl= split(/ +/,$line);
if (@sl>10 && $sl[9] eq "age:"){
my $key = $sl[2];
my $time = $sl[10];
my $hours = &parseTime($time);

#free the license
if ($hours >= $timeout){
`almfree $key`;
print "Key freed from $sl[4] on $sl[6] at $checktimen" if ($verbose);
}
}
}

#Parse the timestring and return the number of hours the license has been checked out.
sub parseTime($)
{
my $timeString = shift;
my $hours =0;
my $days = 0;
if($timeString =~ s/h.*//){
$days = $timeString;
$hours = $timeString;
$days =~ s/d.*//;
$hours =~ s/.*d//;
$hours = $hours + 24*$days;
}
return $hours;
}

The command almstatus will show what licenses are checked out by the License Manager.

The almstatus executable can be run from a client or the license server, and needs to be accessed through a command prompt. It is located in the same directory as Understand.

Example

On the license server below, Pete Kuhlmann has 1 license of Understand for C checked out.

CODE:
C:Program FilesSTIbinpc-win95>almstatus
Using V2 License File: C:Program FilesSTIconflicenselicense.dat
Server: shire (hostid: 8bd0ea3a, port: 9000)
understand_pro_l1 qty: 5 inuse: 0 checkout: 0 checkin: 0 timeout: 0 deny: 0 maxout: 0
understand_ada qty: 1 inuse: 0 checkout: 0 checkin: 0 timeout: 0 deny: 0 maxout: 0
understand_analyst_l2 qty: 1 inuse: 1 checkout: 8 checkin: 7 timeout: 0 deny: 1 maxout: 1
key: 0x7a05b82d user: Pete Kuhlmann host: KuhlKoder qty: 1 age: 5s, expires: 55
understand_f qty: 1 inuse: 0 checkout: 0 checkin: 0 timeout: 0 deny: 0 maxout: 0

Details

• qty: Total number of licenses available
• inuse: Total number of licenses currently being used
• checkout: Running count of licenses that have been checked out
• checkin: Running count of licenses that have been checked back in
• timeout: Running count of licenses that have timed out & been checked in automatically
• deny: Running count of requested licenses denied for any reason
• maxout: The highest number of licenses checked out at any given time

All of these are reset every time the service is started.

Sometimes some servers are setup in such a manner that users cannot create services from the command line. This seems to happen mostly on Windows Server 2003 and 2008 for some reason. The license manager seems to start, but a check in the services list does not show the "STI License Manager" Service. The work around for this is to create a scheduled task to launch the License Manager at machine startup instead of using services.

• Under Start | Accessories | System Tools select Scheduled Tasks
• Select Add a Scheduled task
• Browse to the almd executable, by default it is at: C:\Program Files\sti\bin\pc-win32\almd.exe
• Perform this task: "When my computer starts"
• Enter the login username and password for an administrative user
• Open the advanced properties of the task
• Under the settings tab, uncheck the "stop the task if it runs for 72 hours" box
• Save the task, and reboot.
• The license manager should now be running in the background

You can verify it is running by looking at the task manager for "almd", or by running almstatus on the server.