The HJ Distribution
--------------------

This HJ distribution has the following hierarchy:

	/bin
		/hjc	  	: hj compiler 	
		/hj			: hj runtime
	/lib	
		/*.jar 		: jar files needed by commands
	/examples		: Some simple examples	
	INSTALL			: this file


Requirements
-------------

1) Java 1.6 or later with JRE (please check your JAVA_HOME environment variable is set) 
2) Apache Ant 1.7 or later


Setup
-----

Java 1.6 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


Installing The Distribution
----------------------------

1) Define the HJ_HOME variable to point to the distribution folder.

	export HJ_HOME='path_to_this_folder'

Note: if you cd to the folder that contains this INSTALL file, you can just copy/paste this command:

	export HJ_HOME=`pwd`
	
2) Update your PATH in order to be able to use 'hjc' and 'hj' commands.

	export PATH=$HJ_HOME/bin:$PATH

Testing Installation
----------------------------

If you invoke `which hjc` in a terminal, it should print the path to the hjc binary.
In case this is not working you should check for errors in your HJ_HOME and PATH environment variable

Example:
	echo $HJ_HOME

Using hj commands
-----------------

The hj commands are very similar to standard java commands.
You can get a list of option by using the --help option on both
the compiler and the runtime command.

1) COMPILATION

SAMPLE USAGE:
   hjc --help
   hjc Example.hj
   hjc ./src/pack/pack2/Example2.hj
   hjc -sp ./src -cp ./classes Example.hj

Try "hjc HelloWorld.hj" in examples

2) EXECUTION

SAMPLE USAGE:
	hj --help
	hj Example
	hj pack.pack2.Example2
	hj -cp ./classes Example


Try "hj HelloWorld" in examples as an example.

Using Abstract Execution Metrics
--------------------------------

The abstract execution metrics provide a way to easily calculate the total work and 
critical path length of a parallel program. hj.lang.perf.addLocalOps() provides a simple 
API to count the number of operations at any execution point in the program as a unit of 
work. At the end of execution, the runtime will report the total number of operations 
executed in the program and also the critical path length.

See ArraySum1 and ArraySum2 in the examples/ directory.

Usage:

hj -ABSTRACT_EXECUTION_STATS=true -ABSTRACT_EXECUTION_OVERHEAD=<value> -RT=wsh <filename>

where:
ABSTRACT_EXECUTION_STATS        := enables printing of execution metrics
ABSTRACT_EXECUTION_OVERHEAD     := specifies the number of overhead cycles for every async
RT                              := specifies which runtime to use <wsh = worksharing>

Contact vcave at rice.edu if you face any problems.
