Jif @VERSION@
The Jif Language and Compiler
-----------------------------
Jif is an implementation of the JFlow language (with several
extensions) described in the 1999 paper, Practical Mostly-Static
Information Flow Control, published in the Proceedings of the 26th ACM
Symposium on Principles of Programming Languages (POPL), January 1999,
pp. 228-241, by Andrew C. Myers.
Since you are reading this file, you have already downloaded and unpacked
the Jif distribution. Your installation directory contains the following
sub-directories:
- src: the complete source code of the Jif compiler
- doc: Jif documentation
- lib: needed JAR files
- bin: scripts to run the Jif compiler
- examples: Jif examples
- rt-src: source code for the Jif runtime classes
- sig-src: Jif signatures for standard Java classes, e.g. java.lang.Object
- lib-src: Jif source code for utility classes, e.g. jif.util.List
- tests: Some Jif source code to test the Jif compiler
Requirements
------------
This Jif distribution builds on Unix (Linux, MacOS) and on Windows under the
Cygwin environment. Jif 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 7 or later.
Jif and Cygwin: Jif 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
Jif 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 Jif programs must be
understandable by both the javac compiler and ant. Thus, for
example, if setting the environment variable JIF to the Jif
installation directory, the variable should be set to either the
string "c:\data\jif", or "c:/data/jif". It should not be set to
the string "/cygdrive/c/data/jif", 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 Jif, however, cygwin-1.5.16-1 appears to
be compatible.
Jif is implemented using the Polyglot extensible compiler toolkit,
also developed at Cornell. Polyglot can be obtained from the web site:
http://www.cs.cornell.edu/Projects/polyglot
This Jif distribution contains the files polyglot.jar, jflex.jar and
java_cup.jar from the Polyglot @POLYGLOT_VERSION@ distribution. These files are
required to build Jif.
This Jif distribution contains some C++ code, used to produce
platform-specific Jif runtime support. Jif requires the g++ compiler
to be present to compile this C++ code.
Building Jif
------------
Jif is compiled with the Ant build tool
(http://jakarta.apache.org/ant). Follow these steps to build the Jif
compiler:
1. Ensure javac is on your path and that you are using JDK 7 or
later. Set the JAVA_HOME environment variable to the Java home
directory. The file $JAVA_HOME/include/jni.h should exist.
2. Go to the root directory of the Jif 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 reflect your system configuration.
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. (OPTIONAL)
Run ant to build the Jif compiler, Jif signatures for standard Java
classes and the Jif 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 Jif. A suggested starting point is
the BattleShip example, in the directory
$JIF/examples/battleship. See the README file in that directory for
more detailed information on compiling and running the BattleShip
example.
Running Jif
-----------
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 Jif compiler, and the jif script provides a convenient way to
execute the compiled Jif 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.
Credits
-------
The Jif project is supervised by Andrew Myers at the Cornell University
Computer Science Department. Many people have contributed to this
software.
This release of the Jif compiler was developed by Tom Magrino, Jed Liu,
Owen Arden, and Chinawat Isradisaikul. Steve Chong, Mike George, Matt Loring,
Nate Nystrom, K. Vikram, Steve Zdancewic, Danfeng Zhang, Lantian Zheng, and
Xin Zheng helped develop earlier versions. Thanks also to Aslan Askarov,
Cormac Flanagan, Robert Grabowski, Doaa Hassan, Daniel Hedin, Boniface Hicks,
Dave King, Karl Mazurak, Todd Millstein, Andrei Sabelfeld, Thomas Schmitz,
Lilia Sfaxi, and Steve Zdancewic, who contributed bug reports and feedback for
previous versions of Jif.
Restrictions on use
-------------------
This release of Jif is governed by the GNU Lesser General Public
License as described by the following copyright notice.
Jif @VERSION@
Copyright (C) 1999-@YEAR@ Jif project group, Cornell University
Jif is free software; you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as
published by the Free Software Foundation; either version 2.1 of
the License, or (at your option) any later version.
Jif 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
Lesser General Public License for more details.
A copy of the GNU Lesser General Public License version 2.1 can
be found in the file LICENSE.LGPL, included in this distribution.
More information
----------------
More information about Jif, including the latest release, can be found
at the Jif web site at
http://www.cs.cornell.edu/jif
If you use Jif, we'd appreciate your letting us know. Send your
comments and bug reports to Andrew Myers at andru@cs.cornell.edu. There
is also a Jif users mailing list and a Jif announcement mailing list.
If you would like to receive notification of future Jif updates, please
join these mailing lists; details are on the Jif web site.
Other Acknowledgments
---------------------
This Jif software release was supported by NSF Grant 0964409, by ONR grant
N000140910652, and by the USAF Research Laboratory. Any opinions expressed or
implied in this release are those of the software developers alone, and not
necessarily those of these sponsors.