Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance. Project price only 1 $
You can buy this project and download/modify it how often you want.
<?xml-stylesheet type="text/xsl" href="soot_options.xsl" ?>
<options>
<intro>
<p>
The descriptions of Soot options talk about three categories of
classes: argument classes, application classes, and library classes.</p>
<p>
<var>Argument classes</var> are those you specify explicitly to
Soot. When you use Soot's command line interface, argument
classes are those classes which are either listed explicitly on
the command line or found in a directory specified with the
<tt>-process-dir</tt> option. When you use the Soot's Eclipse
plug-in, argument classes are those which you selected before
starting Soot from the Navigator popup menu, or all classes in
the current project if you started Soot from the Project
menu.</p>
<p>
<var>Application classes</var> are classes that Soot analyzes,
transforms, and turns into output files.</p>
<p>
<var>Library classes</var> are classes which are referred to,
directly or indirectly, by the application classes, but which are
not themselves application classes. Soot resolves these classes
and reads <tt>.class</tt> or <tt>.jimple</tt> source files for
them, but it does not perform transformations on library classes
or write output files for them.</p>
<p>
All argument classes are necessarily application classes. When
Soot <emph>is not</emph> in ``application mode'', argument
classes are the only application classes; other classes
referenced from the argument classes become library classes.</p>
<p>
When Soot <emph>is</emph> in application mode, every class
referenced from the argument classes, directly or indirectly, is
also an application class, unless its package name indicates that
it is part of the standard Java runtime system.</p>
<p>
Users may fine-tune the designation of application and library
classes using the Application Mode Options.
</p>
<p>
Here is a simple example to clarify things. Suppose your program
consists of three class files generated from the following
source:
<pre>
// UI.java
interface UI {
public void display(String msg);
}
// HelloWorld.java
class HelloWorld {
public static void main(String[] arg) {
UI ui = new TextUI();
ui.display("Hello World");
}
}
// TextUI.java
import java.io.*;
class TextUI implements UI {
public void display(String msg) {
System.out.println(msg);
}
}
</pre></p>
<p>
If you run
<pre>
java soot.Main HelloWorld
</pre>
<tt>HelloWorld</tt> is the only argument class and the only
application class. <tt>UI</tt> and <tt>TextUI</tt> are library
classes, along with <tt>java.lang.System</tt>,
<tt>java.lang.String</tt>, <tt>java.io.PrintStream</tt>, and a
host of other classes from the Java runtime system that get
dragged in indirectly by the references to <tt>String</tt> and
<tt>System.out</tt>.</p>
<p>
If you run
<pre>
java soot.Main --app HelloWorld
</pre>
<tt>HelloWorld</tt> remains the
only argument class, but the application classes include <tt>UI</tt>
and <tt>TextUI</tt> as well as <tt>HelloWorld</tt>.
<tt>java.lang.System</tt> et. al. remain library classes.
</p>
<p>
If you run
<pre>
java soot.Main -i java. --app HelloWorld
</pre>
<tt>HelloWorld</tt> is still the only argument class, but the set
of application classes includes the referenced Java runtime
classes in packages whose names start with <tt>java.</tt> as well
as <tt>HelloWorld</tt>, <tt>UI</tt>, and <tt>textUI</tt>. The set
of library classes includes the referenced classes from other
packages in the Java runtime.</p>
</intro>
<section>
<name>General Options</name>
<boolopt>
<name>Help</name>
<alias>h</alias>
<alias>help</alias>
<short_desc>Display help and exit</short_desc>
<long_desc>
Display the textual help message and exit immediately without
further processing.
</long_desc>
</boolopt>
<boolopt>
<name>Phase List</name>
<alias>pl</alias>
<alias>phase-list</alias>
<short_desc>Print list of available phases</short_desc>
<long_desc>
Print a list of the available phases and sub-phases, then exit.
</long_desc>
</boolopt>
<listopt>
<name>Phase Help</name>
<alias>ph</alias>
<alias>phase-help</alias>
<set_arg_label>phase</set_arg_label>
<short_desc>Print help for specified <use_arg_label/></short_desc>
<long_desc>
Print a help message about the phase or sub-phase named
<use_arg_label/>, then exit. To see the help message of
more than one phase, specify multiple phase-help options.
</long_desc>
</listopt>
<boolopt>
<name>Version</name>
<alias>version</alias>
<short_desc>Display version information and exit</short_desc>
<long_desc>
Display information about the version of Soot being run, then
exit without further processing.
</long_desc>
</boolopt>
<boolopt>
<name>Verbose</name>
<alias>v</alias>
<alias>verbose</alias>
<short_desc>Verbose mode</short_desc>
<long_desc>
Provide detailed information about what Soot is doing as it runs.
</long_desc>
</boolopt>
<boolopt>
<name>Interactive Mode</name>
<alias>interactive-mode</alias>
<short_desc>Run in interactive mode</short_desc>
<long_desc>
Runs interactively, with Soot providing detailed information as it iterates through intra-procedural analyses.
</long_desc>
</boolopt>
<boolopt>
<name>Unfriendly Mode</name>
<alias>unfriendly-mode</alias>
<short_desc>Allow Soot to run with no command-line options</short_desc>
<long_desc>
With this option, Soot does not stop even if it received no command-line options. Useful when setting Soot options programmatically and then calling soot.Main.main() with an empty list.
</long_desc>
</boolopt>
<boolopt>
<name>Application Mode</name>
<alias>app</alias>
<short_desc>Run in application mode</short_desc>
<long_desc>
<p>
Run in application mode, processing all classes referenced by
argument classes.</p>
</long_desc>
</boolopt>
<boolopt>
<name>Whole-Program Mode</name>
<alias>w</alias>
<alias>whole-program</alias>
<short_desc>Run in whole-program mode</short_desc>
<long_desc>
<p>
Run in whole program mode, taking into consideration the whole
program when performing analyses and transformations. Soot
uses the Call Graph Constructor to build a call graph for the
program, then applies enabled transformations in the Whole-Jimple
Transformation, Whole-Jimple Optimization, and Whole-Jimple
Annotation packs before applying enabled intraprocedural
transformations.</p>
<p>
Note that the Whole-Jimple Optimization pack is normally disabled
(and thus not applied by whole program mode), unless you also
specify the Whole Program Optimize option.</p>
</long_desc>
</boolopt>
<boolopt>
<name>Whole-Shimple Mode</name>
<alias>ws</alias>
<alias>whole-shimple</alias>
<short_desc>Run in whole-shimple mode</short_desc>
<long_desc>
<p>
Run in whole shimple mode, taking into consideration the whole program
when performing Shimple analyses and transformations. Soot uses the
Call Graph Constructor to build a call graph for the program, then
applies enabled transformations in the Whole-Shimple Transformation
and Whole-Shimple Optimization before applying enabled intraprocedural
transformations.</p>
<p>
Note that the Whole-Shimple Optimization pack is normally disabled
(and thus not applied by whole shimple mode), unless you also
specify the Whole Program Optimize option.</p>
</long_desc>
</boolopt>
<boolopt>
<name>Validate</name>
<alias>validate</alias>
<short_desc>Run internal validation on bodies</short_desc>
<long_desc>
Causes internal checks to be done on bodies in the various Soot IRs,
to make sure the transformations have not done something strange.
This option may degrade Soot's performance.
</long_desc>
</boolopt>
<boolopt>
<name>Debug</name>
<alias>debug</alias>
<short_desc>Print various Soot debugging info</short_desc>
<long_desc>
Print various debugging information as Soot runs, particularly
from the Baf Body Phase and the Jimple Annotation Pack Phase.
</long_desc>
</boolopt>
<boolopt>
<name>Debug Resolver</name>
<alias>debug-resolver</alias>
<short_desc>Print debugging info from SootResolver</short_desc>
<long_desc>
Print debugging information about class resolving.
</long_desc>
</boolopt>
</section>
<section>
<name>Input Options</name>
<stropt>
<name>Soot Classpath</name>
<alias>cp</alias>
<alias>soot-class-path</alias>
<alias>soot-classpath</alias>
<set_arg_label>path</set_arg_label>
<short_desc>Use <use_arg_label/> as the classpath for finding classes.</short_desc>
<long_desc>
<p>
Use <use_arg_label/> as the list of directories in which Soot
should search for classes. <use_arg_label/> should be a series of
directories, separated by the path separator character for your
system.</p>
<p>
If no classpath is set on the command line, but the system
property <tt>soot.class.path</tt> has been set, Soot uses its
value as the classpath.</p>
<p>
If neither the command line nor the system properties specify a
Soot classpath, Soot falls back on a default classpath consisting
of the value of the system property <tt>java.class.path</tt>
followed <var>java.home</var><tt>/lib/rt.jar</tt>, where
<var>java.home</var> stands for the contents of the system property
<tt>java.home</tt> and <tt>/</tt> stands for the system file
separator.</p>
</long_desc>
</stropt>
<boolopt>
<name>Prepend classpath</name>
<alias>pp</alias>
<alias>prepend-classpath</alias>
<short_desc>Prepend the given soot classpath to the default classpath.</short_desc>
<long_desc>
<p>
Instead of replacing the default soot classpath with the classpath given on the command line,
prepent it with that classpath.
The default classpath holds whatever is set in the CLASSPATH environment variable,
followed by rt.jar (resolved through the JAVA-UNDERSCORE-HOME environment variable).
If whole-program mode is enabled, jce.jar is also appended in the end.
</p>
</long_desc>
</boolopt>
<listopt>
<name>Process Directories</name>
<alias>process-path</alias>
<alias>process-dir</alias>
<set_arg_label>dir</set_arg_label>
<short_desc>Process all classes found in <use_arg_label/></short_desc>
<long_desc>
<p>
Add all classes found in <use_arg_label/> to the set of argument classes
which is analyzed and transformed by Soot. You can specify the
option more than once, to add argument classes from multiple directories.
You can also state JAR files.
</p>
<p>
If subdirectories of <use_arg_label/> contain <tt>.class</tt> or
<tt>.jimple</tt> files, Soot assumes that the subdirectory names
correspond to components of the classes' package names. If
<use_arg_label/> contains <tt>subA/subB/MyClass.class</tt>, for
instance, then Soot assumes <tt>MyClass</tt> is in package
<tt>subA.subB</tt>.</p>
</long_desc>
</listopt>
<boolopt>
<name>Compute AST Metrics</name>
<alias>ast-metrics</alias>
<short_desc>Compute AST Metrics if performing java to jimple</short_desc>
<long_desc>
If this flag is set and soot converts java to jimple then AST metrics will be computed.
</long_desc>
</boolopt>
<multiopt>
<name>Input Source Precedence</name>
<alias>src-prec</alias>
<set_arg_label>format</set_arg_label>
<short_desc>Sets source precedence to <use_arg_label/> files</short_desc>
<long_desc>
Sets <use_arg_label/> as Soot's preference for the type of source files to read when
it looks for a class.
</long_desc>
<value>
<name>Class File</name>
<alias>c</alias>
<alias>class</alias>
<short_desc>Favour class files as Soot source</short_desc>
<long_desc>
Try to resolve classes first from <tt>.class</tt> files found in
the Soot classpath. Fall back to <tt>.jimple</tt> files
only when unable to find a <tt>.class</tt> file.
</long_desc>
<default/>
</value>
<value>
<name>Only Class File</name>
<alias>only-class</alias>
<short_desc>Use only class files as Soot source</short_desc>
<long_desc>
Try to resolve classes first from <tt>.class</tt> files found in
the Soot classpath. Do not try any other types of files even when
unable to find a <tt>.class</tt> file.
</long_desc>
</value>
<value>
<name>Jimple File</name>
<alias>J</alias>
<alias>jimple</alias>
<short_desc>Favour Jimple files as Soot source</short_desc>
<long_desc>
Try to resolve classes first from <tt>.jimple</tt> files found in
the Soot classpath. Fall back to <tt>.class</tt> files only when
unable to find a <tt>.jimple</tt> file.
</long_desc>
</value>
<value>
<name>Java File</name>
<alias>java</alias>
<short_desc>Favour Java files as Soot source</short_desc>
<long_desc>
Try to resolve classes first from <tt>.java</tt> files found in
the Soot classpath. Fall back to <tt>.class</tt> files only when
unable to find a <tt>.java</tt> file.
</long_desc>
</value>
</multiopt>
<boolopt>
<name>Force complete resolver</name>
<alias>full-resolver</alias>
<short_desc>Force transitive resolving of referenced classes</short_desc>
<long_desc>
Normally, Soot resolves only that application classes and any classes that they
refer to, along with any classes it needs for the Jimple typing, but it does not
transitively resolve references in these additional classes that were resolved
only because they were referenced. This switch forces full transitive resolution
of all references found in all classes that are resolved, regardless of why they
were resolved.
In whole-program mode, class resolution is always fully transitive. Therefore,
in whole-program mode, this switch has no effect, and class resolution is
always performed as if it were turned on.
</long_desc>
</boolopt>
<boolopt>
<name>Allow Phantom References</name>
<alias>allow-phantom-refs</alias>
<short_desc>Allow unresolved classes; may cause errors</short_desc>
<long_desc>
Allow Soot to process a class even if it cannot find all classes
referenced by that class. This may cause Soot to produce
incorrect results.
</long_desc>
</boolopt>
<boolopt>
<name>Allow Phantom References</name>
<alias>no-bodies-for-excluded</alias>
<short_desc>Do not load bodies for excluded classes</short_desc>
<long_desc>
Prevents Soot from loading method bodies for all excluded classes (see exclude option), even
when running in whole-program mode. This is useful for computing a shallow points-to analysis
that does not, for instance, take into account the JDK. Of course, such analyses may be unsound.
You get what you are asking for.
</long_desc>
</boolopt>
<boolopt>
<name>Use J2ME mode</name>
<alias>j2me</alias>
<default>false</default>
<short_desc>Use J2ME mode; changes assignment of types</short_desc>
<long_desc>
Use J2ME mode. J2ME does not have class Cloneable nor Serializable, so we have
to change type assignment to not refer to those classes.
</long_desc>
</boolopt>
<stropt>
<name>Main Class</name>
<alias>main-class</alias>
<set_arg_label>class</set_arg_label>
<short_desc>Sets the main class for whole-program analysis.</short_desc>
<long_desc>
<p>
By default, the first class encountered with a main method is treated
as the main class (entry point) in whole-program analysis. This option
overrides this default.
</p>
</long_desc>
</stropt>
<boolopt>
<name>Use Polyglot frontend</name>
<alias>polyglot</alias>
<default>false</default>
<short_desc>Use Java 1.4 Polyglot frontend instead of JastAdd</short_desc>
<long_desc>
Use Java 1.4 Polyglot frontend instead of JastAdd, which supports Java 5 syntax.
</long_desc>
</boolopt>
</section>
<section>
<name>Output Options</name>
<stropt>
<name>Output Directory</name>
<alias>d</alias>
<alias>output-dir</alias>
<default>./sootOutput</default>
<set_arg_label>dir</set_arg_label>
<short_desc>Store output files in <use_arg_label/></short_desc>
<long_desc>
Store output files in <use_arg_label/>. <use_arg_label/> may be
relative to the working directory.
</long_desc>
</stropt>
<multiopt>
<name>Output Format</name>
<alias>f</alias>
<alias>output-format</alias>
<set_arg_label>format</set_arg_label>
<short_desc>Set output format for Soot</short_desc>
<long_desc>
<p>
Specify the format of output files Soot should produce, if
any.</p>
<p>
Note that while the abbreviated formats (<tt>jimp</tt>,
<tt>shimp</tt>, <tt>b</tt>, and <tt>grimp</tt>) are easier to
read than their unabbreviated counterparts (<tt>jimple</tt>,
<tt>shimple</tt>, <tt>baf</tt>, and <tt>grimple</tt>), they may
contain ambiguities. Method signatures in the abbreviated
formats, for instance, are not uniquely determined.</p>
</long_desc>
<value>
<name>Jimple File</name>
<alias>J</alias>
<alias>jimple</alias>
<short_desc>Produce <tt>.jimple</tt> Files</short_desc>
<long_desc>
Produce <tt>.jimple</tt> files, which contain a textual
form of Soot's Jimple internal representation.
</long_desc>
</value>
<value>
<name>Jimp File</name>
<alias>j</alias>
<alias>jimp</alias>
<short_desc>Produce <tt>.jimp</tt> (abbreviated Jimple) files</short_desc>
<long_desc>
Produce <tt>.jimp</tt> files, which contain an abbreviated form
of Jimple.
</long_desc>
</value>
<value>
<name>Shimple File</name>
<alias>S</alias>
<alias>shimple</alias>
<short_desc>Produce <tt>.shimple</tt> files</short_desc>
<long_desc>
Produce <tt>.shimple files</tt>, containing a textual form of
Soot's SSA Shimple internal representation. Shimple adds
Phi nodes to Jimple.
</long_desc>
</value>
<value>
<name>Shimp File</name>
<alias>s</alias>
<alias>shimp</alias>
<short_desc>Produce <tt>.shimp</tt> (abbreviated Shimple) files</short_desc>
<long_desc>
Produce .shimp files, which contain an abbreviated form of
Shimple.
</long_desc>
</value>
<value>
<name>Baf File</name>
<alias>B</alias>
<alias>baf</alias>
<short_desc>Produce <tt>.baf</tt> files</short_desc>
<long_desc>
Produce <tt>.baf</tt> files, which contain a textual form of
Soot's Baf internal representation.
</long_desc>
</value>
<value>
<name>Abbreviated Baf File</name>
<alias>b</alias>
<short_desc>Produce <tt>.b</tt> (abbreviated Baf) files</short_desc>
<long_desc>
Produce <tt>.b</tt> files, which contain an abbreviated form of Baf.
</long_desc>
</value>
<value>
<name>Grimp File</name>
<alias>G</alias>
<alias>grimple</alias>
<short_desc>Produce <tt>.grimple</tt> files</short_desc>
<long_desc>
Produce <tt>.grimple</tt> files, which contain a textual
form of Soot's Grimp internal representation.
</long_desc>
</value>
<value>
<name>Abbreviated Grimp File</name>
<alias>g</alias>
<alias>grimp</alias>
<short_desc>Produce <tt>.grimp</tt> (abbreviated Grimp) files</short_desc>
<long_desc>
Produce <tt>.grimp</tt> files, which contain an abbreviated form
of Grimp.
</long_desc>
</value>
<value>
<name>Xml File</name>
<alias>X</alias>
<alias>xml</alias>
<short_desc>Produce <tt>.xml</tt> Files</short_desc>
<long_desc>
Produce <tt>.xml</tt> files containing an annotated
version of the Soot's Jimple internal representation.
</long_desc>
</value>
<value>
<name>No Output File</name>
<alias>n</alias>
<alias>none</alias>
<short_desc>Produce no output</short_desc>
<long_desc>
Produce no output files.
</long_desc>
</value>
<value>
<name>Jasmin File</name>
<alias>jasmin</alias>
<short_desc>Produce <tt>.jasmin</tt> files</short_desc>
<long_desc>
Produce <tt>.jasmin</tt> files, suitable as input to the jasmin
bytecode assembler.
</long_desc>
</value>
<value>
<name>Class File</name>
<alias>c</alias>
<alias>class</alias>
<default/>
<short_desc>Produce <tt>.class</tt> Files</short_desc>
<long_desc>
Produce Java <tt>.class</tt> files, executable by any Java
Virtual Machine.
</long_desc>
</value>
<value>
<name>Dava Decompiled File</name>
<alias>d</alias>
<alias>dava</alias>
<short_desc>Produce dava-decompiled <tt>.java</tt> files</short_desc>
<long_desc>
Produce <tt>.java</tt> files generated by the Dava decompiler.
</long_desc>
</value>
<value>
<name>Jimle Template File</name>
<alias>t</alias>
<alias>template</alias>
<short_desc>Produce <tt>.java</tt> files with Jimple templates.</short_desc>
<long_desc>
Produce <tt>.java</tt> files with Jimple templates.
</long_desc>
</value>
</multiopt>
<boolopt>
<name>Output Jar File</name>
<alias>outjar</alias>
<alias>output-jar</alias>
<short_desc>Make output dir a Jar file instead of dir</short_desc>
<long_desc>
Saves output files into a Jar file instead of a directory. The output
Jar file name should be specified using the Output Directory
(<tt>output-dir</tt>) option. Note that if the output Jar file exists
before Soot runs, any files inside it will first be removed.
</long_desc>
</boolopt>
<boolopt>
<name>Save Tags to XML</name>
<alias>xml-attributes</alias>
<short_desc>Save tags to XML attributes for Eclipse</short_desc>
<long_desc>
Save in XML format a variety of tags which Soot has attached to
its internal representations of the application classes. The XML
file can then be read by the Soot plug-in for the Eclipse IDE,
which can display the annotations together with the program
source, to aid program understanding.
</long_desc>
</boolopt>
<boolopt>
<name>Print Tags in Output</name>
<alias>print-tags</alias>
<alias>print-tags-in-output</alias>
<short_desc>Print tags in output files after stmt</short_desc>
<long_desc>
Print in output files (either in Jimple or Dave) a variety of tags which
Soot has attached to
its internal representations of the application classes. The tags will
be printed on the line succeeding the stmt that they are attached to.
</long_desc>
</boolopt>
<boolopt>
<name>Don't Output Source File Attribute</name>
<alias>no-output-source-file-attribute</alias>
<short_desc>Don't output Source File Attribute when producing class files</short_desc>
<long_desc>
Don't output Source File Attribute when producing class files.
</long_desc>
</boolopt>
<boolopt>
<name>Don't Output Inner Classes Attribute</name>
<alias>no-output-inner-classes-attribute</alias>
<short_desc>Don't output inner classes attribute in class files</short_desc>
<long_desc>
Don't output inner classes attribute in class files.
</long_desc>
</boolopt>
<listopt>
<name>Body Dumping Phases</name>
<alias>dump-body</alias>
<set_arg_label>phaseName</set_arg_label>
<short_desc>Dump the internal representation of each method before and after phase <use_arg_label/></short_desc>
<long_desc>
<p>
Specify that <use_arg_label/> is one of the phases to be dumped.
For example <code>-dump-body jb -dump-body jb.a</code> would dump each
method before and after the <code>jb</code> and <code>jb.a</code>
phases. The pseudo phase name ``<code>ALL</code>''
causes all phases to be dumped.</p>
<p>
Output files appear in subdirectories under the
soot output directory, with names like
<var>className</var><code>/</code><var>methodSignature</var><code>/</code><var>phasename</var><code>-</code><var>graphType</var><code>-</code><var>number</var><code>.in</code>
and
<var>className</var><code>/</code><var>methodSignature</var><code>/</code><var>phasename</var><code>-</code><var>graphType</var><code>-</code><var>number</var><code>.out</code>.
The ``<code>in</code>'' and
``<code>out</code>'' suffixes distinguish the internal
representations of the method before and after the phase
executed.</p>
</long_desc>
</listopt>
<listopt>
<name>CFG Dumping Phases</name>
<alias>dump-cfg</alias>
<set_arg_label>phaseName</set_arg_label>
<short_desc>Dump the internal representation of each CFG constructed during phase <use_arg_label/></short_desc>
<long_desc>
<p>
Specify that any control flow graphs constructed during the
<use_arg_label/> phases should be dumped.
For example <code>-dump-cfg jb -dump-cfg bb.lso</code> would dump
all
CFGs constructed during the <code>jb</code> and <code>bb.lso</code>
phases. The pseudo phase name ``<code>ALL</code>''
causes CFGs constructed in all phases to be dumped.</p>
<p>The control flow graphs are dumped in the form
of a file containing input to <code>dot</code> graph visualization
tool. Output <code>dot</code> files are stored beneath the soot
output directory, in files with names like:
<var>className</var><code>/</code><var>methodSignature</var><code>/</code><var>phasename</var><code>-</code><var>graphType</var><code>-</code><var>number</var><code>.dot</code>,
where <var>number</var> serves to distinguish graphs in phases
that produce more than one (for example, the Aggregator may
produce multiple <code>ExceptionalUnitGraph</code>s).</p>
</long_desc>
</listopt>
<boolopt>
<name>Show Exception Destinations</name>
<alias>show-exception-dests</alias>
<default>true</default>
<short_desc>Include exception destination edges as well as CFG edges in dumped CFGs</short_desc>
<long_desc>
Indicate whether to show exception destination edges as
well as control flow edges in
dumps of exceptional control flow graphs.
</long_desc>
</boolopt>
<boolopt>
<name>GZipped IR output</name>
<alias>gzip</alias>
<default>false</default>
<short_desc>GZip IR output files</short_desc>
<long_desc>
This option causes Soot to compress output files of intermediate representations
with GZip. It does not apply to class files output by Soot.
</long_desc>
</boolopt>
</section>
<section>
<name>Processing Options</name>
<phaseopt>
<name>Phase Options</name>
<alias>p</alias>
<alias>phase-option</alias>
<set_arg_label>phase opt:val</set_arg_label>
<short_desc>Set <var>phase</var>'s <var>opt</var> option to <var>value</var></short_desc>
<long_desc>
<p>
Set <var>phase</var>'s run-time option named <var>opt</var> to
<var>value</var>.</p>
<p>
This is a mechanism for specifying phase-specific options to
different parts of Soot. See <var>Soot phase options</var> for
details about the available phases and options.</p>
</long_desc>
<phase>
<name>Jimple Body Creation</name>
<alias>jb</alias>
<class>JBOptions</class>
<short_desc>Creates a <tt>JimpleBody</tt> for each method</short_desc>
<long_desc>
Jimple Body Creation creates a <tt>JimpleBody</tt> for each input
method, using either coffi, to read <tt>.class</tt> files, or the
jimple parser, to read <tt>.jimple</tt> files.
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
<short_desc/>
<long_desc/>
</boolopt>
<boolopt>
<name>Use Original Names</name>
<alias>use-original-names</alias>
<default>false</default>
<short_desc/>
<long_desc>
Retain the original names for local variables when the source
includes those names. Otherwise, Soot gives variables generic
names based on their types.
</long_desc>
</boolopt>
<boolopt>
<name>Preserve source-level annotations</name>
<alias>preserve-source-annotations</alias>
<default>false</default>
<short_desc/>
<long_desc>
Preserves annotations of retention type SOURCE. (for
everything but package and local variable annotations)
</long_desc>
</boolopt>
<sub_phase>
<name>Local Splitter</name>
<alias>jb.ls</alias>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
</boolopt>
<short_desc>Local splitter: one local per DU-UD web</short_desc>
<long_desc>
The Local Splitter identifies DU-UD webs for local variables and
introduces new variables so that each disjoint web is associated
with a single local.
</long_desc>
</sub_phase>
<sub_phase>
<name>Jimple Local Aggregator</name>
<alias>jb.a</alias>
<short_desc>Aggregator: removes some unnecessary copies</short_desc>
<long_desc>
<p>
The Jimple Local Aggregator removes some unnecessary copies by
combining local variables. Essentially, it finds definitions
which have only a single use and, if it is safe to do so, removes
the original definition after replacing the use with the
definition's right-hand side.</p>
<p>
At this stage in <tt>JimpleBody</tt> construction, local
aggregation serves largely to remove the copies to and from stack
variables which simulate load and store instructions in the
original bytecode.</p>
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
</boolopt>
<boolopt>
<name>Only Stack Locals</name>
<alias>only-stack-locals</alias>
<long_desc>
Only aggregate locals that represent stack locations in the
original bytecode. (Stack locals can be distinguished in Jimple
by the <dollar/> character with which their names begin.)
</long_desc>
<default>true</default>
</boolopt>
</sub_phase>
<sub_phase>
<name>Unused Local Eliminator</name>
<alias>jb.ule</alias>
<short_desc>Unused local eliminator</short_desc>
<long_desc>
The Unused Local Eliminator removes any unused locals from the
method.
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
</boolopt>
</sub_phase>
<sub_phase>
<short_desc>Assigns types to locals</short_desc>
<long_desc>
The Type Assigner gives local variables types which will
accommodate the values stored in them over the course of the
method.
</long_desc>
<name>Type Assigner</name>
<class>JBTROptions</class>
<alias>jb.tr</alias>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
</boolopt>
<boolopt>
<name>Ignore wrong static-ness</name>
<alias>ignore-wrong-staticness</alias>
<default>false</default>
<short_desc>Ignores errors due to wrong staticness</short_desc>
<long_desc>
Some projects have been shown to contain invalid bytecode that tries to access
a static field or method in a non-static way or the other way around. The VM's bytecode
verifier will reject such bytecode when loaded into the VM. This option, when enabled,
causes to create Jimple bodies in such cases nontheless, ignoring the error.
</long_desc>
</boolopt>
<boolopt>
<name>Use older type assigner</name>
<alias>use-older-type-assigner</alias>
<default>false</default>
<short_desc>Enables the older type assigner</short_desc>
<long_desc>
This enables the older type assigner that was in use until May 2008.
The current type assigner is a reimplementation by Ben Bellamy
that uses an entirely new and faster algorithm which always assigns
the most narrow type possible. If compare-type-assigners is on,
this option causes the older type assigner to execute first.
(Otherwise the newer one is executed first.)
</long_desc>
</boolopt>
<boolopt>
<name>Compare type assigners</name>
<alias>compare-type-assigners</alias>
<default>false</default>
<short_desc>Compares Ben Bellamy's and the older type assigner</short_desc>
<long_desc>
Enables comparison (both runtime and results) of Ben Bellamy's type assigner with the
older type assigner that was in Soot.
</long_desc>
</boolopt>
</sub_phase>
<sub_phase>
<name>Unsplit-originals Local Packer</name>
<alias>jb.ulp</alias>
<short_desc>Local packer: minimizes number of locals</short_desc>
<long_desc>
The Unsplit-originals Local Packer executes only when the
`<tt>use-original-names</tt>' option is chosen for the
`<tt>jb</tt>' phase. The Local Packer attempts to minimize
the number of local variables required in a method by reusing the
same variable for disjoint DU-UD webs. Conceptually, it is the
inverse of the Local Splitter.
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
<short_desc/>
<long_desc/>
</boolopt>
<boolopt>
<name>Unsplit Original Locals</name>
<alias>unsplit-original-locals</alias>
<default>true</default>
<short_desc/>
<long_desc>
Use the variable names in the original source as a guide when
determining how to share local variables among non-interfering
variable usages. This recombines named locals which were split by
the Local Splitter.
</long_desc>
</boolopt>
</sub_phase>
<sub_phase>
<name>Local Name Standardizer</name>
<alias>jb.lns</alias>
<short_desc>Local name standardizer</short_desc>
<long_desc>
The Local Name Standardizer assigns generic names to local variables.
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
<short_desc/>
<long_desc/>
</boolopt>
<boolopt>
<name>Only Stack Locals</name>
<alias>only-stack-locals</alias>
<default>false</default>
<short_desc/>
<long_desc>
Only standardizes the names of variables that represent stack
locations in the original bytecode. This becomes the default when
the `<tt>use-original-names</tt>' option is specified for
the `<tt>jb</tt>' phase.
</long_desc>
</boolopt>
</sub_phase>
<sub_phase>
<name>Copy Propagator</name>
<alias>jb.cp</alias>
<short_desc>Copy propagator</short_desc>
<long_desc>
This phase performs cascaded copy propagation.
If the propagator encounters situations of the form:
<pre>
A: a = ...;
...
B: x = a;
...
C: ... = ... x;
</pre>
where <tt>a</tt> and <tt>x</tt> are each defined only once (at
<tt>A</tt> and <tt>B</tt>, respectively), then it can propagate
immediately without checking between <tt>B</tt> and <tt>C</tt>
for redefinitions of <tt>a</tt>. In
this case the propagator is global.
Otherwise, if <tt>a</tt> has multiple definitions then the
propagator checks for redefinitions and propagates copies
only within extended basic blocks.
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
<short_desc/>
<long_desc/>
</boolopt>
<boolopt>
<name>Only Regular Locals</name>
<alias>only-regular-locals</alias>
<default>false</default>
<short_desc/>
<long_desc>
Only propagate copies through ``regular'' locals, that is,
those declared in the source bytecode.
</long_desc>
</boolopt>
<boolopt>
<name>Only Stack Locals</name>
<alias>only-stack-locals</alias>
<default>true</default>
<short_desc/>
<long_desc>
Only propagate copies through locals that represent stack locations in
the original bytecode.
</long_desc>
</boolopt>
</sub_phase>
<sub_phase>
<name>Dead Assignment Eliminator</name>
<alias>jb.dae</alias>
<short_desc>Dead assignment eliminator</short_desc>
<long_desc>
The Dead Assignment Eliminator eliminates assignment statements
to locals whose values are not subsequently used, unless
evaluating the right-hand side of the assignment may cause
side-effects.
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
<short_desc/>
<long_desc/>
</boolopt>
<boolopt>
<name>Only Stack Locals</name>
<alias>only-stack-locals</alias>
<default>true</default>
<short_desc/>
<long_desc>
Only eliminate dead assignments to locals that represent stack
locations in the original bytecode.
</long_desc>
</boolopt>
</sub_phase>
<sub_phase>
<name>Post-copy propagation Unused Local Eliminator</name>
<alias>jb.cp-ule</alias>
<short_desc>Post-copy propagation unused local eliminator</short_desc>
<long_desc>
This phase removes any locals that are unused after copy propagation.
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
</boolopt>
</sub_phase>
<sub_phase>
<name>Local Packer</name>
<alias>jb.lp</alias>
<short_desc>Local packer: minimizes number of locals</short_desc>
<long_desc>
The Local Packer attempts to minimize the number of local
variables required in a method by reusing the same variable for
disjoint DU-UD webs. Conceptually, it is the inverse of the
Local Splitter.
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>false</default>
</boolopt>
<boolopt>
<name>Unsplit Original Locals</name>
<alias>unsplit-original-locals</alias>
<default>false</default>
<long_desc>
Use the variable names in the original source as a guide when
determining how to share local variables across non-interfering
variable usages. This recombines named locals which were split by
the Local Splitter.
</long_desc>
</boolopt>
</sub_phase>
<sub_phase>
<name>Nop Eliminator</name>
<alias>jb.ne</alias>
<short_desc>Nop eliminator</short_desc>
<long_desc>
The Nop Eliminator removes <tt>nop</tt> statements from the method.
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
</boolopt>
</sub_phase>
<sub_phase>
<name>Unreachable Code Eliminator</name>
<alias>jb.uce</alias>
<short_desc>Unreachable code eliminator</short_desc>
<long_desc>
The Unreachable Code Eliminator removes unreachable code and
traps whose catch blocks are empty.
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
</boolopt>
<boolopt>
<name>Remove unreachable traps</name>
<alias>remove-unreachable-traps</alias>
<default>false</default>
<long_desc>
Remove exception table entries when none of the protected instructions can
throw the exception being caught.
</long_desc>
</boolopt>
</sub_phase>
<sub_phase>
<name>Trap Tightener</name>
<alias>jb.tt</alias>
<short_desc>Trap Tightener</short_desc>
<long_desc>
The Trap Tightener changes the area protected by each exception handler,
so that it begins with the first instruction in the old protected
area which is actually capable of throwing an exception caught by the
handler, and ends just after the last instruction in the old
protected area which can throw an exception caught by the
handler. This reduces the chance of producing unverifiable code
as a byproduct of pruning exceptional control flow within CFGs.
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>false</default>
</boolopt>
</sub_phase>
</phase>
<phase>
<name>Java To Jimple Body Creation</name>
<alias>jj</alias>
<class>JJOptions</class>
<short_desc>Creates a <tt>JimpleBody</tt> for each method directly from source</short_desc>
<long_desc>
Jimple Body Creation creates a <tt>JimpleBody</tt> for each input
method, using polyglot, to read <tt>.java</tt> files.
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
<short_desc/>
<long_desc/>
</boolopt>
<boolopt>
<name>Use Original Names</name>
<alias>use-original-names</alias>
<default>true</default>
<short_desc/>
<long_desc>
Retain the original names for local variables when the source
includes those names. Otherwise, Soot gives variables generic
names based on their types.
</long_desc>
</boolopt>
<sub_phase>
<name>Local Splitter</name>
<alias>jj.ls</alias>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>false</default>
</boolopt>
<short_desc>Local splitter: one local per DU-UD web</short_desc>
<long_desc>
The Local Splitter identifies DU-UD webs for local variables and
introduces new variables so that each disjoint web is associated
with a single local.
</long_desc>
</sub_phase>
<sub_phase>
<name>Jimple Local Aggregator</name>
<alias>jj.a</alias>
<short_desc>Aggregator: removes some unnecessary copies</short_desc>
<long_desc>
<p>
The Jimple Local Aggregator removes some unnecessary copies by
combining local variables. Essentially, it finds definitions
which have only a single use and, if it is safe to do so, removes
the original definition after replacing the use with the
definition's right-hand side.</p>
<p>
At this stage in <tt>JimpleBody</tt> construction, local
aggregation serves largely to remove the copies to and from stack
variables which simulate load and store instructions in the
original bytecode.</p>
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
</boolopt>
<boolopt>
<name>Only Stack Locals</name>
<alias>only-stack-locals</alias>
<long_desc>
Only aggregate locals that represent stack locations in the
original bytecode. (Stack locals can be distinguished in Jimple
by the <dollar/> character with which their names begin.)
</long_desc>
<default>true</default>
</boolopt>
</sub_phase>
<sub_phase>
<name>Unused Local Eliminator</name>
<alias>jj.ule</alias>
<short_desc>Unused local eliminator</short_desc>
<long_desc>
The Unused Local Eliminator removes any unused locals from the
method.
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
</boolopt>
</sub_phase>
<sub_phase>
<short_desc>Assigns types to locals</short_desc>
<long_desc>
The Type Assigner gives local variables types which will
accommodate the values stored in them over the course of the
method.
</long_desc>
<name>Type Assigner</name>
<alias>jj.tr</alias>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>false</default>
</boolopt>
</sub_phase>
<sub_phase>
<name>Unsplit-originals Local Packer</name>
<alias>jj.ulp</alias>
<short_desc>Local packer: minimizes number of locals</short_desc>
<long_desc>
The Unsplit-originals Local Packer executes only when the
`<tt>use-original-names</tt>' option is chosen for the
`<tt>jb</tt>' phase. The Local Packer attempts to minimize
the number of local variables required in a method by reusing the
same variable for disjoint DU-UD webs. Conceptually, it is the
inverse of the Local Splitter.
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>false</default>
<short_desc/>
<long_desc/>
</boolopt>
<boolopt>
<name>Unsplit Original Locals</name>
<alias>unsplit-original-locals</alias>
<default>false</default>
<short_desc/>
<long_desc>
Use the variable names in the original source as a guide when
determining how to share local variables among non-interfering
variable usages. This recombines named locals which were split by
the Local Splitter.
</long_desc>
</boolopt>
</sub_phase>
<sub_phase>
<name>Local Name Standardizer</name>
<alias>jj.lns</alias>
<short_desc>Local name standardizer</short_desc>
<long_desc>
The Local Name Standardizer assigns generic names to local variables.
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
<short_desc/>
<long_desc/>
</boolopt>
<boolopt>
<name>Only Stack Locals</name>
<alias>only-stack-locals</alias>
<default>false</default>
<short_desc/>
<long_desc>
Only standardizes the names of variables that represent stack
locations in the original bytecode. This becomes the default when
the `<tt>use-original-names</tt>' option is specified for
the `<tt>jb</tt>' phase.
</long_desc>
</boolopt>
</sub_phase>
<sub_phase>
<name>Copy Propagator</name>
<alias>jj.cp</alias>
<short_desc>Copy propagator</short_desc>
<long_desc>
This phase performs cascaded copy propagation.
If the propagator encounters situations of the form:
<pre>
A: a = ...;
...
B: x = a;
...
C: ... = ... x;
</pre>
where <tt>a</tt> and <tt>x</tt> are each defined only once (at
<tt>A</tt> and <tt>B</tt>, respectively), then it can propagate
immediately without checking between <tt>B</tt> and <tt>C</tt>
for redefinitions of <tt>a</tt>. In
this case the propagator is global.
Otherwise, if <tt>a</tt> has multiple definitions then the
propagator checks for redefinitions and propagates copies
only within extended basic blocks.
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
<short_desc/>
<long_desc/>
</boolopt>
<boolopt>
<name>Only Regular Locals</name>
<alias>only-regular-locals</alias>
<default>false</default>
<short_desc/>
<long_desc>
Only propagate copies through ``regular'' locals, that is,
those declared in the source bytecode.
</long_desc>
</boolopt>
<boolopt>
<name>Only Stack Locals</name>
<alias>only-stack-locals</alias>
<default>true</default>
<short_desc/>
<long_desc>
Only propagate copies through locals that represent stack locations in
the original bytecode.
</long_desc>
</boolopt>
</sub_phase>
<sub_phase>
<name>Dead Assignment Eliminator</name>
<alias>jj.dae</alias>
<short_desc>Dead assignment eliminator</short_desc>
<long_desc>
The Dead Assignment Eliminator eliminates assignment statements
to locals whose values are not subsequently used, unless
evaluating the right-hand side of the assignment may cause
side-effects.
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
<short_desc/>
<long_desc/>
</boolopt>
<boolopt>
<name>Only Stack Locals</name>
<alias>only-stack-locals</alias>
<default>true</default>
<short_desc/>
<long_desc>
Only eliminate dead assignments to locals that represent stack
locations in the original bytecode.
</long_desc>
</boolopt>
</sub_phase>
<sub_phase>
<name>Post-copy propagation Unused Local Eliminator</name>
<alias>jj.cp-ule</alias>
<short_desc>Post-copy propagation unused local eliminator</short_desc>
<long_desc>
This phase removes any locals that are unused after copy propagation.
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
</boolopt>
</sub_phase>
<sub_phase>
<name>Local Packer</name>
<alias>jj.lp</alias>
<short_desc>Local packer: minimizes number of locals</short_desc>
<long_desc>
The Local Packer attempts to minimize the number of local
variables required in a method by reusing the same variable for
disjoint DU-UD webs. Conceptually, it is the inverse of the
Local Splitter.
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>false</default>
</boolopt>
<boolopt>
<name>Unsplit Original Locals</name>
<alias>unsplit-original-locals</alias>
<default>false</default>
<long_desc>
Use the variable names in the original source as a guide when
determining how to share local variables across non-interfering
variable usages. This recombines named locals which were split by
the Local Splitter.
</long_desc>
</boolopt>
</sub_phase>
<sub_phase>
<name>Nop Eliminator</name>
<alias>jj.ne</alias>
<short_desc>Nop eliminator</short_desc>
<long_desc>
The Nop Eliminator removes <tt>nop</tt> statements from the method.
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
</boolopt>
</sub_phase>
<sub_phase>
<name>Unreachable Code Eliminator</name>
<alias>jj.uce</alias>
<short_desc>Unreachable code eliminator</short_desc>
<long_desc>
The Unreachable Code Eliminator removes unreachable code and
traps whose catch blocks are empty.
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
</boolopt>
</sub_phase>
</phase>
<phase>
<name>Whole Jimple Pre-processing Pack</name>
<alias>wjpp</alias>
<short_desc>Whole Jimple Pre-processing Pack</short_desc>
<long_desc>
<p>
This pack allows you to insert pre-processors that are run before
call-graph construction. Only enabled in whole-program mode.</p>
<p>
In an unmodified copy of Soot, this pack is empty.</p>
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
</boolopt>
</phase>
<phase>
<name>Whole Shimple Pre-processing Pack</name>
<alias>wspp</alias>
<short_desc>Whole Shimple Pre-processing Pack</short_desc>
<long_desc>
<p>
This pack allows you to insert pre-processors that are run before
call-graph construction. Only enabled in whole-program Shimple mode.</p>
<p>
In an unmodified copy of Soot, this pack is empty.</p>
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
</boolopt>
</phase>
<radio_phase>
<name>Call Graph Constructor</name>
<alias>cg</alias>
<class>CGOptions</class>
<short_desc>Call graph constructor</short_desc>
<long_desc>
The Call Graph Constructor computes a call graph for whole
program analysis. When this pack finishes, a call graph is
available in the Scene. The different phases in this pack are
different ways to construct the call graph. Exactly one phase in
this pack must be enabled; Soot will raise an error otherwise.
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
</boolopt>
<boolopt>
<name>Safe forName</name>
<alias>safe-forname</alias>
<default>false</default>
<short_desc>Handle Class.forName() calls conservatively</short_desc>
<long_desc>When a program calls
Class.forName(), the named class is resolved, and its static initializer
executed. In many cases, it cannot be determined statically which
class will be loaded, and which static initializer executed. When this
option is set to true, Soot will conservatively assume that any static
initializer could be executed. This may make the call graph very large.
When this option is set to false, any calls to Class.forName() for which
the class cannot be determined statically are assumed to call no
static initializers.
</long_desc>
</boolopt>
<boolopt>
<name>Safe newInstance</name>
<alias>safe-newinstance</alias>
<default>false</default>
<short_desc>Handle Class.newInstance() calls conservatively</short_desc>
<long_desc>When a program calls
Class.newInstance(), a new object is created and its constructor
executed. Soot does not determine statically which
type of object will be created, and which constructor executed. When this
option is set to true, Soot will conservatively assume that any constructor
could be executed. This may make the call graph very large.
When this option is set to false, any calls to Class.newInstance()
are assumed not to call the constructor of the created object.
</long_desc>
</boolopt>
<boolopt>
<name>Verbose</name>
<alias>verbose</alias>
<default>false</default>
<short_desc>Print warnings about where the call graph may be incomplete</short_desc>
<long_desc>Due to the effects of native methods and reflection, it may not always be possible to construct a fully conservative call graph. Setting this option to true causes Soot to point out the parts of the call graph that may be incomplete, so that they can be checked by hand.
</long_desc>
</boolopt>
<intopt>
<name>JDK version</name>
<alias>jdkver</alias>
<default>3</default>
<short_desc>JDK version for native methods</short_desc>
<long_desc>This option sets the JDK version of the standard library being analyzed so that Soot can simulate the native methods in the specific version of the library. The default, 3, refers to Java 1.3.x.</long_desc>
</intopt>
<boolopt>
<name>All Application Class Methods Reachable</name>
<alias>all-reachable</alias>
<default>false</default>
<short_desc>Assume all methods of application classes are reachable.</short_desc>
<long_desc>When this option is false, the call graph is built starting at a set of entry points, and only methods reachable from those entry points are processed. Unreachable methods will not have any call graph edges generated out of them. Setting this option to true makes Soot consider all methods of application classes to be reachable, so call edges are generated for all of them. This leads to a larger call graph. For program visualization purposes, it is sometimes desirable to include edges from unreachable methods; although these methods are unreachable in the version being analyzed, they may become reachable if the program is modified.</long_desc>
</boolopt>
<boolopt>
<name>Implicit Entry Points</name>
<alias>implicit-entry</alias>
<default>true</default>
<short_desc>Include methods called implicitly by the VM as entry points</short_desc>
<long_desc>When this option is true, methods that are called implicitly by the VM are considered entry points of the call graph. When it is false, these methods are not considered entry points, leading to a possibly incomplete call graph.</long_desc>
</boolopt>
<boolopt>
<name>Trim Static Initializer Edges</name>
<alias>trim-clinit</alias>
<default>true</default>
<short_desc>Removes redundant static initializer calls</short_desc>
<long_desc>The call graph contains an edge
from each statement that could trigger execution of a static initializer to that
static initializer. However, each static initializer is triggered only once.
When this option is enabled, after the call graph is built, an intra-procedural
analysis is performed to detect static initializer edges leading to methods
that must have already been executed. Since these static initializers cannot be
executed again, the corresponding call graph edges are removed from the call graph.
</long_desc>
</boolopt>
<stropt>
<name>Reflection Log</name>
<alias>reflection-log</alias>
<short_desc>Uses a reflection log to resolve reflective calls.</short_desc>
<long_desc>Load a reflection log
from the given file and use this log to resolve reflective call sites. Note that
when a log is given, the following other options have no effect: safe-forname,
safe-newinstance.
</long_desc>
</stropt>
<stropt>
<name>Guarding strategy</name>
<alias>guards</alias>
<default>ignore</default>
<short_desc>Describes how to guard the program from unsound assumptions.</short_desc>
<long_desc>Using a reflection log is only sound for method executions that were logged.
Executing the program differently may be unsound. Soot can insert guards at program points for which the reflection log
contains no information. When these points are reached (because the program is executed differently) then the follwing will happen,
depending on the value of this flag. ignore: no guard is inserted, the program executes normally but under unsound assumptions.
print: the program prints a stack trace when reaching a porgram location that was not traced but continues to run. throw (default):
the program throws an Error instead.
</long_desc>
</stropt>
<sub_phase>
<name>Class Hierarchy Analysis</name>
<alias>cg.cha</alias>
<class>CHAOptions</class>
<short_desc>Builds call graph using Class Hierarchy Analysis</short_desc>
<long_desc>This phase uses Class Hierarchy Analysis to generate a call graph.</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
</boolopt>
<boolopt>
<name>Verbose</name>
<alias>verbose</alias>
<default>false</default>
<short_desc>Print statistics about the resulting call graph</short_desc>
<long_desc>Setting this option to true causes Soot to print out statistics about the call graph computed by this phase, such as the number of methods determined to be reachable.</long_desc>
</boolopt>
</sub_phase>
<sub_phase>
<name>Spark</name>
<class>SparkOptions</class>
<alias>cg.spark</alias>
<short_desc>Spark points-to analysis framework</short_desc>
<long_desc>Spark is a flexible points-to analysis framework. Aside from building a call graph, it also generates information about the targets of pointers. For details about Spark, please see <a href="http://www.sable.mcgill.ca/publications/thesis/#olhotakMastersThesis">Ondrej Lhotak's M.Sc. thesis</a>.</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>false</default>
<short_desc/>
<long_desc/>
</boolopt>
<section>
<name>Spark General Options</name>
<boolopt>
<name>Verbose</name>
<alias>verbose</alias>
<default>false</default>
<short_desc>Print detailed information about the execution of Spark</short_desc>
<long_desc>
When this option is set to true, Spark prints detailed information about its execution.
</long_desc>
</boolopt>
<boolopt>
<name>Ignore Types Entirely</name>
<alias>ignore-types</alias>
<default>false</default>
<short_desc>Make Spark completely ignore declared types of variables</short_desc>
<long_desc>
When this option is set to true, all parts of Spark completely ignore
declared types of variables and casts.
</long_desc>
</boolopt>
<boolopt>
<name>Force Garbage Collections</name>
<alias>force-gc</alias>
<default>false</default>
<short_desc>Force garbage collection for measuring memory usage</short_desc>
<long_desc>
When this option is set to true, calls to System.gc() will be made at
various points to allow memory usage to be measured.
</long_desc>
</boolopt>
<boolopt>
<name>Pre Jimplify</name>
<alias>pre-jimplify</alias>
<default>false</default>
<short_desc>Jimplify all methods before starting Spark</short_desc>
<long_desc>
When this option is set to true, Spark converts all available methods to Jimple
before starting the points-to analysis. This allows the Jimplification
time to be separated from the points-to time. However, it increases the
total time and memory requirement, because all methods are Jimplified,
rather than only those deemed reachable by the points-to analysis.
</long_desc>
</boolopt>
</section>
<section>
<name>Spark Pointer Assignment Graph Building Options</name>
<boolopt>
<name>VTA</name>
<alias>vta</alias>
<default>false</default>
<short_desc>Emulate Variable Type Analysis</short_desc>
<long_desc>
Setting VTA to true has the effect of setting field-based,
types-for-sites, and simplify-sccs to true, and on-fly-cg to false,
to simulate Variable Type
Analysis, described in <a href="http://www.sable.mcgill.ca/publications/papers/#oopsla2000">our OOPSLA 2000 paper</a>. Note that the
algorithm differs from the original VTA in that it handles array
elements more precisely.
</long_desc>
</boolopt>
<boolopt>
<name>RTA</name>
<alias>rta</alias>
<default>false</default>
<short_desc>Emulate Rapid Type Analysis</short_desc>
<long_desc>
Setting RTA to true sets types-for-sites to true, and causes Spark to use
a single points-to set for all variables, giving <a href="http://doi.acm.org/10.1145/236337.236371">Rapid Type
Analysis</a>.
</long_desc>
</boolopt>
<boolopt>
<name>Field Based</name>
<alias>field-based</alias>
<default>false</default>
<short_desc>Use a field-based rather than field-sensitive representation</short_desc>
<long_desc>
When this option is set to true, fields are represented by variable
(Green) nodes, and the object that the field belongs to is ignored
(all objects are lumped together), giving a field-based analysis. Otherwise, fields are represented by
field reference (Red) nodes, and the objects that they belong to are
distinguished, giving a field-sensitive analysis.
</long_desc>
</boolopt>
<boolopt>
<name>Types For Sites</name>
<alias>types-for-sites</alias>
<default>false</default>
<short_desc>Represent objects by their actual type rather than allocation site</short_desc>
<long_desc>
When this option is set to true, types rather than allocation sites are
used as the elements of the points-to sets.
</long_desc>
</boolopt>
<boolopt>
<name>Merge String Buffer</name>
<alias>merge-stringbuffer</alias>
<default>true</default>
<short_desc>Represent all StringBuffers as one object</short_desc>
<long_desc>
When this option is set to true, all allocation sites creating
<tt>java.lang.StringBuffer</tt> objects are grouped together as a single
allocation site.
</long_desc>
</boolopt>
<boolopt>
<name>Propagate All String Constants</name>
<alias>string-constants</alias>
<default>false</default>
<short_desc>Propagate all string constants, not just class names</short_desc>
<long_desc>
When this option is set to false, Spark only distinguishes string constants that
may be the name of a class loaded dynamically using reflection, and all other
string constants are lumped together into a single string constant node.
Setting this option to true causes all string constants to be propagated
individually.
</long_desc>
</boolopt>
<boolopt>
<name>Simulate Natives</name>
<alias>simulate-natives</alias>
<default>true</default>
<short_desc>Simulate effects of native methods in standard class library</short_desc>
<long_desc>
When this option is set to true, the effects of native methods in the standard Java class library are simulated.
</long_desc>
</boolopt>
<boolopt>
<name>Treat EMPTY as Alloc</name>
<alias>empties-as-allocs</alias>
<default>false</default>
<short_desc>Treat singletons for empty sets etc. as allocation sites</short_desc>
<long_desc>
When this option is set to true, Spark treats references to <code>EMPTYSET</code>, <code>EMPTYMAP</code>, and
<code>EMPTYLIST</code> as allocation sites for <code>HashSet</code>, <code>HashMap</code> and <code>LinkedList</code> objects respectively, and references to <code>Hashtable.emptyIterator</code> as allocation sites for <code>Hashtable.EmptyIterator</code>. This enables subsequent analyses to differentiate different uses of Java's immutable empty collections.
</long_desc>
</boolopt>
<boolopt>
<name>Simple Edges Bidirectional</name>
<alias>simple-edges-bidirectional</alias>
<default>false</default>
<short_desc>Equality-based analysis between variable nodes</short_desc>
<long_desc>
When this option is set to true, all edges connecting variable (Green)
nodes are made bidirectional, as in <a href="http://doi.acm.org/10.1145/237721.237727">Steensgaard's analysis</a>.
</long_desc>
</boolopt>
<boolopt>
<name>On Fly Call Graph</name>
<alias>on-fly-cg</alias>
<default>true</default>
<short_desc>Build call graph as receiver types become known</short_desc>
<long_desc>
When this option is set to true, the call graph is computed on-the-fly
as points-to information is computed. Otherwise, an initial
CHA approximation to the call graph is used.
</long_desc>
</boolopt>
</section>
<section>
<name>Spark Pointer Assignment Graph Simplification Options</name>
<boolopt>
<name>Simplify Offline</name>
<alias>simplify-offline</alias>
<default>false</default>
<short_desc>Collapse single-entry subgraphs of the PAG</short_desc>
<long_desc>
When this option is set to true, variable (Green) nodes which form
single-entry subgraphs (so they must have the same points-to set) are
merged before propagation begins.
</long_desc>
</boolopt>
<boolopt>
<name>Simplify SCCs</name>
<alias>simplify-sccs</alias>
<default>false</default>
<short_desc>Collapse strongly-connected components of the PAG</short_desc>
<long_desc>
When this option is set to true, variable (Green) nodes which form
strongly-connected components (so they must have the same points-to set)
are merged before propagation begins.
</long_desc>
</boolopt>
<boolopt>
<name>Ignore Types For SCCs</name>
<alias>ignore-types-for-sccs</alias>
<default>false</default>
<short_desc>Ignore declared types when determining node equivalence for SCCs</short_desc>
<long_desc>
When this option is set to true, when collapsing strongly-connected
components, nodes forming SCCs are collapsed regardless of their declared type.
The collapsed SCC is given the most general type of all the nodes in the
component.
When this option is set to false, only edges connecting nodes of the
same type are considered when detecting SCCs.
This option has no effect unless <tt>simplify-sccs</tt> is true.
</long_desc>
</boolopt>
</section>
<section>
<name>Spark Points-To Set Flowing Options</name>
<multiopt>
<name>Propagator</name>
<alias>propagator</alias>
<value>
<name>Iter</name>
<alias>iter</alias>
<short_desc>Simple iterative algorithm</short_desc>
<long_desc>
Iter is a simple, iterative algorithm, which propagates everything until the
graph does not change.
</long_desc>
</value>
<value>
<name>Worklist</name>
<alias>worklist</alias>
<default/>
<short_desc>Fast, worklist-based algorithm</short_desc>
<long_desc>
Worklist is a worklist-based algorithm that tries
to do as little work as possible. This is currently the fastest algorithm.
</long_desc>
</value>
<value>
<name>Cycle</name>
<alias>cycle</alias>
<short_desc>Unfinished on-the-fly cycle detection algorithm</short_desc>
<long_desc>This algorithm finds cycles in the PAG on-the-fly. It is not yet finished.</long_desc>
</value>
<value>
<name>Merge</name>
<alias>merge</alias>
<short_desc>Unfinished field reference merging algorithms</short_desc>
<long_desc>
Merge is an algorithm that merges all concrete field (yellow) nodes with their corresponding
field reference (red) nodes. This algorithm is not yet finished.
</long_desc>
</value>
<value>
<name>Alias</name>
<alias>alias</alias>
<short_desc>Alias-edge based algorithm</short_desc>
<long_desc>
Alias is an alias-edge based algorithm. This algorithm tends to take
the least memory for very large problems, because it does not represent
explicitly points-to sets of fields of heap objects.
</long_desc>
</value>
<value>
<name>None</name>
<alias>none</alias>
<short_desc>Disable propagation</short_desc>
<long_desc>
None means that propagation is not done; the graph is only built and
simplified. This is useful if an external solver is being used to perform the
propagation.
</long_desc>
</value>
<short_desc>Select propagation algorithm</short_desc>
<long_desc>
This option tells Spark which propagation algorithm to use.
</long_desc>
</multiopt>
<multiopt>
<name>Set Implementation</name>
<alias>set-impl</alias>
<value>
<name>Hash set</name>
<alias>hash</alias>
<short_desc>Use Java HashSet</short_desc>
<long_desc>
Hash is an implementation based on Java's built-in hash-set.
</long_desc>
</value>
<value>
<name>Bit-vector</name>
<alias>bit</alias>
<short_desc>Bit vector</short_desc>
<long_desc>
Bit is an implementation using a bit vector.
</long_desc>
</value>
<value>
<name>Hybrid</name>
<alias>hybrid</alias>
<short_desc>Hybrid representation using bit vector for large sets</short_desc>
<long_desc>
Hybrid is an implementation that keeps an explicit list of up to
16 elements, and switches to a bit-vector when the set gets
larger than this.
</long_desc>
</value>
<value>
<name>Sorted array</name>
<alias>array</alias>
<short_desc>Sorted array representation</short_desc>
<long_desc>
Array is an implementation that keeps the elements of the
points-to set in a sorted array. Set membership is tested using
binary search, and set union and intersection are computed using
an algorithm based on the merge step from merge sort.
</long_desc>
</value>
<value>
<name>Heintze</name>
<alias>heintze</alias>
<short_desc>Heintze's shared bit-vector and overflow list representation</short_desc>
<long_desc>Heintze's representation has elements represented by a bit-vector + a small
'overflow' list of some maximum number of elements. The bit-vectors can be shared
by multiple points-to sets, while the overflow lists are not.
</long_desc>
</value>
<value>
<name>Shared List</name>
<alias>sharedlist</alias>
<short_desc>Shared list representation</short_desc>
<long_desc>Shared List stores its elements in a linked list, and might share
its tail with other similar points-to sets.
</long_desc>
</value>
<value>
<name>Double</name>
<alias>double</alias>
<default/>
<short_desc>Double set representation for incremental propagation</short_desc>
<long_desc>
Double is an implementation that itself uses a pair of sets for
each points-to set. The first set in the pair stores new pointed-to
objects that have not yet been propagated, while the second set stores
old pointed-to objects that have been propagated and need not be
reconsidered. This allows the propagation algorithms to be incremental,
often speeding them up significantly.
</long_desc>
</value>
<short_desc>Select points-to set implementation</short_desc>
<long_desc>
Select an implementation of points-to sets for Spark to use.
</long_desc>
</multiopt>
<multiopt>
<name>Double Set Old</name>
<alias>double-set-old</alias>
<value>
<name>Hash set</name>
<alias>hash</alias>
<short_desc>Use Java HashSet</short_desc>
<long_desc>
Hash is an implementation based on Java's built-in hash-set.
</long_desc>
</value>
<value>
<name>Bit-vector</name>
<alias>bit</alias>
<short_desc>Bit vector</short_desc>
<long_desc>
Bit is an implementation using a bit vector.
</long_desc>
</value>
<value>
<name>Hybrid</name>
<alias>hybrid</alias>
<default/>
<short_desc>Hybrid representation using bit vector for large sets</short_desc>
<long_desc>
Hybrid is an implementation that keeps an explicit list of up to
16 elements, and switches to a bit-vector when the set gets
larger than this.
</long_desc>
</value>
<value>
<name>Sorted array</name>
<alias>array</alias>
<short_desc>Sorted array representation</short_desc>
<long_desc>
Array is an implementation that keeps the elements of the
points-to set in a sorted array. Set membership is tested using
binary search, and set union and intersection are computed using
an algorithm based on the merge step from merge sort.
</long_desc>
</value>
<value>
<name>Heintze</name>
<alias>heintze</alias>
<short_desc>Heintze's shared bit-vector and overflow list representation</short_desc>
<long_desc>Heintze's representation has elements represented by a bit-vector + a small
'overflow' list of some maximum number of elements. The bit-vectors can be shared
by multiple points-to sets, while the overflow lists are not.
</long_desc>
</value>
<value>
<name>Shared List</name>
<alias>sharedlist</alias>
<short_desc>Shared list representation</short_desc>
<long_desc>Shared List stores its elements in a linked list, and might share
its tail with other similar points-to sets.
</long_desc>
</value>
<short_desc>Select implementation of points-to set for old part of double set</short_desc>
<long_desc>
Select an implementation for sets of old objects in the double
points-to set implementation.
This option has no effect unless Set Implementation is set to double.
</long_desc>
</multiopt>
<multiopt>
<name>Double Set New</name>
<alias>double-set-new</alias>
<value>
<name>Hash set</name>
<alias>hash</alias>
<short_desc>Use Java HashSet</short_desc>
<long_desc>
Hash is an implementation based on Java's built-in hash-set.
</long_desc>
</value>
<value>
<name>Bit-vector</name>
<alias>bit</alias>
<short_desc>Bit vector</short_desc>
<long_desc>
Bit is an implementation using a bit vector.
</long_desc>
</value>
<value>
<name>Hybrid</name>
<alias>hybrid</alias>
<default/>
<short_desc>Hybrid representation using bit vector for large sets</short_desc>
<long_desc>
Hybrid is an implementation that keeps an explicit list of up to
16 elements, and switches to a bit-vector when the set gets
larger than this.
</long_desc>
</value>
<value>
<name>Sorted array</name>
<alias>array</alias>
<short_desc>Sorted array representation</short_desc>
<long_desc>
Array is an implementation that keeps the elements of the
points-to set in a sorted array. Set membership is tested using
binary search, and set union and intersection are computed using
an algorithm based on the merge step from merge sort.
</long_desc>
</value>
<value>
<name>Heintze</name>
<alias>heintze</alias>
<short_desc>Heintze's shared bit-vector and overflow list representation</short_desc>
<long_desc>Heintze's representation has elements represented by a bit-vector + a small
'overflow' list of some maximum number of elements. The bit-vectors can be shared
by multiple points-to sets, while the overflow lists are not.
</long_desc>
</value>
<value>
<name>Shared List</name>
<alias>sharedlist</alias>
<short_desc>Shared list representation</short_desc>
<long_desc>Shared List stores its elements in a linked list, and might share
its tail with other similar points-to sets.
</long_desc>
</value>
<short_desc>Select implementation of points-to set for new part of double set</short_desc>
<long_desc>
Select an implementation for sets of new objects in the double
points-to set implementation.
This option has no effect unless Set Implementation is set to double.
</long_desc>
</multiopt>
</section>
<section>
<name>Spark Output Options</name>
<boolopt>
<name>Dump HTML</name>
<alias>dump-html</alias>
<default>false</default>
<short_desc>Dump pointer assignment graph to HTML for debugging</short_desc>
<long_desc>
When this option is set to true, a browseable HTML representation of the
pointer assignment graph is output to a file called <tt>pag.jar</tt> after the analysis completes. Note
that this representation is typically very large.
</long_desc>
</boolopt>
<boolopt>
<name>Dump PAG</name>
<alias>dump-pag</alias>
<default>false</default>
<short_desc>Dump pointer assignment graph for other solvers</short_desc>
<long_desc>
When this option is set to true, a representation of the pointer assignment graph
suitable for processing with other solvers (such as the BDD-based solver) is
output before the analysis begins.
</long_desc>
</boolopt>
<boolopt>
<name>Dump Solution</name>
<alias>dump-solution</alias>
<default>false</default>
<short_desc>Dump final solution for comparison with other solvers</short_desc>
<long_desc>
When this option is set to true, a representation of the resulting points-to
sets is dumped. The format is similar to that of the Dump PAG
option, and is therefore suitable for comparison with the results of other
solvers.
</long_desc>
</boolopt>
<boolopt>
<name>Topological Sort</name>
<alias>topo-sort</alias>
<default>false</default>
<short_desc>Sort variable nodes in dump</short_desc>
<long_desc>
When this option is set to true, the representation dumped by the
Dump PAG option
is dumped with the variable (green) nodes in (pseudo-)topological order.
This option has no effect unless Dump PAG is true.
</long_desc>
</boolopt>
<boolopt>
<name>Dump Types</name>
<alias>dump-types</alias>
<default>true</default>
<short_desc>Include declared types in dump</short_desc>
<long_desc>
When this option is set to true, the representation dumped by the
Dump PAG option
includes type information for all nodes.
This option has no effect unless Dump PAG is true.
</long_desc>
</boolopt>
<boolopt>
<name>Class Method Var</name>
<alias>class-method-var</alias>
<default>true</default>
<short_desc>In dump, label variables by class and method</short_desc>
<long_desc>
When this option is set to true, the representation dumped by the
Dump PAG option
represents nodes by numbering each class, method, and variable within
the method separately, rather than assigning a single integer to each
node.
This option has no effect unless Dump PAG is true. Setting Class
Method Var to true has the effect of setting Topological Sort to
false.
</long_desc>
</boolopt>
<boolopt>
<name>Dump Answer</name>
<alias>dump-answer</alias>
<default>false</default>
<short_desc>Dump computed reaching types for comparison with other solvers</short_desc>
<long_desc>
When this option is set to true, the computed reaching types for each variable are
dumped to a file, so that they can be compared with the results of
other analyses (such as the old VTA).
</long_desc>
</boolopt>
<boolopt>
<name>Add Tags</name>
<alias>add-tags</alias>
<default>false</default>
<short_desc>Output points-to results in tags for viewing with the Jimple</short_desc>
<long_desc>
When this option is set to true, the results of the analysis are encoded within
tags and printed with the resulting Jimple code.
</long_desc>
</boolopt>
<boolopt>
<name>Calculate Set Mass</name>
<alias>set-mass</alias>
<default>false</default>
<short_desc>Calculate statistics about points-to set sizes</short_desc>
<long_desc>
When this option is set to true, Spark computes and prints various
cryptic statistics about the size of the points-to sets computed.
</long_desc>
</boolopt>
</section>
<section>
<name>Context-sensitive refinement</name>
<boolopt>
<name>Demand-driven refinement-based context-sensitive points-to analysis</name>
<alias>cs-demand</alias>
<default>false</default>
<short_desc>After running Spark, refine points-to sets on demand with context information</short_desc>
<long_desc>
When this option is set to true, Manu Sridharan's demand-driven,
refinement-based points-to analysis (PLDI 06) is applied after Spark
was run.
</long_desc>
</boolopt>
<boolopt>
<name>Create lazy points-to sets</name>
<alias>lazy-pts</alias>
<default>true</default>
<short_desc>Create lazy points-to sets that create context information only when needed.</short_desc>
<long_desc>
When this option is disabled, context information is computed for every query to the reachingObjects method.
When it is enabled, a call to reachingObjects returns a lazy wrapper object that contains a context-insensitive
points-to set. This set is then automatically refined with context information when necessary, i.e.
when we try to determine the intersection with another points-to set and this intersection seems to be
non-empty.
</long_desc>
</boolopt>
<intopt>
<name>Maximal traversal</name>
<alias>traversal</alias>
<default>75000</default>
<short_desc>Make the analysis traverse at most this number of nodes per query.</short_desc>
<long_desc>
Make the analysis traverse at most this number of nodes per query.
This quota is evenly shared between multiple passes (see next option).
</long_desc>
</intopt>
<intopt>
<name>Maximal number of passes</name>
<alias>passes</alias>
<default>10</default>
<short_desc>Perform at most this number of refinement iterations.</short_desc>
<long_desc>
Perform at most this number of refinement iterations.
Each iteration traverses at most ( traverse / passes ) nodes.
</long_desc>
</intopt>
</section>
<section>
<name>Geometric, context-sensitive analysis (ISSTA 2011)</name>
<boolopt>
<name>Geometric, context-sensitive points-to analysis</name>
<alias>geom-pta</alias>
<default>false</default>
<short_desc>This switch enables/disables the geometric analysis.</short_desc>
<long_desc>
This switch enables/disables the geometric analysis.
</long_desc>
</boolopt>
<multiopt>
<name>Encoding methodology used</name>
<alias>geom-encoding</alias>
<default>Geom</default>
<short_desc>Encoding methodology</short_desc>
<long_desc>
This switch specifies the encoding methodology used in the analysis.
All possible options are: Geom, HeapIns, PtIns. The efficiency order
is (from slow to fast) Geom - HeapIns - PtIns, but the precision order is
the reverse.
</long_desc>
<value>
<name>Geometric</name>
<alias>Geom</alias>
<short_desc>Geometric Encoding</short_desc>
<long_desc>
Geometric Encoding.
</long_desc>
<default/>
</value>
<value>
<name>Heap Insensitive</name>
<alias>HeapIns</alias>
<short_desc>Heap Insensitive Encoding</short_desc>
<long_desc>
Heap Insensitive Encoding. Omit the heap context range term in the encoded representation, and in turn, we assume all the contexts for this heap object are used.
</long_desc>
</value>
<value>
<name>Pointer Insensitive</name>
<alias>PtIns</alias>
<short_desc>PtIns</short_desc>
<long_desc>
Pointer Insensitive Encoding. Similar to HeapIns, but we omit the pointer context range term.
</long_desc>
</value>
</multiopt>
<multiopt>
<name>Worklist type</name>
<alias>geom-worklist</alias>
<default>PQ</default>
<short_desc>Worklist type</short_desc>
<long_desc>
Specifies the worklist used for selecting the next propagation pointer. All possible options are: PQ, FIFO. They stand for the priority queue (sorted by the last fire time and topology order) and FIFO queue.
</long_desc>
<value>
<name>Priority Queue</name>
<alias>PQ</alias>
<short_desc>Priority Queue</short_desc>
<long_desc>
Priority Queue (sorted by the last fire time and topology order)
</long_desc>
<default/>
</value>
<value>
<name>FIFO Queue</name>
<alias>FIFO</alias>
<short_desc>FIFO Queue</short_desc>
<long_desc>
FIFO Queue
</long_desc>
</value>
</multiopt>
<stropt>
<name>Verbose dump file</name>
<alias>geom-dump-verbose</alias>
<default></default>
<set_arg_label>name</set_arg_label>
<short_desc>Filename for detailed execution log</short_desc>
<long_desc>
If you want to persist the detailed execution information for future analysis, please provide a file name.
</long_desc>
</stropt>
<stropt>
<name>Verification file</name>
<alias>geom-verify-name</alias>
<default></default>
<set_arg_label>path</set_arg_label>
<short_desc>Filename for verification file</short_desc>
<long_desc>
If you want to compare the precision of the points-to results with other solvers (e.g. Paddle), you can use the "verify-file" to specify the list of methods (soot method signature format) that are reachable by that solver. Then, in the internal evaluations (see the switch geom-eval), we only consider the methods that are present to both solvers.
</long_desc>
</stropt>
<intopt>
<name>Precision evaluation methodologies</name>
<alias>geom-eval</alias>
<default>0</default>
<short_desc>Precision evaluation methodologies</short_desc>
<long_desc>
We internally provide some precision evaluation methodologies, and classify the evaluation strength into three levels. If level is 0, we do nothing. If level is 1, we report the basic information about the points-to result. If level is 2, we perform the virtual callsite resolution, static cast safety and all alias pairs evaluations.
</long_desc>
</intopt>
<boolopt>
<name>Transform to context-insensitive result</name>
<alias>geom-trans</alias>
<default>false</default>
<short_desc>Transform to context-insensitive result</short_desc>
<long_desc>
If your work only concern the context insensitive points-to information, you can use this option to transform the context sensitive result to insensitive result. Or, sometimes your code wants to directly access to the points-to vector other than using the standard querying interface, you can use this option to guarantee the correct behavior (because we clear the SPARK points-to result when running the geom solver). After the transformation, the context sensitive points-to result is cleared in order to save memory space for your other jobs.
</long_desc>
</boolopt>
<intopt>
<name>Fractional parameter</name>
<alias>geom-frac-base</alias>
<default>40</default>
<short_desc>Fractional parameter for precision/performance trade-off</short_desc>
<long_desc>
This option specifies the fractional parameter, which is used to manually tune the precision and performance trade-off. The smaller the value, the better the performance but the worse the precision.
</long_desc>
</intopt>
<boolopt>
<name>Blocking strategy for recursive calls</name>
<alias>geom-blocking</alias>
<default>true</default>
<short_desc>Enable blocking strategy for recursive calls</short_desc>
<long_desc>
When this option is on, we perform the blocking strategy to the recursive calls. This strategy significantly improves the precision. The details are presented in our paper.
</long_desc>
</boolopt>
<intopt>
<name>Iterations</name>
<alias>geom-runs</alias>
<default>1</default>
<short_desc>Iterations of analysis</short_desc>
<long_desc>
We can run multiple times of the geometric analysis to continuously improve the analysis precision.
</long_desc>
</intopt>
-->
</section>
</sub_phase>
<sub_phase>
<name>Paddle</name>
<class>PaddleOptions</class>
<alias>cg.paddle</alias>
<short_desc>Paddle points-to analysis framework</short_desc>
<long_desc>Paddle is a BDD-based interprocedural analysis framework. It includes points-to analysis, call graph construction, and various client analyses.</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>false</default>
<short_desc/>
<long_desc/>
</boolopt>
<section>
<name>Paddle General Options</name>
<boolopt>
<name>Verbose</name>
<alias>verbose</alias>
<default>false</default>
<short_desc>Print detailed information about the execution of Paddle</short_desc>
<long_desc>
When this option is set to true, Paddle prints detailed information about its execution.
</long_desc>
</boolopt>
<multiopt>
<name>Configuration</name>
<alias>conf</alias>
<value>
<name>On-the fly call graph</name>
<alias>ofcg</alias>
<default/>
<short_desc>On-the fly call graph</short_desc>
<long_desc>
Performs points-to analysis and builds call graph together, on-the-fly.
</long_desc>
</value>
<value>
<name>CHA only</name>
<alias>cha</alias>
<short_desc>CHA only</short_desc>
<long_desc>
Builds only a call graph using Class Hieararchy Analysis, and performs no
points-to analysis.
</long_desc>
</value>
<value>
<name>CHA ahead-of-time call graph</name>
<alias>cha-aot</alias>
<short_desc>CHA ahead-of-time callgraph</short_desc>
<long_desc>
First builds a call graph using CHA, then uses the call graph in a fixed-call-graph points-to analysis.
</long_desc>
</value>
<value>
<name>OFCG-AOT</name>
<alias>ofcg-aot</alias>
<short_desc>OFCG-AOT callgraph</short_desc>
<long_desc>
First builds a call graph on-the-fly during a points-to analysis, then
uses the resulting call graph to perform a second points-to analysis
with a fixed call graph.
</long_desc>
</value>
<value>
<name>CHA-Context-AOT call graph</name>
<alias>cha-context-aot</alias>
<short_desc>CHA-Context-AOT callgraph</short_desc>
<long_desc>
First builds a call graph using CHA, then makes it context-sensitive using
the technique described by Calman and Zhu in PLDI 04,
then uses the call graph in a fixed-call-graph points-to analysis.
</long_desc>
</value>
<value>
<name>OFCG-Context-AOT</name>
<alias>ofcg-context-aot</alias>
<short_desc>OFCG-Context-AOT callgraph</short_desc>
<long_desc>
First builds a call graph on-the-fly during a points-to analysis, then
makes it context-sensitive using the technique described by Calman and
Zhu in PLDI 04, then uses the resulting call graph to perform a second
points-to analysis with a fixed call graph.
</long_desc>
</value>
<value>
<name>CHA-Context call graph</name>
<alias>cha-context</alias>
<short_desc>CHA-Context callgraph</short_desc>
<long_desc>
First builds a call graph using CHA, then makes it context-sensitive using
the technique described by Calman and Zhu in PLDI 04. Does not produce
points-to information.
</long_desc>
</value>
<value>
<name>OFCG-Context</name>
<alias>ofcg-context</alias>
<short_desc>OFCG-Context callgraph</short_desc>
<long_desc>
First builds a call graph on-the-fly during a points-to analysis, then
makes it context-sensitive using the technique described by Calman and
Zhu in PLDI 04. Does not perform a subsequent points-to analysis.
</long_desc>
</value>
<short_desc>Select Paddle configuration</short_desc>
<long_desc>
Selects the configuration of points-to analysis and call graph construction
to be used in Paddle.
</long_desc>
</multiopt>
<boolopt>
<name>Use BDDs</name>
<alias>bdd</alias>
<default>false</default>
<short_desc>Use BDD version of Paddle</short_desc>
<long_desc>
Causes Paddle to use BDD versions of its components
</long_desc>
</boolopt>
<intopt>
<name>Variable ordering</name>
<alias>order</alias>
<default>32</default>
<short_desc/>
<long_desc>
Selects one of the BDD variable orderings hard-coded in Paddle.
</long_desc>
</intopt>
<boolopt>
<name>Dynamic reordering</name>
<alias>dynamic-order</alias>
<short_desc/>
<long_desc>
Allows the BDD package to perform dynamic variable ordering.
</long_desc>
</boolopt>
<boolopt>
<name>Profile</name>
<alias>profile</alias>
<default>false</default>
<short_desc>Profile BDDs using JeddProfiler</short_desc>
<long_desc>
Turns on JeddProfiler for profiling BDD operations.
</long_desc>
</boolopt>
<boolopt>
<name>Verbose GC</name>
<alias>verbosegc</alias>
<default>false</default>
<short_desc>Print memory usage at each BDD garbage collection.</short_desc>
<long_desc>
Print memory usage at each BDD garbage collection.
</long_desc>
</boolopt>
<multiopt>
<name>Worklist Implementation</name>
<alias>q</alias>
<value>
<name>Select Automatically</name>
<alias>auto</alias>
<default/>
<short_desc>Select queue implementation based on bdd option</short_desc>
<long_desc>
When the bdd option is true, the BDD-based worklist implementation will be used.
When the bdd option is false, the Traditional worklist implementation will be used.
</long_desc>
</value>
<value>
<name>Traditional</name>
<alias>trad</alias>
<short_desc>Normal worklist queue implementation</short_desc>
<long_desc>
Normal worklist queue implementation
</long_desc>
</value>
<value>
<name>BDD</name>
<alias>bdd</alias>
<short_desc>BDD-based queue implementation</short_desc>
<long_desc>
BDD-based queue implementation
</long_desc>
</value>
<value>
<name>Debug</name>
<alias>debug</alias>
<short_desc>Debugging queue implementation</short_desc>
<long_desc>
An implementation of worklists that includes both traditional and BDD-based
implementations, and signals an error whenever their contents differ.
</long_desc>
</value>
<value>
<name>Trace</name>
<alias>trace</alias>
<short_desc>Tracing queue implementation</short_desc>
<long_desc>
A worklist implementation that prints out all tuples added to every worklist.
</long_desc>
</value>
<value>
<name>Number Trace</name>
<alias>numtrace</alias>
<short_desc>Number-tracing queue implementation</short_desc>
<long_desc>
A worklist implementation that prints out the number of tuples added to
each worklist after each operation.
</long_desc>
</value>
<short_desc>Select queue implementation</short_desc>
<long_desc>
Select the implementation of worklists to be used in Paddle.
</long_desc>
</multiopt>
<multiopt>
<name>Backend</name>
<alias>backend</alias>
<value>
<name>Select Automatically</name>
<alias>auto</alias>
<default/>
<short_desc>Select backend based on bdd option</short_desc>
<long_desc>
When the bdd option is true, the BuDDy backend will be used.
When the bdd option is false, the backend will be set to none, to avoid
loading any BDD backend.
</long_desc>
</value>
<value>
<name>BuDDy</name>
<alias>buddy</alias>
<short_desc>BuDDy backend</short_desc>
<long_desc>
Use BuDDy implementation of BDDs.
</long_desc>
</value>
<value>
<name>CUDD</name>
<alias>cudd</alias>
<short_desc>CUDD backend</short_desc>
<long_desc>
Use CUDD implementation of BDDs.
</long_desc>
</value>
<value>
<name>SableJBDD</name>
<alias>sable</alias>
<short_desc>SableJBDD backend</short_desc>
<long_desc>Use SableJBDD implementation of BDDs.</long_desc>
</value>
<value>
<name>JavaBDD</name>
<alias>javabdd</alias>
<short_desc>JavaBDD backend</short_desc>
<long_desc>
Use JavaBDD implementation of BDDs.
</long_desc>
</value>
<value>
<name>None</name>
<alias>none</alias>
<short_desc>No BDDs</short_desc>
<long_desc>
Don't use any BDD backend. Any attempted use of BDDs will cause Paddle to crash.
</long_desc>
</value>
<short_desc>Select BDD backend</short_desc>
<long_desc>
This option tells Paddle which implementation of BDDs to use.
</long_desc>
</multiopt>
<intopt>
<name>BDD Nodes</name>
<alias>bdd-nodes</alias>
<default>0</default>
<short_desc>Number of BDD nodes to allocate (0=unlimited)</short_desc>
<long_desc>
This option specifies the number of BDD nodes to be used by the BDD backend.
A value of 0 causes the backend to start with one million nodes, and allocate
more as required. A value other than zero causes the backend to start with
the specified size, and prevents it from ever allocating any more nodes.
</long_desc>
</intopt>
<boolopt>
<name>Ignore Types Entirely</name>
<alias>ignore-types</alias>
<default>false</default>
<short_desc>Make Paddle completely ignore declared types of variables</short_desc>
<long_desc>
When this option is set to true, all parts of Paddle completely ignore
declared types of variables and casts.
</long_desc>
</boolopt>
<boolopt>
<name>Pre Jimplify</name>
<alias>pre-jimplify</alias>
<default>false</default>
<short_desc>Jimplify all methods before starting Paddle</short_desc>
<long_desc>
When this option is set to true, Paddle converts all available methods to Jimple
before starting the points-to analysis. This allows the Jimplification
time to be separated from the points-to time. However, it increases the
total time and memory requirement, because all methods are Jimplified,
rather than only those deemed reachable by the points-to analysis.
</long_desc>
</boolopt>
</section>
<section>
<name>Paddle Context Sensitivity Options</name>
<multiopt>
<name>Context abstraction</name>
<alias>context</alias>
<value>
<name>Context-insensitive</name>
<alias>insens</alias>
<default/>
<short_desc>Builds a context-insensitive call graph</short_desc>
<long_desc>
Builds a context-insensitive call graph.
</long_desc>
</value>
<value>
<name>1-CFA</name>
<alias>1cfa</alias>
<short_desc>Builds a 1-CFA call graph</short_desc>
<long_desc>
Builds a 1-CFA call graph.
</long_desc>
</value>
<value>
<name>k-CFA</name>
<alias>kcfa</alias>
<short_desc>Builds a k-CFA call graph</short_desc>
<long_desc>
Builds a k-CFA call graph.
</long_desc>
</value>
<value>
<name>Object Sensitive</name>
<alias>objsens</alias>
<short_desc>Builds an object-sensitive call graph</short_desc>
<long_desc>
Builds an object-sensitive call graph.
</long_desc>
</value>
<value>
<name>k-Object Sensitive</name>
<alias>kobjsens</alias>
<short_desc>Builds a k-object-sensitive call graph</short_desc>
<long_desc>
Builds a context-sensitive call graph where the context is a string of up to
k receiver objects.
</long_desc>
</value>
<value>
<name>Unique k-Object Sensitive</name>
<alias>uniqkobjsens</alias>
<short_desc>Builds a unique-k-object-sensitive call graph</short_desc>
<long_desc>
Builds a context-sensitive call graph where the context is a string of up to
k unique receiver objects. If the receiver of a call already appears in the
context string, the context string is just reused as is.
</long_desc>
</value>
<value>
<name>Thread k-Object Sensitive</name>
<alias>threadkobjsens</alias>
<short_desc>Experimental option for thread-entry-point sensitivity</short_desc>
<long_desc>
Experimental option for thread-entry-point sensitivity.
</long_desc>
</value>
<short_desc>Select context-sensitivity level</short_desc>
<long_desc>
This option tells Paddle which level of context-sensitivity to use in constructing the call graph.
</long_desc>
</multiopt>
<intopt>
<name>Context length (k)</name>
<alias>k</alias>
<default>2</default>
<short_desc/>
<long_desc>
The maximum length of call string or receiver object string used as context.
</long_desc>
</intopt>
<boolopt>
<name>Context-sensitive Heap Locations</name>
<alias>context-heap</alias>
<default>false</default>
<short_desc>Treat allocation sites context-sensitively</short_desc>
<long_desc>
When this option is set to true, the context-sensitivity level that is set
for the context-sensitive call graph and for pointer variables is also used
to model heap locations context-sensitively. When this option is false,
heap locations are modelled context-insensitively regardless of the
context-sensitivity level.
</long_desc>
</boolopt>
</section>
<section>
<name>Paddle Pointer Assignment Graph Building Options</name>
<boolopt>
<name>RTA</name>
<alias>rta</alias>
<default>false</default>
<short_desc>Emulate Rapid Type Analysis</short_desc>
<long_desc>
Setting RTA to true sets types-for-sites to true, and causes Paddle to use
a single points-to set for all variables, giving <a href="http://doi.acm.org/10.1145/236337.236371">Rapid Type
Analysis</a>.
</long_desc>
</boolopt>
<boolopt>
<name>Field Based</name>
<alias>field-based</alias>
<default>false</default>
<short_desc>Use a field-based rather than field-sensitive representation</short_desc>
<long_desc>
When this option is set to true, fields are represented by variable
(Green) nodes, and the object that the field belongs to is ignored
(all objects are lumped together), giving a field-based analysis. Otherwise, fields are represented by
field reference (Red) nodes, and the objects that they belong to are
distinguished, giving a field-sensitive analysis.
</long_desc>
</boolopt>
<boolopt>
<name>Types For Sites</name>
<alias>types-for-sites</alias>
<default>false</default>
<short_desc>Represent objects by their actual type rather than allocation site</short_desc>
<long_desc>
When this option is set to true, types rather than allocation sites are
used as the elements of the points-to sets.
</long_desc>
</boolopt>
<boolopt>
<name>Merge String Buffer</name>
<alias>merge-stringbuffer</alias>
<default>true</default>
<short_desc>Represent all StringBuffers as one object</short_desc>
<long_desc>
When this option is set to true, all allocation sites creating
<tt>java.lang.StringBuffer</tt> objects are grouped together as a single
allocation site. Allocation sites creating a <tt>java.lang.StringBuilder</tt>
object are also grouped together as a single allocation site.
</long_desc>
</boolopt>
<boolopt>
<name>Propagate All String Constants</name>
<alias>string-constants</alias>
<default>false</default>
<short_desc>Propagate all string constants, not just class names</short_desc>
<long_desc>
When this option is set to false, Paddle only distinguishes string constants that
may be the name of a class loaded dynamically using reflection, and all other
string constants are lumped together into a single string constant node.
Setting this option to true causes all string constants to be propagated
individually.
</long_desc>
</boolopt>
<boolopt>
<name>Simulate Natives</name>
<alias>simulate-natives</alias>
<default>true</default>
<short_desc>Simulate effects of native methods in standard class library</short_desc>
<long_desc>
When this option is set to true, the effects of native methods in the standard Java class library are simulated.
</long_desc>
</boolopt>
<boolopt>
<name>Global Nodes in Simulated Natives</name>
<alias>global-nodes-in-natives</alias>
<default>false</default>
<short_desc>Use global node to model variables in simulations of native methods</short_desc>
<long_desc>
The simulations of native methods such as System.arraycopy() use
temporary local variable nodes. Setting this switch to true causes them
to use global variable nodes instead, reducing precision. The switch
exists only to make it possible to measure this effect on precision;
there is no other practical reason to set it to true.
</long_desc>
</boolopt>
<boolopt>
<name>Simple Edges Bidirectional</name>
<alias>simple-edges-bidirectional</alias>
<default>false</default>
<short_desc>Equality-based analysis between variable nodes</short_desc>
<long_desc>
When this option is set to true, all edges connecting variable (Green)
nodes are made bidirectional, as in <a href="http://doi.acm.org/10.1145/237721.237727">Steensgaard's analysis</a>.
</long_desc>
</boolopt>
<boolopt>
<name>this Pointer Assignment Edge</name>
<alias>this-edges</alias>
<default>false</default>
<short_desc>Use pointer assignment edges to model this parameters</short_desc>
<long_desc>
When constructing a call graph on-the-fly during points-to analysis, Paddle
normally propagates only those receivers that cause a method to be invoked
to the this pointer of the method. When this option is set to true, however,
Paddle instead models flow of receivers as an assignnment edge from the
receiver at the call site to the this pointer of the method, reducing
precision.
</long_desc>
</boolopt>
<boolopt>
<name>Precise newInstance</name>
<alias>precise-newinstance</alias>
<default>true</default>
<short_desc>Make newInstance only allocate objects of dynamic classes</short_desc>
<long_desc>
Normally, newInstance() calls are treated as if they may return an object
of any type. Setting this option to true causes them to be treated as if
they return only objects of the type of some dynamic class.
</long_desc>
</boolopt>
</section>
<section>
<name>Paddle Points-To Set Flowing Options</name>
<multiopt>
<name>Propagator</name>
<alias>propagator</alias>
<value>
<name>Select Automatically</name>
<alias>auto</alias>
<default/>
<short_desc>Select propagation algorithm based on bdd option</short_desc>
<long_desc>
When the bdd option is true, the Incremental BDD propagation algorithm will be used.
When the bdd option is false, the Worklist propagation algorithm will be used.
</long_desc>
</value>
<value>
<name>Iter</name>
<alias>iter</alias>
<short_desc>Simple iterative algorithm</short_desc>
<long_desc>
Iter is a simple, iterative algorithm, which propagates everything until the
graph does not change.
</long_desc>
</value>
<value>
<name>Worklist</name>
<alias>worklist</alias>
<short_desc>Fast, worklist-based algorithm</short_desc>
<long_desc>
Worklist is a worklist-based algorithm that tries
to do as little work as possible. This is currently the fastest algorithm.
</long_desc>
</value>
<value>
<name>Alias</name>
<alias>alias</alias>
<short_desc>Alias-edge based algorithm</short_desc>
<long_desc>
Alias is an alias-edge based algorithm. This algorithm tends to take
the least memory for very large problems, because it does not represent
explicitly points-to sets of fields of heap objects.
</long_desc>
</value>
<value>
<name>BDD</name>
<alias>bdd</alias>
<short_desc>BDD-based propagator</short_desc>
<long_desc>
BDD is a propagator that stores points-to sets in binary decision diagrams.
</long_desc>
</value>
<value>
<name>Incrementalized BDD</name>
<alias>incbdd</alias>
<short_desc>Incrementalized BDD-based propagator</short_desc>
<long_desc>
A propagator that stores points-to sets in binary decision diagrams, and propagates them incrementally.
</long_desc>
</value>
<short_desc>Select propagation algorithm</short_desc>
<long_desc>
This option tells Paddle which propagation algorithm to use.
</long_desc>
</multiopt>
<multiopt>
<name>Set Implementation</name>
<alias>set-impl</alias>
<value>
<name>Hash set</name>
<alias>hash</alias>
<short_desc>Use Java HashSet</short_desc>
<long_desc>
Hash is an implementation based on Java's built-in hash-set.
</long_desc>
</value>
<value>
<name>Bit-vector</name>
<alias>bit</alias>
<short_desc>Bit vector</short_desc>
<long_desc>
Bit is an implementation using a bit vector.
</long_desc>
</value>
<value>
<name>Hybrid</name>
<alias>hybrid</alias>
<short_desc>Hybrid representation using bit vector for large sets</short_desc>
<long_desc>
Hybrid is an implementation that keeps an explicit list of up to
16 elements, and switches to a bit-vector when the set gets
larger than this.
</long_desc>
</value>
<value>
<name>Sorted array</name>
<alias>array</alias>
<short_desc>Sorted array representation</short_desc>
<long_desc>
Array is an implementation that keeps the elements of the
points-to set in a sorted array. Set membership is tested using
binary search, and set union and intersection are computed using
an algorithm based on the merge step from merge sort.
</long_desc>
</value>
<value>
<name>Heintze</name>
<alias>heintze</alias>
<short_desc>Heintze's shared bit-vector and overflow list representation</short_desc>
<long_desc>Heintze's representation has elements represented by a bit-vector + a small
'overflow' list of some maximum number of elements. The bit-vectors can be shared
by multiple points-to sets, while the overflow lists are not.
</long_desc>
</value>
<value>
<name>Double</name>
<alias>double</alias>
<default/>
<short_desc>Double set representation for incremental propagation</short_desc>
<long_desc>
Double is an implementation that itself uses a pair of sets for
each points-to set. The first set in the pair stores new pointed-to
objects that have not yet been propagated, while the second set stores
old pointed-to objects that have been propagated and need not be
reconsidered. This allows the propagation algorithms to be incremental,
often speeding them up significantly.
</long_desc>
</value>
<short_desc>Select points-to set implementation</short_desc>
<long_desc>
Select an implementation of points-to sets for Paddle to use.
</long_desc>
</multiopt>
<multiopt>
<name>Double Set Old</name>
<alias>double-set-old</alias>
<value>
<name>Hash set</name>
<alias>hash</alias>
<short_desc>Use Java HashSet</short_desc>
<long_desc>
Hash is an implementation based on Java's built-in hash-set.
</long_desc>
</value>
<value>
<name>Bit-vector</name>
<alias>bit</alias>
<short_desc>Bit vector</short_desc>
<long_desc>
Bit is an implementation using a bit vector.
</long_desc>
</value>
<value>
<name>Hybrid</name>
<alias>hybrid</alias>
<default/>
<short_desc>Hybrid representation using bit vector for large sets</short_desc>
<long_desc>
Hybrid is an implementation that keeps an explicit list of up to
16 elements, and switches to a bit-vector when the set gets
larger than this.
</long_desc>
</value>
<value>
<name>Sorted array</name>
<alias>array</alias>
<short_desc>Sorted array representation</short_desc>
<long_desc>
Array is an implementation that keeps the elements of the
points-to set in a sorted array. Set membership is tested using
binary search, and set union and intersection are computed using
an algorithm based on the merge step from merge sort.
</long_desc>
</value>
<value>
<name>Heintze</name>
<alias>heintze</alias>
<short_desc>Heintze's shared bit-vector and overflow list representation</short_desc>
<long_desc>Heintze's representation has elements represented by a bit-vector + a small
'overflow' list of some maximum number of elements. The bit-vectors can be shared
by multiple points-to sets, while the overflow lists are not.
</long_desc>
</value>
<short_desc>Select implementation of points-to set for old part of double set</short_desc>
<long_desc>
Select an implementation for sets of old objects in the double
points-to set implementation.
This option has no effect unless Set Implementation is set to double.
</long_desc>
</multiopt>
<multiopt>
<name>Double Set New</name>
<alias>double-set-new</alias>
<value>
<name>Hash set</name>
<alias>hash</alias>
<short_desc>Use Java HashSet</short_desc>
<long_desc>
Hash is an implementation based on Java's built-in hash-set.
</long_desc>
</value>
<value>
<name>Bit-vector</name>
<alias>bit</alias>
<short_desc>Bit vector</short_desc>
<long_desc>
Bit is an implementation using a bit vector.
</long_desc>
</value>
<value>
<name>Hybrid</name>
<alias>hybrid</alias>
<default/>
<short_desc>Hybrid representation using bit vector for large sets</short_desc>
<long_desc>
Hybrid is an implementation that keeps an explicit list of up to
16 elements, and switches to a bit-vector when the set gets
larger than this.
</long_desc>
</value>
<value>
<name>Sorted array</name>
<alias>array</alias>
<short_desc>Sorted array representation</short_desc>
<long_desc>
Array is an implementation that keeps the elements of the
points-to set in a sorted array. Set membership is tested using
binary search, and set union and intersection are computed using
an algorithm based on the merge step from merge sort.
</long_desc>
</value>
<value>
<name>Heintze</name>
<alias>heintze</alias>
<short_desc>Heintze's shared bit-vector and overflow list representation</short_desc>
<long_desc>Heintze's representation has elements represented by a bit-vector + a small
'overflow' list of some maximum number of elements. The bit-vectors can be shared
by multiple points-to sets, while the overflow lists are not.
</long_desc>
</value>
<short_desc>Select implementation of points-to set for new part of double set</short_desc>
<long_desc>
Select an implementation for sets of new objects in the double
points-to set implementation.
This option has no effect unless Set Implementation is set to double.
</long_desc>
</multiopt>
</section>
<section>
<name>Paddle Output Options</name>
<boolopt>
<name>Print Context Counts</name>
<alias>context-counts</alias>
<default>false</default>
<short_desc>Print number of contexts for each method</short_desc>
<long_desc>
Causes Paddle to print the number of contexts for each method and
call edge, and the number of equivalence classes of contexts for
each variable node.
</long_desc>
</boolopt>
<boolopt>
<name>Print Context Counts (Totals only)</name>
<alias>total-context-counts</alias>
<default>false</default>
<short_desc>Print total number of contexts</short_desc>
<long_desc>
Causes Paddle to print the number of contexts and number of context
equivalence classes.
</long_desc>
</boolopt>
<boolopt>
<name>Method Context Counts (Totals only)</name>
<alias>method-context-counts</alias>
<default>false</default>
<short_desc>Print number of contexts for each method</short_desc>
<long_desc>
Causes Paddle to print the number of contexts and number of context
equivalence classes split out by method. Requires total-context-counts to also be turned on.
</long_desc>
</boolopt>
<boolopt>
<name>Calculate Set Mass</name>
<alias>set-mass</alias>
<default>false</default>
<short_desc>Calculate statistics about points-to set sizes</short_desc>
<long_desc>
When this option is set to true, Paddle computes and prints various
cryptic statistics about the size of the points-to sets computed.
</long_desc>
</boolopt>
<boolopt>
<name>Number nodes</name>
<alias>number-nodes</alias>
<default>true</default>
<short_desc>Print node numbers in dumps</short_desc>
<long_desc>
When printing debug information about nodes, this option causes the node number
of each node to be printed.
</long_desc>
</boolopt>
</section>
</sub_phase>
</radio_phase>
<phase>
<name>Whole Shimple Transformation Pack</name>
<alias>wstp</alias>
<short_desc>Whole-shimple transformation pack</short_desc>
<long_desc>
<p>
Soot can perform whole-program analyses. In whole-shimple mode, Soot
applies the contents of the Whole-Shimple Transformation Pack to the
scene as a whole after constructing a call graph for the program.</p>
<p>
In an unmodified copy of Soot the Whole-Shimple Transformation
Pack is empty.</p>
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
</boolopt>
</phase>
<phase>
<name>Whole Shimple Optimization Pack</name>
<alias>wsop</alias>
<short_desc>Whole-shimple optimization pack</short_desc>
<long_desc>
<p>
If Soot is running in whole shimple mode and the Whole-Shimple
Optimization Pack is enabled, the pack's transformations are
applied to the scene as a whole after construction of the call
graph and application of any enabled Whole-Shimple
Transformations.</p>
<p>
In an unmodified copy of Soot the Whole-Shimple Optimization
Pack is empty.</p>
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>false</default>
</boolopt>
</phase>
<phase>
<name>Whole-Jimple Transformation Pack</name>
<alias>wjtp</alias>
<short_desc>Whole-jimple transformation pack</short_desc>
<long_desc>
<p>
Soot can perform whole-program analyses. In whole-program mode,
Soot applies the contents of the Whole-Jimple Transformation Pack
to the scene as a whole after constructing a call graph for the
program.</p>
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
<short_desc/>
<long_desc/>
</boolopt>
<sub_phase>
<name>May Happen in Parallel Analyses</name>
<class>MhpTransformer</class>
<alias>wjtp.mhp</alias>
<short_desc>Determines what statements may be run concurrently</short_desc>
<long_desc>
May Happen in Parallel (MHP) Analyses determine what program statements may
be run by different threads concurrently. This phase does not perform any
transformation.
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>false</default>
<short_desc/>
<long_desc/>
</boolopt>
</sub_phase>
<sub_phase>
<name>Lock Allocator</name>
<class>LockAllocator</class>
<alias>wjtp.tn</alias>
<short_desc>Finds critical sections, allocates locks</short_desc>
<long_desc>
The Lock Allocator finds critical sections (synchronized regions)
in Java programs and assigns locks for execution on both
optimistic and pessimistic JVMs. It can also be used to analyze the existing
locks.
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>false</default>
<short_desc/>
<long_desc/>
</boolopt>
<multiopt>
<name>Locking Scheme</name>
<alias>locking-scheme</alias>
<set_arg_label>granularity</set_arg_label>
<short_desc>Selects the granularity of the generated lock allocation</short_desc>
<long_desc>Selects the granularity of the generated lock allocation</long_desc>
<!-- <value>
<name>Fine Grained</name>
<alias>fine-grained</alias>
<short_desc>Use multiple runtime objects for synchronization</short_desc>
<long_desc>
Try to identify transactional regions that can employ fine-grained locking to
increase parallelism. All side effects must be protected by a single object.
This locking scheme aims to achieve simple fine-grained locking.
</long_desc>
</value> -->
<value>
<name>Medium Grained</name>
<alias>medium-grained</alias>
<short_desc>Use a runtime object for synchronization where possible</short_desc>
<long_desc>
Try to identify transactional regions that can employ a dynamic lock to
increase parallelism. All side effects must be protected by a single object.
This locking scheme aims to approximate typical Java Monitor usage.
</long_desc>
<default/>
</value>
<value>
<name>Coarse Grained</name>
<alias>coarse-grained</alias>
<short_desc>Use static objects for synchronization</short_desc>
<long_desc>
Insert static objects into the program for synchronization. One object will be
used for each group of conflicting synchronized regions. This locking scheme
achieves code-level locking.
</long_desc>
</value>
<value>
<name>Single Static Lock</name>
<alias>single-static</alias>
<short_desc>Use just one static synchronization object for all transactional regions</short_desc>
<long_desc>
Insert one static object into the program for synchronization for all
transactional regions. This locking scheme is for research purposes.
</long_desc>
</value>
<value>
<name>Leave Original Locks</name>
<alias>leave-original</alias>
<short_desc>Analyse the existing lock structure without making changes</short_desc>
<long_desc>
Analyse the existing lock structure of the program, but do not change it. With
one of the print options, this can be useful for comparison between the original
program and one of the generated locking schemes.
</long_desc>
</value>
</multiopt>
<boolopt>
<name>Perform Deadlock Avoidance</name>
<alias>avoid-deadlock</alias>
<default>true</default>
<short_desc>Perform Deadlock Avoidance</short_desc>
<long_desc>
Perform Deadlock Avoidance by enforcing a lock ordering where necessary.
</long_desc>
</boolopt>
<boolopt>
<name>Use Open Nesting</name>
<alias>open-nesting</alias>
<default>true</default>
<short_desc>Use an open nesting model</short_desc>
<long_desc>
Use an open nesting model, where inner transactions are allowed to commit
independently of any outer transaction.
</long_desc>
</boolopt>
<boolopt>
<name>Perform May-Happen-in-Parallel Analysis</name>
<alias>do-mhp</alias>
<default>true</default>
<short_desc>Perform a May-Happen-in-Parallel analysis</short_desc>
<long_desc>
Perform a May-Happen-in-Parallel analysis to assist in allocating locks.
</long_desc>
</boolopt>
<boolopt>
<name>Perform Local Objects Analysis</name>
<alias>do-tlo</alias>
<default>true</default>
<short_desc>Perform a Local-Objects analysis</short_desc>
<long_desc>
Perform a Local-Objects analysis to assist in allocating locks.
</long_desc>
</boolopt>
<boolopt>
<name>Print Topological Graph</name>
<alias>print-graph</alias>
<default>false</default>
<short_desc>Print topological graph of transactions</short_desc>
<long_desc>
Print a topological graph of the program's transactions in the format used by the graphviz package.
</long_desc>
</boolopt>
<boolopt>
<name>Print Table</name>
<alias>print-table</alias>
<default>false</default>
<short_desc>Print table of transactions</short_desc>
<long_desc>
Print a table of information about the program's transactions.
</long_desc>
</boolopt>
<boolopt>
<name>Print Debugging Info</name>
<alias>print-debug</alias>
<default>false</default>
<short_desc>Print debugging info</short_desc>
<long_desc>
Print debugging info, including every statement visited.
</long_desc>
</boolopt>
</sub_phase>
</phase>
<phase>
<name>Whole-Jimple Optimization Pack</name>
<alias>wjop</alias>
<short_desc>Whole-jimple optimization pack</short_desc>
<long_desc>
<p>
If Soot is running in whole program mode and the Whole-Jimple
Optimization Pack is enabled, the pack's transformations are
applied to the scene as a whole after construction of the call
graph and application of any enabled Whole-Jimple
Transformations.</p>
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>false</default>
<short_desc/>
<long_desc/>
</boolopt>
<sub_phase>
<name>Static Method Binder</name>
<class>SMBOptions</class>
<alias>wjop.smb</alias>
<short_desc>Static method binder: Devirtualizes monomorphic calls</short_desc>
<long_desc>
The Static Method Binder statically binds monomorphic call
sites. That is, it searches the call graph for virtual method
invocations that can be determined statically to call only a single
implementation of the called method. Then it replaces such virtual
invocations with invocations of a static copy of the single called
implementation.
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>false</default>
<short_desc/>
<long_desc/>
</boolopt>
<boolopt>
<name>Insert Null Checks</name>
<alias>insert-null-checks</alias>
<default>true</default>
<short_desc/>
<long_desc>
Insert a check that, before invoking the static copy of the
target method, throws a <tt>NullPointerException</tt> if the
receiver object is null. This ensures that static method binding does
not eliminate exceptions which would have occurred in its absence.
</long_desc>
</boolopt>
<boolopt>
<name>Insert Redundant Casts</name>
<alias>insert-redundant-casts</alias>
<default>true</default>
<short_desc/>
<long_desc>
<p>
Insert extra casts for the Java bytecode verifier. If the target
method uses its <tt>this</tt> parameter, a reference to the
receiver object must be passed to the static copy of the target
method. The verifier may complain if the declared type of the
receiver parameter does not match the type implementing the
target method.</p>
<p>
Say, for example, that <tt>Singer</tt> is an interface declaring
the <tt>sing()</tt> method and that the call graph shows all
receiver objects at a particular call site,
<tt>singer.sing()</tt> (with <tt>singer</tt> declared as a
<tt>Singer</tt>) are in fact <tt>Bird</tt> objects (<tt>Bird</tt>
being a class that implements <tt>Singer</tt>). The virtual call
<tt>singer.sing()</tt> is effectively replaced with the static
call <tt>Bird.staticsing(singer)</tt>. <tt>Bird.staticsing()</tt>
may perform operations on its parameter which are only allowed on
<tt>Bird</tt>s, rather than <tt>Singer</tt>s. The Insert
Redundant Casts option inserts a cast of <tt>singer</tt> to the
<tt>Bird</tt> type, to prevent complaints from the verifier.</p>
</long_desc>
</boolopt>
<multiopt>
<name>Allowed Modifier Changes</name>
<alias>allowed-modifier-changes</alias>
<value>
<name>Unsafe</name>
<alias>unsafe</alias>
<short_desc/>
<long_desc>
Modify the visibility on code so that all inlining is permitted.
</long_desc>
<default/>
</value>
<value>
<name>Safe</name>
<alias>safe</alias>
<short_desc/>
<long_desc>
Preserve the exact meaning of the analyzed program.
</long_desc>
</value>
<value>
<name>None</name>
<alias>none</alias>
<short_desc/>
<long_desc>
Change no modifiers whatsoever.
</long_desc>
</value>
<short_desc/>
<long_desc>
Specify which changes in visibility modifiers
are allowed.
</long_desc>
</multiopt>
</sub_phase>
<sub_phase>
<name>Static Inliner</name>
<class>SIOptions</class>
<alias>wjop.si</alias>
<short_desc>Static inliner: inlines monomorphic calls</short_desc>
<long_desc>
The Static Inliner visits all call sites in the call graph in a
bottom-up fashion, replacing monomorphic calls with inlined
copies of the invoked methods.
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
<short_desc/>
<long_desc/>
</boolopt>
<boolopt>
<name>Reconstruct Jimple body after inlining</name>
<alias>rerun-jb</alias>
<default>true</default>
<short_desc/>
<long_desc>
When a method with array parameters is inlined, its variables may need to
be assigned different types than they had in the original method to produce
compilable code. When this option is set, Soot re-runs the Jimple Body pack
on each method body which has had another method inlined into it so that
the typing algorithm can reassign the types.
</long_desc>
</boolopt>
<boolopt>
<name>Insert Null Checks</name>
<alias>insert-null-checks</alias>
<default>true</default>
<short_desc/>
<long_desc>
Insert, before the inlined body of the target method, a check
that throws a <tt>NullPointerException</tt> if the receiver
object is null. This ensures that inlining will not eliminate
exceptions which would have occurred in its absence.
</long_desc>
</boolopt>
<boolopt>
<name>Insert Redundant Casts</name>
<alias>insert-redundant-casts</alias>
<default>true</default>
<short_desc/>
<long_desc>
<p>
Insert extra casts for the Java bytecode verifier. The verifier
may complain if the inlined method uses <tt>this</tt> and the
declared type of the receiver of the call being inlined is
different from the type implementing the target method being
inlined.</p>
<p>
Say, for example, that <tt>Singer</tt> is an interface declaring
the <tt>sing()</tt> method and that the call graph shows that all
receiver objects at a particular call site,
<tt>singer.sing()</tt> (with <tt>singer</tt> declared as a
<tt>Singer</tt>) are in fact <tt>Bird</tt> objects (<tt>Bird</tt>
being a class that implements <tt>Singer</tt>). The
implementation of <tt>Bird.sing()</tt> may perform operations on
<tt>this</tt> which are only allowed on <tt>Bird</tt>s, rather
than <tt>Singer</tt>s. The Insert Redundant Casts option ensures that
this cannot lead to verification errors, by inserting a cast of
<tt>bird</tt> to the <tt>Bird</tt> type before inlining the body
of <tt>Bird.sing()</tt>.</p>
</long_desc>
</boolopt>
<multiopt>
<name>Allowed Modifier Changes</name>
<alias>allowed-modifier-changes</alias>
<value>
<name>Unsafe</name>
<alias>unsafe</alias>
<short_desc/>
<long_desc>
Modify the visibility on code so that all inlining is permitted.
</long_desc>
<default/>
</value>
<value>
<name>Safe</name>
<alias>safe</alias>
<short_desc/>
<long_desc>
Preserve the exact meaning of the analyzed program.
</long_desc>
</value>
<value>
<name>None</name>
<alias>none</alias>
<short_desc/>
<long_desc>
Change no modifiers whatsoever.
</long_desc>
</value>
<short_desc/>
<long_desc>
Specify which changes in visibility modifiers
are allowed.
</long_desc>
</multiopt>
<flopt>
<name>Expansion Factor</name>
<alias>expansion-factor</alias>
<default>3</default>
<short_desc/>
<long_desc>
Determines the maximum allowed expansion of a method. Inlining
will cause the method to grow by a factor of no more than
the Expansion Factor.
</long_desc>
</flopt>
<intopt>
<name>Max Container Size</name>
<alias>max-container-size</alias>
<default>5000</default>
<short_desc/>
<long_desc>
Determines the maximum number of Jimple statements for a container
method. If a method has more than this number of Jimple statements,
then no methods will be inlined into it.
</long_desc>
</intopt>
<intopt>
<name>Max Inlinee Size</name>
<alias>max-inlinee-size</alias>
<default>20</default>
<short_desc/>
<long_desc>
Determines the maximum number of Jimple statements for an inlinee
method. If a method has more than this number of Jimple statements,
then it will not be inlined into other methods.
</long_desc>
</intopt>
</sub_phase>
</phase>
<phase>
<name>Whole-Jimple Annotation Pack</name>
<short_desc>Whole-jimple annotation pack: adds interprocedural tags</short_desc>
<alias>wjap</alias>
<long_desc>
<p>
Some analyses do not transform Jimple body directly, but annotate
statements or values with tags. Whole-Jimple annotation pack provides
a place for annotation-oriented analyses in whole program mode.</p>
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
</boolopt>
<sub_phase>
<name>Rectangular Array Finder</name>
<alias>wjap.ra</alias>
<short_desc>Rectangular array finder</short_desc>
<long_desc>
<p>
The Rectangular Array Finder traverses Jimple statements
based on the static call graph, and finds array variables which always
hold rectangular two-dimensional array objects.</p>
<p>
In Java, a multi-dimensional array is an array of arrays, which
means the shape of the array can be ragged. Nevertheless, many
applications use rectangular arrays. Knowing that an array is
rectangular can be very helpful in proving safe array bounds
checks.</p>
<p>
The Rectangular Array Finder does not change the
program being analyzed. Its results are used by the Array Bound
Checker.</p>
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>false</default>
</boolopt>
</sub_phase>
<sub_phase>
<name>Unreachable Method Tagger</name>
<alias>wjap.umt</alias>
<short_desc>Tags all unreachable methods</short_desc>
<long_desc><p>Uses the call graph to determine which methods are unreachable and adds color tags so they can be highlighted in a source browser.</p></long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>false</default>
</boolopt>
</sub_phase>
<sub_phase>
<name>Unreachable Fields Tagger</name>
<alias>wjap.uft</alias>
<short_desc>Tags all unreachable fields</short_desc>
<long_desc><p>Uses the call graph to determine which fields are unreachable and adds color tags so they can be highlighted in a source browser.</p></long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>false</default>
</boolopt>
</sub_phase>
<sub_phase>
<name>Tightest Qualifiers Tagger</name>
<alias>wjap.tqt</alias>
<short_desc>Tags all qualifiers that could be tighter</short_desc>
<long_desc><p>Determines which methods and fields have qualifiers that could be tightened. For example: if a field or method has the qualifier of public but is only used within the declaring class it could be private. This, this field or method is tagged with color tags so that the results can be highlighted in a source browser.</p></long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>false</default>
</boolopt>
</sub_phase>
<sub_phase>
<name>Call Graph Grapher</name>
<class>CGGOptions</class>
<alias>wjap.cgg</alias>
<short_desc>Creates graphical call graph.</short_desc>
<long_desc><p>Creates graphical call graph.</p></long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>false</default>
</boolopt>
<boolopt>
<name>Show Library Methods</name>
<alias>show-lib-meths</alias>
<default>false</default>
</boolopt>
</sub_phase>
<sub_phase>
<name>Purity Analysis [AM]</name>
<class>PurityOptions</class>
<alias>wjap.purity</alias>
<short_desc>Emit purity attributes</short_desc>
<long_desc>
Purity anaysis implemented by Antoine Mine and based on the paper
A Combined Pointer and Purity Analysis for Java Programs by
Alexandru Salcianu and Martin Rinard.
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>false</default>
</boolopt>
<boolopt>
<name>Dump one .dot files for each method summary</name>
<alias>dump-summaries</alias>
<default>true</default>
</boolopt>
<boolopt>
<name>Dump .dot call-graph annotated with method summaries (huge)</name>
<alias>dump-cg</alias>
<default>false</default>
</boolopt>
<boolopt>
<name>Dump one .dot for each intra-procedural method analysis (long)</name>
<alias>dump-intra</alias>
<default>false</default>
</boolopt>
<boolopt>
<name>Print analysis results</name>
<alias>print</alias>
<default>true</default>
</boolopt>
<boolopt>
<name>Annotate class files</name>
<short_desc>Marks pure methods with a purity bytecode attribute</short_desc>
<alias>annotate</alias>
<default>true</default>
</boolopt>
<boolopt>
<name>Be (quite) verbose</name>
<alias>verbose</alias>
<default>false</default>
</boolopt>
</sub_phase>
</phase>
<phase>
<name>Shimple Control</name>
<alias>shimple</alias>
<class>ShimpleOptions</class>
<short_desc>Sets parameters for Shimple SSA form</short_desc>
<long_desc>
<p>
Shimple Control sets parameters which apply throughout the
creation and manipulation of Shimple bodies. Shimple is Soot's
SSA representation.</p>
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
</boolopt>
<boolopt>
<name>Shimple Node Elimination Optimizations</name>
<alias>node-elim-opt</alias>
<short_desc>Node elimination optimizations</short_desc>
<default>true</default>
<long_desc>
<p>
Perform some optimizations, such as dead code elimination
and local aggregation, before/after eliminating nodes.
</p>
</long_desc>
</boolopt>
<boolopt>
<name>Local Name Standardization</name>
<alias>standard-local-names</alias>
<default>false</default>
<short_desc>Uses naming scheme of the Local Name
Standardizer.</short_desc>
<long_desc>
If enabled, the Local Name Standardizer is applied whenever
Shimple creates new locals. Normally, Shimple will retain
the original local names as far as possible and use an
underscore notation to denote SSA subscripts. This
transformation does not otherwise affect Shimple
behaviour.
</long_desc>
</boolopt>
<boolopt>
<name>Extended SSA (SSI)</name>
<alias>extended</alias>
<default>false</default>
<short_desc>Compute extended SSA (SSI) form.</short_desc>
<long_desc>
If enabled, Shimple will created extended SSA (SSI) form.
</long_desc>
</boolopt>
<boolopt>
<name>Debugging Output</name>
<alias>debug</alias>
<default>false</default>
<short_desc>Enables debugging output, if any.</short_desc>
<long_desc>
If enabled, Soot may print out warnings and messages
useful for debugging the Shimple module. Automatically
enabled by the global debug switch.
</long_desc>
</boolopt>
</phase>
<phase>
<name>Shimple Transformation Pack</name>
<alias>stp</alias>
<short_desc>Shimple transformation pack</short_desc>
<long_desc>
<p>
When the Shimple representation is produced, Soot applies the
contents of the Shimple Transformation Pack to each method
under analysis. This pack contains no transformations in an
unmodified version of Soot.
</p>
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
</boolopt>
</phase>
<phase>
<name>Shimple Optimization Pack</name>
<alias>sop</alias>
<short_desc>Shimple optimization pack</short_desc>
<long_desc>
<p>
The Shimple Optimization Pack contains transformations that
perform optimizations on Shimple, Soot's SSA
representation.
</p>
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>false</default>
</boolopt>
<sub_phase>
<name>Shimple Constant Propagator and Folder</name>
<short_desc>Shimple constant propagator and folder</short_desc>
<long_desc>
<p>
A powerful constant propagator and folder based on an
algorithm sketched by Cytron et al that takes
conditional control flow into account. This
optimization demonstrates some of the benefits of SSA
-- particularly the fact that Phi nodes represent
natural merge points in the control flow.
</p>
</long_desc>
<alias>sop.cpf</alias>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
</boolopt>
<boolopt>
<name>Prune Control Flow Graph</name>
<alias>prune-cfg</alias>
<default>true</default>
<short_desc>Take advantage of CFG optimization
opportunities.</short_desc>
<long_desc>
<p>
Conditional branching statements that are found to
branch unconditionally (or fall through) are replaced
with unconditional branches (or removed). This
transformation exposes more opportunities for dead
code removal.
</p>
</long_desc>
</boolopt>
</sub_phase>
</phase>
<phase>
<name>Jimple Transformation Pack</name>
<alias>jtp</alias>
<short_desc>Jimple transformation pack: intraprocedural analyses added to Soot</short_desc>
<long_desc>
Soot applies the contents of the Jimple Transformation Pack to
each method under analysis. This pack contains no
transformations in an unmodified version of Soot.
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
</boolopt>
</phase>
<phase>
<name>Jimple Optimization Pack</name>
<alias>jop</alias>
<short_desc>Jimple optimization pack (intraprocedural)</short_desc>
<long_desc>
When Soot's Optimize option is on, Soot applies the
Jimple Optimization Pack to every <tt>JimpleBody</tt> in
application classes. This section lists the default
transformations in the Jimple Optimization Pack.
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>false</default>
<short_desc>Eliminates common subexpressions</short_desc>
<long_desc/>
</boolopt>
<sub_phase>
<name>Common Subexpression Eliminator</name>
<alias>jop.cse</alias>
<short_desc>Common subexpression eliminator</short_desc>
<long_desc>
<p>
The Common Subexpression Eliminator runs an available expressions
analysis on the method body, then eliminates common
subexpressions.
</p>
<p>
This implementation is especially slow, as it runs on individual
statements rather than on basic blocks. A better implementation
(which would find most common subexpressions, but not all) would use
basic blocks instead.
</p>
<p>
This implementation is also slow because the flow universe is
explicitly created; it need not be. A better implementation
would implicitly compute the kill sets at every node.
</p>
<p>
Because of its current slowness, this transformation is not
enabled by default.
</p>
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>false</default>
<short_desc/>
<long_desc/>
</boolopt>
<boolopt>
<name>Naive Side Effect Tester</name>
<alias>naive-side-effect</alias>
<default>false</default>
<short_desc>Use naive side effect analysis even if interprocedural information is available</short_desc>
<long_desc>
<p>
If Naive Side Effect Tester is <tt>true</tt>, the Common
Subexpression Eliminator uses the conservative side effect
information provided by the <tt>NaiveSideEffectTester</tt> class,
even if interprocedural information about side effects is
available.</p>
<p>
The naive side effect analysis is based solely on the information
available locally about a statement. It assumes, for example,
that any method call has the potential to write and read all
instance and static fields in the program.</p>
<p>
If Naive Side Effect Tester is set to <tt>false</tt> and Soot is
in whole program mode, then the Common Subexpression
Eliminator uses the side effect information provided by the
<tt>PASideEffectTester</tt> class. <tt>PASideEffectTester</tt>
uses a points-to analysis to
determine which fields and statics may be written or read by a
given statement.</p>
<p>
If whole program analysis is not performed, naive side effect
information is used regardless of the setting of
Naive Side Effect Tester.
</p>
</long_desc>
</boolopt>
</sub_phase>
<sub_phase>
<name>Busy Code Motion</name>
<alias>jop.bcm</alias>
<class>BCMOptions</class>
<short_desc>Busy code motion: unaggressive partial redundancy elimination</short_desc>
<long_desc>
Busy Code Motion is a straightforward implementation of Partial
Redundancy Elimination. This implementation is not very
aggressive. Lazy Code Motion is an improved version which
should be used instead of Busy Code Motion.
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>false</default>
<short_desc/>
<long_desc/>
</boolopt>
<boolopt>
<name>Naive Side Effect Tester</name>
<alias>naive-side-effect</alias>
<default>false</default>
<short_desc>Use a naive side effect analysis even if interprocedural information is available</short_desc>
<long_desc>
<p>
If Naive Side Effect Tester is set to <tt>true</tt>, Busy Code
Motion uses the conservative side effect information provided by
the <tt>NaiveSideEffectTester</tt> class, even if interprocedural
information about side effects is available.</p>
<p>
The naive side effect analysis is based solely on the information
available locally about a statement. It assumes, for example,
that any method call has the potential to write and read all
instance and static fields in the program.</p>
<p>
If Naive Side Effect Tester is set to <tt>false</tt> and Soot is
in whole program mode, then Busy Code Motion uses the side effect
information provided by the <tt>PASideEffectTester</tt>
class. <tt>PASideEffectTester</tt> uses a points-to analysis to
determine which fields and statics may be written or read by a
given statement.</p>
<p>
If whole program analysis is not performed, naive side effect
information is used regardless of the setting of
Naive Side Effect Tester.
</p>
</long_desc>
</boolopt>
</sub_phase>
<sub_phase>
<name>Lazy Code Motion</name>
<class>LCMOptions</class>
<alias>jop.lcm</alias>
<short_desc>Lazy code motion: aggressive partial redundancy elimination</short_desc>
<long_desc>
Lazy Code Motion is an enhanced version of Busy Code Motion, a
Partial Redundancy Eliminator. Before doing Partial Redundancy Elimination,
this optimization performs loop inversion (turning <tt>while</tt> loops
into <tt>do while</tt> loops inside an <tt>if</tt> statement).
This allows the Partial Redundancy Eliminator
to optimize loop invariants of <tt>while</tt> loops.
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>false</default>
<short_desc/>
<long_desc/>
</boolopt>
<multiopt>
<name>Safety</name>
<alias>safety</alias>
<value>
<name>Safe</name>
<alias>safe</alias>
<short_desc/>
<long_desc>
Safe, but only considers moving additions,
subtractions and multiplications.
</long_desc>
<default/>
</value>
<value>
<name>Medium</name>
<alias>medium</alias>
<short_desc/>
<long_desc>
Unsafe in multi-threaded programs, as it may reuse the values
read from field accesses.
</long_desc>
</value>
<value>
<name>Unsafe</name>
<alias>unsafe</alias>
<short_desc/>
<long_desc>
May violate Java's exception semantics, as it may move or reorder
exception-throwing statements, potentially outside of
<tt>try-catch</tt> blocks.
</long_desc>
</value>
<short_desc/>
<long_desc>
This option controls which fields and statements are candidates
for code motion.
</long_desc>
</multiopt>
<boolopt>
<name>Unroll</name>
<alias>unroll</alias>
<short_desc/>
<long_desc>
If <tt>true</tt>, perform loop inversion before doing the
transformation.
</long_desc>
<default>true</default>
</boolopt>
<boolopt>
<name>Naive Side Effect Tester</name>
<alias>naive-side-effect</alias>
<default>false</default>
<short_desc>Use a naive side effect analysis even if interprocedural information is available</short_desc>
<long_desc>
<p>
If Naive Side Effect Tester is set to <tt>true</tt>, Lazy Code
Motion uses the conservative side effect information provided by
the <tt>NaiveSideEffectTester</tt> class, even if interprocedural
information about side effects is available.</p>
<p>
The naive side effect analysis is based solely on the information
available locally about a statement. It assumes, for example,
that any method call has the potential to write and read all
instance and static fields in the program.</p>
<p>
If Naive Side Effect Tester is set to <tt>false</tt> and Soot is
in whole program mode, then Lazy Code Motion uses the side effect
information provided by the <tt>PASideEffectTester</tt>
class. <tt>PASideEffectTester</tt> uses a points-to analysis to
determine which fields and statics may be written or read by a
given statement.</p>
<p>
If whole program analysis is not performed, naive side effect
information is used regardless of the setting of
Naive Side Effect Tester.
</p>
</long_desc>
</boolopt>
</sub_phase>
<sub_phase>
<name>Copy Propagator</name>
<class>CPOptions</class>
<alias>jop.cp</alias>
<short_desc>Copy propagator</short_desc>
<long_desc>
<p>
This phase performs cascaded copy propagation.</p>
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
<short_desc/>
<long_desc/>
</boolopt>
<boolopt>
<name>Only Regular Locals</name>
<alias>only-regular-locals</alias>
<default>false</default>
<short_desc/>
<long_desc>
Only propagate copies through ``regular'' locals, that is,
those declared in the source bytecode.
</long_desc>
</boolopt>
<boolopt>
<name>Only Stack Locals</name>
<alias>only-stack-locals</alias>
<default>false</default>
<short_desc/>
<long_desc>
Only propagate copies through locals that represent stack locations in
the original bytecode.
</long_desc>
</boolopt>
</sub_phase>
<sub_phase>
<name>Jimple Constant Propagator and Folder</name>
<alias>jop.cpf</alias>
<short_desc>Constant propagator and folder</short_desc>
<long_desc>
The Jimple Constant Propagator and Folder evaluates any expressions
consisting entirely of compile-time constants, for example <tt>2
* 3</tt>, and replaces the expression with the constant result,
in this case <tt>6</tt>.
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
</boolopt>
</sub_phase>
<sub_phase>
<name>Conditional Branch Folder</name>
<alias>jop.cbf</alias>
<short_desc>Conditional branch folder</short_desc>
<long_desc>
The Conditional Branch Folder statically evaluates the
conditional expression of Jimple <tt>if</tt> statements. If the
condition is identically <tt>true</tt> or
<tt>false</tt>, the Folder replaces the conditional branch
statement with an unconditional <tt>goto</tt> statement.
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
<short_desc/>
<long_desc/>
</boolopt>
</sub_phase>
<sub_phase>
<name>Dead Assignment Eliminator</name>
<alias>jop.dae</alias>
<short_desc>Dead assignment eliminator</short_desc>
<long_desc>
The Dead Assignment Eliminator eliminates assignment statements
to locals whose values are not subsequently used, unless
evaluating the right-hand side of the assignment may cause
side-effects.
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
<short_desc/>
<long_desc/>
</boolopt>
<boolopt>
<name>Only Tag Dead Code</name>
<alias>only-tag</alias>
<default>false</default>
<short_desc/>
<long_desc>
Only tag dead assignment statements instead of eliminaing them.
</long_desc>
</boolopt>
<boolopt>
<name>Only Stack Locals</name>
<alias>only-stack-locals</alias>
<default>false</default>
<short_desc/>
<long_desc>
Only eliminate dead assignments to locals that represent stack
locations in the original bytecode.
</long_desc>
</boolopt>
</sub_phase>
<sub_phase>
<name>Null Check Eliminator</name>
<alias>jop.nce</alias>
<short_desc>Null Check Eliminator</short_desc>
<long_desc>
Replaces statements 'if(x!=null) goto y' with 'goto y' if x is
known to be non-null or with 'nop' if it is known to be null,
etc. Generates dead code and is hence followed by unreachable
code elimination. Disabled by default because it can be
expensive on methods with many locals.
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>false</default>
<short_desc/>
<long_desc/>
</boolopt>
</sub_phase>
<sub_phase>
<name>Unreachable Code Eliminator 1</name>
<alias>jop.uce1</alias>
<short_desc>Unreachable code eliminator, pass 1</short_desc>
<long_desc>
The Unreachable Code Eliminator removes unreachable code and
traps whose catch blocks are empty.
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
<short_desc/>
<long_desc/>
</boolopt>
<boolopt>
<name>Remove unreachable traps</name>
<alias>remove-unreachable-traps</alias>
<default>false</default>
<long_desc>
Remove exception table entries when none of the protected instructions can
throw the exception being caught.
</long_desc>
</boolopt>
</sub_phase>
<sub_phase>
<name>Unconditional Branch Folder 1</name>
<alias>jop.ubf1</alias>
<short_desc>Unconditional branch folder, pass 1</short_desc>
<long_desc>
<p>
The Unconditional Branch Folder removes unnecessary `<tt>goto</tt>'
statements from a <tt>JimpleBody</tt>.</p>
<p>
If a <tt>goto</tt> statement's target is the next instruction,
then the statement is removed. If a <tt>goto</tt>'s target is
another <tt>goto</tt>, with target <tt>y</tt>, then the first
statement's target is changed to <tt>y</tt>.</p>
<p>
If some <tt>if</tt> statement's target is a <tt>goto</tt>
statement, then the <tt>if</tt>'s target can be replaced with the
<tt>goto</tt>'s target.</p>
<p>
(These situations can result from other optimizations, and branch
folding may itself generate more unreachable code.)</p>
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
<short_desc/>
<long_desc/>
</boolopt>
</sub_phase>
<sub_phase>
<name>Unreachable Code Eliminator 2</name>
<alias>jop.uce2</alias>
<short_desc>Unreachable code eliminator, pass 2</short_desc>
<long_desc>
Another iteration of the Unreachable Code Eliminator.
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
<short_desc/>
<long_desc/>
</boolopt>
<boolopt>
<name>Remove unreachable traps</name>
<alias>remove-unreachable-traps</alias>
<default>false</default>
<long_desc>
Remove exception table entries when none of the protected instructions can
throw the exception being caught.
</long_desc>
</boolopt>
</sub_phase>
<sub_phase>
<name>Unconditional Branch Folder 2</name>
<alias>jop.ubf2</alias>
<short_desc>Unconditional branch folder, pass 2</short_desc>
<long_desc>
Another iteration of the Unconditional Branch Folder.
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
<short_desc/>
<long_desc/>
</boolopt>
</sub_phase>
<sub_phase>
<name>Unused Local Eliminator</name>
<alias>jop.ule</alias>
<short_desc>Unused local eliminator</short_desc>
<long_desc>
The Unused Local Eliminator phase removes any unused locals from
the method.
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
<short_desc/>
<long_desc/>
</boolopt>
</sub_phase>
</phase>
<phase>
<name>Jimple Annotation Pack</name>
<alias>jap</alias>
<short_desc>Jimple annotation pack: adds intraprocedural tags</short_desc>
<long_desc>
The Jimple Annotation Pack contains phases which add annotations
to Jimple bodies individually (as opposed to the Whole-Jimple
Annotation Pack, which adds annotations based on the analysis of
the whole program).
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
</boolopt>
<sub_phase>
<name>Null Pointer Checker</name>
<class>NPCOptions</class>
<alias>jap.npc</alias>
<short_desc>Null pointer checker</short_desc>
<long_desc>
The Null Pointer Checker finds instruction which have the potential
to throw <tt>NullPointerException</tt>s and adds annotations
indicating whether or not the pointer being dereferenced can be
determined statically not to be null.
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>false</default>
<short_desc/>
<long_desc/>
</boolopt>
<boolopt>
<name>Only Array Ref</name>
<alias>only-array-ref</alias>
<default>false</default>
<short_desc>Annotate only array references</short_desc>
<long_desc>
Annotate only array-referencing instructions, instead of all
instructions that need null pointer checks.
</long_desc>
</boolopt>
<boolopt>
<name>Profiling</name>
<alias>profiling</alias>
<default>false</default>
<short_desc>Insert instructions to count safe pointer accesses</short_desc>
<long_desc>
<p>
Insert profiling instructions that at runtime count the number of
eliminated safe null pointer checks. The inserted profiling code
assumes the existence of a <tt>MultiCounter</tt> class
implementing the methods invoked. For details, see the
<tt>NullPointerChecker</tt> source code.</p>
</long_desc>
</boolopt>
</sub_phase>
<sub_phase>
<name>Null Pointer Colourer</name>
<alias>jap.npcolorer</alias>
<default>true</default>
<short_desc>Null pointer colourer: tags references for eclipse</short_desc>
<long_desc>
Produce colour tags that the Soot plug-in for Eclipse can use to
highlight null and non-null references.
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>false</default>
<long_desc></long_desc>
</boolopt>
</sub_phase>
<sub_phase>
<name>Array Bound Checker</name>
<class>ABCOptions</class>
<alias>jap.abc</alias>
<short_desc>Array bound checker</short_desc>
<long_desc>
<p>
The Array Bound Checker performs a static analysis to determine
which array bounds checks may safely be eliminated and then annotates
statements with the results of the analysis.</p>
<p>
If Soot is in whole-program mode, the Array Bound Checker can
use the results provided by the Rectangular Array Finder.</p>
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>false</default>
<short_desc/>
<long_desc/>
</boolopt>
<boolopt>
<name>With All</name>
<alias>with-all</alias>
<default>false</default>
<short_desc/>
<long_desc>
<p>
Setting the With All option to true is equivalent to setting each
of With CSE, With Array Ref, With Field Ref,
With Class Field, and With Rectangular Array to true.</p>
</long_desc>
</boolopt>
<boolopt>
<name>With Common Sub-expressions</name>
<alias>with-cse</alias>
<default>false</default>
<short_desc/>
<long_desc>
<p>
The analysis will consider common subexpressions. For example,
consider the situation where <tt>r1</tt> is assigned
<tt>a*b</tt>; later, <tt>r2</tt> is assigned <tt>a*b</tt>, where
neither <tt>a</tt> nor <tt>b</tt> have changed between the two
statements. The analysis can conclude that <tt>r2</tt> has the
same value as <tt>r1</tt>. Experiments show that this option can
improve the result slightly.</p>
</long_desc>
</boolopt>
<boolopt>
<name>With Array References</name>
<alias>with-arrayref</alias>
<default>false</default>
<short_desc/>
<long_desc>
<p>
With this option enabled, array references can be considered as
common subexpressions; however, we are more conservative when
writing into an array, because array objects may be aliased. We
also assume that the application is single-threaded or that the
array references occur in a synchronized block. That is, we
assume that an array element may not be changed by other threads
between two array references.</p>
</long_desc>
</boolopt>
<boolopt>
<name>With Field References</name>
<alias>with-fieldref</alias>
<default>false</default>
<short_desc/>
<long_desc>
<p>
The analysis treats field references (static and instance) as
common subexpressions; however, we are more conservative when
writing to a field, because the base of the field reference may
be aliased. We also assume that the application is
single-threaded or that the field references occur in a
synchronized block. That is, we assume that a field may
not be changed by other threads between two field references.</p>
</long_desc>
</boolopt>
<boolopt>
<name>With Class Field</name>
<alias>with-classfield</alias>
<default>false</default>
<short_desc/>
<long_desc>
<p>
This option makes the analysis work on the class level. The
algorithm analyzes <tt>final</tt> or <tt>private</tt> class
fields first. It can recognize the fields that hold array objects
of constant length. In an application using lots of array
fields, this option can improve the analysis results
dramatically.</p>
</long_desc>
</boolopt>
<boolopt>
<name>With Rectangular Array</name>
<alias>with-rectarray</alias>
<default>false</default>
<short_desc/>
<long_desc>
This option is used together with <tt>wjap.ra</tt> to make Soot run the whole-program
analysis for rectangular array objects. This analysis is based on the
call graph, and it usually takes a long time. If the application uses
rectangular arrays, these options can improve the analysis
result.
</long_desc>
</boolopt>
<boolopt>
<name>Profiling</name>
<alias>profiling</alias>
<default>false</default>
<short_desc>Profile the results of array bounds check analysis.</short_desc>
<long_desc>
<p>
Profile the results of array bounds check analysis. The inserted
profiling code assumes the existence of a <tt>MultiCounter</tt>
class implementing the methods invoked. For details, see the
<tt>ArrayBoundsChecker</tt> source code.</p>
</long_desc>
</boolopt>
<boolopt>
<name>Add Color Tags</name>
<alias>add-color-tags</alias>
<default>false</default>
<short_desc>Add color tags to results of array bound check analysis.</short_desc>
<long_desc>Add color tags to the results of the array bounds check analysis.</long_desc>
</boolopt>
</sub_phase>
<sub_phase>
<name>Profiling Generator</name>
<alias>jap.profiling</alias>
<class>ProfilingOptions</class>
<short_desc>Instruments null pointer and array checks</short_desc>
<long_desc>
<p>
The Profiling Generator inserts the method invocations required
to initialize and to report the results of any profiling
performed by the Null Pointer Checker and Array Bound
Checker. Users of the Profiling Generator must provide a
<tt>MultiCounter</tt> class implementing the methods invoked. For
details, see the <tt>ProfilingGenerator</tt> source code.
</p>
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>false</default>
<short_desc/>
<long_desc/>
</boolopt>
<boolopt>
<name>Not Main Entry</name>
<alias>notmainentry</alias>
<default>false</default>
<short_desc>Instrument <tt>runBenchmark()</tt> instead of <tt>main()</tt></short_desc>
<long_desc>
<p>
Insert the calls to the <tt>MultiCounter</tt> at the
beginning and end of methods with the signature
<tt>long runBenchmark(java.lang.String[])</tt>
instead of the signature
<tt>void main(java.lang.String[])</tt>.</p>
</long_desc>
</boolopt>
</sub_phase>
<sub_phase>
<name>Side Effect tagger</name>
<alias>jap.sea</alias>
<class>SETOptions</class>
<short_desc>Side effect tagger</short_desc>
<long_desc>
<p>
The Side Effect Tagger
uses the active invoke graph to produce side-effect attributes, as
described in the <a
href="http://www.sable.mcgill.ca/publications/thesis/#olhotakMastersThesis">Spark
thesis</a>, chapter 6.</p>
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>false</default>
<short_desc/>
<long_desc/>
</boolopt>
<boolopt>
<name>Build naive dependence graph</name>
<alias>naive</alias>
<default>false</default>
<short_desc/>
<long_desc>
<p>
When set to true, the dependence graph is built with a node for
each statement, without merging the nodes for equivalent
statements. This makes it possible to measure the effect of
merging nodes for equivalent statements on the size of the
dependence graph.</p>
</long_desc>
</boolopt>
</sub_phase>
<sub_phase>
<name>Field Read/Write Tagger</name>
<class>FRWOptions</class>
<alias>jap.fieldrw</alias>
<short_desc>Field read/write tagger</short_desc>
<long_desc>
<p>
The Field Read/Write Tagger uses the active invoke graph to
produce tags indicating which fields may be read or written by
each statement, including invoke statements.</p>
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>false</default>
<short_desc/>
<long_desc/>
</boolopt>
<intopt>
<name>Maximum number of fields</name>
<alias>threshold</alias>
<default>100</default>
<short_desc/>
<long_desc>
If a statement reads/writes more than this number of fields, no tag will be
produced for it, in order to keep the size of the tags reasonable.
</long_desc>
</intopt>
</sub_phase>
<sub_phase>
<name>Call Graph Tagger</name>
<alias>jap.cgtagger</alias>
<short_desc>Call graph tagger</short_desc>
<long_desc>
The Call Graph Tagger produces LinkTags based on the call
graph. The Eclipse plugin uses these tags to produce
linked popup lists which indicate the source and target methods
of the statement. Selecting a link from the list moves the
cursor to the indicated method.
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>false</default>
</boolopt>
</sub_phase>
<sub_phase>
<name>Parity Tagger</name>
<alias>jap.parity</alias>
<short_desc>Parity tagger</short_desc>
<long_desc>
The Parity Tagger produces StringTags and ColorTags indicating
the parity of a variable (even, odd, top, or bottom). The eclipse
plugin can use tooltips and variable colouring to display the
information in these tags. For example, even variables (such as
<tt>x</tt> in <tt>x = 2</tt>) are coloured yellow.
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>false</default>
</boolopt>
</sub_phase>
<sub_phase>
<name>Parameter Alias Tagger</name>
<alias>jap.pat</alias>
<short_desc>Colour-codes method parameters that may be aliased</short_desc>
<long_desc>For each method with parameters of reference type, this tagger indicates the aliasing relationships between the parameters using colour tags. Parameters that may be aliased are the same colour. Parameters that may not be aliased are in different colours.</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>false</default>
</boolopt>
</sub_phase>
<sub_phase>
<name>Live Variables Tagger</name>
<alias>jap.lvtagger</alias>
<short_desc>Creates color tags for live variables</short_desc>
<long_desc>Colors live variables.</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>false</default>
</boolopt>
</sub_phase>
<sub_phase>
<name>Reaching Defs Tagger</name>
<alias>jap.rdtagger</alias>
<short_desc>Creates link tags for reaching defs</short_desc>
<long_desc>For each use of a local in a stmt creates a link to the reaching def.</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>false</default>
</boolopt>
</sub_phase>
<sub_phase>
<name>Cast Elimination Check Tagger</name>
<alias>jap.che</alias>
<short_desc>Indicates whether cast checks can be eliminated</short_desc>
<long_desc>Indicates whether cast checks can be eliminated.</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>false</default>
</boolopt>
</sub_phase>
<sub_phase>
<name>Unreachable Method Transformer</name>
<alias>jap.umt</alias>
<short_desc>Inserts assertions into unreachable methods</short_desc>
<long_desc>When the whole-program analysis determines a method to be unreachable, this transformer inserts an assertion into the method to check that it is indeed unreachable.</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>false</default>
</boolopt>
</sub_phase>
<sub_phase>
<name>Loop Invariant Tagger</name>
<alias>jap.lit</alias>
<short_desc>Tags loop invariants</short_desc>
<long_desc>An expression whose operands are constant or have reaching definitions from outside the loop body are tagged as loop invariant.</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>false</default>
</boolopt>
</sub_phase>
<sub_phase>
<name>Available Expressions Tagger</name>
<class>AETOptions</class>
<alias>jap.aet</alias>
<short_desc>Tags statements with sets of available expressions</short_desc>
<long_desc>A each statement a set of available expressions is after the statement is added as a tag.</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>false</default>
</boolopt>
<multiopt>
<name>Kind</name>
<alias>kind</alias>
<value>
<name>Optimistic</name>
<alias>optimistic</alias>
<default/>
</value>
<value>
<name>Pessimistic</name>
<alias>pessimistic</alias>
</value>
</multiopt>
</sub_phase>
<sub_phase>
<name>Dominators Tagger</name>
<alias>jap.dmt</alias>
<short_desc>Tags dominators of statement</short_desc>
<long_desc>Provides link tags at a statement to all of the satements dominators.</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>false</default>
</boolopt>
</sub_phase>
</phase>
<!--<phase>
<name>CFG Viewer</name>
<alias>cfg</alias>
<short_desc>Produces CFGs for viewing purposes</short_desc>
<long_desc>Produces CFGs in the form of dot files when run from the command line runs or graphs when run from within Eclipse.</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>false</default>
<short_desc/>
<long_desc/>
</boolopt>
<sub_phase>
<name>CFG Output Options</name>
<class>CFGOutputOptions</class>
<alias>cfg.output</alias>
<short_desc>Determines the type of graphs to output</short_desc>
<long_desc>Determines the type of graphs to output</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>false</default>
<short_desc/>
<long_desc/>
</boolopt>
<multiopt>
<name>Graph Type</name>
<alias>graph-type</alias>
<short_desc>Determines which type of graph to output</short_desc>
<long_desc>Determines which type of graph to output based on whether nodes are units or blocks and whether control flow associated with Exceptions is taken into consideration or not.</long_desc>
<value>
<name>Complete Unit Graph</name>
<alias>complete-unit-graph</alias>
<short_desc>Output a complete Unit Graph</short_desc>
<long_desc>Output a complete Unit Graph, where nodes are units and control flow associated with Exceptions is taken into account.</long_desc>
<default/>
</value>
<value>
<name>Unit Graph</name>
<alias>unit-graph</alias>
<short_desc>Output a Unit Graph</short_desc>
<long_desc>Output a Unit Graph, where nodes are units and control flow associated with Exceptions is not taken into account.</long_desc>
</value>
<value>
<name>Complete Block Graph</name>
<alias>complete-block-graph</alias>
<short_desc>Output a complete Block Graph</short_desc>
<long_desc>Output a complete Block Graph, where nodes are blocks and control flow associated with Exceptions is taken into account.</long_desc>
</value>
<value>
<name>Brief Block Graph</name>
<alias>brief-block-graph</alias>
<short_desc>Output a brief Block Graph</short_desc>
<long_desc>Output a brief Block Graph, where nodes are blocks and control flow associated with Exceptions is ignored.</long_desc>
</value>
<value>
<name>Array Block Graph</name>
<alias>array-block-graph</alias>
<short_desc>Output an array Block Graph</short_desc>
<long_desc>Output an array Block Graph</long_desc>
</value>
</multiopt>
<multiopt>
<name>Output Type</name>
<alias>output-type</alias>
<short_desc>Determines which type of files to generate</short_desc>
<long_desc>Determines which type of files to generate</long_desc>
<value>
<name>Dot Files</name>
<alias>dot-files</alias>
<short_desc>Generate graphs as dot files</short_desc>
<long_desc>Generate graphs as dot files that can be then be converted to post-script for viewing.</long_desc>
</value>
<value>
<name>Eclipse Graphs</name>
<alias>eclipse-graphs</alias>
<short_desc>Generate graphs that can be manipulated within Eclipse</short_desc>
<long_desc>Generate graphs that can be manipulated within Eclipse.</long_desc>
</value>
</multiopt>
</sub_phase>
</phase>-->
<phase>
<name>Grimp Body Creation</name>
<alias>gb</alias>
<short_desc>Creates a GrimpBody for each method</short_desc>
<long_desc>
The Grimp Body Creation phase creates a <tt>GrimpBody</tt> for
each source method. It is run only if the output format is
<tt>grimp</tt> or <tt>grimple</tt>, or if class files are being
output and the Via Grimp option has been specified.
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
<short_desc/>
<long_desc/>
</boolopt>
<sub_phase>
<name>Grimp Pre-folding Aggregator</name>
<alias>gb.a1</alias>
<short_desc>Aggregator: removes some copies, pre-folding</short_desc>
<long_desc>
The Grimp Pre-folding Aggregator combines some local variables,
finding definitions with only a single use and removing the
definition after replacing the use with the definition's
right-hand side, if it is safe to do so. While the mechanism is
the same as that employed by the Jimple Local Aggregator, there
is more scope for aggregation because of Grimp's more complicated
expressions.
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
<short_desc/>
<long_desc/>
</boolopt>
<boolopt>
<name>Only Stack Locals</name>
<alias>only-stack-locals</alias>
<default>true</default>
<short_desc/>
<long_desc>
Aggregate only values stored in stack locals.
</long_desc>
</boolopt>
</sub_phase>
<sub_phase>
<name>Grimp Constructor Folder</name>
<alias>gb.cf</alias>
<short_desc>Constructor folder</short_desc>
<long_desc>
The Grimp Constructor Folder combines <tt>new</tt> statements
with the <tt>specialinvoke</tt> statement that calls the new
object's constructor. For example, it turns
<pre>
r2 = new java.util.ArrayList;
r2.<lt/>init<gt/>();
</pre>
into
<pre>
r2 = new java.util.ArrayList();
</pre>
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
</boolopt>
</sub_phase>
<sub_phase>
<name>Grimp Post-folding Aggregator</name>
<alias>gb.a2</alias>
<short_desc>Aggregator: removes some copies, post-folding</short_desc>
<long_desc>
The Grimp Post-folding Aggregator combines local variables after
constructors have been folded. Constructor folding typically
introduces new opportunities for aggregation, since when a
sequence of instructions like
<pre>
r2 = new java.util.ArrayList;
r2.<lt/>init<gt/>();
r3 = r2
</pre>is replaced by
<pre>
r2 = new java.util.ArrayList();
r3 = r2
</pre>the invocation of <tt><lt/>init<gt/></tt> no longer represents a potential side-effect
separating the two definitions, so they can be combined into
<pre>
r3 = new java.util.ArrayList();
</pre>(assuming there are no subsequent uses of <tt>r2</tt>).
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
<short_desc/>
<long_desc/>
</boolopt>
<boolopt>
<name>Only Stack Locals</name>
<alias>only-stack-locals</alias>
<default>true</default>
<short_desc/>
<long_desc>
Aggregate only values stored in stack locals.
</long_desc>
</boolopt>
</sub_phase>
<sub_phase>
<name>Grimp Unused Local Eliminator</name>
<alias>gb.ule</alias>
<short_desc>Unused local eliminator</short_desc>
<long_desc>
This phase removes any locals that are unused after constructor
folding and aggregation.
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
</boolopt>
</sub_phase>
</phase>
<phase>
<name>Grimp Optimization</name>
<alias>gop</alias>
<short_desc>Grimp optimization pack</short_desc>
<long_desc>
The Grimp Optimization pack performs optimizations on
<tt>GrimpBody</tt>s (currently there are no optimizations
performed specifically on <tt>GrimpBody</tt>s, and the pack is
empty). It is run only if the output format is <tt>grimp</tt> or
<tt>grimple</tt>, or if class files are being output and the Via
Grimp option has been specified.
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>false</default>
</boolopt>
</phase>
<phase>
<name>Baf Body Creation</name>
<alias>bb</alias>
<short_desc>Creates Baf bodies</short_desc>
<long_desc>
The Baf Body Creation phase creates a
<tt>BafBody</tt> from each source method. It is
run if the output format is <tt>baf</tt> or <tt>b</tt>, or
if class files are being output and the Via Grimp option
has not been specified.
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
</boolopt>
<sub_phase>
<name>Load Store Optimizer</name>
<alias>bb.lso</alias>
<short_desc>Load store optimizer</short_desc>
<long_desc>
The Load Store Optimizer replaces some combinations of loads to and stores from local variables with stack instructions. A simple example would be the replacement of
<pre>
store.r $r2;
load.r $r2;
</pre>
with
<pre>
dup1.r
</pre>
in cases where the value of <tt><dollar/>r2</tt> is not used subsequently.
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
</boolopt>
<boolopt>
<name>Debug</name>
<alias>debug</alias>
<default>false</default>
<long_desc>
Produces voluminous debugging output describing the progress of
the load store optimizer.
</long_desc>
</boolopt>
<boolopt>
<name>Inter</name>
<alias>inter</alias>
<default>false</default>
<long_desc>
Enables two simple inter-block optimizations which attempt to
keep some variables on the stack between blocks. Both are
intended to catch <tt>if</tt>-like constructions where control
flow branches temporarily into two paths that converge at a later
point.
</long_desc>
</boolopt>
<boolopt>
<name>sl</name>
<alias>sl</alias>
<default>true</default>
<long_desc>
Enables an optimization which attempts to eliminate
<tt>store</tt>/<tt>load</tt> pairs.
</long_desc>
</boolopt>
<boolopt>
<name>sl2</name>
<alias>sl2</alias>
<default>false</default>
<long_desc>
Enables an a second pass of the optimization which attempts to
eliminate <tt>store</tt>/<tt>load</tt> pairs.
</long_desc>
</boolopt>
<boolopt>
<name>sll</name>
<alias>sll</alias>
<default>true</default>
<long_desc>
Enables an optimization which attempts to eliminate
<tt>store</tt>/<tt>load</tt>/<tt>load</tt>
trios with some variant of <tt>dup</tt>.
</long_desc>
</boolopt>
<boolopt>
<name>sll2</name>
<alias>sll2</alias>
<default>false</default>
<long_desc>
Enables an a second pass of the optimization which attempts to
eliminate <tt>store</tt>/<tt>load</tt>/<tt>load</tt> trios with
some variant of <tt>dup</tt>.
</long_desc>
</boolopt>
</sub_phase>
<sub_phase>
<name>Peephole Optimizer</name>
<alias>bb.pho</alias>
<short_desc>Peephole optimizer</short_desc>
<long_desc>
Applies peephole optimizations to the Baf intermediate
representation. Individual optimizations must be implemented by
classes implementing the <tt>Peephole</tt> interface. The
Peephole Optimizer reads the names of the <tt>Peephole</tt>
classes at runtime from the file <tt>peephole.dat</tt> and loads
them dynamically. Then it continues to apply the
<tt>Peephole</tt>s repeatedly until none of them are able to
perform any further optimizations.
<p>
Soot provides only one <tt>Peephole</tt>, named
<tt>ExamplePeephole</tt>, which is not enabled by the delivered
<tt>peephole.dat</tt> file.
<tt>ExamplePeephole</tt> removes all <tt>checkcast</tt>
instructions.</p>
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
</boolopt>
</sub_phase>
<sub_phase>
<name>Unused Local Eliminator</name>
<alias>bb.ule</alias>
<short_desc>Unused local eliminator</short_desc>
<long_desc>
This phase removes any locals that are unused after load store optimization
and peephole optimization.
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
</boolopt>
</sub_phase>
<sub_phase>
<name>Local Packer</name>
<alias>bb.lp</alias>
<short_desc>Local packer: minimizes number of locals</short_desc>
<long_desc>
The Local Packer attempts to minimize the number of local
variables required in a method by reusing the same variable for
disjoint DU-UD webs. Conceptually, it is the inverse of the
Local Splitter.
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
</boolopt>
<boolopt>
<name>Unsplit Original Locals</name>
<alias>unsplit-original-locals</alias>
<default>false</default>
<long_desc>
Use the variable names in the original source as a guide when
determining how to share local variables across non-interfering
variable usages. This recombines named locals which were split by
the Local Splitter.
</long_desc>
</boolopt>
</sub_phase>
</phase>
<phase>
<name>Baf Optimization</name>
<alias>bop</alias>
<short_desc>Baf optimization pack</short_desc>
<long_desc>
The Baf Optimization pack performs optimizations on
<tt>BafBody</tt>s (currently there are no optimizations performed
specifically on <tt>BafBody</tt>s, and the pack is empty). It is
run only if the output format is <tt>baf</tt> or <tt>b</tt>, or
if class files are being output and the Via Grimp option
has not been specified.
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>false</default>
</boolopt>
</phase>
<phase>
<name>Tag Aggregator</name>
<alias>tag</alias>
<short_desc>Tag aggregator: turns tags into attributes</short_desc>
<long_desc>
<p>
The Tag Aggregator pack aggregates tags attached to individual units
into a code attribute for each method, so that these attributes can be
encoded in Java class files.</p>
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
</boolopt>
<sub_phase>
<name>Line Number Tag Aggregator</name>
<alias>tag.ln</alias>
<short_desc>Line number aggregator</short_desc>
<long_desc>
<p>
The Line Number Tag Aggregator aggregates line number
tags.</p>
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
<short_desc/>
<long_desc/>
</boolopt>
</sub_phase>
<sub_phase>
<name>Array Bounds and Null Pointer Check Tag Aggregator</name>
<alias>tag.an</alias>
<short_desc>Array bounds and null pointer check aggregator</short_desc>
<long_desc>
<p>
The Array Bounds and Null Pointer Tag Aggregator aggregates
tags produced by the Array Bound Checker and Null Pointer Checker.</p>
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>false</default>
<short_desc/>
<long_desc/>
</boolopt>
</sub_phase>
<sub_phase>
<name>Dependence Tag Aggregator</name>
<alias>tag.dep</alias>
<short_desc>Dependence aggregator</short_desc>
<long_desc>
<p>
The Dependence Tag Aggregator aggregates
tags produced by the Side Effect Tagger.</p>
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>false</default>
<short_desc/>
<long_desc/>
</boolopt>
</sub_phase>
<sub_phase>
<name>Field Read/Write Tag Aggregator</name>
<alias>tag.fieldrw</alias>
<short_desc>Field read/write aggregator</short_desc>
<long_desc>
The Field Read/Write Tag Aggregator aggregates field read/write
tags produced by the Field Read/Write Tagger, phase
<tt>jap.fieldrw</tt>.
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>false</default>
<short_desc/>
<long_desc/>
</boolopt>
</sub_phase>
</phase>
<phase>
<name>Dava Body Creation</name>
<alias>db</alias>
<short_desc>Dummy phase to store options for Dava</short_desc>
<long_desc>
The decompile (Dava) option is set using the -f dava options in Soot.
Options provided by Dava are added to this dummy phase so as not to clutter the soot general arguments.
-p db (option name):(value) will be used to set all required values for Dava.
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
<short_desc/>
<long_desc/>
</boolopt>
<boolopt>
<name>Source</name>
<alias>source-is-javac</alias>
<default>true</default>
<short_desc/>
<long_desc>
check out soot.dava.toolkits.base.misc.ThrowFinder
In short we want to ensure that if there are throw exception info in the class file dava uses this info.
</long_desc>
</boolopt>
<sub_phase>
<name>Transformations</name>
<alias>db.transformations</alias>
<short_desc>The Dava back-end with all its transformations</short_desc>
<long_desc>
The transformations implemented using AST Traversal and structural flow analses on Dava's AST
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
</boolopt>
</sub_phase>
<sub_phase>
<name>Renamer</name>
<alias>db.renamer</alias>
<short_desc>Apply heuristics based naming of local variables</short_desc>
<long_desc>If set, the renaming analyses implemented in Dava are applied to each method body being decompiled. The analyses use heuristics to choose potentially better names for local variables. (As of February 14th 2006, work is still under progress on these analyses (dava.toolkits.base.renamer).
</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>false</default>
</boolopt>
</sub_phase>
<sub_phase>
<name>De-obfuscate</name>
<alias>db.deobfuscate</alias>
<short_desc> Apply de-obfuscation analyses</short_desc>
<long_desc>Certain analyses make sense only when the bytecode is obfuscated code.
There are plans to implement such analyses and apply them on methods only if this flag is set.
Dead Code elimination which includes removing code guarded by some condition which is always false or always true is one such
analysis. Another suggested analysis is giving default names to classes and fields. Onfuscators love to use weird names
for fields and classes and even a simple re-naming of these could be a good help to the user.
Another more advanced analysis would be to check for redundant constant fields added by obfuscators and then remove uses
of these constant fields from the code.</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
</boolopt>
</sub_phase>
<sub_phase>
<name>Force Recompilability</name>
<alias>db.force-recompile</alias>
<short_desc> Try to get recompilable code.</short_desc>
<long_desc>While decompiling we have to be clear what our aim is: do we want to convert bytecode
to Java syntax and stay as close to the actual execution of bytecode or do we want recompilably Java source representing
the bytecode. This distinction is important because some restrictions present in Java source are absent from the bytecode.
Examples of this include that fact that in Java a call to a constructor or super needs to be the first statement in
a constructors body. This restriction is absent from the bytecode. Similarly final fields HAVE to be initialized
once and only once in either the static initializer (static fields) or all the constructors (non-static fields). Additionally
the fields should be initialized on all possible execution paths. These restrictions are again absent from the bytecode.
In doing a one-one conversion of bytecode to Java source then no attempt should be made to fix any of these and similar problems
in the Java source. However, if the aim is to get recompilable code then these and similar issues need to be fixed.
Setting the force-recompilability flag will ensure that the decompiler tries its best to produce recompilable Java source.</long_desc>
<boolopt>
<name>Enabled</name>
<alias>enabled</alias>
<default>true</default>
</boolopt>
</sub_phase>
</phase>
</phaseopt>
<macroopt>
<name>Optimize</name>
<alias>O</alias>
<alias>optimize</alias>
<expansion>-p</expansion>
<expansion>gb.a1</expansion>
<expansion>only-stack-locals:false</expansion>
<expansion>-p</expansion>
<expansion>gb.a2</expansion>
<expansion>only-stack-locals:false</expansion>
<expansion>-p</expansion>
<expansion>bop</expansion>
<expansion>enabled:true</expansion>
<expansion>-p</expansion>
<expansion>gop</expansion>
<expansion>enabled:true</expansion>
<expansion>-p</expansion>
<expansion>jop</expansion>
<expansion>enabled:true</expansion>
<expansion>-p</expansion>
<expansion>sop</expansion>
<expansion>enabled:true</expansion>
<short_desc>Perform intraprocedural optimizations</short_desc>
<long_desc>
Perform intraprocedural optimizations on the application classes.
</long_desc>
</macroopt>
<macroopt>
<name>Whole Program Optimize</name>
<alias>W</alias>
<alias>whole-optimize</alias>
<expansion>-p</expansion>
<expansion>wjop</expansion>
<expansion>enabled:true</expansion>
<expansion>-p</expansion>
<expansion>wsop</expansion>
<expansion>enabled:true</expansion>
<expansion>-w</expansion>
<expansion>-O</expansion>
<short_desc>Perform whole program optimizations</short_desc>
<long_desc>
Perform whole program optimizations on the application
classes. This enables the Whole-Jimple Optimization pack as well
as whole program mode and intraprocedural optimizations.
</long_desc>
</macroopt>
<boolopt>
<name>Via Grimp</name>
<alias>via-grimp</alias>
<short_desc>Convert to bytecode via Grimp instead of via Baf</short_desc>
<long_desc>
Convert Jimple to bytecode via the Grimp intermediate
representation instead of via the Baf intermediate
representation.
</long_desc>
</boolopt>
<boolopt>
<name>Via Shimple</name>
<alias>via-shimple</alias>
<short_desc>Enable Shimple SSA representation</short_desc>
<long_desc>
Enable Shimple, Soot's SSA representation. This generates Shimple
bodies for the application classes, optionally transforms them
with analyses that run on SSA form, then turns them back into
Jimple for processing by the rest of Soot. For more information,
see the documentation for the <tt>shimp</tt>, <tt>stp</tt>, and
<tt>sop</tt> phases.
</long_desc>
</boolopt>
<multiopt>
<name>Default ThrowAnalysis</name>
<alias>throw-analysis</alias>
<long_desc>
This option specifies how to estimate the exceptions which each statement
may throw when constructing exceptional CFGs.
</long_desc>
<value>
<name>Pedantic</name>
<alias>pedantic</alias>
<default/>
<short_desc>Pedantically conservative throw analysis</short_desc>
<long_desc>
Says that any instruction may throw any
<code>Throwable</code> whatsoever. Strictly speaking this is
correct, since the Java libraries include the
<code>Thread.stop(Throwable)</code>
method, which allows other threads to cause arbitrary exceptions
to occur at arbitrary points in the execution of a victim thread.
</long_desc>
</value>
<value>
<name>Unit</name>
<alias>unit</alias>
<short_desc>Unit Throw Analysis</short_desc>
<long_desc>
Says that each statement in the intermediate representation
may throw those exception types associated with the corresponding
Java bytecode instructions in the JVM Specification. The
analysis deals with each statement in isolation, without regard
to the surrounding program.
</long_desc>
</value>
</multiopt>
<boolopt>
<name>Omit Excepting Unit Edges</name>
<alias>omit-excepting-unit-edges</alias>
<short_desc>Omit CFG edges to handlers from excepting units which lack side effects</short_desc>
<long_desc>
<p>
When constructing an <code>ExceptionalUnitGraph</code> or
<code>ExceptionalBlockGraph</code>, include edges to an exception
handler only from the predecessors of an instruction which may
throw an exception to the handler, and not from the excepting
instruction itself, unless the excepting instruction has
potential side effects.
</p>
<p>
Omitting edges from excepting units allows more accurate flow
analyses (since if an instruction without side effects throws an
exception, it has not changed the state of the computation). This
accuracy, though, could lead optimizations to generate
unverifiable code, since the dataflow analyses performed by
bytecode verifiers might include paths to exception handlers from
all protected instructions, regardless of whether the
instructions have side effects. (In practice, the pedantic throw
analysis suffices to pass verification in all VMs tested with
Soot to date, but the JVM specification does allow for less
discriminating verifiers which would reject some code that might
be generated using the pedantic throw analysis without also
adding edges from all excepting units.)</p>
</long_desc>
</boolopt>
<macroopt>
<name>Trim CFGs</name>
<alias>trim-cfgs</alias>
<expansion>-throw-analysis</expansion>
<expansion>unit</expansion>
<expansion>-omit-excepting-unit-edges</expansion>
<expansion>-p</expansion>
<expansion>jb.tt</expansion>
<expansion>enabled:true</expansion>
<short_desc>Trim unrealizable exceptional edges from CFGs</short_desc>
<long_desc>
<p>
When constructing CFGs which include exceptional edges, minimize
the number of edges leading to exception handlers by analyzing
which instructions might actually be executed before an exception
is thrown, instead of assuming that every instruction protected
by a handler has the potential to throw an exception the handler
catches.
</p>
<p>
<code>-trim-cfgs</code> is shorthand for <code>-throw-analysis
unit -omit-excepting-unit-edges -p jb.tt enabled:true</code>.</p>
</long_desc>
</macroopt>
</section>
<section>
<name>Application Mode Options</name>
<listopt>
<name>Include Package</name>
<alias>i</alias>
<alias>include</alias>
<set_arg_label>pkg</set_arg_label>
<short_desc>Include classes in <use_arg_label/> as application classes</short_desc>
<long_desc>
<p>
Designate classes in packages whose names begin with
<use_arg_label/> (e.g. <tt>java.util.</tt>) as application
classes which should be analyzed and output. This option allows
you to selectively analyze classes in some packages that Soot
normally treats as library classes.</p>
<p>
You can use the include option multiple times, to designate
the classes of multiple packages as application classes.</p>
<p>
If you specify both include and exclude options, first the
classes from all excluded packages are marked as library classes,
then the classes from all included packages are marked as
application classes.</p>
</long_desc>
</listopt>
<listopt>
<name>Exclude Package</name>
<alias>x</alias>
<alias>exclude</alias>
<set_arg_label>pkg</set_arg_label>
<short_desc>Exclude classes in <use_arg_label/> from application classes</short_desc>
<long_desc>
<p>
Excludes any classes in packages whose names begin with
<use_arg_label/> from the set of application classes which are
analyzed and output, treating them as library classes instead.
This option allows you to selectively exclude classes
which would normally be treated as application classes
</p>
<p>
You can use the exclude option multiple times, to designate
the classes of multiple packages as library classes.</p>
<p>
If you specify both include and exclude options, first the
classes from all excluded packages are marked as library classes,
then the classes from all included packages are marked as
application classes.</p>
</long_desc>
</listopt>
<boolopt>
<name>Include All Packages</name>
<alias>include-all</alias>
<short_desc>Set default excluded packages to empty list</short_desc>
<long_desc>
Soot uses a default list of packages (such as java.) which are deemed
to contain library classes. This switch removes the default packages from the
list of packages containing library classes.
Individual packages can then be added using the exclude option.
</long_desc>
</boolopt>
<listopt>
<name>Dynamic Classes</name>
<alias>dynamic-class</alias>
<set_arg_label>class</set_arg_label>
<short_desc>Note that <use_arg_label/> may be loaded dynamically</short_desc>
<long_desc>
<p>
Mark <use_arg_label/> as a class which the application may load
dynamically. Soot will read it as a library class even if it is
not referenced from the argument classes. This permits whole
program optimizations on programs which load classes dynamically
if the set of classes that can be loaded is known at compile
time.</p>
<p>
You can use the dynamic class option multiple
times to specify more than one dynamic class.</p>
</long_desc>
</listopt>
<listopt>
<name>Dynamic Directories</name>
<alias>dynamic-dir</alias>
<set_arg_label>dir</set_arg_label>
<short_desc>Mark all classes in <use_arg_label/> as potentially dynamic</short_desc>
<long_desc>
<p>Mark all class files in <use_arg_label/> as classes that may
be loaded dynamically. Soot will read them as library classes
even if they are not referenced from the argument classes.</p>
<p>
You can specify more than one directory of potentially dynamic
classes by specifying multiple dynamic directory options.</p>
</long_desc>
</listopt>
<listopt>
<name>Dynamic Package</name>
<alias>dynamic-package</alias>
<set_arg_label>pkg</set_arg_label>
<short_desc>Marks classes in <use_arg_label/> as potentially dynamic</short_desc>
<long_desc>
<p>
Marks all class files belonging to the package <use_arg_label/>
or any of its subpackages as classes which the application may
load dynamically. Soot will read all classes in <use_arg_label/> as
library classes, even if they are not referenced by any of the
argument classes.</p>
<p>To specify more than one dynamic package, use the dynamic
package option multiple times.</p>
</long_desc>
</listopt>
</section>
<section>
<name>Input Attribute Options</name>
<boolopt>
<name>Keep Line Number</name>
<alias>keep-line-number</alias>
<default>true</default>
<short_desc>Keep line number tables</short_desc>
<long_desc>
Preserve line number tables for class files throughout the
transformations.
</long_desc>
</boolopt>
<boolopt>
<name>Keep Bytecode Offset</name>
<alias>keep-bytecode-offset</alias>
<alias>keep-offset</alias>
<short_desc>Attach bytecode offset to IR</short_desc>
<long_desc>Maintain bytecode offset tables for class files throughout the transformations.</long_desc>
</boolopt>
</section>cg.spark
<section>
<name>Annotation Options</name>
<macroopt>
<name>Purity Annotation [AM]</name>
<alias>annot-purity</alias>
<expansion>-w</expansion>
<expansion>-p</expansion>
<expansion>cg.spark</expansion>
<expansion>enabled:true</expansion>
<expansion>-p</expansion>
<expansion>wjap.purity</expansion>
<expansion>enabled:true</expansion>
<short_desc>Emit purity attributes</short_desc>
<long_desc>
Purity anaysis implemented by Antoine Mine and based on the paper
A Combined Pointer and Purity Analysis Java Programs
by Alexandru Salcianu and Martin Rinard.
</long_desc>
</macroopt>
<macroopt>
<name>Null Pointer Annotation</name>
<alias>annot-nullpointer</alias>
<expansion>-p</expansion>
<expansion>jap.npc</expansion>
<expansion>enabled:true</expansion>
<expansion>-p</expansion>
<expansion>tag.an</expansion>
<expansion>enabled:true</expansion>
<short_desc>Emit null pointer attributes</short_desc>
<long_desc>
Perform a static analysis of which dereferenced pointers may have
null values, and annotate class files with attributes
encoding the results of the analysis. For details, see the
documentation for Null Pointer Annotation and for the
Array Bounds and Null Pointer Check Tag Aggregator.
</long_desc>
</macroopt>
<macroopt>
<name>Array Bounds Annotation</name>
<alias>annot-arraybounds</alias>
<expansion>-p</expansion>
<expansion>wjap.ra</expansion>
<expansion>enabled:true</expansion>
<expansion>-p</expansion>
<expansion>jap.abc</expansion>
<expansion>enabled:true</expansion>
<expansion>-p</expansion>
<expansion>tag.an</expansion>
<expansion>enabled:true</expansion>
<short_desc>Emit array bounds check attributes</short_desc>
<long_desc>
Perform a static analysis of which array bounds checks may safely
be eliminated and annotate output class files with attributes
encoding the results of the analysis. For details, see the
documentation for Array Bounds Annotation and for the Array
Bounds and Null Pointer Check Tag Aggregator.
</long_desc>
</macroopt>
<macroopt>
<name>Side effect annotation</name>
<alias>annot-side-effect</alias>
<expansion>-w</expansion>
<expansion>-p</expansion>
<expansion>jap.sea</expansion>
<expansion>enabled:true</expansion>
<expansion>-p</expansion>
<expansion>tag.dep</expansion>
<expansion>enabled:true</expansion>
<short_desc>Emit side-effect attributes</short_desc>
<long_desc>
Enable the generation of side-effect attributes.
</long_desc>
</macroopt>
<macroopt>
<name>Field read/write annotation</name>
<alias>annot-fieldrw</alias>
<expansion>-w</expansion>
<expansion>-p</expansion>
<expansion>jap.fieldrw</expansion>
<expansion>enabled:true</expansion>
<expansion>-p</expansion>
<expansion>tag.fieldrw</expansion>
<expansion>enabled:true</expansion>
<short_desc>Emit field read/write attributes</short_desc>
<long_desc>Enable the generation of field read/write attributes.</long_desc>
</macroopt>
</section>
<section>
<name>Miscellaneous Options</name>
<boolopt>
<name>Time</name>
<alias>time</alias>
<short_desc>Report time required for transformations</short_desc>
<long_desc>
Report the time required to perform some of Soot's transformations.
</long_desc>
</boolopt>
<boolopt>
<name>Subtract Garbage Collection Time</name>
<alias>subtract-gc</alias>
<short_desc>Subtract gc from time</short_desc>
<long_desc>
Attempt to subtract time spent in garbage collection from
the reports of times required for transformations.
</long_desc>
</boolopt>
</section>
</options>
