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:
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
- 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.
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.
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
that reinstalling the product after an uninstall will produce expected
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.