Setting Up Soot
---------------

1) Make sure that you are subscribed to the JDK-CURRENT package: run
'subscribe' on stdsun; if you are not subscribed, subscribe, log out,
and log in again. As of the time this document was written, running
'java -version' should produce

java version "1.5.0_06"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_06-b05)
Java HotSpot(TM) Client VM (build 1.5.0_06-b05, mixed mode)

NOTE: if you are running out of memory in the JVM, run java with "java
-Xmx288m ...." or something like that - this increases the heap size

2) update your classpath. For example, if you are using tcsh, add the
following to your ~/.cshrc file

setenv CLASSPATH .':'/home/9/rountev/soot-2.2.4/soot-2708/classes':'/home/9/rountev/soot-2.2.4/jasmin-2708/classes':'/home/9/rountev/soot-2.2.4/polyglot-1.3.4/classes':'/home/9/rountev/soot-2.2.4/polyglot-1.3.4/cup-classes

and then log out and log in again

3) first quick test: 'java soot.Main -help' should produce a long list of command-line options

4) second quick test: in some directory, create a file Test.java with the following code:

class Test { 
 public static void main(String[] a) { 
  int x = 5; 
  int y = x + 6; 
  System.out.println(y);
 }
}

Compile the code (javac Test.java). Then, in that same directory, run

java soot.Main -f J Test

As a result, a new file sootOutput/Test.jimple is created. This file
contains a pretty-print version of the intermediate representation
(IR) used by Soot. This representation is called Jimple and it is
constructed from the bytecode of class Test (i.e., from file
Test.class). Have a look inside Test.jimple to get some idea what is
the IR for the input Java class Test.

Static Analysis with Soot
-------------------------

For illustration purposes, we will use a Java program called jlex
(version 1.2.6); this program is similar to the classis 'lex' scanner
generator. First, we will focus on static analysis of the Jimple for
program's methods. 

1) Download, uncompress, and compile jlex: gunzip jlex.tar.gz; tar xvf
jlex.tar; cd jlex-1.2.6; javac JLex/Main.java

2) In the jlex directory that contains subdirectory 'JLex', run 

java soot.Main -f J -app JLex.Main

This processes the bytecode for the main JLex class and all JLex
transitively reachable from it (i.e., all application classes; thus
the -app option). The Jimple for all these classes is created and
stored in directory sootOutput.

3) In some directory (e.g., /home/111/myname/courses/788.12/mycode),
create a subdirectory 'cta' (short for 'compile-time analysis') and
add in it files Main.java, etc. from the web page. These are sample
classes that process the Jimple of each method body; they belong to
package 'cta' (download it from cta.tar.gz). Essentially, this is a
rudimentary plug-in you are going to insert in Soot.  Compile package
'cta' (java cta/*java). Add '/home/111/myname/courses/788.12/mycode'
to your classpath.

4) In the jlex-1.2.6 directory, run 

java cta.Main -f J -app JLex.Main

This is similar to step 2, except now you have plugged your 'cta'
package into Soot. Every time a method body is processed, method
internalTransform in your MyTransform class is called on this
body.

5) Look at the code in MyTransform and change it to measure the
following:

a) Total number of Jimple statements in all methods

b) Total number of Jimple statements in all methods that are branching
statements. These include instances of interfaces GotoStmt, IfStmt,
TableSwitchStmt, and LookupSwitchStmt. Note that these are abstract
types: the concrete classes implementing them are JGotoStmt,
etc. Strictly speaking, we also need to consider ThrowStmt (since it
throws an exception and the flow of control jumps to the exception
handler), but for now we will ignore exceptions and ThrowStmt.

Email me, by noon on Tuesday 9/28, the numbers from (a) and (b) for jlex.