Notes on RELAY 0.7.07
---------------------

What is RELAY?
--------------

RELAY is a static data race detector for C programs.
Version 0.9.09 means this is the September 2009 release 
(the "0." prefix is there to make sure this doesn't 
sound too advanced and bug-free =P)

Changes since 0.7.07:

  - Mainly bug fixes
  - Support for Andersens pointer analysis
  - Hooks for call-graphs generated by other analyses
  - Some tests from Locksmith added
  - Ported some of CIL 1.3.7 over to local copy of CIL

Installation:
-------------

see the included INSTALL text file for instructions


Running RELAY:
--------------

Pick your favorite C program, or try one of the ones included in the test
directory. Let's call that program "PUT" (the program under test).


1) Pick the files to analyze: We first need a list of the source 
   files that should be analyzed. The desired files should
   be listed in a file called "gcc-log.txt" in PUT's directory. 
   This "gcc-log.txt" file can be written manually, or it filled-in 
   by a script that intercepts gcc calls from a Makefile.

   If PUT has a Makefile, first modify $RELAY_DIR/scripts/intercept.sh
   to point to the right $RELAY_DIR, then run:

   $RELAY_DIR/scripts/intercept.sh make -e

   from the PUT directory.


2) Pre-process the source files: We now need to pre-process and generate
   additional linking information for the source files. First edit
   the $RELAYROOT value in the script "$RELAY_DIR/scripts/dump-calls.sh" 
   to point to the location of your RELAY installation. Next, from the PUT 
   directory, run:

   $RELAY_DIR/scripts/dump-calls.sh

   After this completes, there should be a "ciltrees" directory within
   the PUT directory. Within ciltrees, there should be a "calls.XYZ"
   file containing a text representation of the program's callgraph,
   among other files.


3) Now let's run the actual analysis. Change directories to the $RELAY_DIR.
   To test, simply run:
     
     ./relay_single.sh $PUT_DIR/ciltrees

   The results will be echo'ed on screen as well as logged in 
   $PUT_DIR/ciltrees/log.relay. If you have a multi-core processor
   and would like to utilize them, you can run (1) server process 
   and run (n) worker processes. Run the server with

     ./server.sh $PUT_DIR/ciltrees

   And run workers with:

     ./relay.sh $PUT_DIR/ciltrees

   Logs, in that mode will be dumped to stdout which you can re-direct
   however you like.

   Either way, the analysis will write some of status messages along with the
   data race. Additionally, the warning data will be written to 
   $PUT_DIR/ciltrees/warnings.xml. The data can then be loaded into a database. 

   Scripts in $RELAY_DIR/ui/relay/warnings are available for parsing 
   the XML and loading it into a database. Additionally, scripts for 
   filtering-out unlikely race warnings is available. At the moment, however, 
   this optional component depends on the Django web framework.

4) Testing: a few sanity tests are included in the "racetests" directory.
   To run use it run "make renew_small" then run "make" and look in the 
   diff_out file to see if there are any differences from the output
   logs that were generated by my version of RELAY.

