Support free tutorials:











vogella training Training Books



Eclipse Products and Deployment - Tutorial

Lars Vogel

Version 7.3

20.02.2013

Revision History
Revision 0.1 - 7.3 14.08.2007 - 02.01.2014 Lars
Vogel
Several bug fixes and enhancements

Eclipse RCP

This tutorial describes how the product configuration file and the deployment process of Eclipse RCP applications. It is based on Eclipse 4.2 (Eclipse Juno).


Table of Contents

1. Products and branding
1.1. Product and application
1.2. Feature or plug-in based products
1.3. Splash screen
1.4. Icons, launcher name and program arguments
2. Deployment of your application
2.1. Exporting via the product file
2.2. Which artifacts are included in the export?
2.3. Export for multiple platforms via the delta pack
3. JRE and headless build
3.1. Including the required JRE into the export
3.2. Headless build
4. Exercise: Create application
5. Exercise: Export your product
5.1. Export your product
5.2. Add a splash screen
5.3. Include splash screen into the exported application
5.4. Change launcher name
5.5. Create feature project
5.6. Change product configuration file to use features
6. Common problems while exporting your product
6.1. Export problem number #1: export folder is not empty
6.2. Checklist for common export problems
7. Support free vogella tutorials
7.1. Thank you
7.2. Questions and Discussion
8. Links and Literature
8.1. Source Code
8.2. Eclipse product and export resources
8.3. vogella Resources

Get the book Eclipse IDE book

1. Products and branding

1.1. Product and application

A product configuration file, or in shorter form a product, defines the configuration of your Eclipse application, e.g. icons, splash screen and which plug-ins or features are included in your application.

The product is a development artifact which describes the content of your application and is not required at runtime.

A product always points to one Application class. This Application class must implement the IApplication interface and for Eclipse 4 RCP applications it should point to the org.eclipse.e4.ui.workbench.swt.E4Application class.

You define your product configuration via a .product file. A product configuration file can be created via a right-click on your project and by selecting NewProduct Configuration.

On the Overview tab of your product you can start the product.

Pressing the Synchronize link writes the relevant product configuration information into the plugin.xml file.

Product definition file show the overview tab

Warning

It is possible to enter an ID for the product. Avoid using the same ID for the product as for a plug-in as this might create problems during a product export. Convention is to add the .product extension to the ID.

1.2. Feature or plug-in based products

A product can either be based on plug-ins or on features. This setting is done on the Overview tab of the product configuration file.

Configuration of the product can be based on features or plug-ins

On the Dependency tab you maintain the plug-ins or features your products consists of. A product does not perform automatic dependency resolution. If you add a feature to your product and want to add its dependencies, press the Add Required button.

1.3. Splash screen

The Splash tab allows you to specify the plug-in which contains the splash screen. You need to put the splash.bmp file into the project main directory.

Tip

The name and location of the splash.bmp file is predefined in Eclipse, but the path can be changed via the osgi.splashPath parameter, the file name can be changed with the -showsplash path_to_file. See ??? to learn how to set launch parameters.

Show the tab splash from the product configuration file

1.4. Icons, launcher name and program arguments

You can configure the launcher name and icon for your exported product. The launcher is the executable program that is created during the deployment of the product. A launcher is platform specific. For example eclipse.exe on the Windows platform. This launcher has also an icon associated with it. To change the name and the icon, select the Launching tab of your product configuration.

Here you can specify the file name of the launcher and the icon which should be used. Make sure the format of the icons is correct, otherwise Eclipse will not use them.

Tip

The icon configuration depends on the platform you are using. Eclipse allows you to export your application for multiple platforms and uses the correct ones based on your product configuration.

In the Launching Arguments section you can specify parameters for your Eclipse application and arguments for the Java runtime environment. Program Arguments are parameters passed to the Eclipse application.

The relevant sections are highlighted in the following screenshot.

Highlighting the section where the icons are maintained.

2. Deployment of your application

2.1. Exporting via the product file

Your product configuration file can be used to export your application to run outside of Eclipse.

Exporting your product creates a folder with all required artifacts to run your application. This includes a native launcher specific to the platforms, e.g. Windows or Linux, you have exported it for.

To export the product switch to your product configuration file, select the Overview tab and click on the Eclipse Product export wizard link. In the wizard you can specify the location of the exported product via the Directory property in the Destination group/section. The export wizard is depicted in the following screenshot.

The Root directory property can be used to specify a sub-folder in the destination which contains the complete exported application. This is useful if you export the product as an archive file.

The resulting directory can be for example compressed (zipped) and shared with others. The export dialog allows you to create an archive file directly, which makes it easier to transfer all files to another machine.

If you transfer the content of this directory to another machine (with the same architecture, e.g. Linux 64 bit) your application can start on this machine. Of course the correct Java version must be installed there.

2.2. Which artifacts are included in the export?

The plug-ins artifacts which are included in an export are defined by the build.properties file of an plug-in.

Eclipse adds the compiled Java classes by default. You have to add other files manually, e.g. icons or splash screen images.

Make sure the following items (if available) are included in each plug-in of the exported application::

  • META-INF/MANIFEST.MF

  • plugin.xml

  • other static files, e.g. icons, splash.bmp, etc.

  • Application.e4xmi

  • CSS files

  • OSGi service definition files

  • model fragments

  • translation files

An Eclipse application started from the Eclipse IDE will have access to resources which are not contained in the build.properties file, but these files will not be contained in the exported application. Your exported application will therefore fail to find the files.

Tip

Always include new resources directly in the build.properties file. This is a good rule to avoid errors after the export of your application.

2.3. Export for multiple platforms via the delta pack

2.3.1. Delta pack

The delta pack contains the platform specific features and plug-ins which are required to build and export Eclipse applications for multiple platforms. It also includes binary launchers for all platforms in the org.eclipse.equinox.executable feature.

The delta pack can be found on the following URL: Eclipse download page.

Click on the release you are interested in, e.g. 4.3 and search on the resulting page for the Delta word.

Download it and extract it to a new directory.

2.3.2. Make the delta pack available in Eclipse

To make the delta pack available to the Eclipse IDE, add it to your target platform under WindowPreferencesPlug-in DevelopmentTarget Platform.

Add the directory in which the delta pack is located to the target platform.

Afterwards you can export your Eclipse application for multiple platforms.

3. JRE and headless build

3.1. Including the required JRE into the export

You can also deploy your own RCP application bundled with a JRE to make sure that a certain JRE is used. An Eclipse application first searches in the installation directory for a folder called jre and for a contained Java-VM. If it finds one, then this JRE is used to start the Eclipse application.

To include the JRE from your running environment, select the Bundle JRE for this environment with the product flag on the Launching tab of your product configuration file.

3.2. Headless build

A headless build is an automatic build without user interaction and without a graphical user interface. It can be triggered from the command line. Typically the build is automatically done via an additional software component called the build server which does so in a clean (and remote) environment.

An example for a build server would be the Jenkins continuous integration (system). See the online Jenkins tutorial for an introduction into the setup, configuration and usage of Jenkins.

Several solutions exists for building Eclipse RCP applications via a headless build. Currently the most popular approach is based on Apache Maven. See the online Maven Tycho tutorial for an introduction into headless builds for Eclipse RCP applications.

4. Exercise: Create application

Create an Eclipse 4 RCP application in a plug-in called com.example.e4.rcp.wizard.

5. Exercise: Export your product

5.1. Export your product

Use the .product file of your com.example.e4.rcp.wizard project to export your Eclipse application.

Export product

Enter a new directory in the Directory field. If in doubt use the Browse button to find a valid directory. The following screenshot shows an example selection under Ubuntu.

Selecting the output directory in the product export dialog

After the export check the Root directory folder in the Directory folder. A double-click on the native launcher starts your application.

Make sure that you can start the application from your exported directory.

Tip

If you face issues during the product export, check the list of common export problems from Section 6, “Common problems while exporting your product” and try to solve the problem.

5.2. Add a splash screen

Add a splash screen to your application. For this create or download a splash.bmp bitmap file. You find an example under the following URL: Example splash screen.

Add the splash.bmp file to the main directory of your application. You can copy and paste it into the Project Explorer view.

Warning

If you add files outside of the Eclipse IDE, you need to Refresh (via F5) your project in the Project Explorer view, to see the file in Eclipse.

Afterwards your project should look like the following screenshot.

Adding a splash bmp file

Warning

The file name and the location of the file must be correct otherwise Eclipse will not use your splash screen.

On the Splash tab of your product configuration file, define that your application plug-in contains the splash screen.

Adding splash to the product configuration file

Verify that the splash is displayed if you start your application from the Eclipse IDE.

5.3. Include splash screen into the exported application

Configure that the splash.bmp file is included into the exported application by adding it to the build.properties file of your application plug-in.

Add splash to build properties

Export your product again and ensure that the splash screen is also shown if you start the exported application. Make sure that the target directory of the export is empty before you start the export.

5.4. Change launcher name

The Eclipse export defaults the launcher for your Eclipse RCP application to eclipse, e.g. on Windows to eclipse.exe.

Change this launcher name to mywizard on the Launching tab of your product configuration file.

Change launcher name

Export your product again and validate that the launcher name has changed.

5.5. Create feature project

Create a new feature project called com.example.e4.rcp.wizard.feature via FileNewOther...Plug-in DevelopmentFeature Project.

Include the com.example.e4.rcp.wizard plug-in into this feature.

Include plug-in into a feature

5.6. Change product configuration file to use features

Open your product configuration file and select the Overview tab.

Select the option that your product configuration file is based on features. This selection is highlighted in the following screenshot.

Switching to features in the product configuration file.

Add your new feature to this product, as well as the org.eclipse.e4.rcp and its dependencies. As a result of this you should have four features in your product.

Switching to features in the product configuration file.

Warning

All four features are required to start your application. Assure you start via the product and not with an existing launch configuration to ensure that your new product configuration is used.

Test that your application starts from the Eclipse IDE. Afterwards export is again into an empty directory and ensure that it starts also as exported application.

6. Common problems while exporting your product

6.1. Export problem number #1: export folder is not empty

The most common problem is that the folder to which you export is not empty. If you export to a certain folder, ensure that the folder is empty. Exporting twice to the same folder may create file locks or results in error messages reporting version conflicts.

6.2. Checklist for common export problems

If the export encounters a problem please have a look into the following table for a solution:

Table 1. Problems with the product export

Problem Possible cause
Export fails Try using an empty target directory, sometimes the export cannot delete the existing files and therefore fails.
No executable file after the export Check the flag "The product includes native launcher artifacts" in your .product file on the Overview tab.
Product could not be found Validate that all dependencies are included in the product. Delete an existing launch configuration and restart the product from the IDE to see if everything is configured correctly.
Splash screen or other icons are missing Check the build.properties file to see if all required images and icons are included in the export.
Splash screen is missing Ensure that you have entered the defining plug-in in the "Splash" tab on the product configuration file. If this is not set, the splash screen is not displayed after the export. Unfortunately, it is displayed if you start the plug-in from the Eclipse IDE.
Issues during startup Check the log file in the workspace folder of your exported application to see the error messages during startup. Alternatively add the "-consoleLog" parameter to the ".ini" file in folder of the exported application.
applicationXMI argument is missing Check the build.properties file to see if the Application.e4xmi and the plugin.xml files are included in the export.
Service could not be found or injected Make sure that the bundle which provides the service has the Activate this plug-in when one of its classes is loaded flag set. Also make sure that the org.eclipse.equinox.ds bundle is started automatically with a Start Level less than 4.
Application ID could not be found Define a start level of 1 and set auto-start to true for the org.eclipse.core.runtime plug-in.
Translations not available in the exported product Ensure via the build.properties file of the relevant plug-in that the files containing the translations are included in the export.


7. Support free vogella tutorials

Maintaining high quality free online tutorials is a lot of work. Please support free tutorials by donating or by reporting typos and factual errors.

7.1. Thank you

Please consider a contribution if this article helped you.

Flattr this

7.2. Questions and Discussion

If you find errors in this tutorial, please notify me (see the top of the page). Please note that due to the high volume of feedback I receive, I cannot answer questions to your implementation. Ensure you have read the vogella FAQ as I don't respond to questions already answered there.

8. Links and Literature

8.1. Source Code

Source Code of Examples

8.2. Eclipse product and export resources

How to create ico files automatically

8.3. vogella Resources

vogella Training Android and Eclipse Training from the vogella team

Android Tutorial Introduction to Android Programming

GWT Tutorial Program in Java, compile to JavaScript and HTML

Eclipse RCP Tutorial Create native applications in Java

JUnit Tutorial Test your application

Git Tutorial Put all your files in a distributed version control system