-----------------------------
| Installation Instructions |
-----------------------------

1. Download DOOP (r160113) and soot-fact-generation (r958) from
   http://doop.program-analysis.org/download.html.

2. Unzip DOOP and soot-fact-generation, then set environment variable DOOP_HOME
   to the directory where you unpack DOOP by:
   $ export DOOP_HOME=unpack_directory/doop-r160113-bin/

3. Download sootclasses-2.5.0.jar from http://www.sable.mcgill.ca/software/sootclasses-2.5.0.jar
   and then put it in $DOOP_HOME/lib/ directory. (DOOP (r160113) provides sootclasses-2.3.0.jar,
   SOLAR's facts generator needs sootclasses-2.5.0.jar)

4. Unzip all files within SOLAR distribution to $DOOP_HOME and then apply solar.patch to DOOP by:
   $ cd $DOOP_HOME
   $ patch -p1 < solar.patch

5. Switch to soot-fact-generation directory, write:
   $ patch -p1 < $DOOP_HOME/gen.patch
   $ ./compile
   $ ./install

Now, the SOLAR has been installed on the top of DOOP.

In addition, to run SOLAR, users should follow the instructions in $DOOP_HOME/README to setup 
the applications and library (to be analyzed) and configure the corresponding paths.

----------
| Usages |
----------

SOLAR has the similar usage with DOOP, except that you cannot use -disable-reflection,
-disable-reflective-methods and -distinguish-no-string-constants options.

In addition, SOLAR adds three options about reflection analysis:
-probe:
 	Switch to PROBE, a simplified version of SOLAR, which is used to identify the
 	problematic reflective calls in the case of that SOLAR is unscalable for a program.

-generate-soot-reflection-log:
	Output reflection analysis results of SOLAR with a format which is supported by Soot
	so that Soot can make use of SOLAR.

-reflect-method FILE:
	Specify the file which includes the annotations for Method-related
	member-introspecting methods, i.e., Class.getMethod(), Class.getDeclaredMethod(),
	Class.getMethods() and Class.getDeclaredMethods().

By default, SOLAR distinguishes a string constants if it is a class name, a method name or a
field name. For fairly comparing with DOOP, SOLAR treats the string constants which represent
method names or field names as one string constant while computing the size of points-to set.


-------------------------
| Using SOLAR with Soot |
-------------------------

It just takes two steps to use SOLAR to facilitate the static analysis with Soot.

Step 1: Running SOLAR and generating reflection log
-------------------------------------------------------------------------------

To let SOLAR create reflection log file, you can use the option "-generate-soot-reflection-log"
which is mentioned above, and then SOLAR will output its reflection analysis results into a
log file.

The log file name is the name of the main class of the program to be analyzed plus ".log" as suffix.

For example, let us use SOLAR to analyze luindex benchmark of DaCapo:  

$ ./run -jre1.6 -generate-soot-reflection-log selective-2-type-sensitive+heap jars/dacapo/luindex.jar
$ ...
$ generating reflection log for Soot at dacapo.luindex.Main.log
$ ...

Now, SOLAR has output its reflection analysis results to dacapo.luindex.Main.log.


Step 2: Running Soot with the reflection log generated by SOLAR
-------------------------------------------------------------------------------

To use the reflection analysis results of SOLAR with Soot, you just need to give Soot the log
file generated by SOLAR by using the option "reflection-log".

Soot provides the option "reflection-log" in call graph construction phase to load
a reflection log from the given file and use it to resolve reflective call sites. 

For example, let us use Soot to analyze luindex with reflection log from SOLAR: 

$ java -cp soot-2.5.0.jar soot.Main \			# run Soot
-w -app -p cg.spark enabled \					# enable Spark
-p cg reflection-log:dacapo.luindex.Main.log \	# use the reflection log from SOLAR
-cp luindex.jar:${JRE}/jce.jar:${JRE}/rt.jar \	# set up class path for Soot
-main-class dacapo.luindex.Main \				# specify main class
dacapo.luindex.Main


---------------------------------------------------------------------------
|Automatic identification of problematic reflective calls, and annotations|
---------------------------------------------------------------------------

SOLAR can automatically identify problematic reflective calls that may threaten its
soundness and precision, together with their corresponding annotation points, to enable
both to be improved with lightweight annotations. For example, if a newInstance() call
generates an unknown object which flows to a type cast (T) and the number of reflective
targets inferred from T is larger than 50, then SOLAR will output the newInstance()
call as a potential imprecise call and identify its related entry method calls.

SOLAR is able to receive annotations for entry methods (i.e., Class.forName() and
ClassLoader.loadClass()) and Method-related member-introspecting methods. You can use
"-dynamic" option provided by DOOP to specify the annotation files for entry methods
and use "-reflect-method" option to specify the annotation files for Method-related
member-introspecting methods as mentioned before. For example:

$ ./run -jre1.6 -dynamic hsqldb.dynamic -reflect-method hsqldb.meth \
selective-2-type-sensitive+heap jars/dacapo/hsqldb.jar

The format of annotation file is quite simple. Each line of the annotations should
contain a reflective call site and one of its target, and the call site and its target
are separated by a tab.

If you are familiar with DOOP, then you should know how DOOP represents a call site:
caller/callee/index

The "caller" specify the method which contains the call site. If the method is not overloaded,
then "caller" should be its class name plus its method name (e.g., java.lang.Object.toString).
If the method is overloaded, then "caller" should be the full signature of the method (e.g.,
<java.lang.Object: void wait(long)>).

The "callee" is the class name plus method name of target method of the call site
(e.g., java.lang.Class.forName).

All call sites (within one method) to the methods with same name are indexed from 0.

For example, you can annotate entry method calls with its target classes like:

org.hsqldb.Function.<init>/java.lang.Class.forName/0	java.lang.Math
org.hsqldb.Function.<init>/java.lang.Class.forName/0	org.hsqldb.Library
...

And you can annotate member-introspecting method calls with its target methods like:

java.beans.Introspector.getPublicDeclaredMethods/java.lang.Class.getMethods/0	<com.puppycrawl.tools.checkstyle.api.Check: void setTabWidth(int)>
java.beans.Introspector.getPublicDeclaredMethods/java.lang.Class.getMethods/0	<com.puppycrawl.tools.checkstyle.api.Check: void setTokens(java.lang.String[])>
...


------------------------
| Main changes to DOOP |
------------------------

- logic/library/solar/annotation-guidance.logic
- logic/library/solar/array.logic
- logic/library/solar/inference.logic
- logic/library/solar/lazy.logic
- logic/library/solar/propagation.logic
- logic/library/solar/reflect-stats.logic
  New added files which contains main parts of SOLAR.
  
- logic/context-sensitive.logic
- logic/library/reflective.logic
  Fix unsound handling of argument passing for reflective invocation.

- logic/library/reflection-delta.logic
  Add place holders for helping reflection analysis.
  
- logic/library/string-constants.logic
  Distinguish string constants whose values equal method names or field names.

- scripts/get-refl-targets.py
- scripts/problematic-call.py
- scripts/soot-converter.py
  New added scripts for assisting SOLAR output its results.
  
- gen-import
  Import more facts for reflection analysis. 
  
- run
  Add "-probe" and "generate-soot-reflection-log" options to facilitate SOLAR.

- stats-simple
  Output reflection analysis results.

  
- soot-fact-generation/src/FactWriter.java
- soot-fact-generation/src/FactGenerator.java
- soot-fact-generation/src/PostDominatorFinder.java
  Generate more facts for reflection analysis, such as the ones involving post dominance.
  

Please feel free to contact the authors if you have any concerns.
