| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><html lang="en"> |
| <HEAD> |
| |
| <meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2012. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." > |
| |
| <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1"> |
| <META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css"> |
| |
| <LINK REL="STYLESHEET" HREF="../book.css" CHARSET="ISO-8859-1" TYPE="text/css"> |
| <TITLE>Product installation guidelines</TITLE> |
| |
| <link rel="stylesheet" type="text/css" HREF="../book.css"> |
| </HEAD> |
| <BODY BGCOLOR="#ffffff"> |
| <h2>Product installation guidelines</h2> |
| <p>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.</p> |
| <p>Consider again the sample directory structure for the acmeweb product:</p> |
| <pre>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/ |
| ...</pre> |
| |
| <p>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:</p> |
| <ul> |
| <li>top-level product files (such as the acmeweb.exe)</li> |
| <li>product features and plug-ins</li> |
| <li>the Eclipse platform itself (this includes the contents of the p2 and configuration folder)</li> |
| <li>the Java runtime environment (JRE)</li> |
| <li>files generated by the installation process itself</li> |
| </ul> |
| <p>A proper installation script will produce the appropriate directory structure |
| by doing the following:</p> |
| <ul> |
| <li>allow the user to specify the top level directory of the install (such as <b>c:\acmeweb. |
| </b>We will refer to it as <b>acmeweb</b> for the remaining steps.)</li> |
| <li>ensure that a product is not already installed in the location</li> |
| <li>copy the files as follows: |
| <ul> |
| <li>Top-level product files are copied to <b>acmeweb</b></li> |
| <li>Eclipse files are copied to <b>acmeweb/eclipse </b>using the expected |
| feature and plugin directory structures</li> |
| <li>JRE files are copied to <b>acmeweb/eclipse/jre</b>. If a JRE is |
| already located elsewhere, then the application shortcut should be setup |
| to invoke eclipse with the <b>-vm</b> command line argument so that the |
| location of the JRE is known by the platform</li> |
| <li>Product features and plug-ins are copied to <b>acmeweb/eclipse/features</b> |
| and <b>acmeweb/eclipse/plugins</b></li> |
| <li>Platform configuration information is copied to <b>acmeweb/eclipse/configuration</b></li> |
| <li>Platform update support information is copied to <b>acmeweb/eclipse/p2</b></li> |
| </ul> |
| </li> |
| <li>create a marker file, <b>.eclipseproduct</b>, in <b>acmeweb/eclipse</b>. |
| The marker file is a <b>java.util.Properties</b> format file that indicates |
| the name, id, and version of the product.</li> |
| <li>store any necessary install info (user, license, date) that is to be shown |
| in the about dialog in <b>acmeweb/eclipse/plugins/com.example.acmefeature_1.0.0/about.mappings</b></li> |
| <li>if the primary feature mechanism (pre R3.0) is used to define the product, replace the |
| <b>acmeweb/eclipse/install.ini</b> with one that sets the property <b>feature.default.id |
| </b>to the product's primary feature</li> |
| <li>invoke the product executable using the <b>-initialize</b> 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.</li> |
| </ul> |
| <h3>Multi-user issues</h3> |
| <p>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 <b>workspace</b> |
| directory) from the shared product install directory.</p> |
| <h3>Uninstall issues</h3> |
| <p>When a product is uninstalled, the following concepts are important.</p> |
| <ul> |
| <li><b>all</b> files in the <b>eclipse/features</b> and <b>eclipse/plugins</b> |
| 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.</li> |
| <li>except for the point above, <b>only</b> those files installed by the |
| installation program in other directories should be removed. It is |
| important to preserve any important data, such as the <b> workspace</b> |
| directory, so |
| that reinstalling the product after an uninstall will produce expected |
| results.</li> |
| </ul> |
| <h3>Reinstalling the product</h3> |
| <p>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 <b>acmeweb/eclipse/.eclipseproduct</b>. 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 <b>acmeweb/eclipse/plugins/com.example.acmefeature_1.0.1 </b>would |
| indicate that the 1.0.1 version update had already been applied to the product.</p> |
| <p>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. </p> |
| <p>Additional information on installing products can be found in <a href="../reference/misc/eclipse-install.html">How |
| to write an Eclipse installer</a>.</p> |
| |
| </BODY> |
| </HTML> |