Running and Debugging

You can test your plugin in a special sandbox called the runtime workbench. This way, even if the runtime workbench gets corrupted, Eclipse still works. This is available in the Overview page by clicking on either the link "Launch a runtime workbench" or "Launch a runtime workbench in Debug mode." The first time you run the runtime workbench, the folder eclipse\runtime-workbench-workspace is created. A new Eclipse instance is started. It is exactly like the normal Eclipse window, except now your plugin is available.

But first create a Java project from the menu File -> New -> Project and select Java Project. The name of the project should be Test. Figure 6 shows the runtime workbench with the wizard and editor we created.

Figure 6. Running the plugin

Now let's have a look at the Invokatron wizard. This is visible from the menu File -> New -> Other. Look at the category Invokatron Wizard. Select Invokatron Wizard and click Next. This wizard creates an empty Invokatron document. Select the Test project in the Container field and click Finish. A new Invokatron editor shows up. This editor has three pages: a text editor page, a Properties page (font selection), and a Preview page (sorted words, drawn with the selected font).

In the few next articles of this column, we'll add graphical widgets and Java code generation to our plugin.

Supporting Files

There are many places where you can specify what files are required for your plugin to compile and run. This makes things confusing for us Eclipse users. Let's try to clarify some of these issues.

Supporting files come in three categories:

Classes and resources that form the plugin code itself. These are packaged together by the build process into one or more .jar files.

Classes and resources that are needed to compile and run the plugin. These are to be included in the classpath, and we must specify that they'll be copied when exporting.

Resources that are included with plugin, such as a readme.txt file. These aren't in the classpath.

The compilation environment can be set up in the Build page of the plugin editor. Again, this maps to the build.properties file. This page may be confusing at first, as it has four separate sections:

Runtime Information: Lists the produced library files (output for category 1). Usually, there's only one library file that contains all of the classes of your plugin, but you may want to separate this into smaller chunks.

Source Build: lists the class files that should be included in the .jar file(s) (input for category 1).

Binary Build: Lists the files (category 3) that should be copied to the exported plugin folder or archive. The produced library file(s) are included in this automatically when the above box is checked.

Extra Classpath Entries: Lists the .jar files (category 2) that are needed by your application for compilation (which not produced by compiling your code). These are automatically added to your project's libraries. It is a typical mistake to include a .jar file in both the Java Build Path in the project's Properties and in this list.

If your plugin uses a special library, make sure you add it to your project. Then add it to the Source Build and the Extra Classpath Entries.

Other important pages in the plugin editor are:

Dependencies: If your plugin depends on other plugins, you must specify so here.

Runtime: In this page, you can specify special behavior of the plugin.

These are more advanced and will be covered in another article.

Exporting

Once the plugin is coded, and tested in the workbench, it is ready to be deployed to the "real" Eclipse environment. To do this, go to the Overview page and click on the Export Wizard link. The Export Options box allows you to choose among three types of deployments:

A directory structure: Deploys the files in a folder ready to be used by Eclipse immediately. The Destination can then be set to your local Eclipse folder (e.g., c:\dev\eclipse) to use the plugin directly.

A single .zip file: That same folder is compressed into a .zip file, ready to be shipped to your customers. In turn, they need to unzip the file on top of their Eclipse folder to install your plugin. You must specify the name of the .zip file in the File name field.

Individual .jar archive for the Update site: Produces a .jar file that is compatible with the automatic update system used by Eclipse.

Once you click on Finish, the selected output is produced. If you elected to export as a directory structure, you'll have to restart Eclipse for the plugin to take effect.

Looking at the Examples and Source Code

The best source of information about writing Eclipse plugins is the set of many plugin examples that are provided with it. If I had to choose a single source of information to help me write Eclipse plugins, this would be it.

To download these plugins, simply go to the Eclipse downloads page and select the latest version of Eclipse. Then go to the middle of the page, where it says "Example Plug-ins," and download the .zip file (less than 2MB). Unzip this into the folder where Eclipse is located, such as c:\dev, for example. This will create many folders under the folders eclipse/features and eclipse/plugins. The source code for these examples is located in numerous .zip files in the folder C:\dev\eclipse\plugins, listed below.

Editor's Note: we have inserted line breaks in these paths to
accommodate the page layout. Each should be all on one line, without spaces, in your
work.

There are also useful examples of GEF and Draw2D plugins. To get those, go to the GEF page and click on the latest version. Then locate "GEF Examples" in the middle of the Release Build page. Download the .zip file. At the time this was written, it was the file GEF-examples-3.0.1.zip (.5MB). Unzip this into the folder where Eclipse is located (for example, C:\dev). You will see two examples:

Finding Information on Plugin Development

The first place to look is the examples the previous section. Secondly there's the help system, which is of good quality. This is in menu Help -> Help Content. The relevant categories are:

Platform Plug-in Development

JTD Plug-in Development

PDE Guide

Draw2D Developers Guide

GEF Developer Guide

Conclusion

You now have enough information to create amazing, graphical plugins for Eclipse. With so many libraries at your service, only your imagination limits what you can do. The secret is to know what tools are at your disposal and to use the right tool for the right job. In the coming articles of this series, we will explore more areas of plugin development: menus, wizards, dialogs, GEF, Draw2D, etc.