# $Id: README,v 1.3 2004/06/21 15:42:50 zeller Exp $
# Igor README file

Igor is an automated debugging utility that isolates the cause-effect
chain for program failures: "First, x was 12, therefore, y became 15,
and therefore, the program failed."  Think of Igor as a tool which
automatically tells you why your program failed.

Igor is a research prototype, an experimental tool with lots of bugs
and open issues.  This distribution is targeted towards other
researchers who want to toy around with Igor.  It will take a long
time until these techniques are ready for prime time.  Just be warned.


INSTALLATION

0. You need 
   - an i386 computer with Linux
   - Python 2.3
   - the GNU debugger (GDB)

1. Unpack this directory in a place of your choice - for instance,
   your home directory (say, /home/smith/igor-0.0)

2. In the file igor-0.0/bin/igor, make ROOT point to the actual
   location of the `igor-0.0' directory (default is ~/igor-0.0)

3. Set up your PATH environment variable such that the igor-0.0/bin
   directory is included - for instance:

        $ PATH=$HOME/igor-0.0:$PATH; export PATH

4. For a quick test, run the following steps:

   * Compile and run the 'sample' program:

        $ cd igor-0.0/sample
        $ gcc -g -o sample sample.c
        $ ./sample 7 9 8
        Output: 7 8 9
        $ ./sample 14 11
        Output: 0 11
        $ _

   * Get the diagnosis:

        $ igor sample 'sample 14 11' 'sample 7 9 8' 2> /dev/null
        'sample' FAILS  if it outputs (?i)(\s|\A)0(\s|\Z)
        'sample' PASSES if it outputs (?i)(\s|\A)9(\s|\Z)

        This is what happens when 'sample' is invoked as 'sample 14 11':
        At 'main' (sample.c:35), a[2] is 0
        At 'main' (sample.c:39), a[0] is 0, argc is 3
        At 'main' (sample.c:40) <no relevant state>
        $ _

5. To uninstall igor, just remove the 'igor-0.0' directory.


USER DOCUMENTATION

See http://www.askigor.org/ for resources and tips on how to use Igor.

The man/ directory contains a simple manual page which can be
installed in a usual location (such as /usr/share/man/man1) or simply
viewed using nroff:

        $ cd igor-0.0/man
        $ nroff -man igor.1 | less



USING THE SOURCE CODE

Before you start using the source code, be sure to read and understand
the papers on Igor.  The most important is

    Andreas Zeller: Isolating Cause-Effect Chains from Computer
    Programs. Proc. ACM SIGSOFT 10th International Symposium on the
    Foundations of Software Engineering (FSE-10), Charleston, South
    Carolina, November 2002.  

A PDF copy is available at the ACM digital library as well as at

    http://www.st.cs.uni-sb.de/papers/fse2002/

Once you read the paper, you can have a look at the Igor source.  Igor
is a quite complex program, and its code is hard to read and
understand (despite or because Igor is written in Python).

Note that most of the modules can be run as stand-alone utilities.
Here are the most important Python modules, along with usage examples:

    * GDB - An interface to the GNU debugger (GDB)

        To execute the sample program:

        $ ./GDB.py 'sample' 'sample 7 9 8'

    
    * StateGDB - An subclass of the GDB module which can return a program
      state (state()) as a memory graph (StateGraph)

        To create a new test case (for instance, "sample-pass"):

        $ vi Testcase.py    # Specify program + location in testcase

        To obtain a memory graph for the given test case

        $ ./StateGDB.py sample-pass
        
        To dump the memory graph to standard output:
        
        $ ./dumpstate.py sample-pass.pickle

        To view the memory graph in a graph editor:

        $ ./pickle2dot.py sample-pass.pickle > sample-pass.dot
        $ dotty sample-pass.dot

        To create a PostScript picture:

        $ ./pickle2dot.py sample-pass.pickle > sample-pass.dot
        $ dot -Tps sample-pass.dot > sample-pass.eps


    * StateDelta - Compute a set of deltas (get_deltas()) from two state graphs

        To verify the correct computation of deltas:

        $ ./StateDelta.py sample-pass sample-fail

    
    * DD - An implementation of the delta debugging algorithm

        To run delta debugging on a simple input:
        
        $ ./DD.py


    * StateDD - Delta debugging on states

        To run delta debugging on two testcases `sample-pass' and
        `sample-fail':
        
        $ ./StateDD.py sample

    
    * Run - determine run properties

        To determine the properties of a single run:

        $ ./Run.py sample 'sample 7 8 9'

        To get a testing predicate:

        $ ./TestFactory.py sample 'sample 7 8 9' 'sample 11 14'


    * TesterDD - Run DD on state deltas, using tests as determined from runs

    * BacktraceMatcher - find appropriate breakpoints in two runs
    
To see how these modules interact, have a look at the "igor/igor.py"
script; the "igor" command line utility is just a small wrapper around
'igor.py'.


SUPPORT AND MAINTENANCE

We are busy on a number of projects, so we cannot provide support for
Igor sources.  (We are willing to provide meta-support, though - if
you want to provide support, we will support you!)  Patches and
extensions are gladly accepted, though, and may be incorporated in
future releases.


Happy debugging,

Andreas Zeller