/compiler/src/main/java/soot/options/soot_options.xml

Large files files are truncated, but you can click here to view the full file

<?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>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-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.
</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>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>
		</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>&apos;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>&apos; option is chosen for the
`<tt>jb</tt>&apos; 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>&apos; option is specified for
the `<tt>jb</tt>&apos; 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&apos;&apos; 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>&apos; option is chosen for the
`<tt>jb</tt>&apos; 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>&apos; option is specified for
the `<tt>jb</tt>&apos; 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&apos;&apos; 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>
			<radio_phase>
				<name>Call Graph Constructor</name>
				<alias>cg</alias>
                                <class>CGOptions</class>
                                <short_desc>Call graph constructor</short_desc>
                                <long_desc>
The Call Grap…