Soot Options:

1. Options are divided into several sections. Each section consists of a number of options.

2. Each option is of a specific type, defining its syntax.

2.a) Boolean options are either be present or absent, and will not take any arguments.

2.b) Multi-valued (radio) options 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 result in an error. Each multi-valued option has a default value which is 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 take exactly one argument, which is a set of strings separated by a colon on Unix or a semicolon on Windows. Multiple occurrences of a path option causes the values to be appended, separated with a colon or semicolon depending on the OS.

2.d) Phase options take exactly two arguments: the phase name and the options for the phase.

2.e) Macro options take no arguments, and expand to some fixed string of other options. For example, -O is a macro option expanding to something like -p jop enabled:true. The expansion of a macro option is 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, if the option can not be specified using one of the above types.

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 options are organized into sections as follows.

General options

Input options

Output options

Processing options

Phase Options

Single-file mode options:

Applications mode options:

Input attribute options

Annotation options:

Miscellaneous

7. Each option has 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.

8. Phase options work as they currently do, they are all documented, and are classified into several types:

8.a) Boolean

8.b) Multi-valued

8.c) Integer

8.d) Float

9. All options are specified in an XML file. From this file, we generate, using XSLT, the Java source for the parser and for the usage string, the LaTeX documentation, and the Eclipse dialog. This ensures that all of these will remain up-to-date with respect to changes in the options.

A) Example XML file: see src/soot/options/soot_options.xml

To add a new option the only thing you need to do is update the soot_options.xml file. Everything else is generated.