Sometimes plug-in developers write their plug-ins and test them in the Eclipse environment and everything works fine. But then they export their plug-in and try to run it in an Eclipse build and its not there. Here are a few debugging tips for plug-in developers to help them figure out what is going on within the Eclipse system. These tips are also handy when supplying Eclipse plug-in developers information in bug reports when you are trying to help them track down problems.

Note that this document was written with a win32 system in mind but most items can be applied to other platforms.

Eclipse has a log file where problems are recorded and usually this is the first thing that an Eclipse developer asks for when you report a problem. The log file can be found in a couple of places:

• Workspace log - This is the most common location for the log file, It is stored in your workspace in the meta-data directory. Check out workspace/.metadata/.log.
• Configuration log - Sometimes information is recored in the configuration log file instead of the workspace log. (especially if the workspace hasn't been created yet, there isn't one, or it cannot be created) Check your configuration area for a configuration log file. (configuration/<timestamp>.log)
• Startup - Occasionally problems happen in the system really early before there is a workspace and before there is a configuration area. This means that there is nowhere to write the log file so information is written to the console, See the notes below on running with a console to get these messages.

When you double-click on the Eclipse icon, the Eclipse executable searches your path and runs the first Java executable that it finds. This can be problematic people aren't always aware of what they have installed. Sometimes multiple Java VMs may be on your path but an older version may appear first so that is the one that is being used to run Eclipse. Its always best to explicitly run with a known vm using the -vm command line argument and specifying the path to the executable.

eclipse -vm c:\jdks\java_1.4.2_06\jre\bin\java.exe

When you double-click on the Eclipse icon to start Eclipse, by default it runs with javaw.exe. This is nice because there is one less item in your system tray (and hey its all about real estate) but you really need that console if something goes wrong. Therefore we recommend you run Eclipse with the regular java.exe and not the javaw.exe. (use the same command-line as above)

If you are running with a console, then you are able to ask the VM for a stack dump of the threads that are currently running. In the console, hit ctrl-break to get this output. This is useful especially in deadlocking scenerios so you can see exactly what is going on.

Above when we said "console" we meant DOS console but just so they don't feel left out OSGi has a console too! And it can provide you with lots of useful information. Start Eclipse with the -console command line argument to start the OSGi console. The "ss" command will print out a list of plug-ins in the system and their current state. This is very helpful when trying to debug if your new plug-in is actually being recognized by the system.

eclipse -console

Generally in Eclipse when you get an error, a message and stack trace is logged to your workspace log. This is great but can easily be missed unless you are looking for it. And some plug-ins silently log entries to the log file. Tsk tsk. In order to never miss entries being logged, we use the -consoleLog command-line argument. This basically means "anything you log to the log file should be logged to the console as well".

eclipse -consoleLog

Most plug-ins take advantage of the debug options file mechanism that the runtime provides. This means that you can provide a file with a list of key/value pairs of debug options and the appropriate plug-ins will recognize this and print out their debug information.

Most plug-ins which use this mechanism provide a default .options file in their plug-in for users to copy and edit for their debugging purposes. See the example .options files in the org.eclipse.osgi and org.eclipse.core.runtime plug-ins.

With the -debug command line argument you can optionally specify the location of the debug options file to use. If you don't specify one, then it is assumed that the file is named .options and it is found in the same folders as the Eclipse executable.

Even if you use -debug without specifying a file path and no options file exists at the default location, some basic debug information will be displayed.

Note that all debug information is displayed to the console and not to a log file.

eclipse -debug
eclipse -debug c:\eclipse\my_profile.debug

If you are having problems getting the system to pick up your new plug-in, then perhaps your configuration is out of date. This might be the case if you just unzipped a new plug-in into your /plugins directory and started up...Eclipse had parsed and cached the list of plug-ins that were previously in that directory and now it has changed without it recognizing that fact. You can clear any per-configuration cached data by using the -clean command line argument.

Note that -clean flushes the registry caches (amung other information) and forces the plug-in manifests to be parsed in order to regenerate the registry. This is not optimal for everyone all the time because (depending on the size of your development environment) it may take up to a couple of minutes.

eclipse -clean

There are other optional arguments that can be passed along to the VM and these must be put at the end of the command-line. Common arguments to pass are the maximum VM heap size and values for System properties.

eclipse -vmargs -Xmx384M -Dmy.property=true

That's a lot of information and command-line arguments. Here is an example where it is all put together.

eclipse -vm c:\jdks\java_1.4.2_06\jre\bin\java.exe -console -consoleLog -debug -vmargs -Xmx384M