General Notes:
--------------

* In order to install JCilk, you need to download the following software:
- jcilk.tar 
  I assume you have this already, since you are reading this note.

* You also need to the following software in your PATH:
- some version of the gcc / cc compiler to compile gcc as part of the 
  JCilk compiler
- bison for generating a new parser according to the yacc files 
  $BASEDIR/jcilk_release/jgo/gcc-3.3.3/gcc/java/*.y 
- apache-ant for compiling polyglot
- Java 5 or above for running and compiling JCilk runtime system, which uses 
  the Atomic variables from Java 5 API.  If you have various versions of Java
  lying around, and you don't want to put a specific one in your path, you 
  will need to manually modify the following files to setup the JAVA 
  variable to point to the right path:

  $BASEDIR/jcilk_release/runtime/lib/Makefile.jni
  $BASEDIR/jcilk_release/bin/run-bench.pl
  $BASEDIR/jcilk_release/bin/run-jcilk.sh

* The most difficult installation step is perhaps getting the modified gcj
  to install correctly.
  
* The installation will end up using roughly 1.5G disk space


Installation Steps: 
-------------------

* Compile / install modified gcj:
  unzip jcilk.zip into $BASEDIR 
  cd into $BASEDIR/jcilk_release/jgo/srcdir
  unzip and untar gcc-3.3.3.tar.gz in the directory 
  cd into $BASEDIR/jcilk_release/jgo/srcdir/gcc-3.3.3

* Apply patches:
  patch -p3 < ../jgo.patch
  patch -p1 < ../gcc-3.3.3-3.3.4.diff
  patch -p1 < ../gcc-3.3.4-3.3.5.diff
  patch -p1 < ../gcc-3.3.5-3.3.6.diff

* Since we patched parse.y and parse-scan.y, we want to regenerate parse.c 
  and parse-scan.c.  Manually remove these two files:

  rm $BASEDIR/jcilk_release/jgo/srcdir/gcc-3.3.3/gcc/java/parse.c
  rm $BASEDIR/jcilk_release/jgo/srcdir/gcc-3.3.3/gcc/java/parse-scan.c

* To install gcc, follow the usual instructions at 
  http://gcc.gnu.org/install/ as a reference

  Specifically, this is what one may do:

  mkdir objdir in $BASEDIR/jcilk_release/jgo/ 
  cd into objdir
  ../srcdir/gcc-3.3.3/configure --prefix="$BASEDIR/jcilk_release/jgo" --enable-thread=posix --enable-shared --enable-language=c++,java --with-as=<assembler to use> --with-ld=<linker to use>
  make bootstrap
  make
  make install 

  Notes: 
  - in the configuration step, it is important to specify the prefix flag 
    so that this installation does not clobber your existing installation of
    gcc.  The binary from this installation will be called gcc still.  I have
    tried using the --program-transform-name to rename the binary, but that
    didn't work so well, so I recommend against it unless you want to debug
    the config file from gcc or the generated Makefile.
  - if you didn't specify $BASEDIR/jcilk_release/jgo as your default
    installation path, then you should modify the $JGOC variable in
    $BASEDIR/jcilk_release/benchmarks/Makefile.bench for the Makefile to
    work properly.
  - the --enable-thread and --enable-language are obviously important in
    this installation.
  - the other flags are optional; gcc installation instruction recommends
    using the gnu version of as and ld; you can use the --with-as and
    --with-ld flag to specify the path to gnu as and gnu ld if they are not
    specified as your default as / ld. 
  - my make -k check did output some errors, but the overall installation
    seems to work still.

* Compile jcilk polyglot extension:
  make sure that apache ant is installed and in your PATH
  cd into $BASEDIR/jcilk_release/polyglot-1.3.2-src
  ant 
  ant jcilk

* Compile jcilk runtime:
  cd into $BASEDIR/jcilk_release/runtime/lib
  make -f Makefile.jni
  cd ..
  javac -classpath lib jcilk/*.java
  javac -classpath lib profile/*.java
  
* Setup the scripts and Makefile, i.e. change the var $JCILKBASE in the 
  following files: 
  
  $BASEDIR/jcilk_release/benchmarks/Makefile.bench 
  $BASEDIR/jcilk_release/bin/run-bench.pl
  $BASEDIR/jcilk_release/bin/run-jcilk.sh
  
  to be '$(BASEDIR)/jcilk_release'

* Setup your environment variables:
  set $PATH to include $BASEDIR/jcilk_release/bin
  set $LD_LIBRARY_PATH to include $BASEDIR/runtime/lib
  
* Test your installation:
  cd into $BASEDIR/jcilk_release/benchmarks/fib
  make -f ../Makefile.bench Fib.class

  This should produce Fib.java and Fib.class in the same directory.
  Then run:

  $BASEDIR/jcilk_release/bin/run-jcilk.sh Fib 33 

  This should give you the answer of 3524578 ... if not, something has gone
  horribly wrong.  

  In which case, to test which step has gone wrong, try:

  make -f ../Makefile.bench Fib.java
  If this does not produce a Fib.java, then Polyglot subcomponent is not 
  working correctly.
  
  If that worked, try: 
  make -f ../Makefile.bench Fib.class
  If this does not produce a Fib.class, then the modified gcj subcomponent is 
  not working correctly.

  If that worked, try: 
  $BASEDIR/jcilk_release/bin/run-jcilk.sh Fib --nproc <n> 33 
  with <n> replaced with the number of processors you like to use to run 
  the Fib program.  If this does not output result of 3524578, then the 
  JCilk runtime is not working correctly.

  Feel free to contact me at angelee AT mit DOT edu to help you debug the
  installation.


Components:
-----------

* The JCilk system includes the following:
- The compiler, which includes two parts
  polyglot -- compile *.jcilk to *.java (with goto statements)
  jgo -- compile *.java with goto to *.class
- The runtime system, which includes two branches and one library
  implemented in jni:
  lib -- implemented in jni for timing purpose  
         the library gets time via making the system call gethrtime() 
         (so your system needs to support this in order to use this lib)
  jcilk -- the implementation of JCilk runtime in Java that doesn't include
           any timing facility
  profile -- the implementation of JCilk runtime in Java for profiling
             purposes; this branch includes timing calls (use the jni lib) 
             and other extra stuff for getting better timing, such as 
             padding to prevent false cache sharing between threads,
             wasteful loop execution to warm up the OS before timing, etc. 
- The benchmarks:
  Regular benchmarks: fib, matrixOp, queens
  To compile any benchmarks, go into any of the directory and do 
  make -f ../Makefile.bench <file>.class  
  To run, do:
  $BASEDIR/jcilk_release/bin/run-jcilk.sh <file> parameters 
  extra paramemeters for JCilk: 
    --nproc <n> to run the program with n threads.

  Profiling benchmarks: profile
  The files in this directory are Java files compiled by polyglot then
  subsequently hand-modified by me to include things that needed for getting
  better timing.  To compile any of the files, do:
  make -f ../Makefile.bench <file>.class  
  To run, do:
  perl $BASEDIR/jcilk_release/bin/run-bench.pl [-options] file [arg] 
  where options include: 
    --runs  | -n         The number of runs to execute
    --nproc | -p         The max number of processors to use
    --dir   | -d         The name to use for the output folder
                         Output to stdout if not specified
    --clear | -c         Clear the output file if it exists;
                         otherwise append the output
    --help  | -h         Display this help message

  Running this script produces *.txt files with the timing results
  To parse the timing results, do:
  perl $BASEDIR/jcilk_release/bin/parseOutput.pl <file>-*.txt

- The bin directory:
  Just the few scripts that I mentioned above.

 
For more details on how the JCilk compiler is implemented, see paper:
http://supertech.csail.mit.edu/papers/jcilk-scp.pdf

For a list of publication on the JCilk project, check out the project page:
http://supertech.csail.mit.edu/jCilkImp.html 


Restriction on Distribution:
----------------------------

This release of the JCilk distribution is governed by the GPLv3
license as described by the following copyright notice.

Copyright (C) 2005, 2007 John Danaher, I-Ting Angelina Lee 

JCilk is free software: you can redistribute it and/or modify it under the
terms of the GNU General Public License as published by the Free Software
Foundation, either version 3 of the License, or (at your option) any later
version.

JCilk is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
details.
 
You should have received a copy of the GNU General Public License along with
JCilk, in the file named COPYING.  If not, see <http://www.gnu.org/licenses/>.

The polyglot component is also released under the Eclipse Public License. 
For more details, refer to the README and LICENSE.Eclipse file under the
polyglot directory.


