File: @(#)r3ciREADME.txt	1.3 - 02/15/05

PROGRAM: r3cinst - Recon3 C/C++ instrumentor

SYNOPSIS: Instruments a single C/C++ source file by inserting calls
   to functions in the Recon3 Trace Manager Interface (TMI). When executed,
   the instrumented program will produce traces of execution which
   may be analyzed by other tools in the Recon3 toolset. See the
   Recon3 web site at:
              http://www.cs.uwf.edu/~recon
   for more information about how to use the different tools in the
   toolset. In accepting and using Recon3 you agree to the Disclaimer
   of Warranty posted on that web site.

USAGE:  r3cinst [-derx] <source> <destination>

  -d            Instrument decisions.
  -e            Instrument function entry points.
  -r            Instrument function return points.
  -x            Instrument exit calls.

  source        C/C++ source file to be instrumented.
  destination   Destination file for the instrumented source.

If no flags from the set [-derx] are specified, all flags in
the set will default to on.

DESCRIPTION: r3cinst copies the file at the path
specified by <source> to the path specified by <destination>.
For example the command:
  r3cinst /mySystem/hello.cc /myInstSystem/hello.cc
will copy the file hello.cc from the /mySystem directory
to the /myInstSystem directory, inserting instrumentation
as it copies. The source file is not changed.

Instrumentation consists of calls to functions in the Recon3
C/C++ Trace Manager Interface. The flags control the kinds
of instrumentation to be inserted.

When compiling the instrumented source program, the following must be
observed:

1. The user needs to specify the target operating system and the target
   architecture by uncommenting an appropriate #define statement in
   the file r3.h. See the Recon3 web site page on Configuring
   Recon for more information about the choices.

   For a first trial of Recon3 you might want to use:
      R3_SYS_ANY_OS      - ANY OS with ANSI C library
      R3_ARC_BASIC       - Basic architecture.
   Alternately, these preprocessor macros may be defined by setting
   them on the command line (e.g. "-DR3_SYS_ANY_OS -DR3_ARC_BASIC")
   or in your programming environment.

2. The header files r3.h and r3ctminf.h must be available to
   the compiler, probably in the same directory as each instrumented
   source file.

3. The instrumented program must be linked with r3ctminf.c. (If the
   extended architecture has been specified r3ulbsys.h and r3ulbsys.c
   must be provided too.)

Thus the compile command for the instrumented "hello.cc" program mentioned
above could now be something like:
  g++ -o hello -DR3_SYS_ANY_OS -DR3_ARC_BASIC hello.cc r3ctminf.c

When the resulting program "hello" is executed, trace records will be
written. In the simplest case of the Basic architecture, the trace
file will be named "default.r3t" in the current working directory. 
Much greater control over tracing is provided by using the Extended
architecture and the r3ctmc trace manager.

When instrumenting a large system, r3cinst will need to be called
many times to instrument all the files. The user may want to
use our Instrumentation Script Builder (ISBuilder) tool, a simple
Java program that walks a directory structure creating a script file
or batch file of instrumentation commands.

KNOWN BUGS OR LIMITATIONS:

   r3cinst may be confused by extensive use of the C preprocessor, for
   example using #define to allow "BEGIN ... END" instead of "{ ... }" or 
   using #ifdef within the predicate of an "if" statement.   

SEE ALSO:

   r3ctmcREADME.txt - README file for the Recon3 C/C++ Trace Manager Client
   r3uisbREADME.txt - README file for the ISBuilder program

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.