Section 9.1.  Exporting Hyperbola - Eclipse Rich Client Platform: Designing, Coding, and Packaging Java Applications

9.1. Exporting Hyperbola

So far, you have been running Hyperbola in-place in the workspace. To export it, you have to identify what parts of the org.eclipsercp.hyperbola project go into the org.eclipsercp.hyperbola plug-in.

Open the plug-in editor for the Hyperbola plug-in and switch to the Build page. The Binary Build section shown in Figure 9-1 lists the set of development-time files and folders that are also part of the Runtime plug-in structure. PDE takes care of adding the compiled Java classes to the build output, but you have to manage the other files. For example, the whole META-INF directory and plugin.xml are required at runtime as they describe the plug-in. These were added to the list in Chapter 4, "The Hyperbola Application," when the project was first created.

In Chapters 5, "Starting the Hyperbola Prototype," and 8, "Branding Hyperbola," you added an icons directory, the splash.bmp file, the about.html file and the plugin.properties fileall of which are runtime artifacts. Update the build specification for the Hyperbola plug-in by checking these resources in the list. If a resource is not checked, it is not included in the output.

To start off, find the hyperbola.product file in the Package Explorer or Navigator. Right-click and choose Export... > Eclipse product. Alternatively, open the product editor, select the Overview page, and click on the Product Export wizard link. Either way, you should see the product export wizard, as shown in Figure 9-2.

First, ensure that the Hyperbola product configuration is selected in the Configuration drop-down. Then, fill in the Root directory, the top-level directory that is embedded in the export output. For example, it is useful to set this to be the name of your product with the version number. This way, people can extract the product and it gets laid out on disk in a descriptive directory structure. For now, use "Hyperbola 1.0" in this field.

Earlier we talked about how the product configuration is an aggregation of information maintained in several different files. Checking the Synchronization checkbox ensures that the product configuration is properly synchronized before exporting. This helps avoid any surprising, and typically quite hard to debug, problems when running the exported product. Leaving this checked is highly recommended.

Next, pick the Export Destination and set the shape of the export Archive file or Directory. This setting does not affect the content of the outputit is the same either way. Choose Directory so you can easily test what you are exporting. Later you can export as an archive to make Hyperbola easier to distribute. Put the output in any convenient location, but remember the root directory entered earlier is appended to the location specified here.

Having set the various options, click Finish and PDE starts the export in the background (i.e., you can continue using Eclipse while the export completes). First, it compiles the code from the workspace according to the configuration you described. The export wizard then gathers the compiled code and required parts of the target and outputs them to the specified location.

When the export is done, c:\Hyperbola 1.0 contains a fully branded Hyperbola that runs outside the workspace. Navigate to c:\Hyperbola 1.0\hyperbola.exe. Notice that the executable has a branded icon. Run the executable and enjoy your completed RCP product!

Undoubtedly you will want to share Hyperbola with your friends and co-workers. Go back and export the product again. This time, specify an Archive file output and mail them the archive.

Cleaning the install When you run from the workspace, PDE takes care of many details. Once you export the product and run it directly from the filesystem, PDE is no longer in the loop and cannot help. This crops up notably in Eclipse's cache management. Typically, Eclipse keeps a number of caches to improve startup time and reduce memory footprint. Since most production installations are not manually modified by users, Eclipse does only rudimentary cache validation on startup. During development, however, there are a number of scenarios where previously installed files are changed without going through the standard channels. For example, if you export Hyperbola on top of a previous installation, some of the plug-in content may change but the plug-in was never "updated" or "uninstalled." As such, the Runtime does not notice the change. To you it appears as though your changes are not being picked up. The easiest way around this is to avoid overwriting or tweaking previous installs. Failing that, however, you can run Eclipse using the -clean command line argument or put the osgi.clean=true system property in the product's config.ini or launcher initialization file. Running this way during development is useful as it tells Eclipse to flush all of its caches and rebuild its state. Startup is a little slower, but you are guaranteed to get the latest information.