Eclipse Plugin Installation

The Soot Eclipse Plugin

Overview

The Soot - Eclipse Plugin integrates Soot, a Java optimization framework, with the Eclipse IDE for Java, allowing the user to:

• optimize class files automatically and use more advanced optimization Options
• import class files and decompile them using the Dava Decompiler
• use a Jimple editor with syntax highlighting^
• view attribute information at source and IR Levels
• develop analyses with an interactive control flow graph

This plugin works with the Eclipse official release 3.3 (tested on 3.3.2) and should run in any of the later releases.

Installing the Plugin

There are several ways to install the Soot plugin for Eclipse.

Simple Installation

The easiest way to install the Soot-Eclipse plugin is to download the Eclipse Plugin Quickstart zip from the Soot download page, and expand it inside the root directory of your Eclipse installation. This package contains compiled versions of everything you need to run Soot in Eclipse: the plugin itself, Soot, Jasmin and Polyglot; these are all placed in subdirectories of your Eclipse "plugins" and "features" directories.

Download

Eclipse Update Site

There is also an Eclipse Update Site that you can add to your Eclipse installation and use to obtain the plugin.

Custom Installation

For various reasons (such as building Soot from source), you may not want to install everything in your Eclipse plugins directory. If you are installing the Soot-Eclipse plugin by hand, you must ensure the following:

• The plugin must be compiled. In the main soot directory there is a file called ant.settings.template. Make a copy of this file, named ant.settings, and edit it to reflect the locations of your directories. This is the same settings file for all of Soot so you may have already modified it. Then you can run "ant eclipse-plugin" to compile the plugin.

• The following files and directories from soot/eclipse/ca.mcgill.sable.soot must be copied or symlinked to a directory named ca.mcgill.sable.soot in your Eclipse plugins directory: soot-plugin.jar, plugin.xml, plugin.properties, icons. It is OK to just copy or symlink the whole ca.mcgill.sable.soot directory into the Eclipse plugins directory.

• The plugin.xml file is Eclipse's way of specifying, among other things, where to find class files (much the same information as is given in the CLASSPATH when running Java from the command line).

• The Soot plugin must be able to find the classes of Soot and of Jasmin and of Polyglot (this is new - a version of Polyglot can be downloaded from the Soot downloads page in a jar format). Their locations are specified inside the plugins.xml by <library> tags inside the <runtime> tag. The plugin.xml contains some sample paths that you can edit. As on the CLASSPATH, either jars or directories containing classes are allowed. Pathnames can be absolute, or relative to the plugins/ca.mcgill.sable.soot directory. Eclipse seems to have a bug (or feature) which causes it to ignore .. (parent directory) in the path.

• The online help for the plugin is located in the directory soot/eclipse/ca.mcgill.sable.soot in the Soot distribution. In order to install it in Eclipse (recommended), the doc directory and the three files toc.xml, toc_Concepts.xml and toc_Reference.xml must be copied or symlinked into the ca.mcgill.sable.soot directory in your Eclispe plugins directory.

Using the Eclipse Plugin

Once you have installed the soot-eclipse plugin and restarted Eclipse you must make the menus available by the following:

• Select Window -- Customize Perspective
• Expand Other option in the tree
• Click on soot then OK

Now under the Project menu there should be a Soot section (the menu items may be grayed out at this point).

You must also switch to the Java Perspective in Eclipse: Select Window -- Open Perspective -- Java. This isn't actually necessary to use Soot, but it is if you want to demonstrate that your Java class runs.

As Soot runs on java classes, you must create or import some. Example:

Step 1: click File -> New -> Project
This brings up the New Project Dialog
Step 2: click Java then Java Project then Next
Step 3: enter a name for your project and click Next
This brings you to New Java Project Dialog and the Source Tab
Step 4: click Add Folder
This brings you to the Source Folder Selection Dialog
Step 5: click Create New Folder
Step 6: enter src for Folder Name and click OK
Step 7: click OK
Step 8: click Yes in response to the question about changing folders
Step 9: click Finish

You now have a project with a src folder ready for use. For more information about Eclipse Help see www.eclipse.org (look for Online Help section).

Caveat: source folder. One note, currently there are problems with the soot plugin in you don't make a src folder in your Java project and instead use the project as the source folder. What happens is the first time you run Soot everything works fine, except that the sootOutput folder automatically becomes a package (as the project output folder is the project folder). The second time you run Soot (at the project level) it tries to process files inside the sootOutput folder which are not on the class path and all sorts of errors occur. So don't do this.

Running Soot on all the classes in the output folder of your project:

• First build the classes.
• Then select any java file in the project.
• Then select Project -- Soot and any menu item: ** There are currently four: ** Create Jimple for Project - creates Jimple files ** Dava Decompile Project - decompiles ** Run Soot ... - opens a dialog box containing all Soot options ** Manage Configurations ... - opens a dialog where you can create and save, edit, remove and run different configurations of the Soot options

Running Soot on imported folder of classes:

• Select any class file. Right click and select Soot -- and any menu item (they are similar to the project menu items)
• Select the foler. Right click and select Soot -- Dava Decompile (to decompile all the classes in your imported folder of classes)

Running Soot on files:

• Select the file. Right click and select Soot -- and any menu item (they are similar to the project menu items)

Attributes:

Selecting Output Options -- Output Format -- Jimple File and under Jimple Annotations Pack:

Null Pointer Check Options -- unselect Disabled -- select Only Array Ref

Array Bounds Check Options -- unselect Disabled -- select With All

Running this configuration causes a bunch of attribute tags to be generated. After running open a generated Jimple File and there should be markers in the file indicating attributes. Mouse over the line in the editor with a marker and you should see a tooltip with the attribute. Also these attributes tooltips should appear in the original Java source file.

Note: One other note: For long-running memory intensive Soot configurations Eclipse may run out of memory. To handle this start Eclipse with: eclipse -vmargs -Xmx300M