Notes on RELAY / RADAR 0.10.03
---------------------

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

RELAY is a static data race detector for C programs. Version 0.10.03 means 
that this is the March 2010 release (the "0." prefix is there to make 
sure this doesn't sound too bug-free =/)

RADAR is a framework for converting non-thread-aware dataflow analyses into
being thread-aware. There are a few demo dataflow analyses provided:

 - constant propagation
 - non-null pointer
 - very busy expressions

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

See the included INSTALL text file for setup instructions and notes on tests.


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. 
   
   IMPORTANT: Edit the the $RELAYROOT value in the script 
   $RELAY_DIR/scripts/dump-calls.sh and $RELAY_DIR/scripts/dump-with-stats.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.


Running RADAR:
--------------

Similar setup as RELAY.

As an example, to run the provided concurrent VBE analysis run:

  ./very_busy.sh $PUT_DIR/ciltrees

Also available are scripts {const_prop.sh, null_check.sh}. The other 
null-related scripts are likely outdated.