soot.options.soot-options.txt Maven / Gradle / Ivy

Go to download
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 ...