Product installation guidelines

Product Installation Guidelines

The platform provides standard tools for updating and extending products. In order to participate in the platform mechanisms for updating and extending products, your packaged product should follow the following guidelines. This will allow your product to peacefully coexist with, or even enhance, other Eclipse based products.

Consider again the sample directory structure for the acmeweb product:

acmeweb/
	acmeweb.exe
	eclipse/	
		.eclipseproduct
		artifacts.xml	
		eclipse.exe	
		install.ini	
		.config/	
			platform.cfg
		jre/
		dropins/
		features/	
			com.example.acme.acmefeature_1.0.0/
				feature.xml
			...
		plugins/
			com.example.acme.acmefeature_1.0.0/
				plugin.xml
				about.ini
				about.html
				about.mappings
				about.properties
				acme.png
				plugin_customization.ini
				splash.bmp
				welcome.xml
			com.example.acme.acmewebsupport_1.0.0/
			...
		links/
			...
		p2/
			...

Where did these files come from? Let's look at the product content from the perspective of the development team. The installed files can be grouped into five main categories:

top-level product files (such as the acmeweb.exe)
product features and plug-ins
the Eclipse platform itself (this includes the contents of the p2 and configuration folder)
the Java runtime environment (JRE)
files generated by the installation process itself

A proper installation script will produce the appropriate directory structure by doing the following:

allow the user to specify the top level directory of the install (such as c:\acmeweb. We will refer to it as acmeweb for the remaining steps.)
ensure that a product is not already installed in the location
copy the files as follows:
- Top-level product files are copied to acmeweb
- Eclipse files are copied to acmeweb/eclipse using the expected feature and plugin directory structures
- JRE files are copied to acmeweb/eclipse/jre. If a JRE is already located elsewhere, then the application shortcut should be setup to invoke eclipse with the -vm command line argument so that the location of the JRE is known by the platform
- Product features and plug-ins are copied to acmeweb/eclipse/features and acmeweb/eclipse/plugins
- Platform configuration information is copied to acmeweb/eclipse/configuration
- Platform update support information is copied to acmeweb/eclipse/p2
create a marker file, .eclipseproduct, in acmeweb/eclipse. The marker file is a java.util.Properties format file that indicates the name, id, and version of the product.
store any necessary install info (user, license, date) that is to be shown in the about dialog in acmeweb/eclipse/plugins/com.example.acmefeature_1.0.0/about.mappings
if the primary feature mechanism (pre R3.0) is used to define the product, replace the acmeweb/eclipse/install.ini with one that sets the property feature.default.id to the product's primary feature
invoke the product executable using the -initialize option. This causes the platform to quietly perform all time-consuming first-time processing and cache the results, so that when the user starts the product it comes up promptly in an open-for-business state.

Multi-user Issues

When a product is installed with the intention of sharing the installation among multiple users, care must be taken to separate individual user's data (such as the workspace directory) from the shared product install directory.

Uninstall Issues

When a product is uninstalled, the following concepts are important.

all files in the eclipse/features and eclipse/plugins directories should be removed, even if they weren't originally installed by the installation program. This ensures that files added by the platform installer are removed when the product is removed.
except for the point above, only those files installed by the installation program in other directories should be removed. It is important to preserve any important data, such as the workspace directory, so that reinstalling the product after an uninstall will produce expected results.

Reinstalling the Product

When the product is already installed, the installer should allow a service update or upgrade if one is available. The existence of the product can be confirmed by looking for acmeweb/eclipse/.eclipseproduct. The information in this marker file can be used to confirm with the user that the correct product is being updated. The availability of updates can be confirmed with pattern matches against feature names. For example, the presence of acmeweb/eclipse/plugins/com.example.acmefeature_1.0.1 would indicate that the 1.0.1 version update had already been applied to the product.

Once the validity of the reinstall is established, the install program should copy or replace files as needed. If the version of the underlying Eclipse platform has not changed, there is a good chance that complete directories can be ignored. The version numbers appended to the platform features and plugins can be used to determine whether any changes underneath a plug-in or feature's directory are necessary.

Additional information on installing products can be found in How to write an Eclipse installer.