soot.options.soot-options.txt Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of robovm-soot Show documentation
Show all versions of robovm-soot Show documentation
RoboVM fork of Soot - A Java optimization framework
Soot Options Proposal
=====================
This is a proposal describing how the Soot options should be cleaned up.
Comments are welcome.
1. Options will be divided into several sections. Each section will consist
of a number of options.
2. Each option will be of a specific type, defining its syntax.
2.a) Boolean options will either be present or absent, and will not take
any arguments.
2.b) Multi-valued (radio) options will take exactly one argument, which
may be one of a pre-defined number of strings. Multiple occurences of
the same multi-valued option with different values will result in an
error. Each multi-valued option will have a default value which will
be used if the option is not present on the command line. Each value
of a multi-valued option may have zero or more aliases (for exmaple,
J and jimple).
2.c) Path options will take exactly one argument, which will be a set
of strings separated by a colon on Unix or a semicolon on Windows.
Multiple occurrences of a path option will cause the values to be
appended, separated with a colon or semicolon depending on the OS.
2.d) Phase options will take exactly two arguments: the phase name
and the options for the phase.
2.e) Macro options will take no arguments, and will expand to some
fixed string of other options. For example, -O will be a macro option
expanding to something like -p jop enabled:true. The expansion of
a macro option will be given in the XML file describing the options.
2.f) A string option takes exactly one string as an argument.
2.g) Additional option types may be added after careful consideration.
3. The syntax @file will be used to read options out of a file. A path
may be specified as part of file, either absolute or relative to the
current directory when Soot is invoked.
4. Each option may have zero or more aliases. Each alias may be
specified with either a single dash or a double dash. That is, we
are removing the rule that long options must have two dashes. This
is consistent with most Java tools, and avoids problems with people
giving the wrong number of dashes. It makes it impossible to group
short options together; however, this was never supported in Soot, and
most Soot options that one would want to group together only have long
versions anyway.
5. The policy for new options will be to have a short form only if
the option is likely to be used often to avoid polluting the limited
space of short options.
6. The current options will be affected as follows:
6.a) The -j, --jimp, --njimple, -s, --jasmin, -J, --jimple, -B,
--baf, -b, -g, -grimp, -G, --grimple, -c, --class, -X, --xml,
--nooutput, --dava, and --final-rep options will be replaced
with a single multi-valued option -o, alias --output-format. Its
values (with aliases) will be:
j jimp
njimple
J jimple
B baf
b
g grimp
G grimple
X xml
n none
s jasmin jasmin-through-baf
jasmin-through-grimp
c class class-through-baf
class-through-grimp
d dava
The default value will be c.
6.b) The --src-prec option will become a multi-valued option with values:
J jimple
c class
6.c) The --soot-class-path option will be removed as it is an
undocumented duplicate of --soot-classpath. A short alias -cp will be
added for --soot-classpath.
6.d) The -cp --soot-classpath, --process-path, -x --exclude, -i --include,
--dynamic-classes, --dynamic-path, --dynamic-packages options will become
path options.
6.e) The -d --output-dir option will become a string option.
6.f) The -h --help, --version, -v --verbose, --time, --subtract-gc,
--app, -a --analyze-context options will become boolean options.
6.g) The short form -t for --time will be removed, as it is rarely used.
6.h) -O --optimize will be a macro option expanding to -p jop enabled:true.
-W --whole-optimize will be a macro option expanding to -p wjop enabled:true.
6.i) The -A option, which is currently very overloaded, will be changed
to:
Boolean option --keep-line-number (replacing -A LineNumber)
Boolean option --keep-bytecode-offset --keep-offset (replacing -A BytecodeOffset)
Macro option --annot-nullpointer (replacing -A nullpointer and -A both)
with expansion -p jtp.npc enabled:true -p jtp.profiling enabled:true -p agg.an enabled:true
Macro option --annot-arraybounds (replacing -A arraybounds and -A both)
with expansion -p wjtp2.ra enabled:true -p jtp.abc enabled:true -p jtp.profiling enabled:true -p agg.an enabled:true
6.j) The people who added the --lazy, --debug, --tag-file options will
speak up, and tell us why they were added, what they do, and where they
are documented, if anywhere. Based on these answers, we will decide what
to do with them.
6.k) The -k --cache-dir, --with-cache options will be removed, as they
were an undocumented quick hack that never really worked.
6.l) The -p --phase-option option will become a phase option.
7) The options will be organized into sections as follows.
General options
-h --help
--version
-v --verbose
--app
Input options
-cp --soot-classpath
--src-prec
Output options
-d --output-dir
-o --output-format
Processing options
-p --phase-option
-O --optimize
-W --whole-optimize
Single-file mode options:
--process-path
Applications mode options:
-i --include
-x --exclude
-a --analyze-context
--dynamic-classes
--dynamic-path
--dynamic-packages
Input attribute options
--keep-line-number
--keep-bytecode-offset --keep-offset
Annotation options:
--annot-arraybounds
--annot-nullpointer
Miscellaneous
--time
--subtract-gc
8) Each option will have a name (for dialog box), a short description
to be displayed in the --help screen, and a long description to be
displayed in the documentation.
9) Phase options will work as they currently do, will all be documented,
and will be classified into several types:
9.a) Boolean
9.b) Multi-valued
9.c) Integer
9.d) Float
10) All options will be specified in an XML file. From this file, we will
generate, using XSLT, the Java source for the parser and for the usage string,
the LaTeX documentation, and the Eclipse dialog. This will ensure that all
of these will remain up-to-date with respect to changes in the options.
An (incomplete) example of such an XML file is attached. There will be
a separate XML file for each phase to simlarly specify the phase options.
A) Old to new option conversion chart (only documented old options listed):
old new
--version unchanged
-h, --help unchanged
-d PATH unchanged
-x, --exclude PACKAGE unchanged
-i, --include PACKAGE unchanged
-a, --analyze-context unchanged
--dynamic-path PATH unchanged
--dynamic-packages PACKAGES unchanged
--dynamic-classes CLASSES unchanged
--process-path PATH unchanged
-O, --optimize unchanged
-W, --whole-optimize unchanged
--soot-classpath PATH unchanged
--src-prec [jimple|class] unchanged
--subtract-gc unchanged
-v --verbose unchanged
-p --phase-option unchanged
--app unchanged
-b, --b -o b
-B, --baf -o B, -o baf
-j, --jimp -o j, -o jimp
-J, --jimple -o J, -o jimple
-g, --grimp etc.
-G, --grimple
-s, --jasmin
-c, --class
-X, --xml
--final-rep grimp -o class-through-grimp
or -o jasmin-through-grimp
--final-rep baf (this is the default)
--final-rep jimple (this is the default when producing Jimple)
-t, --time only --time allowed
-A LineNumber --keep-line-number
-A BytecodeOffset --keep-bytecode-offset --keep-offset
-A arraybounds --annot-arraybounds
-A nullpointer --annot-nullpointer
-A both --annot-arraybounds --annot-nullpointer
--debug To be determined
B) Example XML file:
General Options
Help
help
h
help
display help and exit
This option displays the textual help message and exits immediately without doing any further processing
Version
version
version
output version information and exit
This option outputs the Soot version information and exits immediately without doing any further processing
Verbose
verbose
v
verbose
verbose mode
This option ...
Application Mode
addMode
app
runs in application mode
This option ...
Input Options
Soot Classpath
classpath
cp
soot-classpath
uses given PATH as the classpath for finding classes for Soot processing
This option ...
Input Source Precedence
srcPrec
src-prec
Class File
classFile
c
class
Jimple File
jimpleFile
J
jimple
c
sets the source precedence for Soot
This option ...
Output Options
Output Directory
outputDir
d
output-dir
store produced files in PATH
This option ...
Output Format
outputFormat
o
output-format
Jimp File
jimpFile
j
jimp
Njimple File
njimpFile
njimple
Jimple File
jimpleFile
J
jimple
Baf File
bafFile
B
baf
Aggregated Baf File
bFile
b
Grimp File
grimpFile
g
grimp
Grimple File
grimpleFile
G
grimple
Xml File
xmlFile
X
xml
No Output File
noneFile
n
none
Jasmin File
jasminFile
s
jasmin
jasmin-through-baf
Jasmin Through Grimp File
jasminViaGrimpFile
jasmin-through-grimp
Class File
classFile
c
class
class-through-baf
Class Through Grimp File
classViaGrimpFile
class-through-grimp
Dava Decompiled File
davaFile
d
dava
c
sets the source precedence for Soot
This option ...
Processing Options
Phase Options
phaseOpt
p
phase-option
set run-time option KEY to VALUE for PHASE-NAME
This option ...
Optimize
optimize
O
optimize
-p jop enabled:true
perform scalar optimizations on the classfiles
This option ...
Whole Program Optimize
wholeOptimize
W
whole-optimize
-p wjop enabled:true
perform whole program optimizations on the classfiles
This option ...
Single File Mode Options
Process Path
procPath
process-path
process all classes on the PATH
This option ...
Application Mode Options
Include Package
incPackage
i
include
marks classfiles in PACKAGE (e.g. java.util.)as application classes
This option ...
Exclude Package
excPackage
x
exclude
marks classfiles in PACKAGE (e.g. java.) as context classes
This option ...
Analyze Context
analyzeContext
a
analyze-context
label context classes as library
This option ...
Dynamic Classes
dynClasses
dynamic-classes
marks CLASSES (separated by colons) as potentially dynamic classes
This option ...
Dynamic Path
dynPath
dynamic-path
marks all class files in PATH as potentially dynamic classes
This option ...
Dynamic Package
dynPackage
dynamic-package
marks classfiles in PACKAGES (separated by commas) as potentially dynamic classes
This option ...
Input Attribute Options
Keep Line Number
keepLineNum
keep-line-number
keep line number tables
This option ...
Keep Bytecode Offset
keepByteOffset
keep-bytecode-offset
keep-offset
attach bytecode offset to jimple statement
This option ...
Annotaion Options
Null Pointer Annotation
nullPointerAnn
annot-nullpointer
-p jtp.npc enabled:true -p jtp.profiling enabled:true -p agg.an enabled:true
turn on the annotation for null pointer
This option ...
Array Bounds Annotation
arrayBoundsAnn
annot-arraybounds
-p wjtp2.ra enabled:true -p jtp.abc enabled:true -p jtp.profiling enabled:true -p agg.an enabled:true
turn on the annotation for array bounds check
This option ...
Miscellaneous Options
Time
time
time
print out time statistics about tranformations
This option ...
Subtract Garbage Collection Time
subGC
subtract-gc
attempt to subtract the gc from the time stats
This option ...