UserGuide:Getting Started

From WalaWiki

Jump to: navigation, search

This page steps through the process to download, build, and run a core subset of WALA for standard Java analysis. Later we will describe other available components, in addition to this core subset.

Contents

[edit]

Prerequisites

[edit]

Prerequisites for WALA versions 1.1.1 and later

WALA relies on Java 5.0.

The WALA framework relies on support from Eclipse. You are strongly encouraged to begin exploring WALA from within a fresh Eclipse 3.3 workspace. You can download Eclipse from http://www.eclipse.org/downloads/. WALA is packaged as a bunch of Eclipse plug-ins; you will need a version of Eclipse that includes the Plugin Development Tools. ("For Java Developers" only won't cut it.)

[edit]

Getting the code

All WALA framework code is currently stored in the SourceForge subversion repository: https://wala.svn.sourceforge.net/svnroot/wala . You can work out of the trunk/ branch, or stick with a previous release from the tags branch.

We recommend you install SubClipse to provide subversion support for Eclipse: see http://subclipse.tigris.org/install.html.

To get started, we concentrate on a core subset of WALA for standard Java analysis. Download the following projects (e.g. from the trunk branch) which provide functionality to analyze standard (non-J2EE) Java bytecode: 

   * com.ibm.wala.core (javadoc) (source)
         o core WALA framework support
   * com.ibm.wala.shrike (javadoc) (source)
         o Shrike bytecode manipulation library
   * com.ibm.wala.core.tests (javadoc) (source)
         o basic WALA example programs
[edit]

Building the code

If you import the code as Eclipse projects from the SVN perspective, Eclipse should build everything automatically. Ignore any compiler warnings.

Build problems? Please let me know how to update these instructions.

If you don't use Eclipse, we have some ant scripts that should work. Bug Steve to update these instructions to describe the ant scripts.

[edit]

Configuring WALA properties

You will need to set up a few Java properties files before you can run the WALA code.

In the com.ibm.wala.core project, you need to copy the file dat/wala.properties.sample to dat/wala.properties. You need to then edit wala.properties to reflect your environment. See the properties file for the detailed instructions on what properties you must set. For beginners, we recommend you set the java_runtime_dir property (which is mandatory) and the output_dir property.

In the com.ibm.wala.core.tests project, you need to copy the file dat/wala.examples.properties.sample to dat/wala.examples.properties. For the moment, there are no mandatory settings in this file that you need to worry about, so move on. We will describe a few of the other optional properties shortly.

Note that on Windows all paths must be specified using '/' and not '\'!

[edit]

Running WALA Example programs

We will now step through a few example programs, which will analyze the JLex program from Princeton University. First, you will need a file JLex.jar holding the contents of this program:

  1. Download Main.java http://www.cs.princeton.edu/~appel/modern/java/JLex/Archive/1.2.6/Main.java to a directory of your choice; we'll call it $INPUT_DIRECTORY/JLex. Note that case matters ... the L is uppercase.
  2. Compile the file: javac JLex/Main.java
  3. Create a JLex.jar file: jar cvf JLex.jar JLex/*.class
  • Tip: We recommend you use the launchers we have provided for each example program. If you create your own launch configuration, be sure to specify an adequate heap size, such as 800MB via VM argument -Xmx800MB.
[edit]

Example 1: SWTTypeHierarchy

Our first example program will do the following:

  1. Invoke WALA to build a Java type hierarchy
  2. Spawn an SWT TreeViewer to visualize the type hierarhcy

Use the launcher SWTTypeHierarchy, found within com.ibm.wala.core.tests. (View and edit launchers via Eclipe's Run... drop-down menu.)

Problems? See UserGuide:Troubleshooting.

[edit]

Example 2: GVTypeHierarchy

This example builds a Java type hierarchy, renders a vizualization of the tree using dot, and visualizes it using ghostview.

To run this example, first install the AT&T dot tool from http://www.graphviz.org . Also install gsview from http://www.cs.wisc.edu/~ghost/ .

Next, edit the com.ibm.wala.core.tests/dat/wala.examples.properties file to have the correct paths to the dot and ghostview executables.

Now run the GVTypeHierarchy launcher. (Edit the command-line arguments appropriately, as before). This program should soon launch a viewer for a postscript file representing the type hierarchy.

A common issue:

  • Problem: in ghostview, the graph appears chopped off; can't see the whole graph
    • Fix: dot is generating a larger page size than your ghostview is set to show. Use "Media settings..." in ghostview to force a larger page size.

Other Problems? See UserGuide:Troubleshooting.

  • Tip: dot will choke on large graphs. Don't do it.
[edit]

Other basic examples

The com.ibm.wala.core.tests project contains a number of other simple driver programs, in the package com.ibm.wala.examples.drivers. You should now be able to figure out how to run any of them, using the steps documented above in Examples 1-2.

As of this writing, in addition to Examples 1-2, available example drivers include:

  • ClassPrinter : the WALA (Shrike) equivalent of javap (in the shrike project)
  • GVCallGraph: builds a call graph and ghostviews a postscript representation generated with dot
  • GVWalaIR: builds a WALA IR for a method and ghostviews a postscript representation generated with dot
  • SWTCallGraph: builds a call graph and spawns an SWT TreeViewer to browse it
  • SWTPointsTo: performs pointer analysis and spawns an SWT TreeViewer to browse the results
[edit]

Getting started with WALA CAst, the front end for multiple source languages

WALA now includes the WALA Common Abstract Syntax Tree (CAst) System, a front end for generating IR from program source. Currently there are front ends for Java and JavaScript on the WALA site. The Java front end makes use of polyglot to parse Java and generate Abstract Syntax Trees (ASTs); The JavaScript front end makes use of Rhino to parse JavaScript and create ASTs.

Due to these dependencies and the fact that we cannot distribute these prerequisites directly, there are a couple of build steps needed to get CAst working for you. First of all, you need to obtain the following projects from the trunk of WALA's subversion: 

 * com.ibm.wala.cast (javadoc) (source)
   o The core CAst System machinery
 * com.ibm.wala.cast.java (javadoc) (source)
   o The CAst-based Java front end
 * com.ibm.wala.cast.js (javadoc) (source)
   o The CAst-based JavaScript front end

The JavaScript and Java projects both require libraries that are not included in the repository at this site for legal reasons. For Java, you will need to obtain the latest version of polyglot from here, and install the class files as polyglot.jar and java_cup.jar in the lib/ directory of com.ibm.wala.cast.java. For JavaScript, you will need to obtain the latest version of JavaScript from here and install it as js.jar in the lib/ directory of com.ibm.wala.cast.js; you will also need to put a recent copy of Xalan in xalan.jar in the same directory.

The lib/ directories of com.ibm.wala.cast.java and com.ibm.wala.cast.js each contain a script fetch_libraries.sh that will download and install the appropriate libraries in their respective directories. These are bash scripts that require only basic utilities such as wget, tar, etc.

We also recommend getting the projects of sanity tests for the CAst System front end; that way, you can test that you have things installed and can re-run the tests when you change or update anything. The test projects are the following: 

 * com.ibm.wala.cast.java.test (javadoc) (source)
   o Tests for the CAst-based Java front end
 * com.ibm.wala.cast.js.test (javadoc) (source)
   o Tests for the CAst-based JavaScript front end
[edit]

Getting started on a MAC

On Mac OS X 10.4.9, JRE 5 is available by default. Standard Eclipse for Mac works fine. You need to install the SVN, JST, WST, etc. plugins to download and compile Wala. This is no different from Windows. In wala.properties, the Java runtime directory is at the following location: 

 * java_runtime_dir = /System/Library/Frameworks/JavaVM.framework/Classes

If you need to run Wala examples, you need dot and ghostview. You need to install GraphViz tool (native Mac distribution from www.pixelglow.com/graphviz/) and MacGSView. The latter is available from various sites as a .sit file. To unback the .sit file, you need to fetch the StuffIt tool. See Mac Help on instructions for how to install the StuffIt tool--as it is not standard on Mac OS X 10.4.9. Once these are installed, you need to have the following lines in wala.examples.properties: 

 * ghostview_exe = /Applications/MacGSView/MacGSView
 * dot_exe = /Applications/Graphviz.app/Contents/MacOS/dot

(Programmatic launch of ghostview does not seem to work well for one contributor ... suggestions welcome)

Various build.xml files in Wala distribution on sourceforge have Windows paths in them. One might need to generate a build.xml from the project's MANIFEST.MF file (right click and see the menu). Let me know which ones and we can fix them. Sjfink

[edit]

Incubator projects

In addition to the functionality listed above, WALA has a number of incubator projects. These projects live in the incubator branch of subversion, and not trunk. Incubator projects are not-yet quite ready for prime time, and will likely be less stable, documented, or supported than the rest of WALA.

If you would like to use WALA as a plugin within Eclipse, you should take a look at our Eclipse integration incubator project.

Retrieved from "http://wala.sourceforge.net/wiki/index.php/UserGuide:Getting_Started"
Personal tools
project information