********************************
The CnC-HJ Distribution
********************************

The CnC distribution is created in the folder 'cnc_distrib' which has the following hierarchy:

	/bin
		/cnc_t 		: translate .cnc to .hj
		/cnc_c 		: compiles .hj file to .class
		/cnc_run	  	: runs .class
		/hjc	  		: hj compiler (not directly invoked by cnc user) 	
		/hj			: hj runtime (not directly invoked by cnc user)
	/lib	
		/*.jar 		: jar files needed by commands
	/examples		: contains various .cnc examples
	README.txt		: this file


********************************
Using CnC-HJ
********************************

1) SETUP

1.1) JAVA SETUP

Java 1.5 or later is required, make sure the JAVA_HOME variable is defined in your environment.
Otherwise locate your java installation and execute the following commands:

bash:
export JAVA_HOME=/path/to/java/home
export PATH=${JAVA_HOME}/bin:$PATH

csh:
setenv JAVA_HOME /path/to/java/home
setenv PATH ${JAVA_HOME}/bin:$PATH

1.2) CNC SETUP

You will first need to set two environment variables as follows, assuming that the current directory is set to the uncompressed cnc_distrib folder.

bash:
export CNC_HOME=`pwd`
export PATH=${CNC_HOME}/bin:$PATH

csh:
setenv CNC_HOME `pwd`
setenv PATH ${CNC_HOME}/bin:$PATH

2) CODING

To code a CnC-HJ application, you need to create the following files (you can replace "foo1", "foo2", "foo3", "foo4", "foo5" by any names you choose):

* Graph file --- foo1.cnc, containing a textual representation of the CnC graph

  See examples/FindPrimes/FindPrimes.cnc for a sample.

* Step implementations --- for each step foo2 declared in foo1.cnc, create a concrete class called foo3.hj (say).  The main extensions needed compared to a standard Java 1.4 class are as follows:
   + Add the following import statement, "import CnCHJ.api.*;"
   + Ensure that class foo3 extends class Afoo2 (Afoo2 is automatically generated by the CnC translator)
   + Provide a concrete implementation for the abstract method, compute()

  See examples/FindPrimes/ComputeStep.hj for a sample.

* Main program ---  foo4.hj, written in Habanero Java (HJ).  See examples/FindPrimes/PrimesMain.hj for a sample.  The main extensions needed compared to a standard Java 1.4 main program are as follows:
   + Add the following import statement, "import CnCHJ.api.*;"
   + Add a statement of the form "foo1Graph G = foo1Graph.Factory(new foo3(), ...) where foo1.cnc is the name of the graph file, and foo3, ... are the names of the concrete step classes.
   + Add a statement of the form "finish{ <put-statements> }", where <put-statements> is a computation that performs a series of put() method calls on item and tag collections representing input from the environment.
   + After the finish construct, add get() and dumpContents() method calls for output to the environment.

  See examples/FindPrimes/PrimesMain.hj for a sample.

3) GRAPH TRANSLATION

SAMPLE USAGE: cnc_t foo1.cnc

The cnc_t command invokes the CnC translator.  It takes a .cnc file, foo1.cnc, and generates the following files as output:
   + foo1Graph.hj --- contains a single class with a field for each tag collection and item collection in the program, and a Factory() method to initialize the graph
   + foo5Collection.hj --- for each tag collection foo5 in foo1.cnc, the translator generates a foo5Collection.hj file 
   + Afoo2.hj --- for each step collection foo2 declared in foo1.cnc, the translator generates an Afoo2.hj file containing a single abstract class that specifies the interface for foo2

Try "cnc_t FindPrimes.cnc" in  examples/FindPrimes as an example

3) COMPILATION

SAMPLE USAGE: cnc_c foo4.hj

The cnc_c command invokes the Habanero-Java compiler on the main program (foo4.hj) provided by the programmer.

Try "cnc_c PrimesMain.hj" in  examples/FindPrimes as an example

4) EXECUTION

SAMPLE USAGE:
   cnc_run foo4 <args>
   cnc_run -CNC_NUM_WORKERS nn foo4 <args>

The cnc_run command invokes the Habanero-Java runtime on the main program.  The -CNC_NUM_WORKERS option specifies the number of worker threads to be used by the runtime (typically set to the number of cores in the machine).  <args> is the list of arguments for the main program.

Try "cnc_run PrimesMain 100" in  examples/FindPrimes as an example.  Also try  "cnc_run -CNC_NUM_WORKERS 2 PrimesMain 100".
