UserGuide:Getting Started
From WalaWiki
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 |
Prerequisites
Prerequisites for WALA 1.2.2 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.4 workspace. You can download Eclipse from http://www.eclipse.org/downloads/. WALA is packaged as a bunch of Eclipse plug-ins, so you will need a version of Eclipse that includes the Plugin Development Tools; we recommend the "Eclipse Classic" download.
- Prerequisites for WALA version 1.1.1 through 1.2.1
- Prerequisites for WALA version 1.0.04 through 1.1
- Prerequisites for WALA versions 1.0.03 and Earlier
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 As of 6/22/2009, you also should get * com.ibm.wala.ide (source) o WALA support that relies on Eclipse IDE functionality * com.ibm.wala.ide.tests (source) o tests for WALA support that relies on Eclipse IDE functionality
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.
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 (required for some tests below like PDFTypeHierarchy). Note that the directory specified for output_dir must exist on the filesystem; WALA will not create it.
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 '\'!
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:
- Download Main.java http://www.cs.princeton.edu/~appel/modern/java/JLex/Archive/1.2.6/Main.java to a directory named JLex. Note that case matters ... the L is uppercase.
- Compile the file: from the parent directory of JLex, run javac JLex/Main.java (ignore any compile warnings)
- Create a JLex.jar file: jar cvf JLex.jar JLex/*.class (again from parent of JLex director)
- Copy JLex.jar to the root of the Eclipse workspace containing WALA.
- 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.
Example 1: SWTTypeHierarchy
Our first example program will do the following:
- Invoke WALA to build a Java type hierarchy
- Spawn an SWT TreeViewer to visualize the type hierarchy
Use the launcher SWTTypeHierarchy, found within com.ibm.wala.core.tests. View and edit launchers via Eclipe's Run -> Run Configurations... drop-down menu. The launcher should already be listed under "Java Applications" in the list of launchers. Click the "Run" button to run the program; this should just work if you copied JLex.jar to the workspace as indicated above. If successful, you should see a new window pop up with a tree view of the class hierarchy of JLex.
Problems? See UserGuide:Troubleshooting.
Example 2: PDFTypeHierarchy
This example builds a Java type hierarchy, renders a vizualization of the tree using dot, and visualizes it using a PDF viewer.
To run this example, first install the AT&T dot tool from http://www.graphviz.org . Also install a PDF viewer if you do not already have one.
Next, edit the com.ibm.wala.core.tests/dat/wala.examples.properties file to have the correct paths to the dot and PDF viewer executables; see suggestions in the file.
Now run the PDFTypeHierarchy launcher. This program should soon launch a viewer for a PDF file representing the type hierarchy.
Problems? See UserGuide:Troubleshooting.
- Tip: dot will choke on large graphs. Don't do it.
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)
- PDFCallGraph: builds a call graph and shows a PDF represention generated with dot
- PDFWalaIR: builds a WALA IR for a method and shows a PDF 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
Getting started with J2EE support
The com.ibm.wala.j2ee package includes some support for analyzing Java EE programs, e.g., code to discover entrypoint methods for servlets. To compile the code in Eclipse 3.4, you'll need the Java EE Developer Tools plugins, which can be installed via the Eclipse's built-in software update functionality (under Available Software, go to Ganymede -> Web and Java EE Development -> Java EE Developer Tools).
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. Both use third-party libraries to actually parse the source, from which CAst ASTs are generated.
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. For both front ends, you must obtain the core CAst projects below from the trunk of WALA's subversion; you also need the WALA core projects described above. You can omit all the test projects, but this is highly discouraged.
* com.ibm.wala.cast (javadoc) (source) o The core CAst System machinery * com.ibm.wala.cast.test (javadoc) (source) o Test support for the CAst
The Java Source Front End
The Java front end has two implementations: one makes use of polyglot to parse Java and generate Abstract Syntax Trees (ASTs); the other is based on the Eclipse JDT and was contributed by Evan Battaglia from Berkeley. For either one, you need the following Java source language support projects, along with the CAst core and WALA core projects.
* com.ibm.wala.cast.java (javadoc) (source) o The CAst-based Java front end * com.ibm.wala.cast.java.test (javadoc) (source) o Tests for the CAst-based Java front end * com.ibm.wala.cast.java.test.data (javadoc) (source) o Test data for the CAst-based Java front end
The test data project requires some steps to build. For legal reasons, we do not include some test program source in the project, so you must obtain that separately. We do provide some support scripts to help. The following ought to work:
1) 'cd' to the root directory of the com.ibm.wala.cast.java.test.data project
2) run ./fetch_tests.sh (this requires 'wget' on your path)
3) to use the JDT tests, export the entire project as a zip file (from Eclipse, File->Export->General->Archive File and check 'zip format') to com.ibm.wala.cast.java.test/testdata/test_project.zip
The Eclipse JDT based front end is in the projects given below. Note that due to the architecture of Eclipse, you currently can use the Eclipse ASTs that this front end needs only in the context of a running Eclipse. Thus, this front end is suitable only for plugins, i.e. for use in Eclipse-based applications. If you know how to get around this limitation, I would love to hear about it. Furthermore, this is only ever tested with Eclipse 3.4.
Note that the regression tests in com.ibm.wala.cast.java.test run as JUnit Plugin tests. If you followed step 3 in the instructions above to export the zip file, the tests should be able to construct the needed workspace automatically. Hence, you should just be able to run them as plugin tests without any further setup.
* com.ibm.wala.cast.java.jdt (javadoc) (source) o The JDT- and CAst-based Java front end * com.ibm.wala.cast.java.jdt.test (javadoc) (source) o Tests for the JDT- and CAst-based Java front end
The Polyglot-based front end supports only up to Java 1.4, since that is what Polyglot handles. Hence, it is not suitable for more-recent Java applications that use Java 5 features such as generic types. This front end is in the projects below.
* com.ibm.wala.cast.java.polyglot (javadoc) (source) o The Polyglot- and CAst-based Java front end * com.ibm.wala.cast.java.polyglot.test (javadoc) (source) o Tests for the Polyglot- and CAst-based Java front end
These Polyglot-based projects require libraries that are not included in the repository at this site for legal reasons. 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.
We have some help for this: the lib/ directories of com.ibm.wala.cast.java.polyglot contains a script fetch_libraries.sh that will download and install the appropriate libraries. This bash script requires a few utilities, wget, tar, ant, to be on your path when running it. The tar likely has to be GNU tar, as it must support the z flag.
The JavaScript Source Front End
The JavaScript front end makes use of Rhino to parse JavaScript and create ASTs. The JavaScript front end needs the projects below, along with the core CAst projects and the WALA projects described above.
* com.ibm.wala.cast.js (javadoc) (source) o The CAst-based JavaScript front end * com.ibm.wala.cast.js.test (javadoc) (source) o Tests for the CAst-based JavaScript front end
For legal reasons, you will need to obtain the latest version of Rhino 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.js contains a script fetch_libraries.sh that will download and install the appropriate libraries. This bash script requires only basic utilities such as wget, tar, etc.
The test data project also requires some steps to build. Once again for legal reasons, we do not include some test program source in the project, so you must obtain that separately. You must cd to the example-src directory of com.ibm.wala.cast.js.test and run fetch_tests.sh
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
Otherwise, the general instructions above should work; let us know if they don't.
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
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.
Eclipse Plugin for WALA
- If you would like to use WALA as a plugin within Eclipse, you should take a look at our Eclipse integration incubator project.
Dynamic Load-time Instrumentation Library for Java (Dila)
- Dila uses customized class loading for instrumenting the byte code of a program before it is executed. During the execution of an instrumented program dynamic program representations, such as call graphs, are created, which can be used for various program analyses. Getting started with Dila.
