README

Checker Framework Inference README
==================================

This project aims to provide a general type inference framework
for the Checker Framework.

The checker-framework-inference google drive folder contains additional docs:
https://drive.google.com/drive/u/1/folders/0B7vOZvme6aAOfjQ0bWlFU1VoeVZCVjExVmJLM0lGY3NBV0VLcENYdm03c0RCNGFzZURHX2c

All suggestions for improvements are very welcome!

If you want to extend the framework for your own type system or add
additional constraint solvers, please send us a mail!

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

You will need a JDK and gradle.
I usually use OpenJDK 7.

Install the source-versions of these three tools:

http://types.cs.washington.edu/jsr308/
http://types.cs.washington.edu/annotation-file-utilities/
http://types.cs.washington.edu/checker-framework/

You'll need CHECKERFRAMEWORK, JSR308, JAVA_HOME, and AFU environment variables set up appropriately.

insert-annotations-to-source (from AFU) must be on your path.

Make sure that all tools are compiled correctly and that all Checker
Framework test cases work.

NOTE: gradle on Ubuntu 14.10 hard-codes JAVA_HOME. To change this, edit
    /usr/share/gradle/bin/gradle
  and replace
    export JAVA_HOME=/usr/lib/jvm/default-java
  with
    [ -n "$JAVA_HOME" ] || export JAVA_HOME=/usr/lib/jvm/default-java

Building
------------

To build:
    gradle dist

Execution
------------

Verify you have all of the requirements.

./scripts/inference.py is the script used to run inference.

example:

./scripts/inference.py --log-level FINE --mode roundtrip --checker ostrusted.OsTrustedChecker --solver checkers.inference.solver.PropagationSolver [List of files]

There are a couple of required options:

--mode
Specifies what the tools should do.
Available options are [infer, typecheck, roundtrip, roundtrip-typecheck]

infer:
    Generates and solves the constraints and writes the results to default.jaif file

typecheck:
    Typechecks the existin code

roundtrip:
    Generates and solves the constraints and then inserts the results back into the
    original source code

roundtrip-typecheck:
    Executes roundtrip and then typechecks the result

--checker
Specifies which checker to run.
The two most supported checkers at the moment are

checkers.ostrusted.OsTrustedChecker and
checkers.tainting.TaintingChecker

--solver
Which solver to use on the constraints.

checkers.inference.solver.PropagationSolver is the only real solver at the moment.

Omiting the solver will create an output that numbers all of the annotation positions in the program.

checkers.inference.solver.DebugSolver will output all of the constraints generated


Other options can be found by ./scripts/inference.py --help.