README

   1 This is the *very* early beginning to a new flow engine for the Checker
   2 Framework. The old one was mostly copied directly from Sun javac and had to
   3 work around some of its bad decisions; this one is intended to convert the
   4 abstract syntax tree provided by the Java compiler into a control flow graph
   5 and then work over that.
   6
   7 # Initial Setup #
   8
   9 (This is covered in more detail in the Checker Framework manual; this is just a
  10 jumpstart guide.)
  11
  12 First, get and compile the jsr308-langtools code:
  13
  14     hg clone https://jsr308-langtools.googlecode.com/hg/ jsr308-langtools
  15     cd jsr308-langtools/make
  16     ant build-javac
  17     ant build-javap
  18
  19 Now get and build the Checker framework code:
  20
  21     hg clone https://checker-framework.googlecode.com/hg/ checker-framework
  22     (export CLASSPATH="../../jsr308-langtools/dist/lib/javac.jar:../../\
  23      jsr308-langtools/dist/lib/javap.jar:$CLASSPATH" ; ant)
  24
  25 # Structure of a Java Compiler Plugin #
  26
  27 A javac plugin is just a class that extends `AbstractTypeProcessor`[1] and
  28 implements the following methods (as well as others---these are the ones that
  29 I have found a need to implement):
  30
  31 * `void typeProcess(TypeElement[1], TreePath[2])` is the method called by the
  32 compiler to start up the processor. If you are using a TreePathScanner, then
  33 create it from here and run it on the `TreePath` argument.
  34
  35 * `SourceVersion[3] getSupportedSourceVersion()` should just return
  36 `SourceVersion.RELEASE_7` to indicate that you are using Java 7.
  37
  38 # Implementing a Tree Scanner to Walk the Abstract Syntax Tree #
  39
  40 The Java compiler provides access to the AST via a Visitor[4] class called
  41 TreePathScanner<R, P>. The type parameters are, respectively, the return type
  42 of each of the visit methods implemented by your visitor and the type of the
  43 second parameter of each visit method.
  44
  45 My initial goal would be to create a flow control graph of the given code.
  46 Then, each specific flow analyzer (e.g. the one checking variable nullness)
  47 would walk the CFG and do as they wished with it. The perceived benefits of
  48 this method:
  49
  50 * It is easier for the programmer to understand changes on a CFG than an AST,
  51 and most of the literature demonstrates data flow analysis on CFG:s.
  52
  53 * Bookkeeping by each individual checker is reduced. Checkers only need to
  54 pay attention to the information that affects them. (`NullnessFlow.java` has
  55 941 lines of code; it is expected that this number could be greatly reduced.)
  56
  57 # Building and Running your Compiler Plugin #
  58
  59 When compiling your plugin, ensure that `checker-framework/checkers/binary/\
  60 jsr308-all.jar` is in your CLASSPATH. This contains, in particular, the
  61 updated version of the Java compiler. If you forget to do this the compiler
  62 will complain about `SourceVersion.RELEASE_7` not existing, as that symbol
  63 is not found in the Java 6 compiler.
  64
  65 Also, you can not use the 'javac' command but must instead call the class
  66 directly, like so:
  67
  68     java com.sun.tools.javac.Main \
  69         -Xbootclasspath/p:"$CLASSPATH"
  70         -processor NullFlowChecker \
  71         # put more options here if you need them
  72         ClassToCompile.java
  73
  74 The `-Xbootclasspath/p:` option is particularly important as the compiler
  75 will not see `SourceVersion.RELEASE_7` (and likely some other important
  76 classes in `jsr308-all.jar`) without it.
  77
  78 # Footnotes #
  79
  80 1. Found in package `com.sun.source.util`.
  81 2. Found in package `javax.lang.model.element`.
  82 3. Found in package `javax.lang.model`.
  83 4. See GoF, page 331