File: @(#)r3uatgREADME.txt	1.2 - 07/26/05

PROGRAM: TraceGraph (r3uatg) - Recon3 Trace Visualization Tool

SYNOPSIS:
TraceGraph is a tool to help a software engineer understand a
program he must enhance or maintain. The engineer instruments
the program so that it produces "traces" as it executes. TraceGraph
displays these traces graphically so that the engineer can see
which parts of the program are executed as it performs different tasks.

TraceGraph can run on any computer that has the Java Development
Kit, version 1.4 or better. You will need the "jar" archive program as
well as the "java" interpreter. To check what version of Java you
have installed, give the command:

  java -version

and look for a version of 1.4 or better.

You can get the latest version of the Development Kit (SDK) free from:
  http://java.sun.com/j2se

TraceGraph is part of the Recon3 toolset. See the web site at:
              http://www.cs.uwf.edu/~recon
for more information about how to use the Recon3 tools.
In accepting and using TraceGraph and other Recon3 tools,
you agree to the Disclaimer of Warranty posted on that web site.

USAGE:
In a command line window (e.g. a Windows "command prompt" window
or a Sun shelltool window) cd to the "classes/"
directory created by the TraceGraph installation. Give the command:
     java r3uatg.R3uatgTraceGraph
Alternately in Windows you can give the command:
     TG
to run a bat file to start TraceGraph.

A TraceGraph window should open.

DESCRIPTION:
TraceGraph's display is designed to let a software engineer see quickly how
a program's execution changes as different features are executed. 
To get an idea of how it works we suggest that you try some
of the examples from the "demos" menu to get started. See the
help option on the demos menu for information on how to run them.

For background and some examples of the use of
TraceGraph, see our Technical Report at:
  http://www.cs.uwf.edu/~wilde/publications/TecRpt86F/TR86F_ExSum.htm
(also presented at the International Conference on Software Maintenance
in October, 2000).

To use TraceGraph on your own software, you will probably first
want to instrument it so that it will produce trace records as
it runs. You can do this by hand, by using a profiler or test
coverage tool, or by using one of the Recon3 instrumentors described
on our web site.

Once your program is producing traces, you feed them to TraceGraph
by choosing "Open Trace Source" from the "file" menu. Several different
kinds of trace sources are supported (files, sockets, etc.).

One common situation is that your program has produced a series of
trace files from different test runs. In this case an easy way
to use TraceGraph is to create an empty directory and tell TraceGraph
to open a "Continuing Directory" trace source to read from it. Then
slowly drop the trace files into that directory one at a time, starting with
traces that do not have the feature you are looking for. As you drop
in each trace, TraceGraph should display one more column on its display. 
When you finally add a trace from a test that DOES have the feature
you are looking for you should see some red rectangles that probably
point to the code for that feature.

KNOWN BUGS OR LIMITATIONS:
   TraceGraph is still being actively developed and enhanced. We
   would welcome your suggestions for improvements, bug fixes, etc.
   See the "change request" section on our web site.

SEE ALSO:
   r3ciREADME.txt   - README file for the Recon3 C/C++ instrumentor
   r3fiREADME.txt   - README file for the Recon3 Fortran 77 instrumentor
   r3ctmcREADME.txt - README file for the Recon3 C/C++ Trace Manager Client

The following documentation used by the Recon3 development team
provides detailed specifications which may be useful:

  r3uarch.htm - The Architecture of Recon3.
     Provides an overall description of the toolset, its design
     criteria, the relationships between the different tools,
     the different architectures (Basic, Extended, etc.), the
     different kinds of program events which may be traced,
     trace record and file formats in different modes, etc.

  r3csrs.htm - Recon Instrumentor for C/C++ - SRS.
     Provides a detailed Software Requirements Specification (SRS) for
     the Recon3 C/C++ instrumentor (r3cinst).

  r3ctsrs.htm - Recon3 C/C++ Trace Manager - SRS
     Provides a detailed Software Requirements Specification (SRS) for
     the Recon3 C/C++ trace manager

  r3fisrs.htm - Recon Instrumentor for FORTRAN - SRS
     Provides a detailed Software Requirements Specification (SRS) for
     the Recon FORTRAN instrumentor.