Running Soot

Contributed by Eric Bodden, GitHub account

Download Jar Files

To run Soot at the command line, the first step is to download the Soot .jar file. You can download Jar files from the Maven release repository. You can also download the latest snapshots, which are usually stable.

Now we are ready to give Soot a try!

Using Soot as Command Line

Once you've downloaded the .jar file, you can use the following command to run the Soot: Java –jar soot-version-jar-with-dependencies.jar

1. Processing single files
Soot in general processes a bunch of classes. These classes can come in one of three formats:

• Java source code, i.e. .java files,
• Java bytecode, i.e. .class files, and
• Jimple source, i.e. .jimple files.

Jimple is Soot’s primary intermediate representation, a three-address code representing a simplified version of Java with only around 15 different kinds of statements. You can instruct Soot to convert .java or .class files to .jimple files or the other way around. You can even generate .jimple file from .java, and modify the .jimple with a normal text editor and then convert your .jimple file to .class, thus hand-optimizing your program.

The principal way to have Soot process two classes A and B is just to add them to the command line, which makes them “application classes”:
java -jar soot.jar A B

2. Processing entire directories
You can also process entire directories or JAR files using Soot, using the –process-dir option:
java -jar soot.jar -process-dir

To process a JAR file, just use the same option but provide a path to a JAR instead of a directory. Furthermore, you can use -process-jar-dir to process a directory containing JAR files. Nice, eh? Be careful, though: If you apply the very same command again to the very same folder you will run into a problem now:

What happened? Well, as I noted earlier, Soot places the generated .class files into the folder sootOutput, which resides in the current directory “.”. Therefore Soot now processed the previously generated files, at the same time complaining about the fact that a class of name “A” resides at location ./sootOutput/A and therefore should actually have the name sootOutput.A, i.e. be in the sootOutput package. Therefore, when using the –process-dir option also use the –d option to redirect Soot’s output:
java -jar soot.jar -process-dir /dirpath -d /sootOutputdir

3. Processing certain types of files (.class / .java / .jimple)
Assume you have a directory that contains both A.java and A.class and you invoke Soot as before. In this case Soot will load the definition of A from the file A.class. This may not always be what you want. The –src-prec option tells Soot which input type it should prefer over others. There are four options:

• c or class (default): favour class files as Soot source,
• only-class: use only class files as Soot source,
• J or jimple: favour Jimple files as Soot source, and
• java: favour Java files as Soot source.

So e.g. -src-prec java will load A.java in the above example.

6. Application classes vs. library classes
Classes that Soot actually processes are called “application classes”. This is in opposition to “library classes”, which Soot does not process but only uses for type resolution. Application classes are usually those explicitly stated on the command line or those classes that reside in a directory referred to via –process-dir.

When you use the -app option, however, Soot also processes all classes referenced by these classes. It will not, however, process any classes in the JDK, i.e. classes in one of the java.* and com.sun.*packages. If you wish to include those too you have to use the special –i option, e.g. -i java.. See the guide for this and other command line options.

7. Output of .jimple or .java files
In addition to producing .class files, Soot can also produce .jimple and .java files and others. You can select the output format using the –f option. If you use –f dava to decompile to Java please make sure that the file /lib/jce.jar is on Soot’s classpath.

8. Phase options
Soot supports hundreds of very fine grained options that allow you to tune all the analyses and optimizations to your needs, directly from the command line.

The general format of these command line options is -p PHASE OPT:VAL. To find the complete document of all command-line and phase options please click on the following link below:
https://soot-build.cs.uni-paderborn.de/public/origin/develop/soot/soot-develop/options/soot_options.htm

For instance, let’s say that we want to preserve the names of local variables (if possible) when performing an analysis within Soot. Then we can add the command line option -p jb use-original-names:true. A shortcut is -p jb use-original-names, where the true is implicitly assumed.