Eclipse Article

Exporting an RCP Application

This document intends to provide some tips and tricks to help the creation of a deployable archive of an RCP application.

By Pascal Rapicault, IBM OTI Labs
June 24, 2004

Introduction

You are done writing your RCP application, it compiles and runs in your workspace and it is now time to distribute it. Unfortunately no "export RCP application" wizard made it into eclipse 3.0. This document intends to provide some tips and tricks to help the creation of a deployable archive of an RCP application.

The approach presented in this document makes use of features to control the build process. Note that this will work independently of your choice to ship your application with or without the eclipse update manager, the features discussed here are only used as a build artifact.

Throughout this document we will use the browser application as an example. The code can be obtained from the project org.eclipse.ui.examples.rcp.browser in the eclipse CVS repository.

Identification of the plugins to ship and creation of the feature.

Identifying what will constitue your application download is the first important step. Of course, you want it to include all your plugins, but you still have to decide if it will only include those or if it will also include the RCP plug-ins. In the first case, you deliver your product under the assumption that the user already has or will download the appropriate RCP runtime for its platform. In the second, you ship everything that is necessary for the well being of your application. In this document we only cover the latter case.

Creation of the driving feature

To start, create a new feature (File > New > Plug-in development > Feature project) and name it "RCPExporter". When the wizard query you for the plug-ins to be contained in the feature, select all the plugins constituting your application. In our example, simply select org.eclipse.ui.examples.rcp.browser.

Adding the RCP plug-ins

It exists several ways to include the plug-ins from the RCP base in your application, here we'll mainly describe the feature driven way. A more finer grained way is given in the appendix A.

The feature driven way is the easiest because it minimizes the number of things you have to worry about to export your first RCP application. To start, fetch from the repository the subproject pde-build-home/articles/export rcp apps/feature/org.eclipse.rcpHelper. It contains a feature.xml that lists all the RCP plug-ins for all the platforms. The content of the build.properties will be detailed later on.

Now open the feature.xml from "RCPExporter" feature, go the "advanced" tab, and "add" the "org.eclipse.rcpHelper" in the set of "included features". This inclusion will cause the plug-ins from the included feature to be packaged with the ones from the including one. In our example exporting "RCPExporter" will also cause the content of org.eclipse.rcpHelper feature to be included.

Including the root files.

What is called root files is the set of files that are part of your application but that are neither plugins nor features and that comes as sibling of those folders. Such files includes for example, the eclipse executable, the startup.jar or the configuration folder.

All eclipse executables for all the platforms are located in the platform-launcher project. To make sure you get the ones matching eclipse 3.0, get the project tagged as "v20040602".

The management of root files is handled by features and their build.properties files. For example, the build.properties of org.eclipse.rcpHelper lists, on a configuration basis, which executable must be included. More details about the meaning of these properties can be found in the Help System in PDE Guide > Getting started > Features > Advanced topic... > Build Configuration. Although, the build.properties provided in org.eclipse.rcpHelper provides most of the files, startup.jar and config.ini are still missing.

Including startup.jar

The inclusion of startup.jar will be controlled by the build.properties of the RCPExporter feature. Open the RCPExporter build.properties file and add the following entry and set <YourEclipseInstall> to a value meaningful for your environment. 

root = absolute:file:<YourEclipseInstall>/startup.jar
Including files from an absolute location is usually not recommanded but greatly simplifies the export process.

Removing the bin.includes

In build.properties files, the bin.includes property controls files that get included into the feature folder. Since we do not want to ship the feature, simply remove the bin.includes entry from the RCPExport build.properties.

Creating a generic config.ini

No eclipse install is complete without a config.ini file. This simple property file drives many runtime aspects of the platform such as the list of initial plug-ins to install and start, the splash screen, etc. as well as the application to run.

This file is usually provided in a configuration folder. Because of the way the root mechanism works, folders that must be added to the root of a product must be localized in a folder. For example in the RCPExporter feature, create a folder config.files containing a folder called "configuration" itself containing the config.ini file.

The first thing to add in this file is the list of plug-ins to install (osgi.bundles). If you are not shipping with the update manager, you have to list all the plug-ins of your application and all the plug-ins from the RCP base. The following snippet lists exhaustively the RCP plug-ins and fragments that you have to put on your osgi.bundles list. Then it is your role to add your plug-ins to this list. In our example simply add "org.eclipse.ui.examples.rcp.browser". 

osgi.bundles = org.eclipse.core.runtime@2:start, org.eclipse.core.expressions, org.eclipse.help, \
  org.eclipse.jface, org.eclipse.osgi.services, org.eclipse.osgi, org.eclipse.swt, org.eclipse.swt.gtk, \
  org.eclipse.swt.carbon, org.eclipse.swt.gtk64, org.eclipse.swt.motif, org.eclipse.swt.photon,\
  org.eclipse.swt.win32, org.eclipse.ui.workbench, org.eclipse.ui

The second important setting is the product, which defines which application to run (see XXX). If your application do not define a product, take a look at Appendix E. The value of this property must be the "id" of your product as given in the org.eclipse.core.runtime.products extension (see XXX). In our example it is: 

eclipse.product = org.eclipse.ui.examples.rcp.browser.product

Including the config.ini in the root file list

To add the configuration folder in the set of root files, complement the root property of the RCPExporter by the following value: 

config.files

Creating the final zip.

It is now time to create the final archive that will contain your application. Given all the setup we've done so far, the final step is really done by clicks by using the feature export wizard (File > Export... > Deployable Features). Select the RCPExporter feature and deploy as a "single zip file". A few seconds after your click on Finish you will find your application ready. Congratulation your done.

Appendix A - Fine-grain control over the plug-ins shipped.

If you want to control precisely the plug-ins being shipped with your application, you have to gather a list of all the necessary plug-ins manually. This is a little bit tedious, but you will be guaranteed to obtain the smallest download. To find all the elements of this list, use the "Plug-in dependencies" view, choose "Focus "Focus On..." and select one of your application plugin (here org.eclipse.ui.examples.rcp.browser). While you are navigating the tree that has opened, list all the plugins and add them into the feature (you will have to do that manually using the source pane of the feature editor). Another way to get this list is to create a "run-time workbench" launch configuration, select the "choose plug-ins and fragments to launch from the list" option in the "Plug-ins" tab, select all your plugins and then click "add required plug-ins". Then collect the name of all the plug-ins that are checked and you get your list.

Once you have the list, I recommand you to add and remove all required elements from the org.eclipse.rcpHelper feature.

Appendix B - Shipping with update manager

If you are shipping your product with the update manager (ie: your application uses org.eclipse.update.configurator and/or org.eclipse.update.core), first make sure that those plug-ins are listed in one of the feature. Then you can reduce the list of initial bundles to 
 
osgi.bundles = org.eclipse.osgi, org.eclipse.core.runtime@2, org.eclipse.update.configurator@3
because the update manager will discover the other plugins.

Appendix D - Branding and splash screen

The branding of an RCP application is provided by the org.eclipse.core.runtime.products extension. For more details see XXXX.

The splash screen is provided by setting the osgi.splashPath property

Appendix E - I do not have a product

If you do not have a product replace 
eclipse.product = org.eclipse.ui.examples.rcp.browser.product
by 
eclipse.application = <yourApplicationId>

Appendix F - I want to ship with a JRE

First of all make sure you have the legal rights to do that. Eclipse will automatically use any JRE located in a folder called JRE in the root of the eclipse root. To automate the inclusion of a JRE in your application, simply include a JRE in your root files. For that put your JRE in a folder that you will include thanks to the root property.