#####################################################################
#
# This file is distributed under the terms in the attached LICENSE file.
# If you do not find this file, copies can be found by writing to:
# Intel Research Berkeley, 2150 Shattuck Avenue, Suite 1300,
# Berkeley, CA, 94704.  Attention:  Intel License Inquiry.
# Or
# UC Berkeley EECS Computer Science Division, 387 Soda Hall #1776, 
# Berkeley, CA,  94707. Attention: P2 Group.
# 
# DESCRIPTION: Readme for P2 release.
# 
#   $Id: README,v 1.1.1.1 2007/07/22 14:29:16 atuls Exp $
#

------------------------------------------------------------
-- BUILDING
------------------------------------------------------------

When you've checked out a fresh repository or modified the autoconf
macros, first run setup to configure your new source tree:

   # ./setup

Then configure:

   # ./configure

Typically, we expect the distribution to run with the following
configure invocation:

   # ./configure CXXFLAGS="-g -Wall -DTRACE_OFF"

For running "make install", you may want to pass a "prefix" to
configure; otherwise libraries and binaries will be installed under /usr/local.

   # ./configure --prefix /path/to/your/spot CXXFLAGS="-g -Wall -DTRACE_OFF"

(and of course replace "/path/to/your/spot" with a path of your choice.)

Finally build: 

   # make

and if that goes well, install:

   # make install

If you install into /usr/local or another shared prefix, you may need
to run the "make install" command as root.

Remember never to edit Makefile or Makefile.in.  Instead, make your
changes to Makefile.am.  If you're still having problems, ask the nice
folks on p2devel@yahoogroups.com.

NOTE ABOUT FLEX:

Make sure to have flex version 2.5.31 or greater installed before
building the project.  Note that current Fedora Core distributions (up
to FC5) come with flex version 2.5.4, which is much older. You should
install a newer flex package. For instance, prebuilt binaries for
2.5.31-5 are available on the web.

NOTE ABOUT AUTOMAKE:

If you want to run automake (i.e., if you want to run ./setup), make
sure you have automake version 1.9 or greater.

NOTE ABOUT GCC:

Please use gcc version 4.0 and later to compile P2. Make sure that the
same major version is used to compile the boost binaries you are
using. When compiling on a current version of Fedora Core (e.g., FC5)
this is usually the case.

NOTE ABOUT BOOST:

This release is known to work with Boost version 1.32.0.

NOTE ABOUT libtool:

This release is known to work with libtool version 1.5.16.



------------------------------------------------------------
-- NOW WHAT?  A DATAFLOW GRAPH
------------------------------------------------------------

You can run our measly unit tests:

   # unitTests/p2Test


You can look at some of our test programs under tests/.  

tests/join is a test that demonstrates a dataflow graph that performs
some matching of semi-random tuples produced over time.  It does not use
OverLog, but puts the dataflow graph together directly.

The testSimpleJoin function creates a new Plumber (the container object
for a dataflow graph), and then constructs the following dataflow graph:

             /------TRANSFORM_A----STORE in A
TUPLESOURCE -|                        
             \------TRANSFORM_B----MATCH with A

TUPLESOURCE arranges a timed push source (producing tuples with the
current time at regular intervals) connected to a Print element
(printing out to standard out the tuples it sees) connected to a
duplicator element that duplicates the timed source stream.  One output
of the duplicator is fed into TRANSFORM_A and the other into
TRANSFORM_B.

TRANSFORM_A is a portion of the dataflow graph that takes the first of
the duplicator's outputs, transforms it with a PelTransform element
(transAS), drops some of its tuples with a Filter element (filterAS),
projects the result to remove the filtering field with a PelTransform
element (filterDropAS), performs duplicate elimination with a DupElim
element (dupElimAS), prints what comes through with a Print element
(transAPrintS), and inserts what remains in a local table with an Insert
element (rehashAS), then discarding the result (sinkAS).

TRANSFORM_B is a portion of the dataflow graph that takes the second of
the duplicator's outputs, transforms it with a PelTransform (transBS) in
a way different from transAS, again filters on a transformed field
(filterBS), projects away some of the transformed fields (filterDropBS),
eliminates duplicates (dupElimBS), and prints the output
(transBPrintS). Then this graph joins this stream with the elements
stored by the TRANSFORM_A branch of the graph, using a UniqueLookup
element (lookupBS) on field numbers 1 on either side, printing what
comes back with a Print element (lookupBPrintS), and then discarding it
(sinkBS).


The entire dataflow (as stored into the conf configuration object) is
passed to the plumber, which is then initialized, and run (with
eventLoop()).

The output on the console is rather verbose.  One can look at the
sequence of output from Print elements by doing:

   # tests/join |& grep Print

"AfterSource" entries indicate a new source tuple has been
created. "ATuples" prints out tuples produced (and stored) by
TRANSFORM_A. "BTuples" prints out tuples produces by TRANSFORM_B, before
the join.  "Matches" prints out those B tuples that match (thus far)
stored A tuples on their field numbers 1.  Some "Matches" tuples contain
an empty subtuple for A tuples: those correspond to B tuples that return
no match.



------------------------------------------------------------
-- NOW WHAT?  A DATAFLOW GRAPH
------------------------------------------------------------


