Table of Contents
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 → .
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Always include new resources directly in the build.properties file. This is a good rule to avoid errors after the export of your application.
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.
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.
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.
Create an Eclipse 4 RCP application in a plug-in called com.example.e4.rcp.wizard.
Use the .product file of your com.example.e4.rcp.wizard project to export your Eclipse application.
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.
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.
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.
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.
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.
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.
Verify that the splash is displayed if you start your application from the Eclipse IDE.
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.
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.
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.
Export your product again and validate that the launcher name has changed.
Create a new feature project called com.example.e4.rcp.wizard.feature via → → → → .
Include the com.example.e4.rcp.wizard plug-in into this feature.
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.
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.
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.
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.
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. |
Maintaining high quality free online tutorials is a lot of work. Please support free tutorials by donating or by reporting typos and factual errors.
Please consider a contribution if this article helped you.
