Debugging Eclipse plug-ins for the end user

A focus on plug-in tracing to solve problems

This article will discuss the tracing architecture built into Eclipse, and how end users can use these tracing options to debug problems with Eclipse plug-ins. It also covers how plug-in developers can use tracing options in their own plug-ins in order to provide easier support if the plug-in should fail. Accompanying this article is a software client to assist in finding and using tracing options.

Share:

Matt B Rossner (mrossner@ca.ibm.com), IBM Software Service Analyst, Rational products, IBM

Matt RossnerMatt Rossner works with the IBM Rational support team servicing IBM Rational Application Developer and WebSphere Studio. He completed a 16 month internship working on customer problems specializing in Eclipse workbench and J2EE tooling problems. He is currently still working for the IBM Rational support team assisting in other areas while completing his bachelors degree in Computer Science from Ryerson University, Toronto (expected completion December 2006). The author would like to thank Robert Weisz, IBM Rational Application Developer support team lead, for his support in writing this article.



14 February 2006

Introduction

The Eclipse platform is the basis for many IBM products, including IBM® WebSphere® Studio and now IBM® Rational® Application Developer. The Eclipse platform is an applications framework and was designed to accept plug-ins. Given its plug-ins based architecture, Eclipse is componentized. Having each component represented by a seperate plug-in allows for many developers to be working towards a single finished product. With these components working together, however, many unexpected errors may occur. Fortunately, this was anticipated when the platform itself was being developed, and there are many ways to diagnose and solve these problems.

The .log file

When Eclipse encounters a runtime error there is usually an exception being thrown, so the error should get logged in the .log file. The .log file exists for every Eclipse workspace. It will only get created when an error occurs, and it can be found in the workspace under the .metadata directory. For a plug-in developer the information in this file is crucial, as it will usually consist of an exception followed by a stack trace. Developers can follow a stack trace through their own code to determine where the plug-in is failing.

As an end user, the .log file is also a good place to start when looking for problems, but it may appear daunting and not useful to anyone but the plug-in developers themselves. It is a good way to find out which plug-in has failed, but it will not tell the end user much else.


Tracing options

More information can be determined with Eclipse's tracing support. If the plug-in developer took advantage of the tracing facilities, you will find them useful when reporting a problem with the plug-in. If a plug-in supports tracing options it will have an .options file in the root directory of the plug-in. Using these tracing options, some more detailed information about what a plug-in is doing can be obtained. As the name suggests, a trace of the plug-in is generally printed to the console describing the plug-in's activity.

Option files

Option files are similar to Java™ property files, and by default are named .options. The file consists of key/value pairs. Lines beginning with # represent comments. Typically, the options will be true/false options that will turn the option on or off. Other options may include tracing level (DEBUG, WARN, or ERROR) or filters.

Starting Eclipse in debug mode

In order to utilize tracing options and obtain their output, Eclipse must be started in debug mode. The easiest way to start Eclipse in debug mode is to run it from the command line with the -debug argument, as shown in the following example.

D:\RAD6\rationalsdp.exe -debug [options file]

If the optional .options is left out, Eclipse will look for .options in the current directory.

Example: Eclipse builders

Eclipse has two types of builds: full build and incremental build. An incremental build will only build resources that have been modified. This is determined by checking a resource's last state. When a full build is invoked on a project, all the resources in the project will be rebuilt.

When dealing with large projects, a full build can be quite time consuming. Sometimes it may seem like a full build is occurring when it is not necessary. It is possible to determine whether or not a full build is really occurring by using tracing options. For this example, tracing options from the Java development tools plug-in will be used to monitor Java builder activity.

Listing 1 is the .options file provided by Eclipse for the Java Development Tools (JDT) core plug-in.

Listing 1. org.eclipse.jdt.core_3.0.1\.options
# Turn on debug tracing for org.eclipse.jdt.core plug-in
org.eclipse.jdt.core/debug=false

# Reports buffer manager activity
org.eclipse.jdt.core/debug/buffermanager=false

# Reports incremental builder activity : nature of build, built state reading, indictment process
org.eclipse.jdt.core/debug/builder=false

# Reports compiler activity
org.eclipse.jdt.core/debug/compiler=false

# Reports codeassist completion activity : recovered unit, inferred completions
org.eclipse.jdt.core/debug/completion=false

# Reports classpath variable initialization, and classpath container resolution
org.eclipse.jdt.core/debug/cpresolution=false

# Report type hierarchy connections, refreshes and deltas
org.eclipse.jdt.core/debug/hierarchy=false

# Reports background indexer activity: indexing, saving index file, index queries
org.eclipse.jdt.core/debug/indexmanager=false

# Print notified Java element deltas
org.eclipse.jdt.core/debug/javadelta=false
org.eclipse.jdt.core/debug/javadelta/verbose=false

# Reports Java model elements opening/closing
org.eclipse.jdt.core/debug/javamodel=false

# Reports post actions addition/run
org.eclipse.jdt.core/debug/postaction=false

# Reports java search activity
org.eclipse.jdt.core/debug/search=false

# Reports open on selection activity : recovered unit, inferred selection
org.eclipse.jdt.core/debug/selection=false

# Reports access to zip and jar files through the Java model
org.eclipse.jdt.core/debug/zipaccess=false

Options from this file will be used to create a custom .options file. In this example, it would be desirable to track all the builds of projects in the workspace, because they seem to be taking too long. Options of interest in the above file are shown in Listing 2.

Listing 2. builder.options
#This is a global debug option for the plug-in and is necessary for any other options to work
org.eclipse.jdt.core/debug=true

#This will give us information about the builder's activity
org.eclipse.jdt.core/debug/builder=true

Given the Eclipse home directory of D:\RAD6, save the file as D:\RAD6\builder.options.

Run Eclipse with the following command:

D:\RAD6\rationalsdp.exe -debug builder.options

This will open up a console log window and display the output coming from Eclipse, as shown in Figure 1. You can verify that the options file has been loaded.

Figure 1. Eclipse startup output
console log window

After invoking a full build, your output would be similar to that shown in Figure 2 and Listing 3.

Figure 2. Sample output after invoking a full build of the project
Sample output
Listing 3. Output from full build
Starting build of BuilderExample @ Thu Mar 24 13:35:33 EST 2005
FULL build
About to compile example/ExampleC.java
About to compile example/ExampleB.java
About to compile example/ExampleA.java
Writing new class file ExampleC.class
Writing new class file ExampleB.class
Writing new class file ExampleA.class
Recording new state : State for BuilderExample (#0 @ Thu Mar 24 13:35:34 EST 2005)
Finished build of BuilderExample @ Thu Mar 24 13:35:35 EST 2005

After saving ExampleA.java, your output would resemble that in Figure 3. In contrast to the output from a full build, Listing 4 shows output from an incremental build.

Figure 3. Sample output after saving ExampleA.java
sample output
Listing 4. Output from incremental build
Starting build of BuilderExample @ Thu Mar 24 13:37:25 EST 2005
Found source delta for: BuilderExample
Clearing last state : State for BuilderExample (#0 @ Thu Mar 24 13:35:34 EST 2005)
INCREMENTAL build
Compile this changed source file example/ExampleA.java
About to compile example/ExampleA.java
Writing changed class file ExampleA.class
Recording new state : State for BuilderExample (#1 @ Thu Mar 24 13:35:34 EST 2005)
Finished build of BuilderExample @ Thu Mar 24 13:37:25 EST 2005

These are standard invocations of full and incremental builds, but there are many instances where they will get invoked for unknown reasons. In these cases, having this kind of information can be very useful to help you determine the cause. There are many other tracing options for the JDT plug-in.


Problems using the console

There are certain known problems using the console log window. Text can get wrapped because the console window has a limited buffer. As a result, after a long session some text may get cut off. If you want to save this data, you need to copy and paste it from the command window to a text editor. The solution to this problem is to redirect the output to a file. However, redirecting the output from eclipse.exe will not help, as the executable will call a Java™ Virtual Machine (JVM™) and spawn a new process. The new process will simply open a console window and the same problem will occur. Nevertheless, since Eclipse is a Java application, it can be started as a Java process, which allows you to redirect the output successfully. The main class is located in startup.jar. You can start Eclipse with the following command.

java -cp startup.jar org.eclipse.core.launcher.Main

You can append some additional command line arguments to this command to redirect the output to a file:

java -cp startup.jar org.eclipse.core.launcher.Main -debug builder.options > output.txt 2>&1

You can also create a batch file to make this a bit easier, as shown in Listing 5.

Listing 5. rundebug.bat
@echo off
java.exe -cp startup.jar org.eclipse.core.launcher.Main -data %1 -debug %3 > %2 2>&1

REM Usage: rundebug <workspace> <logfile> [options]
REM If [options] is left out, Eclipse will look for .options in the current directory

Plug-in tracing from the development side

As a plug-in developer you may already be familiar with plug-in tracing. This can be useful when testing plug-ins, and the Eclipse Plug-in Development Environment (PDE) workbench has built-in support for plug-in tracing. Let's take a look at how you can add some tracing options to your own plug-in.

Example: Hello World plug-in

  1. First, create a new plug-in, as shown in Figure 4.
Figure 4. New plug-In project
plug-In project
  1. Click File -> New -> Other -> Plug-in Development -> Plug-in Project
  2. Call the project HelloWorld, as shown in Figure 5.
Figure 5. Plug-in project name
project name
  1. Select the Hello, World template as shown in Figure 6 and click Finish
Figure 6. Selecting a Template
Hello, World template selected
  1. The next step is to create your options file.
  2. Click File -> New -> Other -> Simple -> File, as shown in Figure 7.
Figure 7. Create the .options file
.options file
  1. Create the file in the plug-in root and call the file .options, as shown in Figure 8.
Figure 8. New file name
file name
  1. Add an option, as shown in Figure 9.
Figure 9. .options for HelloWorld
adding an option
  1. Save and close the options file.
  2. Now, add some tracing to the plug-in
  3. Open the SampleAction class and find the run() method, as shown in Figure 10.
Figure 10. SampleAction class
selecting run method for SampleAction class
  1. Options can be accessed with the following method call
  2. Platform.getDebugOption(HelloWorldPlugin.getDefault().getBundle().getSymbolicName() + "/debug")

Explanation of the above method call

Platform.getDebugOption(String option)
This will look at the plug-ins options file and return the String value of that option
 
HelloWorldPlugin.getDefault().getBundle().getSymbolicName()
Instead of hard coding the plug-in ID this will return the plug-in ID - this way if the plug-in ID is ever changed the code does not need to be touched
 
"/debug"
We can now append our own specific options

Listing 6 shows the code for SampleAction.

Listing 6. Code for SampleAction.run()
public void run(IAction action) {

	boolean debug = Platform.getDebugOption(
						HelloWorldplug-in.getDefault()
						.getBundle()
						.getSymbolicName() + "/debug")
						.equalsIgnoreCase("TRUE");
	
	if (debug) {
		System.out.println("Opening message dialog");
	}

	MessageDialog.openInformation(window.getShell(), "HelloWorld Plug-in", "Hello, Eclipse world");
}
  1. The last step is to test the plug-in.
  2. Click Run -> Run...
  3. Select Eclipse Application or Runtime Workbench (this depends on the Eclipse version) and click New, as shown in Figure 11.
Figure 11. Create a runtime workbench configuration
workbench configuration
  1. Switch to the Plug-ins tab and make sure your Hello, World plug-in is selected, as shown in Figure 12.
Figure 12. Select plug-ins
Select Hello, World plug-in
  1. Switch to the Tracing tab.
  2. Enable tracing by selecting the checkbox.
  3. Select your Hello, World plug-in and turn on the debug option, as shown in Figure 13.
Figure 13. Enable tracing
debug option enabled
  1. Click Apply and then click Run.
  2. Once the runtime workbench comes up, try clicking the Hello, World button
  3. Switch back to the PDE workbench and your debug message should be printed to the console.

For more information on plug-in development, see PDE does plug-ins in the Resources section.


The Eclipse debugging utility

In order to make the finding and accessing of these tracing options easier, I have created a small software application that provides a GUI interface similar to the one provided by the Eclipse launch configuration--see the Downloads section.

The debugging utility offers some additional features to aid in determining the cause of problems with Eclipse.

  1. Product detection
    • The debugging utility can detect some existing IBM products based on Eclipse, such as WebSphere Studio or Rational Application Developer.
  2. Tracing options
    • Similar to what the runtime workbench configuration offers, the utility will find options for all plug-ins that have an .options file, and they can be turned on or off.
    • The utility also allows you to import an external .options file, or export an .options file with all of the options selected in the utility.
  3. JVM options
    • The J9 JVM (for IBM, Java™ Developer Kit or JDK) can be turned on or off. In addition, verbose Java output may be obtained from the JVM.
    • These features will not be discussed in this article; however, the debugging utility readme describes how to use them.

Running the builder example with the debugging utility

  1. Download and install the utility.
    • Link to utility.
    • Unzip the archive and extract it to the Eclipse home directory, as shown in Figure 14.
Figure 14. Extract files
extract files to the Eclipse home directory
  1. Run the utility with the provided .bat file, as shown in Figure 15.

D:\RAD6\eclipse\debugUtil.bat

Figure 15. The Eclipse debugging utility
running the Eclipse debugging utility
  • Use debugUtil.bat for IBM products.
  • For base Eclipse or other Eclipse-based products, use debugUtil_noVM.bat
    • This will require java.exe to be in the system path
  1. Find the JDT core plug-in, as shown in Figure 16.
Figure 16. Choose a plug-in
selecting JDT core plug-in
  1. Turn on the options for debug and the builder, as shown in Figure 17.
Figure 17. Select tracing options
Select tracing options for debug and the builder
  1. Enter a workspace location or click Browse to find your workspace in the file system, as shown in Figure 18.
Figure 18. Select a workspace
selecting a workspace in the file system
  1. Click Launch
  2. All output will get sent to two log files.
    • System error will go to the debugOutputErr.log file.
    • System out will go to the debugOutput.log file, as shown in Listing 7.
Listing 7. D:\RAD6\eclipse\debugUtil\log\debugOutput.log
################################################################################
Starting session: 7/17/2005--11:21:51.860
################################################################################
Install location:
    file:/d:/RAD6/eclipse/
Configuration file:
    file:/d:/RAD6/eclipse/configuration/config.ini loaded
Configuration location:
    file:/d:/RAD6/eclipse/configuration/
Configuration file:
    file:/d:/RAD6/eclipse/configuration/config.ini loaded
Framework located:
    file:/d:/RAD6/eclipse/plug-ins/org.eclipse.osgi_3.0.1/
Loading framework classpath from:
    file:/d:/RAD6/eclipse/plug-ins/org.eclipse.osgi_3.0.1/eclipse.properties
Loading extension: com.ibm.jxesupport
Framework classpath:
    file:/d:/RAD6/eclipse/plug-ins/org.eclipse.osgi_3.0.1/core.jar
    file:/d:/RAD6/eclipse/plug-ins/org.eclipse.osgi_3.0.1/console.jar
    file:/d:/RAD6/eclipse/plug-ins/org.eclipse.osgi_3.0.1/osgi.jar
    file:/d:/RAD6/eclipse/plug-ins/org.eclipse.osgi_3.0.1/resolver.jar
    file:/d:/RAD6/eclipse/plug-ins/org.eclipse.osgi_3.0.1/defaultAdaptor.jar
    file:/d:/RAD6/eclipse/plug-ins/org.eclipse.osgi_3.0.1/eclipseAdaptor.jar
    file:/d:/RAD6/eclipse/plug-ins/com.ibm.jxesupport_1.3.6/jxesupport.jar
Debug options:
    file:/D:/RAD6/eclipse/debugUtil/options/1124292111652.options loaded
Time to load bundles: 99
Starting application: 14041
Error querying the registry:The system cannot find the file specified.


Starting build of BuilderExample @ Wed Aug 17 11:25:31 EDT 2005
About to read state...
Successfully read state for BuilderExample
Found source delta for: BuilderExample
Clearing last state : State for BuilderExample (#4 @ Wed Aug 17 10:52:07 EDT 2005)
INCREMENTAL build
Compile this changed source file example/ExampleA.java
About to compile example/ExampleA.java
Writing changed class file ExampleA.class
Recording new state : State for BuilderExample (#5 @ Wed Aug 17 10:52:07 EDT 2005)
Finished build of BuilderExample @ Wed Aug 17 11:25:31 EDT 2005
Saving built state for project BuilderExample
Saved in 20 ms
################################################################################
Ending session: 7/17/2005--11:25:40.249
################################################################################
  1. Once Eclipse is shut down, the debug utility will be notified with the processes exit code, as shown in Figure 19.
Figure 19. Process terminated
process exit code

Debugging Eclipse

Having finished this article, you should now be able to use the features available in WebSphere Studio and Rational Application Developer to debug Eclipse plug-ins. As you have seen, the process is not complicated. In addition, you can use the debug utility to redirect the debug output to log files.


Download

DescriptionNameSize
The Eclipse Debugging Utilitydebugutil.zip1.24 MB

Resources

Learn

  • Getting started with the Eclipse Platform: (developerWorks, November 2002) provides a history and overview of Eclipse, including details on how to install Eclipse and plug-ins.
  • PDE does plug-ins: The Plug-in Development Environment (PDE) provides a set of tools that assist the developer in every stage of plug-in development from genesis to deployment. This article chronicles the creation, development, testing, building, and deployment of a simple "Hello World" plug-in using a subset of these tools.
  • Eclipse In Action: A Guide for Java Developers: (Independent Pub Group, 2003) is a must-read for Java developers using Eclipse.
  • Eclipse.org: For information about Eclipse development.
  • IBM Rational Application Developer product page: Find technical documentation, how-to articles, education, downloads, and product information about Rational Application Developer.

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Rational software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Rational, DevOps
ArticleID=103966
ArticleTitle=Debugging Eclipse plug-ins for the end user
publish-date=02142006