readme.txt

<!-- File: @(#)readme.txt	1.1 Ver 03/14/00 -->


A.  INTRODUCTION
B.  UNIX SETUP AND INSTALLATION INSTRUCTIONS
C.  MS-DOS/WINDOWS SETUP AND INSTALLATION INSTRUCTIONS
D.  DISTRIBUTION FILES
E.  RECON DOCUMENTATION
F.  DEMO TARGET SYSTEM
G.  KNOWN BUGS AND LIMITATIONS
H.  COMMENTS AND SUGGESTIONS
I.  THE HONOR ROLL


A.  INTRODUCTION

    RECON is a tool for "software reconnaissance" -- finding where
    program features are implemented in C/C++ code. Read this document
    along with the RECON Overview and the User's Manual, prior to using
    the program.

    RECON is distributed in source code form as compressed (.Z) files
    for both ANSI and pre-ANSI versions of Unix.  It is also available
    in either source code or pre-compiled form, distributed as a
    self-extracting installation file, for MS-DOS/Windows platforms.
    RECON has been used successfully on a variety of MS-DOS and UNIX
    platforms.


B.  UNIX SETUP AND INSTALLATION INSTRUCTIONS

    To setup RECON (ANSI version) on a Unix system:
    1.  Type "make" to compile the source files to create the
        following six executables:
        - r2inst*
        - r2analyz*
        - r2test*
        - r2end*
        - r2testq*
        - r2endq*

    2.  Type "make clean" to delete the object (*.o) files from
        your working directory.

    3.  Refer to the User's Manual, for an explanation on how to
        run RECON on your software.

    NOTE:  Untarring and uncompressing the distribution file creates
           the following independent subdirectories:
            "recon_ansi" -- contains the RECON program source files
                            needed to instrument your target software.

            "recon_demo" -- contains files and subdirectories for you
                            to practice with the RECON demo "target
                            system." (see the User's Manual for usage
                            instructions)

    NOTE FOR PRE-ANSI USERS:  It is assumed that users who select the
    pre-ANSI version possess the appropriate software compiler to
    compile the executable files.  Please refer to the enclosed
    "Makefile" to determine the file dependencies required for
    compilation.


C.  MS-DOS/WINDOWS SETUP AND INSTALLATION INSTRUCTIONS

    1.  To install the EXECUTABLE distribution:
        a.  Place the downloaded file into a temp directory on your
            system.

        b.  Double-click the downloaded file to begin the installation
            program and follow the on-screen instructions.

            NOTE:  The installation program creates two independent
            subdirectories:
              "recon_ansi" -- contains the RECON program executable
                              files, along with the source files needed
                              to instrument your target software.

              "r2_demo" -- contains files and subdirectories for you to
                           practice with the RECON demo "target system."
                           (see the User's Manual for usage instructions)

        c.  Once the installation has completed, please refer to the
            User's Manual ("userman.html") for instructions on how to
            run RECON on your software.

    2.  To install the SOURCE distribution:

        a.  Follow steps 1a - 1c above.

        b.  Once the installation has completed, you will need a C
            compiler to create the following executable files:
            - r2inst.exe
            - r2analyz.exe
            - r2test.exe
            - r2end.exe

            NOTE:  Please refer to the enclosed "Makefile", provided
            with this distribution, to determine the file dependencies
            for compiling these executable files.  Your compile command
	    line must include the macro definition "-DSYS_DOS".
	    Alternatively, you can define this macro by uncommenting the
	    appropriate line in the r2.h file.

        c.  After compiling the necessary files, please refer to the
            User's Manual ("userman.html") for instructions on how to
            run RECON on your software.


D.  DISTRIBUTION FILES

    The Unix and MS-DOS (source) distributions contain these files:
      instfile.c     r2analyz.h     r2end.c        r2test.c
      instfile.h     r2annote.c     r2inst.c       r2tlist.c
      instpars.c     r2annote.h     r2inst.h       r2tlist.h
      instpars.h     r2build.c      r2outset.c     r2util.c
      instrmnt.c     r2build.h      r2outset.h     r2util.h
      instrmnt.h     r2btree.c      r2read.c       vb_print.c
      instutil.c     r2btree.h      r2read.h       vb_print.h
      instutil.h     r2clist.c      r2select.c
      r2analyz.c     r2clist.h      r2select.h             

    The Unix distribution also contains these extra files:
      r2endq.c  
      r2testq.c
  
    The MS-DOS (executable) distribution contains these four executables:
      r2analyz.exe
      r2end.exe
      r2inst.exe
      r2test.exe

    The following files are included in all distributions:
      Makefile (for UNIX)     rpngetop.c
      r2.h                    rpnmain.c      
      r2anl.lst               rpnstack.c
      r2protos.c              readme.txt
      r2protos.h              overview.html
      rpngetch.c              userman.html


E.  RECON DOCUMENTATION

    Three documents are distributed with RECON:

    1.  README -- this document
    2.  OVERVIEW -- provides brief overview of what RECON does
    3.  USER'S MANUAL -- explains how to run RECON on your software


F.  DEMO TARGET SYSTEM

    A demo "target system" is distributed with RECON to help you try
    it out and to provide examples of the files you need to create to
    use RECON.  The files are included in each distribution and are
    installed as indicated in sections B and C above.  Note that the
    r2anl.lst file contains file pathnames that will probably have to
    be edited to work on your system.  The demo target system is
    explained in the User Manual.  The demo files are:
      - r2anl.lst
      - rpngetch.c
      - rpngetop.c
      - rpnmain.c
      - rpnstack.c


G.  KNOWN BUGS AND LIMITATIONS

    RECON is very sensitive to the exact format of the data in the
    analysis list file (ex. r2anl.lst). Avoid blank lines, extra
    spaces, etc.

    The annotated listing output from r2analyz shows the ">>>>"
    marker just before the LAST line of a multi-line "if" statement
    instead of before the FIRST line of the statement.

    RECON reports "Attempt to write to a closed trace" message for
    instrumented destructors in C++.


H.  COMMENTS AND SUGGESTIONS

    We welcome comments and suggestions about RECON or its methodology.
    We will try to fix defects if we can. Please use the "Problems/
    Program Changes" page found on the RECON homepage whenever possible.
    You may also contact:

    Norman Wilde (email: nwilde@uwf.edu)
    Department of Computer Science
    University of West Florida
    Pensacola, FL 32514
    U. S. A.


I.  THE HONOR ROLL

    RECON is the product of multiple cycles of specification, prototyping,
    experimentation, enhancements, etc. by the students in the Masters in
    Software Engineering Program at the University of West Florida. Major
    contributors were:

    The "FUNFIND" project team, 1991 - 92 Ronald Arlund, Lane Clarke,
    Eldon Ford, Juan Gomez, Thomas Gust, Jessica Hatsfelt, Thomas Minks,
    Joe Parker Jr., Caroline Pepa, Lisa Rung, Joy Siler, Stan Stewart,
    Douglas Strasburg

    The "RECON2" project team, 1992 - 93 David Applegate, Duane A. Barts,
    Stanley Burson, William Chestnut, Lee Greenwood, Jake Goodson, Larry R.
    McCallie, Lawrence P. McCaskill, Doyel McMillon, Ken Leone, Bob
    Littlefield, Tim Parsons, Lou Richard, Greg Wolfe

    The "TEMPORARY" project team, 1994 - 95 Kevin Bongiovani, Scott Brown,
    John Carlin, Chris Casey, Chuck Cooper, Kim Davenport, Mike Jackowski,
    Leslie Love, Gail Mitchell, Suzanne Nagy, Karen Sledge.

    The "ALLSTAR" project team, 1995 - 96 Melanie Ivery, Neale Currie,
    Orlando Figueredo, Mark, Clyde Hurst, Rob Matles, Bryce Meyer, Gail F.
    Mitchell, Indara Outsama, Mark Reeves, Robert L, Mark Gillott, Peter D.
    Tully, Marcela Pohl, Billy C. Miller

    The "Java Brew Crew!" project team, 1996 - 97 Robin Bridges, Charles
    Coker, John Colby, Wayne Flood, Chris Hagen, Don Hall, Rich Jones,
    David Kennedy, Larry Landry, German Maranon, Emily Martinez, Flo Moore,
    Dolf Nation, Ariadne Rivera, Carlyne Rooney, Jim Sahm, Jeff Ward

    The "TDY Bunch, specialists in distance development!" project team,
    1997 - 98 Ann Marie Barden, Bob Boone, Duane Braford, Dan Clapp,
    Alan Conwell, Jay Flint, Tom Gillette, Warren Hall, Donna Karlek,
    Lorn Kerr, Ron Megill

    The "Another TDY Bunch" project team, 1998 - 99 Luis Araujo, Glen Ashby,
    Randy Bauer, Christopher Collins, Joel Cook, Kevin Dewise, J. David
    Fralish, Craig Francks, William Gambrell, Steven Halprin, Timothy
    Hennessey, Phillip Jackson, David Laird, Thomas Marler, Tracie McCoy,
    Alfred McLeod, Brian Merrick, Henry (Hank) Page, Scott Stowell, Aaron
    Tarnosky, Dennis Ward, Michele (Shelly) Wherley

    The "Millennial Developers" project team, 1999 - 2000 Spencer Armour,
    Darsi Ewing, Rob Gruwell, Dave Hebert, Bob Herring, Robb Illich,
    Gary Jordan, Eischelle Krueger, Ginger Mullins, Henry Outlaw,
    Robby Robison, Don Sandaal, Vince Sclafani, John Timm, Ernest Timmie,
    Vic Tucker, Royce White, Amy Williams