Throughout this document I assume that we are using Codesurfer version
1.8 for Linux. I assume that the environment variable CSURF is set in
your .cshrc; I also assume that "set
path = ($path ${CSURF}/bin )" is present in your .cshrc.

How to build an input program using codesurfer (with the correct flags
to ensure that the clone-detection tool works):
-----------------------------------------------

1. Replace "CC = gcc" with

   "CC = csurf -retain-pdg-vertex-to-ast-mapping yes -user-library-path \
     ${CSURF}/libmodels -cfg-edges both -use-def-sets yes cc"

   in the makefile.

   [I am assuming that the
	library stubs have been built in the directory ${CSURF}/libmodels.
	Check out the codesurfer documentation on how to build the library
	stubs. ]
   
2. Sometimes, the source code of the program might need to be modified
   slightly for things to work correctly. Here are some examples of
   changes I performed:

     - the "make" project contains two source files named read.c and
       getopt.c. The problem here is that the library stubs we link
       against (available in ${CSURF}/libmodels) also contains files
       named read.c and getopt.c. Therefore, I renamed these two files
       in the "make" project.

     - remember that codesurfer uses its own versions of the standard
       header files,  not the
       default header files in /usr/include.

       If there are any differences between what the source files in
       the program assume about the header files, and what is present
       in Codesurfer's versions of the header files, there will be
       problems. The source files will then need to be modified
       appropriately. For an example of this, see the differences
       between read.c.orig and renamed-read.c, and the differences
       between dir.c.orig and dir.c, in the program make-3.79.1. In
       each of the these pairs of files, the "orig" version is the
       original whereas the other version is my modified file.

     - In bison-1.25, there is a function xmalloc(n), whose body
       simply is calloc(n, 1). xmalloc is called in many places. I
       manually inlined every call to xmalloc, as that improves the
       accuracy of pointer analysis a lot (each call-site to
       malloc/calloc results in a unique memory location that the
       pointer analysis tracks).

     - Due to a bug in codesurfer, type casts in input programs can
       sometimes cause the clone-detection tool to crash. If that
       happens, the offending type casts need to be determined
       (manually) and removed.

4. After modifying the makefile, and making any necessary changes to
   the source files, say "make a.out" (replace a.out by the
   appropriate name).

How to run the clone-detection on an input program:
---------------------------------------------------

   This is described in the file
   clones-impl/NEW/HOW-TO-RUN-CLONE-DETECTION-TOOL.txt. 

Viewing the clone groups:
-------------------------

1. Choose the minimum group size you are interested in. I call this
   <MINGROUP> from here on. <MINGROUP> has to be >= 2. Choose the
   output file you want to view; this can either be one of the
   OUTPUT.filtered.i.groups files (created by the clone-detection
   tool), or a concatenation of any number of OUTPUT.filtered.i.groups
   files (this concatenation can be created simply by "cat"ing
   together the files).  From here on I call this chosen output file
   <OUTPUT.groups>.

2. Go to the directory containing the project and type "csurf
   <name-of-project>". 

3. Make sure you have a copy of
   clones-impl/NEW/DisplayGroups/display-groups.stk. At the "STk>"
   prompt type ``(load "display-groups.stk")''.

4. At the "STk>" prompt type ``(main "<OUTPUT.groups>"
   <MINGROUP>)''. You can now start viewing the groups. Within each
   group, the clones are displayed two at a time. The menu allows you
   to view the next/previous two clones in the current group, the
   next/previous group, or a specific group (specified using the
   position of the group within <OUTPUT.group>). 
     
How to compile the clone-detection tool:
----------------------------------------

1. Go to clones-impl/NEW/FindClonePairs/reachability,
   clones-impl/NEW/GroupClones/group-pairs/, and
   clones-impl/NEW/FilterClones/filter-pairs/, and in each of these
   directories type "make".

   CAUTION: The various .so files in this distribution are ones that are
   known to work. On the other hand, it is possible that the .cc and .h
   included in this distribution are incorrect versions (i.e., contain changes
   that are incompatible with the .stk scripts). Please save the .so files
   somewhere else before attempting to compile the tool.
