?? userman.html
字號:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
<TITLE>RECON Users' Manual</TITLE>
<META NAME="GENERATOR" CONTENT="Mozilla/3.01Gold (Win95; I) [Netscape]">
</HEAD>
<BODY BGCOLOR="#F5F5F5">
<P>
<!-- SCCS File Identification
/*====================================================================*/
/* Page : @(#)userman.html 2.12 - 04/04/00 */
/*====================================================================*/
-->
<H2 ALIGN=CENTER>RECON USER'S MANUAL</H2>
<P>This software was created as a project by students in the Software Engineering
program at the University of West Florida. </P>
<H3>TABLE OF CONTENTS</H3>
<OL>
<LI><A HREF="#disclaimer">DISCLAIMER OF WARRANTY</A> </LI>
<LI><A HREF="#purpose">INTRODUCTION </A></LI>
<OL>
<LI><A HREF="#purpose">Purpose</A> </LI>
<LI><A HREF="#what">What You Need</A> </LI>
<LI><A HREF="#problem">Problem Reporting</A> </LI>
<LI><A HREF="#cautions">Cautions and Warnings</A> </LI>
</OL>
<LI><A HREF="#about">QUICK START TUTORIAL </A></LI>
<OL>
<LI><A HREF="#about">About the Tutorial Program</A> </LI>
<LI><A HREF="#copying">Copying and Compiling the Recon Source Files</A>
</LI>
<LI><A HREF="#steps">Steps for Tutorial Setup</A> </LI>
<LI><A HREF="#instr">Instrumenting the Source Code</A> </LI>
<LI><A HREF="#compile">Compiling the Instrumented Version</A> </LI>
<LI><A HREF="#test">Testing the Instrumented Version</A> </LI>
<LI><A HREF="#analyze">Analyzing the Test Results</A> </LI>
</OL>
<LI><A HREF="#using">USING RECON OPTIONAL INSTRUMENTATION FEATURES</A>
</LI>
<LI><A HREF="#unix">UNIX MULTI-PROCESS PROGRAMS</A> </LI>
<LI><A HREF="#enhance">RECON ENHANCEMENTS</A> </LI>
<LI><A HREF="#recon">RECON COMMANDS AND FILES</A> </LI>
<LI><A HREF="#glossary">GLOSSARY</A> </LI>
</OL>
<P>
<HR>
<A NAME="disclaimer"></A><B>1.
DISCLAIMER OF WARRANTY</B> </P>
<P>In accepting and using RECON, you agree to the following disclaimer
of warranty: </P>
<P>THIS SOFTWARE AND MANUAL ARE PROVIDED "AS IS" AND WITHOUT
WARRANTIES AS TO PERFORMANCE OR MERCHANTABILITY OR ANY OTHER WARRANTIES
WHETHER EXPRESSED OR IMPLIED. BECAUSE OF THE VARIOUS HARDWARE AND SOFTWARE
ENVIRONMENTS INTO WHICH THIS PROGRAM MAY BE PUT, NO WARRANTY OF FITNESS
FOR A PARTICULAR PURPOSE IS OFFERED. </P>
<P>GOOD COMPUTER PROCEDURE DICTATES THAT ANY PROGRAM BE THOROUGHLY TESTED
WITH NON-CRITICAL DATA BEFORE RELYING ON IT. THE USER MUST ASSUME THE ENTIRE
RISK OF USING THE PROGRAM. ANY LIABILITY OF THE PROVIDER WILL BE LIMITED
EXCLUSIVELY TO PRODUCT REPLACEMENT. </P>
<P>Some states do not allow the exclusion of the limit of liability for
consequential damages, so the above limitation may not apply to you. </P>
<P>This agreement shall be governed by the laws of the State of Florida
and shall inure to the benefit of the Wilde Bunch, the University of West
Florida, and any successors, administrators, heirs, and assigns. Any action
or proceeding brought by either party against the other arising out of
or related to this agreement shall be brought only in a STATE or FEDERAL
COURT of competent jurisdiction located in Okaloosa or Escambia County,
Florida. The parties hereby consent to in personam jurisdiction of said
courts.
<HR></P>
<P>
<A NAME="purpose"></A><B>2.
INTRODUCTION</B><BR>
</P>
<P><B>2.1 Purpose</B> </P>
<P>RECON is a tool to help software engineers locate the parts of a large
target program that implement a particular program feature. First, RECON
makes an <A HREF="#instrumentation">instrumented </A>copy of the user's
target program source code with output statements on each branch structure.
Then, the software engineer compiles and runs the instrumented code using
some test cases that use the feature and others that do not. RECON identifies
which branches in the program were executed most frequently when the feature
was being used. These branches provide good starting points for locating
the feature when reading the program's code. </P>
<P>If you have not already done so, read the document <B><A HREF="overview.html">RECON
- OVERVIEW</A></B> for a quick introduction to the steps in using RECON.
For information on how to install and build RECON on your system, refer
to the "readme.txt" file that is included in the distribution file.<P>
<P>
<A NAME="what"></A><B>2.2
What You Need</B> </P>
<P>To use RECON, you need a C/C++ Compiler. It is assumed that you have a broad
knowledge of C programming and are familiar with compilers, editors and
testing. You must know how to recompile and relink the <A HREF="#target">target
program</A>. You must also understand the purpose of the target program
well enough to be able to write test cases that exhibit the program feature
you want to locate. </P>
<P><A NAME="problem"></A><B>2.3
Problem Reporting</B> </P>
<P>Please report all documentation and software problems to: </P>
<DL>
<DD>Dr. Norman Wilde </DD>
<DD>Department of Computer Science </DD>
<DD>University of West Florida </DD>
<DD>Pensacola, FL 32514<BR>
</DD>
<DD>(904) 474-2548<BR>
</DD>
<DD><A HREF="mailto:nwilde@uwf.edu">nwilde@uwf.edu</A>
</DD>
</DL>
<P>Let us know if you have any suggestions for improvement to RECON.</P>
<P><A NAME="cautions"></A><B>2.4
Cautions and Warnings</B> </P>
<P>Normally, RECON does not modify the original source code files, but
if the user specifies that the instrumented source path is the same as
the original source path, the original source file <B>will be overwritten</B>
by the <A HREF="#instrumentation">instrumentation</A> program. </P>
<P>RECON may <B>substantially slow your software</B> since it keeps track
of each time a branch is executed. If performance is important, keep test
cases short or avoid instrumenting files that contain the innermost loops
of your program. Consider also using the <A HREF="#mintrace">Minimum Trace</A>
option described in the Glossary. There may be a modest size increase in
your compiled code. </P>
<P>
<HR><A NAME="about"></A><B>3.
QUICK START TUTORIAL </B></P>
<P><B>3.1 About the Tutorial Program</B> </P>
<P>All the examples in this document are based on a simple Reverse Polish
Notation (RPN) Calculator program adapted from Kernigan and Ritchie, <B>The
C Programming Language (2nd edition)</B>. The program can be considered
to have four features: addition, subtraction, multiplication and division.
We will show how the branches for the multiplication feature are located.
The four files that comprise the calculator program are: </P>
<DL>
<DD>rpnmain.c </DD>
<DD>rpngetop.c </DD>
<DD>rpnstack.c </DD>
<DD>rpngetch.c </DD>
</DL>
<P>In reverse Polish notation, each operator follows its set of operands;
an infix expression like: </P>
<DL>
<DD>(1 - 2) * (4 + 5) </DD>
</DL>
is entered as: <BR >
<DL>
<DD>1 2 - 4 5 + * Q<CR> </DD>
</DL>
<P>Each test case is terminated by Q<CR> to end execution of the tutorial
program. </P>
<P>To find the unique code where the multiplication operation is executed,
first define a set of test cases, some of which use the multiplication
("*") operator, some of which do not. For the example, we have
selected the test cases in Table 1. Note that there is one test case that
exhibits the multiplication feature and three that do not. </P>
<CENTER><TABLE BORDER=3 CELLPADDING=1>
<TR>
<TH>test case</TH>
<TH>description</TH>
<TH>exhibits feature?</TH>
</TR>
<TR ALIGN=CENTER>
<TD>6 3 * Q<CR></TD>
<TD>multiplication<BR> 6*3=18</TD>
<TD ALIGN=CENTER>Y</TD>
</TR>
<TR ALIGN=CENTER>
<TD>6 3 / Q<CR></TD>
<TD>division<BR> 6/3=2</TD>
<TD>N</TD>
</TR>
<TR ALIGN=CENTER>
<TD>6 3 + Q<CR></TD>
<TD>addition<BR> 6+3=9</TD>
<TD>N</TD>
</TR>
<TR ALIGN=CENTER>
<TD>6 3 - Q<CR></TD>
<TD>subtraction<BR> 6-3=3</TD>
<TD>N</TD>
</TR>
</TABLE></CENTER>
<CENTER><P><B>Table 1. Test Cases for the RPN Calculator</B> </P></CENTER>
<P><A NAME="copying"></A><B>3.2
Copying and Compiling the Recon Source Files</B> </P>
<P><strong>Copy and compile</strong> the RECON source files to a directory as described
in the "readme.txt" file that is included in the distribution file. For the purpose of this document
we will use this path: <STRONG>/usr/cs/<usrname>/<RPN source file dir>
</STRONG>. Substitute a directory name of your choice in its place. </P>
<P><A NAME="steps"></A><B>3.3
Steps for Tutorial Setup</B> </P>
<P>The tutorial examples are shown for the <STRONG>UNIX</STRONG> operating
systems. For the MS DOS operating system, simply add the drive letter and
change the " / " to " \ ". </P>
<P>Create a directory to hold the instrumented source files: </P>
<DL>
<DD><TT>/usr/cs/<usrname>/<RPN source file dir>/inst</TT> </DD>
</DL>
<P>Also create a directory to hold the output trace files and analysis:
</P>
<DL>
<DD><TT>/usr/cs/<usrname>/<RPN source file dir>/inst/out
</TT> </DD>
</DL>
<P><A NAME="instr"></A><B>3.4
Instrumenting the Source Code</B> </P>
<P><B>Introduction<BR>
</B>Your "C/C++" source files will be "instrumented" so
that a trace file will be produced every time your program is executed.
<A HREF="#instrumentation">Instrumentation</A> involves copying your source
files and inserting statements that will write to the trace file when a
branch is executed. </P>
<P>You may not want to instrument some files of your program, either because
you are sure the feature you are looking for is not located in certain
files, or because some files contain loops that will produce a large trace
file. </P>
<P><B>Processing<BR>
</B>At the DOS prompt run <CODE>r2inst</CODE> giving the full path name of the file
to be instrumented and the location of where to place the instrumented
file. It is best to provide the full directory path name of the source
files. If a relative path is given as an input to <CODE>r2inst</CODE>, <CODE>r2analyz</CODE> will
fail to find the source file unless run from the same directory used in
running <CODE>r2inst</CODE>. </P>
<P>For the RPN tutorial, give the following instrumentation commands: </P>
<TT>
r2inst /usr/cs/<usrname>/<RPN source file dir>/inst/rpngetch.c<BR>
r2inst /usr/cs/<usrname>/<RPN source file dir>/inst/rpngetop.c<BR>
r2inst /usr/cs/<usrname>/<RPN source file dir>/inst/rpnmain.c<BR>
r2inst /usr/cs/<usrname>/<RPN source file dir>/inst/rpnstack.c
</TT><BR>
</P>
<P><I><strong>Hint:</strong></I> When using RECON on your own target program, you can create
a <strong>DOS batch file or UNIX shell script</strong> containing the instrumentation commands.
Commands to copy other needed files, such as headers or makefiles, could
also be included. Then you can reinstrument easily by just running the
batch file or shell script. </P>
<P><B>Output<BR>
</B>The result of the <A HREF="#instrumentation">instrumentation</A> process
is a set of instrumented source code files. For example, an "if"
statement on line 5 would be changed from: </P>
<DL>
<DD><TT>if ('a' == c) </TT></DD>
</DL>
to: <BR>
<DL>
<DD><TT>if (('a' == c)?R2True(R2srcfile_ptr,5):R2False(R2srcfile_ptr,5))</TT></DD>
</DL>
<P>where R2srcfile_ptr points to the path of the preinstrumented source
file.</P>
<P>The instrumented RPN Calculator files will be created and placed in
?? 快捷鍵說明
復制代碼
Ctrl + C
搜索代碼
Ctrl + F
全屏模式
F11
切換主題
Ctrl + Shift + D
顯示快捷鍵
?
增大字號
Ctrl + =
減小字號
Ctrl + -