Soot command-line options

CONTENTS

SYNOPSIS

Soot is invoked as follows:

javajavaOptionssoot.Main [ sootOption* ] classname*

DESCRIPTION

This manual documents the command line options of the Soot bytecode compiler/optimizer tool. In essence, it tells you what you can use to replace the sootOption placeholder which appears in the SYNOPSIS.

The descriptions of Soot options talk about three categories of classes: argument classes, application classes, and library classes.

Argument classes 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 -process-dir 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.

Application classes are classes that Soot analyzes, transforms, and turns into output files.

Library classes 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 .class or .jimple source files for them, but it does not perform transformations on library classes or write output files for them.

All argument classes are necessarily application classes. When Soot is not in ``application mode'', argument classes are the only application classes; other classes referenced from the argument classes become library classes.

When Soot is 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.

Users may fine-tune the designation of application and library classes using the Application Mode Options.

Here is a simple example to clarify things. Suppose your program consists of three class files generated from the following source:

// 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);
  }
}

If you run

java soot.Main HelloWorld
HelloWorld is the only argument class and the only application class. UI and TextUI are library classes, along with java.lang.System, java.lang.String, java.io.PrintStream, and a host of other classes from the Java runtime system that get dragged in indirectly by the references to String and System.out.

If you run

java soot.Main --app HelloWorld
HelloWorld remains the only argument class, but the application classes include UI and TextUI as well as HelloWorld. java.lang.System et. al. remain library classes.

If you run

java soot.Main -i java. --app HelloWorld
HelloWorld is still the only argument class, but the set of application classes includes the referenced Java runtime classes in packages whose names start with java. as well as HelloWorld, UI, and textUI. The set of library classes includes the referenced classes from other packages in the Java runtime.

OPTIONS

General Options

-coffi
Use the good old Coffi front end for parsing Java bytecode (instead of using ASM).
-asm-backend
Use the ASM back end for generating Java bytecode (instead of using Jasmin).
-h
-help
Display help and exit
-pl
-phase-list
Print list of available phases
-ph phase
-phase-help phase
Print help for specified phase
-version
Display version information and exit
-v
-verbose
Verbose mode
-interactive-mode
Run in interactive mode
-unfriendly-mode
Allow Soot to run with no command-line options
-app
Run in application mode
-w
-whole-program
Run in whole-program mode
-ws
-whole-shimple
Run in whole-shimple mode
-fly
-on-the-fly
Run in on-the-fly mode
-validate
Run internal validation on bodies
-debug
Print various Soot debugging info
-debug-resolver
Print debugging info from SootResolver
-ignore-resolving-levels
Ignore mismatching resolving levels

Input Options

-cp path
-soot-class-path path
-soot-classpath path
Use path as the classpath for finding classes.
-pp
-prepend-classpath
Prepend the given soot classpath to the default classpath.
-ice
-ignore-classpath-errors
Ignores invalid entries on the Soot classpath.
-process-multiple-dex
Process all DEX files found in APK.
-process-path dir
-process-dir dir
Process all classes found in dir
-oaat
From the process-dir, processes one class at a time.
-android-jars path
Use path as the path for finding the android.jar file
-force-android-jar path
Force Soot to use path as the path for the android.jar file.
-android-api-version version
Force Soot to use version as the API version when readin in APK or DEX files.
-ast-metrics
Compute AST Metrics if performing java to jimple
-src-prec format
class 
only-class 
jimple 
java 
apk 
apk-class-jimple apk-c-j 
Sets source precedence to format files
-full-resolver
Force transitive resolving of referenced classes
-allow-phantom-refs
Allow unresolved classes; may cause errors
-no-bodies-for-excluded
Do not load bodies for excluded classes
-j2me
Use J2ME mode; changes assignment of types
-main-class class
Sets the main class for whole-program analysis.
-polyglot
Use Java 1.4 Polyglot frontend instead of JastAdd
-permissive-resolving
Use alternative sources when classes cannot be found using the normal resolving strategy
-drop-bodies-after-load
Drop the method source after it has served its purpose of loading the method body

Output Options

-d dir
-output-dir dir
Store output files in dir
-f format
-output-format format
jimple 
jimp 
shimple 
shimp 
baf 

grimple 
grimp 
xml 
dex 
force-dex 
none 
jasmin 
class 
dava 
template 
asm 
Set output format for Soot
-java-version version
default 
1.1 
1.2 
1.3 
1.4 
1.5 
1.6 
1.7 
1.8 
Force Java version of bytecode generated by Soot.
-outjar
-output-jar
Make output dir a Jar file instead of dir
-xml-attributes
Save tags to XML attributes for Eclipse
-print-tags
-print-tags-in-output
Print tags in output files after stmt
-no-output-source-file-attribute
Don't output Source File Attribute when producing class files
-no-output-inner-classes-attribute
Don't output inner classes attribute in class files
-dump-body phaseName
Dump the internal representation of each method before and after phase phaseName
-dump-cfg phaseName
Dump the internal representation of each CFG constructed during phase phaseName
-show-exception-dests
Include exception destination edges as well as CFG edges in dumped CFGs
-gzip
GZip IR output files
-force-overwrite
Force Overwrite Output Files

Processing Options

-plugin file
Load all plugins found in file
-wrong-staticness arg
fail 
ignore 
fix 
Ignores or fixes errors due to wrong staticness
-p phase opt:val
-phase-option phase opt:val
Set phase's opt option to value
-O
-optimize
Perform intraprocedural optimizations
-W
-whole-optimize
Perform whole program optimizations
-via-grimp
Convert to bytecode via Grimp instead of via Baf
-via-shimple
Enable Shimple SSA representation
-throw-analysis arg
pedantic 
unit 
dalvik 
-check-init-ta arg
-check-init-throw-analysis arg
auto 
pedantic 
unit 
dalvik 
-omit-excepting-unit-edges
Omit CFG edges to handlers from excepting units which lack side effects
-trim-cfgs
Trim unrealizable exceptional edges from CFGs
-ire
-ignore-resolution-errors
Does not throw an exception when a program references an undeclared field or method.

Application Mode Options

-i pkg
-include pkg
Include classes in pkg as application classes
-x pkg
-exclude pkg
Exclude classes in pkg from application classes
-include-all
Set default excluded packages to empty list
-dynamic-class class
Note that class may be loaded dynamically
-dynamic-dir dir
Mark all classes in dir as potentially dynamic
-dynamic-package pkg
Marks classes in pkg as potentially dynamic

Input Attribute Options

-keep-line-number
Keep line number tables
-keep-bytecode-offset
-keep-offset
Attach bytecode offset to IR

Output Attribute Options

-write-local-annotations
Write out debug annotations on local names

Annotation Options

-annot-purity
Emit purity attributes
-annot-nullpointer
Emit null pointer attributes
-annot-arraybounds
Emit array bounds check attributes
-annot-side-effect
Emit side-effect attributes
-annot-fieldrw
Emit field read/write attributes

Miscellaneous Options

-time
Report time required for transformations
-subtract-gc
Subtract gc from time
-no-writeout-body-releasing
Disables the release of method bodies after writeout. This flag is used internally.

PHASES AND PHASE OPTIONS

Soot supports the powerful--but initially confusing--notion of ``phase options''. This document aims to clear up the confusion so you can exploit the power of phase options.

Soot's execution is divided into a number of phases. For example, JimpleBodys are built by a phase called jb, which is itself comprised of subphases, such as the aggregation of local variables (jb.a).

Phase options provide a way for you to change the behaviour of a phase from the Soot command-line. They take the form -p phase.name option:value. For instance, to instruct Soot to use original names in Jimple, we would invoke Soot like this:

java soot.Main foo -p jb use-original-names:true
Multiple option-value pairs may be specified in a single -p option separated by commas. For example,
java soot.Main foo -p cg.spark verbose:true,on-fly-cg:true

There are five types of phase options:

  1. Boolean options take the values ``true'' and ``false''; if you specify the name of a boolean option without adding a value for it, ``true'' is assumed.
  2. Multi-valued options take a value from a set of allowed values specific to that option.
  3. Integer options take an integer value.
  4. Floating point options take a floating point number as their value.
  5. String options take an arbitrary string as their value.

Each option has a default value which is used if the option is not specified on the command line.

All phases and subphases accept the option ``enabled'', which must be ``true'' for the phase or subphase to execute. To save you some typing, the pseudo-options ``on'' and ``off'' are equivalent to ``enabled:true'' and ``enabled:false'', respectively. In addition, specifying any options for a phase automatically enables that phase.

Adding your own subphases

Within Soot, each phase is implemented by a Pack. The Pack is a collection of transformers, each corresponding to a subphase of the phase implemented by the Pack. When the Pack is called, it executes each of its transformers in order.

Soot transformers are usually instances of classes that extend BodyTransformer or SceneTransformer. In either case, the transformer class must override the internalTransform method, providing an implementation which carries out some transformation on the code being analyzed.

To add a transformer to some Pack without modifying Soot itself, create your own class which changes the contents of the Packs to meet your requirements and then calls soot.Main.

The remainder of this document describes the transformations belonging to Soot's various Packs and their corresponding phase options.

Jimple Body Creation (jb)

Jimple Body Creation creates a JimpleBody for each input method, using either coffi, to read .class files, or the jimple parser, to read .jimple files.

Accepted phase options:

Duplicate CatchAll Trap Remover (jb.dtr)

This transformer detects cases in which the same code block is covered by two different catch all traps with different exception handlers (A and B), and if there is at the same time a third catch all trap that covers the second handler B and jumps to A, then the second trap is unnecessary, because it is already covered by a combination of the other two traps. This transformer removes the unnecessary trap.

Accepted phase options:

Empty Switch Eliminator (jb.ese)

The Empty Switch Eliminator detects and removes switch statements that have no data labels. Instead, the code is transformed to contain a single jump statement to the default label.

Accepted phase options:

Local Splitter (jb.ls)

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.

Accepted phase options:

Jimple Local Aggregator (jb.a)

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. At this stage in JimpleBody construction, local aggregation serves largely to remove the copies to and from stack variables which simulate load and store instructions in the original bytecode.

Accepted phase options:

Unused Local Eliminator (jb.ule)

The Unused Local Eliminator removes any unused locals from the method.

Accepted phase options:

Type Assigner (jb.tr)

The Type Assigner gives local variables types which will accommodate the values stored in them over the course of the method.

Accepted phase options:

Unsplit-originals Local Packer (jb.ulp)

The Unsplit-originals Local Packer executes only when the `use-original-names' option is chosen for the `jb' 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.

Accepted phase options:

Local Name Standardizer (jb.lns)

The Local Name Standardizer assigns generic names to local variables.

Accepted phase options:

Copy Propagator (jb.cp)

This phase performs cascaded copy propagation. If the propagator encounters situations of the form: A: a = ...; ... B: x = a; ... C: ... = ... x; where a and x are each defined only once (at A and B, respectively), then it can propagate immediately without checking between B and C for redefinitions of a. In this case the propagator is global. Otherwise, if a has multiple definitions then the propagator checks for redefinitions and propagates copies only within extended basic blocks.

Accepted phase options:

Dead Assignment Eliminator (jb.dae)

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.

Accepted phase options:

Post-copy propagation Unused Local Eliminator (jb.cp-ule)

This phase removes any locals that are unused after copy propagation.

Accepted phase options:

Local Packer (jb.lp)

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.

Accepted phase options:

Nop Eliminator (jb.ne)

The Nop Eliminator removes nop statements from the method.

Accepted phase options:

Unreachable Code Eliminator (jb.uce)

The Unreachable Code Eliminator removes unreachable code and traps whose catch blocks are empty.

Accepted phase options:

Trap Tightener (jb.tt)

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.

Accepted phase options:

Java To Jimple Body Creation (jj)

Jimple Body Creation creates a JimpleBody for each input method, using polyglot, to read .java files.

Accepted phase options:

Local Splitter (jj.ls)

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.

Accepted phase options:

Jimple Local Aggregator (jj.a)

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. At this stage in JimpleBody construction, local aggregation serves largely to remove the copies to and from stack variables which simulate load and store instructions in the original bytecode.

Accepted phase options:

Unused Local Eliminator (jj.ule)

The Unused Local Eliminator removes any unused locals from the method.

Accepted phase options:

Type Assigner (jj.tr)

The Type Assigner gives local variables types which will accommodate the values stored in them over the course of the method.

Accepted phase options:

Unsplit-originals Local Packer (jj.ulp)

The Unsplit-originals Local Packer executes only when the `use-original-names' option is chosen for the `jb' 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.

Accepted phase options:

Local Name Standardizer (jj.lns)

The Local Name Standardizer assigns generic names to local variables.

Accepted phase options:

Copy Propagator (jj.cp)

This phase performs cascaded copy propagation. If the propagator encounters situations of the form: A: a = ...; ... B: x = a; ... C: ... = ... x; where a and x are each defined only once (at A and B, respectively), then it can propagate immediately without checking between B and C for redefinitions of a. In this case the propagator is global. Otherwise, if a has multiple definitions then the propagator checks for redefinitions and propagates copies only within extended basic blocks.

Accepted phase options:

Dead Assignment Eliminator (jj.dae)

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.

Accepted phase options:

Post-copy propagation Unused Local Eliminator (jj.cp-ule)

This phase removes any locals that are unused after copy propagation.

Accepted phase options:

Local Packer (jj.lp)

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.

Accepted phase options:

Nop Eliminator (jj.ne)

The Nop Eliminator removes nop statements from the method.

Accepted phase options:

Unreachable Code Eliminator (jj.uce)

The Unreachable Code Eliminator removes unreachable code and traps whose catch blocks are empty.

Accepted phase options:

Whole Jimple Pre-processing Pack (wjpp)

This pack allows you to insert pre-processors that are run before call-graph construction. Only enabled in whole-program mode. In an unmodified copy of Soot, this pack is empty.

Accepted phase options:

Whole Shimple Pre-processing Pack (wspp)

This pack allows you to insert pre-processors that are run before call-graph construction. Only enabled in whole-program Shimple mode. In an unmodified copy of Soot, this pack is empty.

Accepted phase options:

Call Graph Constructor (cg)

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.

Accepted phase options:

Class Hierarchy Analysis (cg.cha)

This phase uses Class Hierarchy Analysis to generate a call graph.

Accepted phase options:

Spark (cg.spark)

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 Ondrej Lhotak's M.Sc. thesis.

Accepted phase options:

Paddle (cg.paddle)

Paddle is a BDD-based interprocedural analysis framework. It includes points-to analysis, call graph construction, and various client analyses.

Accepted phase options:

Whole Shimple Transformation Pack (wstp)

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. In an unmodified copy of Soot the Whole-Shimple Transformation Pack is empty.

Accepted phase options:

Whole Shimple Optimization Pack (wsop)

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. In an unmodified copy of Soot the Whole-Shimple Optimization Pack is empty.

Accepted phase options:

Whole-Jimple Transformation Pack (wjtp)

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.

Accepted phase options:

May Happen in Parallel Analyses (wjtp.mhp)

May Happen in Parallel (MHP) Analyses determine what program statements may be run by different threads concurrently. This phase does not perform any transformation.

Accepted phase options:

Lock Allocator (wjtp.tn)

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.

Accepted phase options:

Rename duplicated classes (wjtp.rdc)

Rename duplicated classes when the file system is not case sensitive. If the file system is case sensitive, this phase does nothing.

Accepted phase options:

Whole-Jimple Optimization Pack (wjop)

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.

Accepted phase options:

Static Method Binder (wjop.smb)

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.

Accepted phase options:

Static Inliner (wjop.si)

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.

Accepted phase options:

Whole-Jimple Annotation Pack (wjap)

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.

Accepted phase options:

Rectangular Array Finder (wjap.ra)

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. 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. The Rectangular Array Finder does not change the program being analyzed. Its results are used by the Array Bound Checker.

Accepted phase options:

Unreachable Method Tagger (wjap.umt)

Uses the call graph to determine which methods are unreachable and adds color tags so they can be highlighted in a source browser.

Accepted phase options:

Unreachable Fields Tagger (wjap.uft)

Uses the call graph to determine which fields are unreachable and adds color tags so they can be highlighted in a source browser.

Accepted phase options:

Tightest Qualifiers Tagger (wjap.tqt)

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.

Accepted phase options:

Call Graph Grapher (wjap.cgg)

Creates graphical call graph.

Accepted phase options:

Purity Analysis [AM] (wjap.purity)

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.

Accepted phase options:

Shimple Control (shimple)

Shimple Control sets parameters which apply throughout the creation and manipulation of Shimple bodies. Shimple is Soot's SSA representation.

Accepted phase options:

Shimple Transformation Pack (stp)

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.

Accepted phase options:

Shimple Optimization Pack (sop)

The Shimple Optimization Pack contains transformations that perform optimizations on Shimple, Soot's SSA representation.

Accepted phase options:

Shimple Constant Propagator and Folder (sop.cpf)

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.

Accepted phase options:

Jimple Transformation Pack (jtp)

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.

Accepted phase options:

Jimple Optimization Pack (jop)

When Soot's Optimize option is on, Soot applies the Jimple Optimization Pack to every JimpleBody in application classes. This section lists the default transformations in the Jimple Optimization Pack.

Accepted phase options:

Common Subexpression Eliminator (jop.cse)

The Common Subexpression Eliminator runs an available expressions analysis on the method body, then eliminates common subexpressions. 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. 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. Because of its current slowness, this transformation is not enabled by default.

Accepted phase options:

Busy Code Motion (jop.bcm)

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.

Accepted phase options:

Lazy Code Motion (jop.lcm)

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 while loops into do while loops inside an if statement). This allows the Partial Redundancy Eliminator to optimize loop invariants of while loops.

Accepted phase options:

Copy Propagator (jop.cp)

This phase performs cascaded copy propagation.

Accepted phase options:

Jimple Constant Propagator and Folder (jop.cpf)

The Jimple Constant Propagator and Folder evaluates any expressions consisting entirely of compile-time constants, for example 2 * 3, and replaces the expression with the constant result, in this case 6.

Accepted phase options:

Conditional Branch Folder (jop.cbf)

The Conditional Branch Folder statically evaluates the conditional expression of Jimple if statements. If the condition is identically true or false, the Folder replaces the conditional branch statement with an unconditional goto statement.

Accepted phase options:

Dead Assignment Eliminator (jop.dae)

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.

Accepted phase options:

Null Check Eliminator (jop.nce)

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.

Accepted phase options:

Unreachable Code Eliminator 1 (jop.uce1)

The Unreachable Code Eliminator removes unreachable code and traps whose catch blocks are empty.

Accepted phase options:

Unconditional Branch Folder 1 (jop.ubf1)

The Unconditional Branch Folder removes unnecessary `goto' statements from a JimpleBody. If a goto statement's target is the next instruction, then the statement is removed. If a goto's target is another goto, with target y, then the first statement's target is changed to y. If some if statement's target is a goto statement, then the if's target can be replaced with the goto's target. (These situations can result from other optimizations, and branch folding may itself generate more unreachable code.)

Accepted phase options:

Unreachable Code Eliminator 2 (jop.uce2)

Another iteration of the Unreachable Code Eliminator.

Accepted phase options:

Unconditional Branch Folder 2 (jop.ubf2)

Another iteration of the Unconditional Branch Folder.

Accepted phase options:

Unused Local Eliminator (jop.ule)

The Unused Local Eliminator phase removes any unused locals from the method.

Accepted phase options:

Jimple Annotation Pack (jap)

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).

Accepted phase options:

Null Pointer Checker (jap.npc)

The Null Pointer Checker finds instruction which have the potential to throw NullPointerExceptions and adds annotations indicating whether or not the pointer being dereferenced can be determined statically not to be null.

Accepted phase options:

Null Pointer Colourer (jap.npcolorer)

Produce colour tags that the Soot plug-in for Eclipse can use to highlight null and non-null references.

Accepted phase options:

Array Bound Checker (jap.abc)

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. If Soot is in whole-program mode, the Array Bound Checker can use the results provided by the Rectangular Array Finder.

Accepted phase options:

Profiling Generator (jap.profiling)

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 MultiCounter class implementing the methods invoked. For details, see the ProfilingGenerator source code.

Accepted phase options:

Side Effect tagger (jap.sea)

The Side Effect Tagger uses the active invoke graph to produce side-effect attributes, as described in the Spark thesis, chapter 6.

Accepted phase options:

Field Read/Write Tagger (jap.fieldrw)

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.

Accepted phase options:

Call Graph Tagger (jap.cgtagger)

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.

Accepted phase options:

Parity Tagger (jap.parity)

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 x in x = 2) are coloured yellow.

Accepted phase options:

Parameter Alias Tagger (jap.pat)

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.

Accepted phase options:

Live Variables Tagger (jap.lvtagger)

Colors live variables.

Accepted phase options:

Reaching Defs Tagger (jap.rdtagger)

For each use of a local in a stmt creates a link to the reaching def.

Accepted phase options:

Cast Elimination Check Tagger (jap.che)

Indicates whether cast checks can be eliminated.

Accepted phase options:

Unreachable Method Transformer (jap.umt)

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.

Accepted phase options:

Loop Invariant Tagger (jap.lit)

An expression whose operands are constant or have reaching definitions from outside the loop body are tagged as loop invariant.

Accepted phase options:

Available Expressions Tagger (jap.aet)

A each statement a set of available expressions is after the statement is added as a tag.

Accepted phase options:

Dominators Tagger (jap.dmt)

Provides link tags at a statement to all of the satements dominators.

Accepted phase options:

Grimp Body Creation (gb)

The Grimp Body Creation phase creates a GrimpBody for each source method. It is run only if the output format is grimp or grimple, or if class files are being output and the Via Grimp option has been specified.

Accepted phase options:

Grimp Pre-folding Aggregator (gb.a1)

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.

Accepted phase options:

Grimp Constructor Folder (gb.cf)

The Grimp Constructor Folder combines new statements with the specialinvoke statement that calls the new object's constructor. For example, it turns r2 = new java.util.ArrayList; r2.init(); into r2 = new java.util.ArrayList();

Accepted phase options:

Grimp Post-folding Aggregator (gb.a2)

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 r2 = new java.util.ArrayList; r2.init(); r3 = r2 is replaced by r2 = new java.util.ArrayList(); r3 = r2 the invocation of init no longer represents a potential side-effect separating the two definitions, so they can be combined into r3 = new java.util.ArrayList(); (assuming there are no subsequent uses of r2).

Accepted phase options:

Grimp Unused Local Eliminator (gb.ule)

This phase removes any locals that are unused after constructor folding and aggregation.

Accepted phase options:

Grimp Optimization (gop)

The Grimp Optimization pack performs optimizations on GrimpBodys (currently there are no optimizations performed specifically on GrimpBodys, and the pack is empty). It is run only if the output format is grimp or grimple, or if class files are being output and the Via Grimp option has been specified.

Accepted phase options:

Baf Body Creation (bb)

The Baf Body Creation phase creates a BafBody from each source method. It is run if the output format is baf or b or asm or a, or if class files are being output and the Via Grimp option has not been specified.

Accepted phase options:

Load Store Optimizer (bb.lso)

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 store.r $r2; load.r $r2; with dup1.r in cases where the value of r2 is not used subsequently.

Accepted phase options:

Store Chain Optimizer (bb.sco)

The store chain optimizer detects chains of push/store pairs that write to the same variable and only retains the last store. It removes the unnecessary previous push/stores that are subsequently overwritten.

Accepted phase options:

Peephole Optimizer (bb.pho)

Applies peephole optimizations to the Baf intermediate representation. Individual optimizations must be implemented by classes implementing the Peephole interface. The Peephole Optimizer reads the names of the Peephole classes at runtime from the file peephole.dat and loads them dynamically. Then it continues to apply the Peepholes repeatedly until none of them are able to perform any further optimizations. Soot provides only one Peephole, named ExamplePeephole, which is not enabled by the delivered peephole.dat file. ExamplePeephole removes all checkcast instructions.

Accepted phase options:

Unused Local Eliminator (bb.ule)

This phase removes any locals that are unused after load store optimization and peephole optimization.

Accepted phase options:

Local Packer (bb.lp)

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.

Accepted phase options:

Baf Optimization (bop)

The Baf Optimization pack performs optimizations on BafBodys (currently there are no optimizations performed specifically on BafBodys, and the pack is empty). It is run only if the output format is baf or b or asm or a, or if class files are being output and the Via Grimp option has not been specified.

Accepted phase options:

Tag Aggregator (tag)

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.

Accepted phase options:

Line Number Tag Aggregator (tag.ln)

The Line Number Tag Aggregator aggregates line number tags.

Accepted phase options:

Array Bounds and Null Pointer Check Tag Aggregator (tag.an)

The Array Bounds and Null Pointer Tag Aggregator aggregates tags produced by the Array Bound Checker and Null Pointer Checker.

Accepted phase options:

Dependence Tag Aggregator (tag.dep)

The Dependence Tag Aggregator aggregates tags produced by the Side Effect Tagger.

Accepted phase options:

Field Read/Write Tag Aggregator (tag.fieldrw)

The Field Read/Write Tag Aggregator aggregates field read/write tags produced by the Field Read/Write Tagger, phase jap.fieldrw.

Accepted phase options:

Dava Body Creation (db)

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.

Accepted phase options:

Transformations (db.transformations)

The transformations implemented using AST Traversal and structural flow analses on Dava's AST

Accepted phase options:

Renamer (db.renamer)

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).

Accepted phase options:

De-obfuscate (db.deobfuscate)

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.

Accepted phase options:

Force Recompilability (db.force-recompile)

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.

Accepted phase options: