blob: 8c30f1e551a15eae1e1433d4d087ca5c13b3fb9c [file] [log] [blame]
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>Exporting an RCP Application</title>
<link href="default_style.css" rel=stylesheet>
</head>
<body>
<div align="right">
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<tbody>
<tr>
<td align="left" valign="top" colspan="2" bgcolor="#0080c0"><b><font face="Arial,Helvetica"><font color="#ffffff">Eclipse
Article</font></font></b></td>
</tr>
</tbody>
</table>
</div>
<div align="left">
<h1 title="Exporting an RCP Application"><img src="images/Idea.jpg" align="middle" width="120" height="86"></h1>
</div>
<h1 align="center">Exporting an RCP Application</h1>
<p class="summary">This document intends to provide some tips and tricks to help the
creation of a deployable archive of an RCP application.</p>
<p><b>By Pascal Rapicault, IBM OTI Labs</b><br>
<font size="-1">June 24, 2004</font></p>
<hr width="100%">
<h2>Introduction</h2>
<p>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.</p>
<p>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.</p>
<p>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.
</p>
<p>
</p>
<h3>Identification of the plugins to ship and creation of the feature.</h3>
<p>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.</p>
<h4>Creation of the driving feature</h4>
<p>To start, create a new feature (File &gt; New &gt; Plug-in development &gt; 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.</p>
<h4>Adding the RCP plug-ins</h4>
<p>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 <a href="#Fine-grain control">appendix A</a>.</p>
<p>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.</p>
<p>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.</p>
<h3>Including the root files.</h3>
<p>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.</p>
<p>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".</p>
<p>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.</p>
<h4>Including startup.jar</h4>
<p>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 &lt;YourEclipseInstall&gt;
to a value meaningful for your environment.
<pre>
root = absolute:file:&lt;YourEclipseInstall&gt;/startup.jar
</pre>
Including files from an absolute location is usually not recommanded but greatly simplifies
the export process.
</p>
<h4>Removing the bin.includes</h4>
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.
<h4>Creating a generic config.ini</h4>
<p>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.</p>
<p>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.</p>
<p>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".
<pre>
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
</pre>
<p>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 <a href=#noProduct>Appendix E</a>.
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:
<pre>
eclipse.product = org.eclipse.ui.examples.rcp.browser.product
</pre>
</p>
<h4>Including the config.ini in the root file list</h4>
<p>To add the configuration folder in the set of root files, complement the root property of the RCPExporter by the following value:
<pre>
config.files
</pre>
</p>
<h3>Creating the final zip.</h3>
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.
</p>
<h3><a name="Fine-grain control"></a>Appendix A - Fine-grain control over the plug-ins shipped.</h3>
<p>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.</p>
<p>Once you have the list, I recommand you to add and remove all required elements from
the org.eclipse.rcpHelper feature.</p>
<h3><a name="updateManager"></a>Appendix B - Shipping with update manager</h3>
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
<pre>
osgi.bundles = org.eclipse.osgi, org.eclipse.core.runtime@2, org.eclipse.update.configurator@3
</pre>
because the update manager will discover the other plugins.
<h3><a name="appWithFeature></a>Appendix C - My application is already in a feature</h3>
If your application is already delivered as a feature, do not add the org.eclipse.rcpHelper feature
in your "included feature" list. This would confuse the update manager since it would find the
corresponding feature.xml. Then when you export, select both RCPExporter and org.eclipse.rcpHelper.
<h3><a name="branding"></a>Appendix D - Branding and splash screen</h3>
<p>The branding of an RCP application is provided by the org.eclipse.core.runtime.products extension.
For more details see XXXX.</p>
<p>The splash screen is provided by setting the osgi.splashPath property</p>
<h3><a name="noProduct"></a>Appendix E - I do not have a product</h3>
If you do not have a product replace
<pre>
eclipse.product = org.eclipse.ui.examples.rcp.browser.product
</pre>
by
<pre>
eclipse.application = &lt;yourApplicationId&gt;
</pre>
<h3>Appendix F - I want to ship with a JRE</h3>
<p>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.
</p>
</body>
</html>