7.4 Building and Exporting a Plug-In
Our plug-in is fully debugged and it’s time to share it with the rest of the world. This requires packaging all of its components in a Java archive (.jar). This, too, is a fairly painless process owing to wizards available to help.
There are three steps to going from a working plug-in to its corresponding .jar file:
• Clean up and organize the manifests.
• Configure the build content.
• Build and export the plug-in.
7.4.1 Clean Up and Organize the Manifests
PDE provides an Organize Manifests wizard to help ensure that the information in your MANIFEST.MF file is complete and up to date. Among other things, it gives you the opportunity to override and extend options selected in the Manifest Editor.
The Organize Manifests wizard (Figure 7.9) is accessible from the Overview form in the Exporting section. The various options, which tend to be rather verbose, are:
• Ensure that all packages appear in the MANIFEST.MF: Adds Export-Package declarations for any package in the project that isn’t already exported.
• Mark as internal all packages that match the following filter: Can change the visibility of a package based on its name. The Package filter field is a regular expression that identifies packages to be marked as internal. Internal packages are not available for use by other plug-ins.
• Remove unresolved packages: Removes Export-Package entries that can’t be resolved, probably because they simply don’t exist in the project.
• Calculate ‘uses’ directive for public packages: Does the complex computations for the “uses” directive for packages that other plug-ins have access to. This requires code introspection and can be a lengthy process.
• Handle unresolved dependencies by: Offers the option of removing unresolved dependencies or declaring them as optional. The most common reason a dependency might be unresolved is that an optional plug-in is missing from the configuration.
• Remove unused dependencies: Analyzes the project code for references to unused dependencies, which could result in unnecessary plug-ins being installed at runtime. This can be a time consuming process.
• Add required dependencies: Sort of the complement of the previous option, it looks for dependencies that are not currently included in the manifest. This only finds dependencies for plug-ins listed in the Automated Management of Dependencies section of the Dependencies form of the Manifest Editor. This can be a time consuming operation.
• Remove unnecessary lazy activation headers: Removes so-called “lazy activation headers” if a Bundle-Activator is not defined. The lazy activation header isn’t necessary if a plug-in has nothing to contribute when it is started.
• Delete unnecessary plug-in manifest files: Removes plugin.xml files if a plug-in doesn’t contribute any extensions or extension points.
• Prefix icon paths in plug-in extensions with a $nl$ segment: Modifies icon paths to allow fragments to contribute unique icons for different locales.
• Remove unused keys from the plug-in’s properties file: Finds and removes unused keys in the properties file.
• In most cases the default values are fine.
Figure 7.9: Organize Manifests wizard.
7.4.2 Configure Build Content
The file build.properties defines what is included in the final plug-in. Its contents are specified in the Build form of the Manifest Editor shown in Figure 7.10. Again, for now anyway, the defaults are fine.
Figure 7.10: Build Configuration.
The Binary Build is what you specify for building your plug-in. Oddly, the bin and src directories are not selected, yet they do show up in the actual text of the build.properties file. The Source Build is not commonly used or needed by general users. It’s used if you need to ship source in separate plug-ins rather than in the binary plug-ins.
7.4.3 Build and Export
The final step in creating a deployable plug-in is to build the .jar file and place it somewhere in the file system. The Export Wizard is the last item under Exporting on the Manifest Editor’s Overview form. Clicking that link brings up the dialog in Figure 7.11. The wizard lists the plug-ins that are available to deploy, in this case just our com.eclipsebook.superview project. Check it if it isn’t already checked.
Figure 7.11: Plug-in export wizard.
Select a destination. I chose to store it back in the Superview project folder in the workspace. The wizard stores the .jar file in a subdirectory named plugins/ under the directory you specify. If you’re curious, take a look at the Options and JAR Signing tabs. Click Finish and the plug-in will be built.
The plug-in export wizard can also be accessed from File→Export. Select Plug-in Development→Deployable plug-ins and fragments.
That’s it! You’ve created and deployed an Eclipse plug-in.
7.5 Exploring Further
The PDE provides a number of templates that allow you to explore many features of plug-in extensions. When creating a new plug-in project, at the Plug-in Content dialog, click Next instead of Finish as we did when we created our first plug-in. This brings up the dialog shown in Figure 7.12. Select one and you’ll get a description of what the template creates and what extensions it uses. These are complete, working examples, with reasonably well commented code.
Figure 7.12: PDE plug-in templates.
Try them out!
7.6 Rich Client Platform (RCP)
Up to this point we’ve been using PDE to create plug-ins that operate from within the workbench. We can also use PDE to create so-called rich client applications that build on the Eclipse plug-in architecture, but run as independent programs. The Rich Client Platform, first introduced in version 3.0, is basically a refactoring of the fundamental parts of the Eclipse UI that allows it to be used for non-IDE applications.
Select File→New→Project…→Plug-in Project. Call it “HelloRCP.” In the Plug-in Content dialog, answer “Yes” to “Would you like to create a rich client application?” Click Next to bring up the Templates dialog of Figure 7.13 and select Hello RCP. Click Next. This dialog is just some basic information about our trivial Hello World RCP application. Click Finish.
Figure 7.13: RCP Templates dialog.