TACLE: Downloading and Getting Started
Introduction
TACLE stands for type analysis and call
graph construction for Eclipse. The purpose of this Eclipse
plug-in is to provide information about types of expressions and about
calling relationships between methods in a Java program. Such
information plays an important role in a variety of static analyses
for object-oriented software. The current release implements the
well-known rapid type analysis (RTA) algorithm for Java 1.4
programs.
Additional details about the design of TACLE are available in the
paper Building a Whole-Program Type Analysis
in Eclipse, Mariana Sharp, Jason Sawin, and Atanas Rountev,
Eclipse Technology Exchange Workshop (eTX'05), pages 10-14,
October 2005. [ PDF ] [ BibTeX ] [ Talk ].
Some approaches for reporting the progress of the analysis are described in
Estimating the Run-Time Progress of a Call Graph Construction Algorithm,
Jason Sawin and Atanas Rountev,
IEEE International Workshop on Source Code Analysis and
Manipulation (SCAM'06), pages 53-62, September 2006.
[ PDF ]
[ BibTeX ]
[ Talk ].
Quick Links
Requirements
- Eclipse 3.0 or Eclipse 3.1 (download at www.eclipse.org/downloads)
- 700 MHz (or better) processor is recommended
- 24M of disk space
- 512 MB RAM minimum; 1 GB RAM recommended
- Java 1.4.*
Installation and Running
- Download and unzip the plug-in file tacle_x_y_z.zip into your
main "eclipse" directory (e.g. "C:\Program
Files\eclipse\"). This is the directory that has the main Eclipse
executable (e.g.. eclipse.exe) and the "plugins" and
"features" subfolders.
- Restart (or start) Eclipse. Note: Eclipse should be executed
with the -vmargs -Xmx800m (or higher) option, in order to have sufficient JVM
heap memory.
- Try the examples distributed with TACLE to
ensure that the plug-in was installed successfully.
API
Documentation
Features of the current release
- [new] Since version 1.2.0, TACLE can be used to analyze
partial programs. A call to ICallGraphAnalysis.run(IMethod) could
provide an IMethod that is not a main method: that is, the
analysis can start from any method, not just the main method of the
analyzed application. !!!WARNING!!! Starting the analysis from
a method other than the main method may produce an incomplete call
graph because some instantiated classes and reachable methods may be
missed.
- [new] In versions 1.0.0 and 1.1.0, the algorithm
implementation assumed that the analyzed Java project included the
source code for every reachable method (except for methods from the
standard Java libraries). In version 1.2.0 we have relaxed this
restriction: if some reachable method m1 contains a call to m2 such
that m2's source code is not available in the project (and m2 is not
in the standard Java libraries), the analysis simply ignores the call
from m1 to m2. (A warning is printed to standard output when this
happens.) This allows, for example, to analyze programs that use
external JAR files. !!!WARNING!!! Ignoring the calls to unknown
methods may produce an incomplete call graph because some instantiated
classes and reachable methods may be missed.
- [new] Since version 1.2.0, reachable methods and
instantiated classes can be added programmatically by the client code,
using methods addXYZ provided by ICallGraphAnalysis (e.g.,
addInstantiatedClass).
- [new] In versions 1.0.0 and 1.1.0, the call sites inside a
method are represented as instances of interface ICallSite. In version
1.2.0 we have introduced an interface IInstanceCallSite which is a
sub-interface of ICallSite. For a call site of the form x.m(), the
corresponding IInstanceCallSite can be used to determine the possible
types of the objects that x points to — that is, the possible
receiver types at the call site. For each such type, the
IInstanceCallSite can also be used to find the corresponding run-time
target method.
- The analysis is designed to take as input Java 1.4
programs. If you want to analyze Java 1.5, you will have
to wait for a while — we do plan to extend TACLE to
handle the new features of Java 1.5, but it will take
some time. If you are interested in 1.3, 1.2, or even
1.1, you may still be able to use TACLE, with the
following caveat. The current release of TACLE uses
pre-computed library summary information which captures
the semantic effects of the standard Java libraries for
J2SE 1.4 (J2SE 1.4.2, to be more precise). We have not
tried using this summary information together with,
let's say, Java 1.3 programs that were originally
written on top of the J2SE 1.3 standard libraries. If
you try analyzing such programs using TACLE, please let
us know about the outcome of this experiment.
- Methods called from the initialization expressions of instance
fields or from non-static initializer blocks are reported as being
called from the constructors of the class. This is to circumvent the
fact that in Eclipse there are no IMethods (1) for initialization
expressions in instance field declarations, and (2) for non-static
initializer blocks. Thus, method getCalledMethods invoked on a
constructor will return, among others, all methods that could be
invoked by these initialization expressions/blocks. Furthermore, for
each call site inside such initialization expressions/blocks, method
getCallSites invoked on a constructor will return a corresponding
ICallSite instance.
- Constructors are reported to call finalizer methods by
default. This is a way to report finalizers as reachable, since
finalizers are not called explicitly anywhere. Method
getCalledMethods invoked on a constructor will return, among others,
the finalizer method of the class (if it exists). Furthermore,
getCallSites will return, among others, an ICallSite instance that
represents a "fake" call site invoking the finalizer. This fake call
site does not have a source position, and for it methods
ICallSite.getLength() and ICallSite.getStartPosition() return -1.
- Calls to method start() in interface Runnable or in classes
implementing Runnable target automatically the method run() of the
respective class.
- Calls to method doPriviledged() for
java.security.AccessController or a subclass target automatically the
method run() of the respective class.
Known Issues in Version 1.2.0
- Some of these issues will be resolved in the future, in the
next release of TACLE.
- The plug-in is designed only for the features of Java 1.4. See the
comment above about other versions of Java.
- The plug-in uses pre-computed summary information for
rt.jar, jce.jar, jsse.jar, charsets.jar and sunrsasign.jar.
Any class that is not in one of these jars must have
the source code accessible in the build path of the
project in order to be analyzed. The current behavior is
that the analysis ignores a class if the class
is found neither in the summary nor in the source files
accessible in the build path.
- Calls to constructors through "new" expressions are not reported
if the constructor does not exist explicitly in the code (i.e., if
this is an implicit default constructor). This is done because Eclipse
does not have an IMethod object for the implicit constructor. Because
library methods are not processed from source code but rather from
bytecode-based summary information, this restriction does not apply to
them.
- Implicit superclass-constructor calls "super()" in a constructor
are not reported because there is no corresponding AST node. (For an
explicit call to a superclass constructor, getCalledMethods and
getCallSites reflect that call.) Because library methods are not
processed from source code but rather from bytecode-based summary
information, this restriction does not apply to them.
- Method calls made inside static initializers are not reported
anywhere. This is because static initializers are not represented in
Eclipse by IMethods, and they do not appear in the call graph. Because
library methods are not processed from source code but rather from
bytecode-based summary information, this restriction does not apply to
them.
- The analysis does not take into account the effect of reflective
calls, which are currently ignored.
Examples
The main purpose of the TACLE plug-in is to provide clients with an
API so that they can use the analysis solution in their own plug-ins.
However, some sample client code is included in the TACLE
distribution; this code is accessible from the Eclipse IDE. The
purpose of these examples is twofold: (1) to provide concrete examples
of how to use the TACLE API, and (2) to provide a mechanism to check
that TACLE has been installed properly.
Hello TACLE
This is the simplest of the three examples. It generates a dialog box
that reports the number of reachable methods from the main method. To
use it:
- Download and install TACLE as described above.
- Open in Eclipse any Java project that contains a main method.
- In the Java perspective navigate to the main method in the
"Package Explorer" pane.
- Right-click on the main method and select the "Hello TACLE
Action" option (if this option is not shown, either TACLE was not
installed correctly, or Eclipse was not restarted).
- A popup will appear with the number of reachable methods (the
analysis may take several minutes and the IDE will be unavailable for
that time).
Hello TACLE Job
This action has the same functionality as the previous example, but
works as an Eclipse background job that does not block the IDE. To
use it, perform steps 1-4 as described above. The results are
accessible in Eclipse's Progress View. This view can be opened by
clicking on the icon that appears in the lower right corner of the IDE
once the plug-in is started. When the plug-in finishes execution, an
exclamation sign is displayed on the same icon, indicating that the
plug-in generated a message. By clicking on the icon again, the
message is displayed informing on the number of reachable
methods.
Note: This example is using a very simple locking
mechanism to ensure the data integrity of the analysis. If using a
TACLE job in her client code, it is the user's responsibility to
implement a more refined lock that suits her purposes.
Construct Call Graph
The purpose of this example is to demonstrate more fully the TACLE
API. The example generates a .dot file which can be provided as input
to Graphviz to
generate a call graph of the user-level code. (Note: For ease of
readability, only calls from/to user-defined methods will be included
in the graph.) To use it:
- Download and install TACLE as described above.
- Open in Eclipse any Java project that contains
a main method.
- In the Java perspective navigate to the main
method in the "Package Explorer" pane.
- Right-click on the main method and select the "Construct Call
Graph" option (if this option is not shown, either TACLE was not
installed properly, or Eclipse was not restarted).
- A popup will appear informing you where the dot file has been
generated (the analysis may take several minutes and the IDE will
be unavailable for that time).
Help
For help or further information about the TACLE plug-in
please contact any of the following people: