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.

Back to top

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.

# 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.

#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.

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

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.

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.

Back to top

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.

@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

Back to top

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.

2. Click File -> New -> Other -> Plug-in Development -> Plug-in Project
3. Call the project HelloWorld, as shown in Figure 5.

4. Select the Hello, World template as shown in Figure 6 and click Finish

5. The next step is to create your options file.
6. Click File -> New -> Other -> Simple -> File, as shown in Figure 7.

7. Create the file in the plug-in root and call the file .options, as shown in Figure 8.

8. Add an option, as shown in Figure 9.

9. Save and close the options file.
10. Now, add some tracing to the plug-in
11. Open the SampleAction class and find the run() method, as shown in Figure 10.

12. Options can be accessed with the following method call
13. 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.

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");
}

14. The last step is to test the plug-in.
15. Click Run -> Run...
16. Select Eclipse Application or Runtime Workbench (this depends on the Eclipse version) and click New, as shown in Figure 11.

17. Switch to the Plug-ins tab and make sure your Hello, World plug-in is selected, as shown in Figure 12.

18. Switch to the Tracing tab.
19. Enable tracing by selecting the checkbox.
20. Select your Hello, World plug-in and turn on the debug option, as shown in Figure 13.

21. Click Apply and then click Run.
22. Once the runtime workbench comes up, try clicking the Hello, World button
23. 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.

Back to top

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.

2. Run the utility with the provided .bat file, as shown in Figure 15.

D:\RAD6\eclipse\debugUtil.bat

• 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

3. Find the JDT core plug-in, as shown in Figure 16.

4. Turn on the options for debug and the builder, as shown in Figure 17.

5. Enter a workspace location or click Browse to find your workspace in the file system, as shown in Figure 18.

6. Click Launch
7. 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.

################################################################################
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
################################################################################

8. Once Eclipse is shut down, the debug utility will be notified with the processes exit code, as shown in Figure 19.

Back to top

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.

Back to top

Download

Information about download methods

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

• IBM Rational Application Developer: Download a trial version from developerWorks.
  
  

Discuss

• Participate in the discussion forum.
  
  
• Rational Software Architect, Software Modeler, Application Developer and Web Developer forum: Ask questions about Rational Application Developer.
  
  

About the author

Matt 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.

Rate this article

Comments

Back to top

Table of contents

• Introduction
• Tracing options
• Problems using the console
• Plug-in tracing from the development side
• The Eclipse debugging utility
• Debugging Eclipse
• Download
• Resources
• About the author
• Comments

Dig deeper into Rational on developerWorks

IBM SmartCloud trial. No charge.

Unleash the power of hybrid cloud computing today!

---

Public and private solutions in one trial.

Special offers