| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| <html> |
| <head> |
| <title>Eclipse Platform/Core</title> |
| <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> |
| <link rel="stylesheet" href="http://dev.eclipse.org/default_style.css" type="text/css"> |
| </head> |
| <body> |
| <center> |
| <font class=indextop>core</font><br> |
| <font class=indexsub>the foundation of the platform</font><p></p> |
| <a href="../../main.html">[home]</a> |
| <a href="../../documents.html">[documents]</a> |
| <a href="../../downloads.html">[downloads]</a> |
| <a href="../../resources.html">[resources]</a> |
| <a href="../../planning.html">[planning]</a> |
| <a href="../../testing.html">[testing]</a> |
| </center> |
| <br> |
| |
| <table BORDER=0 CELLPADDING=2 WIDTH="100%" > |
| <tr> |
| <td ALIGN=LEFT VALIGN=TOP COLSPAN="2" BGCOLOR="#0080C0"><b><font face="Arial,Helvetica" color="#FFFFFF">Gathering Information About Your Plug-in</font></b></td> |
| </tr> |
| <!-- |
| <tr> |
| <td ALIGN=RIGHT VALIGN=TOP WIDTH="2%"><img SRC="../../images/Adarrow.gif" BORDER=0 height=16 width=16></td> |
| <td WIDTH="98%"><b>title</b> |
| <ul> |
| <li>item</li> |
| </ul> |
| <p> </p> |
| </td> |
| </tr> |
| --> |
| |
| <tr> |
| <td ALIGN=RIGHT VALIGN=TOP WIDTH="2%"><img SRC="../../images/Adarrow.gif" BORDER=0 height=16 width=16></td> |
| <td WIDTH="98%"><b>Why doesn't my plug-in work? (Debugging your plug-in in the Eclipse SDK)</b> |
| <p>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.</p> |
| <p><em>Note that this document was written with a win32 system in mind but most |
| items can be applied to other platforms.</em></p> |
| <p> </p> |
| </td> |
| </tr> |
| <tr> |
| <td ALIGN=RIGHT VALIGN=TOP WIDTH="2%"><img SRC="../../images/Adarrow.gif" BORDER=0 height=16 width=16></td> |
| <td WIDTH="98%"><b>Where is my Log?</b> |
| <p>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:</p> |
| <ul> |
| <li><em>Workspace log</em> - This is the most common location for the log file, |
| It is stored in your workspace in the meta-data directory. Check out <code>workspace/.metadata/.log</code>.</li> |
| <li><em>Configuration log</em> - 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. (<code>configuration/<timestamp>.log</code>)</li> |
| <li><em>Startup</em> - 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.</li> |
| </ul> |
| <p> </p> |
| </td> |
| </tr> |
| |
| <tr> |
| <td ALIGN=RIGHT VALIGN=TOP WIDTH="2%"><img SRC="../../images/Adarrow.gif" BORDER=0 height=16 width=16></td> |
| <td WIDTH="98%"><b>Know your VM</b> |
| <p>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.</p> |
| <blockquote> |
| <p><code>eclipse -vm c:\jdks\java_1.4.2_06\jre\bin\java.exe</code></p> |
| </blockquote> |
| <p> </p> |
| </td> |
| </tr> |
| |
| <tr> |
| <td ALIGN=RIGHT VALIGN=TOP WIDTH="2%"><img SRC="../../images/Adarrow.gif" BORDER=0 height=16 width=16></td> |
| <td WIDTH="98%"><b>Use a console</b> |
| <p>When you double-click on the Eclipse icon to start Eclipse, by default it runs |
| with <code>javaw.exe</code>. 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 <code>java.exe</code> and <em>not</em> the <code>javaw.exe</code>. |
| (use the same command-line as above)</p> |
| <p> </p> |
| </td> |
| </tr> |
| |
| <tr> |
| <td ALIGN=RIGHT VALIGN=TOP WIDTH="2%"><img SRC="../../images/Adarrow.gif" BORDER=0 height=16 width=16></td> |
| <td WIDTH="98%"><b>Stack dumps</b> |
| <p>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 <code>ctrl-break</code> |
| to get this output. This is useful especially in deadlocking scenerios so you |
| can see exactly what is going on.</p> |
| <p> </p> |
| </td> |
| </tr> |
| |
| <tr> |
| <td ALIGN=RIGHT VALIGN=TOP WIDTH="2%"><img SRC="../../images/Adarrow.gif" BORDER=0 height=16 width=16></td> |
| <td WIDTH="98%"><b>OSGi console</b> |
| <p>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 "<code>ss</code>" 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.</p> |
| <blockquote> |
| <p><code>eclipse -console</code></p> |
| </blockquote> |
| <p> </p> |
| </td> |
| </tr> |
| |
| <tr> |
| <td ALIGN=RIGHT VALIGN=TOP WIDTH="2%"><img SRC="../../images/Adarrow.gif" BORDER=0 height=16 width=16></td> |
| <td WIDTH="98%"><b>Don't Miss Log Entries</b> |
| <p>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 <code>-consoleLog</code> |
| command-line argument. This basically means "anything you log to the log |
| file should be logged to the console as well".</p> |
| <blockquote> |
| <p><code>eclipse -consoleLog</code></p> |
| </blockquote> |
| <p> </p> |
| </td> |
| </tr> |
| |
| <tr> |
| <td ALIGN=RIGHT VALIGN=TOP WIDTH="2%"><img SRC="../../images/Adarrow.gif" BORDER=0 height=16 width=16></td> |
| <td WIDTH="98%"><b>Debug Mode</b> |
| <p>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. </p> |
| <p>Most plug-ins which use this mechanism provide a default <code>.options</code> |
| file in their plug-in for users to copy and edit for their debugging purposes. |
| See the example <code>.options</code> files in the <code>org.eclipse.osgi</code> |
| and <code>org.eclipse.core.runtime</code> plug-ins. </p> |
| <p>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 <code>.options</code> and it is found in the same folders |
| as the Eclipse executable.</p> |
| <p>Even if you use <code>-debug</code> without specifying a file path and no options |
| file exists at the default location, some basic debug information will be displayed.</p> |
| <p>Note that all debug information is displayed to the console and not to |
| a log file.</p> |
| <blockquote> |
| <p><code>eclipse -debug</code><br> |
| <code>eclipse -debug c:\eclipse\my_profile.debug</code></p> |
| </blockquote> |
| <p> </p> |
| </td> |
| </tr> |
| |
| <tr> |
| <td ALIGN=RIGHT VALIGN=TOP WIDTH="2%"><img SRC="../../images/Adarrow.gif" BORDER=0 height=16 width=16></td> |
| <td WIDTH="98%"><b>Cleaning My Configuration</b> |
| <p>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 <code>/plugins</code> 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 <code>-clean</code> |
| command line argument. </p> |
| <p>Note that <code>-clean</code> 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.</p> |
| <blockquote> |
| <p><code>eclipse -clean</code></p> |
| </blockquote> |
| <p> </p> |
| </td> |
| </tr> |
| |
| <tr> |
| <td ALIGN=RIGHT VALIGN=TOP WIDTH="2%"><img SRC="../../images/Adarrow.gif" BORDER=0 height=16 width=16></td> |
| <td WIDTH="98%"><b>VM Args</b> |
| <p>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.</p> |
| <blockquote> |
| <p> <code>eclipse -vmargs -Xmx384M -Dmy.property=true</code></p> |
| </blockquote> |
| <p> </p> |
| </td> |
| </tr> |
| |
| <tr> |
| <td ALIGN=RIGHT VALIGN=TOP WIDTH="2%"><img SRC="../../images/Adarrow.gif" BORDER=0 height=16 width=16></td> |
| <td WIDTH="98%"><b>Putting it all together</b> |
| <p>That's a lot of information and command-line arguments. Here is an example |
| where it is all put together.</p> |
| <p><code>eclipse -vm c:\jdks\java_1.4.2_06\jre\bin\java.exe -console -consoleLog |
| -debug -vmargs -Xmx384M</code></p> |
| <p> </p> |
| <p> </p> |
| </td> |
| </tr> |
| </table> |
| </body> |
| </html> |
