pde-build/articles/export rcp apps/article.html - www.eclipse.org/pde - Git at Google

 <!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>
	<!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 > 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.</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 <YourEclipseInstall>
	to a value meaningful for your environment.
	<pre>
	root = absolute:file:<YourEclipseInstall>/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 = <yourApplicationId>
	</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>