
JRIF: Reactive Information Flow Control for Java
------------------------------------------------

JRIF introduces reactive information flow labels in Jif (http://www.cs.cornell.edu/jif/).
This file is adaptation of the README file in the Jif distribution.

Since you are reading this file, you have already downloaded and unpacked
the JRIF distribution.  Your installation directory contains the following
sub-directories and files:

  - src:      the complete source code of the JRIF compiler
  - doc:      JRIF documentation 
  - lib:      needed JAR files
  - bin:      scripts to run the JRIF compiler
  - examples: JRIF examples (battleship and shared calendar)
  - rt-src:   source code for the JRIF runtime classes
  - sig-src:  JRIF signatures for standard Java classes, e.g. java.lang.Object
  - lib-src:  JRIF source code for utility classes, e.g. jif.util.List
  - tests:    Some JRIF source code to test the JRIF compiler
  - CHANGES:  Changes introduced in the Jif compiler, to implement JRIF 

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

This JRIF distribution builds on Unix (Linux, MacOS) and on Windows under the
Cygwin environment. JRIF is compiled with the Ant build tool
(http://jakarta.apache.org/ant). You must ensure that java, javac, and g++ are
in your path.

Software Versions: We recommend that you use JDK 1.4.2 or later.

JRIF and Cygwin: JRIF can be built and used on a Windows platform running 
   Cygwin. Several issues are worth pointing out however. 
     - The GNU C++ compiler, g++, must be installed in order to build the 
       JRIF native runtime library.
     - The w32api package must be installed, to ensure the appropriate 
       Windows header files are present.
     - Great care must be taken in specifying class paths and environment
       variables. Any classpath used when compiling JRIF programs must be
       understandable by both the javac compiler and ant. Thus, for 
       example, if setting the environment variable JRIF to the JRIF 
       installation directory, the variable should be set to either the 
       string "c:\data\jrif", or "c:/data/jrif". It should not be set to 
       the string "/cygdrive/c/data/jrif", which cannot be interpreted by
       javac correctly.
       In addition, note that the path separator on a Windows platform is
       the semicolon (';'), and, class paths should be set accordingly, 
       for example:
          setenv CLASSPATH "$POLYGLOT/polyglot.jar;$POLYGLOT/lib/jflex.jar;$POLYGLOT/lib/java_cup.jar"
     - We have had some reports that some versions of Cygwin are 
       incompatible with building JRIF, however, cygwin-1.5.16-1 appears to 
       be compatible. 

JRIF is implemented using the Polyglot extensible compiler toolkit,
also developed at Cornell. To built JRIF, please use
the polyglot release included in this installation directory.

Files polyglot.jar, JFlex.jar and java_cup.jar are
required to build JRIF.

This JRIF distribution contains some C++ code, used to produce
platform-specific JRIF runtime support. JRIF requires the g++ compiler
to be present to compile this C++ code.


Building JRIF
------------

We give general instructions on how to build JRIF,
along with particular commands (as an example) used to build JRIF in Ubuntu 14.04.
These commands start with a "-".

Jif is compiled with the Ant build tool
(http://jakarta.apache.org/ant).  Follow these steps to build the JRIF
compiler:

1. Ensure javac is on your path and that you are using JDK 1.4.2 or
   later. Set the JAVA_HOME environment variable to the Java home
   directory.  The file $JAVA_HOME/include/jni.h should exist.

- sudo apt-get update
- sudo apt-get install openjdk-6-jdk
- sudo apt-get install g++
- sudo apt-get install ant

- JAVA_HOME="/usr/lib/jvm/java-6-openjdk-amd64"
- export JAVA_HOME
- echo $JAVA_HOME

2. Install polyglot, included in this directory.
You may place the polyglot directory out of this directory.
See README in polyglot directory for general installation instructions.

- cd polyglot_for_jrif/
- ant
- ant jar

- PATH=$PATH:$HOME/bin:$JAVA_HOME/bin:/home/ubuntu/polyglot_for_jrif/bin
- CLASSPATH=".:/home/ubuntu/polyglot_for_jrif/classes:/home/ubuntu/polyglot_for_jrif/lib/java_cup.jar"
- export PATH
- export CLASSPATH
- echo $PATH
- echo $CLASSPATH

(The definition of variables JAVA_HOME, PATH and CLASSPATH, can also
be done by editing /etc/profile (sudo vi /etc/profile), 
and then executing: source /etc/profile .)


2. Go to the root directory of the JRIF installation (the directory
   this README is in). We'll call this directory $JIF from now on.

    $ cd $JIF

3. Copy config.properties.in to config.properties, and then edit
   config.properties to make "polyglot.home" the absolute
   path of your Polyglot installation.

- Edits:
   * polyglot.home=/home/ubuntu/polyglot_for_jrif  [uncomment and modify]
   * #jdk.home=${java.home}  [comment]
   * jdk.home=${env.JAVA_HOME} [uncomment]


4. Run ant to configure the system.

        $ ant configure
   
   This ensures that the classpath is set appropriately, and creates the
   executable scripts $JIF/bin/jifc and $JIF/bin/jif.


5. Run ant to build the platform-specific Jif runtime support.

        $ ant jif-runtime

   This compiles the $JIF/rt-src directory. Some of the code in this
   directory is C++ code, and the compilation of this code is
   platform-specific. Jif requires the C++ compiler g++ to be
   available to compile this code. If you do not have g++ but do have
   an alternative C++ compiler, you may be able to modify the file
   build.xml file to use the other compiler.

   The resulting files will be stored in $JIF/rt-classes.

   The Jif distribution comes with the Jif compiler almost completely
   pre-built (in the lib directory), and is nearly usable "out of the
   box." If you want, you can now skip step 6, which builds the Jif
   compiler, and proceed directly to step 7.

6. Run ant to build the JRIF compiler, JRIF signatures for standard Java
   classes and the JRIF library code.

        $ ant

   This compiles the $JIF/src, $JIF/sig-src and $JIF/lib-src
   directories.

   The resulting .class files for the source code in $JIF/src,
   $JIF/sig-src and $JIF/lib-src will be stored in $JIF/classes,
   $JIF/sig-classes and $JIF/lib-classes respectively.


7. You are now ready to try out JRIF.  A suggested starting point is
   the BattleShip example, in the directory
   $JIF/examples/rif_battleship. See the README file in that directory for
   more detailed information on compiling and running the BattleShip
   example.



Running JRIF
-----------

Scripts named "jifc" and "jif" are created in the $JIF/bin directory
during the configuration process (see above, step 3). The jifc script
runs the JRIF compiler, and the jif script provides a convenient way to
execute the compiled JRIF code.

The jifc script automatically ensures the directories $JIF/classes and
$JIF/lib-classes are on the classpath, and that the directories
containing the runtime classes and signatures classes ($JIF/rt-classes
and $JIF/sig-classes) are specified with the "-rtcp" and "-sigcp"
flags respectively. In addition, the appropriate jar files (jif.jar,
jiflib.jar, jifrt.jar and jifsig.jar) are also added to the
appropriate classpaths, which allows the Jif compiler to be used "out
of the box."

The command line options for jifc can be viewed by running jifc with the
"-h" flag:
    $ $JIF/bin/jifc -h
    usage: jifc [options] <source-file>.jif ...
    where [options] includes:
      @<file>                  read options from <file>
      -d <directory>           output directory
      -assert                  recognize the assert keyword
      -sourcepath <path>       source path
      -bootclasspath <path>    path for bootstrap class files
      -ext <extension>         use language extension
      -extclass <ext-class>    use language extension
      -commandlineonly         only compile files named on the command-line (may
			       also require -c)
      -preferclassfiles        prefer class files to source files even if the 
			       source is newer
      -fqcn                    use fully-qualified class names
      -sx <ext>                set source extension
      -ox <ext>                set output extension
      -errors <num>            set the maximum number of errors
      -w <num>                 set the maximum width of the .java output files
      -dump <pass>             dump the ast after pass <pass>
      -print <pass>            pretty-print the ast after pass <pass>
      -disable <pass>          disable pass <pass>
      -noserial                disable class serialization
      -nooutput                delete output files after compilation
      -c                       compile only to .java
      -outputamb               allow generating code from ambiguous nodes
      -post <compiler>         run javac-like compiler after translation
      -v -verbose              print verbose debugging information
      -report <topic>=<level>  print verbose debugging information about topic 
			       at specified verbosity
	    Allowed topics: imports, jl, labelEnv, serialize, types, frontend, 
	    time, resolver, cfg, visit, labels, error, dataflow, solver, jif, 
	    debug, errors, context, loader, verbose, qq
      -version                 print version info
      -h                       print this message
      -e -explain              provide more detailed explanations of failed 
			       label checking.
      -robust                  enable checking of robustness conditions for
                               downgrading
      -debug <n>               set debug level to n. Prints more information 
			       about labels.
      -stop_constraint <n>     halt when the nth constraint is added
      -globalsolve             infer label variables globally (default: per 
			       class)
      -sigcp <path>            path for Jif signatures (e.g. for 
			       java.lang.Object)
      -addsigcp <path>         additional path for Jif signatures; prepended to 
			       sigcp
      -rtcp <path>             path for Jif runtime classes
      -addrtcp <path>          additional path for Jif runtime classes; 
			       prepended to rtcp

The jif script automatically ensures that the directories
$JIF/rt-classes and $JIF/lib-classes are on the classpath, and that
the Jif runtime native code is on the library load path.

See the Jif documentation ($JIF/doc/index.html) for more information
about writing Jif programs. See the directories $JIF/examples and
$JIF/tests for some examples of Jif programs.

Restrictions on use
-------------------

This free release of the Jif system may be used, modified, and
redistributed as governed by the license included in the attached file
LICENSE.

This software 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 file
LICENSE for more details.
