Soot Command-Line Documentation

Patrice Pominville
patrice@sable.mcgill.ca

March 8, 2000

SYNOPSIS

Soot can be invoked in the following ways:

soot [option]* [classname]+
soot --app [option]* classname

DESCRIPTION

This manual page documents the command line version of the soot bytecode compiler/optimizer tool.

When given one or several classnames that refers to a Java type, and no --app option, soot will attempt to resolve it by finding a file containing the given type. Once soot has located such a file, it will read in its contents, perform transformations on its bytecode and output the type in a specified output format. This mode of operation is referred to as running soot in single-file mode. All types specified on the commandline are resolved and processed. In this mode, the last file specified on the command-line serves as the main class, when such a notion is needed.

The --app argument can be used to activate soot's application mode. In application mode soot will perform a transitive closure on the types listed in the constant pool of the type provided on the command line. soot will then proceed to transform the types in this closure. The closure will contain Java library types, as well as types particular to the application. By default, only the application-specific types will be processed by soot. This can be overridden by command line options. Clearly, in this case, the file specified on the command-line is the main class.

To resolve a type, soot uses the same semantics as the java command; soot looks for files containing types in the directories specified by the soot.class.path system property. This property serves the same purpose as java's CLASSPATH environment variable. There is also a command line option to override the soot.class.path property. If there is no Soot classpath, then the external Java CLASSPATH is used. (There is a note for Windows users in the section describing the soot-class-path entry).

Once a type has been resolved and read into soot, various transformations can be applied to its code. These are described in the optimization section of the options below.

The Soot framework has 3 different internal representations: Baf, Jimple and Grimp. soot allows one to output a processed class either as a standard classfile or in the textual format corresponding to one of the above internal representations. Thus a class can be outputted as a .baf file, a .jimple file or a .grimple file that will contain textual representations for the Baf , Jimple and Grimp internal representations respectively. Additionally a processed type can be outputed in the Jasmin assembler format, as a .jasmin file.

OPTIONS

Input Options

At present, only the textual representation of Soot's Jimple internal representation can be parsed. Soot can also read .class files directly.

--src-prec jimple
By default soot will resolve types from .class files. If a type cannot be resolved from a classfile, soot will attempt to resolve it from a .jimple file. This option specifies the opposite policy: types are to resolved from .jimple files and only if this fails will an attempt be made to resolve them from .class files.

Output Options

-b, --b
Produces .b files. These contain an abbreviated textual form for soot's Baf internal representation. It is easier to read than its non-abbreviated counterpart, but can also contain ambiguities; for instance, method signatures are not uniquely determined.

-B, --baf
Produces .baf files that contain a textual representation for types in soot's Baf internal representation.

-j, --jimp
Produces .jimp files. These contain an abbreviated textual form for soot's Jimple internal representation. Can contain ambiguous references.

-J, --jimple
Produces .jimple files that contain a textual representation for types in soot's Jimple internal representation.

-g, --grimp
Produces .grimp files. These contain an abbreviated textual form for soot's Grimp internal representation. Can contain ambiguous references.

-G, --grimple
Produces .grimple files that contain a textual representation for types in soot's Grimp internal representation.

-s, --jasmin
Produces .jasmin files for types. These can be understood by the jasmin bytecode assembler tool.

-c, --class
Produces Java .class files executable under any Java Virtual Machine.

-d PATH
Specifies that the outputted files are to be stored in PATH. This may be relative to the working directory.

Application Mode Options

These are only valid if soot is invoked in application mode by specifying the --app command line argument.

-x, --exclude PACKAGE] Marks classfiles in PACKAGE (e.g. java.) as context classes. Jimple is not produced for context classes, but the SootClass, SootField and SootMethod signature objects are created.

[-i, --include PACKAGE] Marks the classfiles in PACKAGE (e.g. java.util.) as application classes. This option can be used to transform library types which by default are not transformed by soot.

[-a, --analyze-context
Relabels all context classes as library classes. This means that Jimple now gets produced for them.

--dynamic-path PATH
Marks all class files in PATH as potentially dynamic classes. This allows aggressive optimization of applications for which the set of dynamic classes that can be loaded is known at compile time.

--dynamic-packages PACKAGES
Marks all class files belonging to a package listed in PACKAGES (or one of its subpackages) as potentially dynamic classes. PACKAGES should be a list of packages separated by commas.
Example: --dynamic-packages java.text.resources,spec.benchmarks._213_javac

Single File Mode Options

--process-path PATH
Process all classes in PATH. All the classes found in PATH will be loaded and transformed in single-file mode.

Optimization Options

-O --optimize
Perform scalar optimizations on the classfiles.
-W --whole-optimize
Perform whole program optimizations on the classfiles; this also enables -O.

Miscellaneous Options

--soot-classpath PATH
Use PATH to resolve types. Overrides the soot.class.path system property.

Important note for Windows users

Note that as of release 1, Soot will treat drive letters correctly, but under Windows the path separator must be a backslash ($\backslash$), not a forward slash (/).

--final-rep baf
When producing .baf, .jasmin or .class output, produce the output using Soot's Baf internal representation. See [VRGH$^+$00] for details on this topic.
-t, --time
Print out time statistics about transformations.
--subtract-gc
Attempt to subtract garbage-collection time from the time stats.
-v, --verbose
Verbose mode.
--debug
Avoid catching exceptions and print debug information.
-p, --phase-option PHASE-NAME KEY:VALUE
Set run-time option KEY to VALUE for PHASE-NAME (default for VALUE is true). This option is quite powerful; it is documented in phase options.
-A, --annotation
$\langle$ both | arraybounds | nullpointer $\rangle$] Enables both array bounds and null pointer annotation, or array bounds annotation only, or null pointer check annotation only, respectively.

EXAMPLES

BUGS

None.

History

March 8, 2000: Initial release.

March 11, 2000: Added note for Windows users.

September 1, 2000: Added the --dynamic-packages option.

October 6, 2000: Added the -A, --annotation option.

March 19, 2001: Fixed a minor mistake in the first example.

Bibliography

VRGH$^+$00
Raja Vallée-Rai, Etienne Gagnon, Laurie Hendren, Patrick Lam, Patrice Pominville, and Vijay Sundaresan.
Optimizing Java bytecode using the Soot framework: is it feasible?.
In Compiler Construction, 9th International Conference, CC 2000, April 2000.

About this document ...

Soot Command-Line Documentation

This document was generated using the LaTeX2HTML translator Version 99.2beta6 (1.42)

Copyright © 1993, 1994, 1995, 1996, Nikos Drakos, Computer Based Learning Unit, University of Leeds.
Copyright © 1997, 1998, 1999, Ross Moore, Mathematics Department, Macquarie University, Sydney.

The command line arguments were:
latex2html usage -split 0 -nonavigation -dir foo

The translation was initiated by Winghong Felix KWOK on 2001-03-19


Winghong Felix KWOK 2001-03-19