platform-update-home/doc/eclipse-installer.html
Parent Directory
| 
Revision Log
Revision 1.3 - (view) (download) (as text)
| 1 : | droberts | 1.3 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| 2 : | vlad | 1.1 | <html> |
| 3 : | |||
| 4 : | <head> | ||
| 5 : | <meta http-equiv="Content-Language" content="en-us"> | ||
| 6 : | <meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> | ||
| 7 : | <meta name="GENERATOR" content="Microsoft FrontPage 4.0"> | ||
| 8 : | <meta name="ProgId" content="FrontPage.Editor.Document"> | ||
| 9 : | <title>How to write an Eclipse installer</title> | ||
| 10 : | </head> | ||
| 11 : | |||
| 12 : | <body> | ||
| 13 : | |||
| 14 : | <h1>How to write an Eclipse installer</h1> | ||
| 15 : | jeem | 1.2 | <p>Last modified 11:15 Monday May 6, 2002</p> |
| 16 : | vlad | 1.1 | <p>Eclipse-based products need to be correctly installed on the end user's |
| 17 : | computer. Special-purpose packaging tools, such as <a href="http://www.installshield.com/">InstallShield</a> | ||
| 18 : | and <a href="http://www.rpm.org/">RPM</a>, are often used to build executable | ||
| 19 : | installers that automate installing, updating, and uninstalling. This note | ||
| 20 : | describes how to write an installer for an Eclipse-based product, and for | ||
| 21 : | separately-installable extensions to Eclipse-based products.</p> | ||
| 22 : | <p>We assume that a product development team is responsible for providing the | ||
| 23 : | raw ingredients that will need to find their way to end users' computers | ||
| 24 : | packaged as an executable installer. The creation of executable installers is | ||
| 25 : | scripted, as are the install time actions needed to interact with the end user | ||
| 26 : | and deposit files on their computer. This note described in detail what these | ||
| 27 : | installers need to do and how they should work. </p> | ||
| 28 : | <p>This note should be treated as a recipe for the person responsible for | ||
| 29 : | writing an installer for an Eclipse-based products. Two good reasons why we | ||
| 30 : | recommend all installers writers follow our recipe:</p> | ||
| 31 : | <ul> | ||
| 32 : | <li><b>Product and extension interoperability.</b> By behaving in standard | ||
| 33 : | ways, an installer for one Eclipse-based product or extension automatically | ||
| 34 : | works with products and extensions laid down by other installers. Otherwise | ||
| 35 : | the idiosyncrasies of one product's installer would require matching quirks | ||
| 36 : | in all extension installers that expected to work with that product.</li> | ||
| 37 : | <li><b>Uniformity of install time user interaction.</b> All installers for | ||
| 38 : | Eclipse-based products and extension should interact with the user in the | ||
| 39 : | same manner. There is nothing to having gratuitous variety in this matter.</li> | ||
| 40 : | </ul> | ||
| 41 : | |||
| 42 : | <h2>Product installer creation script</h2> | ||
| 43 : | |||
| 44 : | <p>A product installer should be self-contained - the kind of thing that could | ||
| 45 : | be distributed on a CD and installed on any machine with a suitable operating | ||
| 46 : | system.</p> | ||
| 47 : | <p>Eclipse requires a Java2 Java Runtime Environment (JRE) to run Java code. | ||
| 48 : | JREs are licensed software, obtained from Java vendors. With a license to | ||
| 49 : | redistribute a JRE from a JRE vendor, a company can include a JRE with its | ||
| 50 : | product, and install it on the end user's computer at the same time as the | ||
| 51 : | product. The alternative is to require that a JRE be pre-installed on the end | ||
| 52 : | user's computer, and associated with at product install time. One way or the | ||
| 53 : | other, an Eclipse-based product requires a suitable JRE, and the product | ||
| 54 : | installer must play a role in either installing a JRE or locating and linking to | ||
| 55 : | a pre-existing JRE. </p> | ||
| 56 : | <p>Assume that a JRE is to be installed with the product. A directory containing | ||
| 57 : | the JRE is one input to the installer creation script. Denote this directory | ||
| 58 : | <<i>JRE</i>>. This directory must have a standard JRE directory structure, | ||
| 59 : | with the Java executable is located at <code>jre/bin/java.exe</code> and the class | ||
| 60 : | library at <code>jre/lib/rt.jar</code> below the <<i>JRE</i>> directory. | ||
| 61 : | For reference, the skeletal structure of this directory looks like:</p> | ||
| 62 : | <p><code><<i>JRE</i>>/<br> | ||
| 63 : | jre/<br> | ||
| 64 : | bin/<br> | ||
| 65 : | java.exe<br> | ||
| 66 : | lib/<br> | ||
| 67 : | rt.jar | ||
| 68 : | </code></p> | ||
| 69 : | <p>There are additional files (and subdirectories) in these directories; we've | ||
| 70 : | only shown a sample to give the general structure. Italicized names in italics | ||
| 71 : | are product-specific.</p> | ||
| 72 : | <p>The second input to the installer creation script is a directory, <<code><i>product | ||
| 73 : | head</i></code>>, | ||
| 74 : | containing the product-specific executable launcher and any files unrelated to | ||
| 75 : | Eclipse. For reference, the skeletal | ||
| 76 : | structure of this directory would look like (italics indicate file names that | ||
| 77 : | will vary from product to product):</p> | ||
| 78 : | <p><code><<i>product head</i>>/<br> | ||
| 79 : | <i> acmeproduct.exe<br> | ||
| 80 : | </i> | ||
| 81 : | <br> | ||
| 82 : | </code>The third input to the installer creation script is a directory, <<code><i>product | ||
| 83 : | body</i></code>>, | ||
| 84 : | containing the features and plug-ins developed for the product. For reference, the skeletal | ||
| 85 : | structure of this directory would look like:</p> | ||
| 86 : | <p><code><<i>product body</i>>/<br> | ||
| 87 : | eclipse/<br> | ||
| 88 : | features/<br> | ||
| 89 : | <i>com.example.acme.acmefeature</i>_<i>1.0.0</i>/<br> | ||
| 90 : | feature.xml<br> | ||
| 91 : | <i>com.example.acme.otherfeature</i>_<i>1.0.0</i>/<br> | ||
| 92 : | feature.xml<br> | ||
| 93 : | plugins/<br> | ||
| 94 : | </code> <code> <i>com.example.acme.acmefeature</i>_<i>1.0.0</i>/<br> | ||
| 95 : | plugin.xml<br> | ||
| 96 : | about.ini<br> | ||
| 97 : | about.properties<br> | ||
| 98 : | about.mappings<br> | ||
| 99 : | plugin_customization.ini<br> | ||
| 100 : | jeem | 1.2 | splash.bmp<br> |
| 101 : | vlad | 1.1 | </code> <code> <i>com.example.acme.otherfeature</i>_<i>1.0.0</i>/<br> |
| 102 : | plugin.xml<br> | ||
| 103 : | about.ini<br> | ||
| 104 : | about.properties<br> | ||
| 105 : | about.mappings<br> | ||
| 106 : | </code> <code> <i>com.example.acme.myplugin</i>_<i>1.0.0</i>/<br> | ||
| 107 : | plugin.xml<br> | ||
| 108 : | <i>myplugin</i>.jar<br> | ||
| 109 : | </code> <code> <i>com.example.acme.otherplugin</i>_<i>1.0.0</i>/<br> | ||
| 110 : | plugin.xml<br> | ||
| 111 : | <i>otherplugin</i>.jar | ||
| 112 : | </code></p> | ||
| 113 : | <p>The fourth input to the installer creation script is a directory, <<code><i>platform</i></code>>, | ||
| 114 : | containing the features and plug-ins for the Eclipse platform itself and any third-party tools being included. | ||
| 115 : | This directory also includes the standard Eclipse executable launcher, <code>eclipse.exe</code>, | ||
| 116 : | (named <code>eclipse</code> on Unix operating environment), its companion <code>startup.jar</code>, and any other Eclipse platform files | ||
| 117 : | required to be at the root of the install. For reference, the skeletal | ||
| 118 : | structure of this directory would look like:</p> | ||
| 119 : | <p><code> | ||
| 120 : | <<i>platform</i>><br> | ||
| 121 : | eclipse/<br> | ||
| 122 : | eclipse.exe<br> | ||
| 123 : | startup.jar<br> | ||
| 124 : | features/<br> | ||
| 125 : | org.eclipse.platform_2.0.0/<br> | ||
| 126 : | org.eclipse.platform.win32_2.0.0/<br> | ||
| 127 : | org.eclipse.jdt_2.0.0/<br> | ||
| 128 : | org.eclipse.pde_2.0.0/<br> | ||
| 129 : | plugins/<br> | ||
| 130 : | org.eclipse.platform_2.0.0/<br> | ||
| 131 : | org.eclipse.core.runtime_2.0.0/<br> | ||
| 132 : | org.eclipse.core.boot_2.0.0/<br> | ||
| 133 : | org.eclipse.core.resources_2.0.0/<br> | ||
| 134 : | org.eclipse.ui_2.0.0/<br> | ||
| 135 : | org.eclipse.jdt_2.0.0/<br> | ||
| 136 : | org.eclipse.jdt.core_2.0.0/<br> | ||
| 137 : | org.eclipse.jdt.ui_2.0.0/<br> | ||
| 138 : | org.eclipse.pde_2.0.0/<br> | ||
| 139 : | org.eclipse.pde.core_2.0.0/<br> | ||
| 140 : | org.eclipse.pde.ui_2.0.0/<br> | ||
| 141 : | (more org.eclipse.* plug-in directories)<br> | ||
| 142 : | <br> | ||
| 143 : | </code>The exact contents of the <<i><code>JRE</code></i>>, <<i><code>product | ||
| 144 : | head</code></i>>, <<i><code>product body</code></i>>, | ||
| 145 : | and <<code><i>platform</i></code>> input directories determine what files | ||
| 146 : | will eventually be installed on the end user's computer.</p> | ||
| 147 : | <p>The final inputs to the installer creation script are the id and version | ||
| 148 : | strings for the product's primary feature; e.g., "<code><i>com.example.acme.acmefeature"</i></code>, | ||
| 149 : | and "<code><i>1.0.0</i></code>"; | ||
| 150 : | and the name of the product executable; e.g., "<code><i>acmeproduct</i></code><code>.exe</code>". | ||
| 151 : | For products that do not require their own product executable, this would be the | ||
| 152 : | path of the standard Eclipse executable launcher "<code>eclipse/eclipse.exe</code>". | ||
| 153 : | These strings have special significance to the installer, appearing in file and | ||
| 154 : | directory names, and in the contents of marker files created at install time.</p> | ||
| 155 : | <p>At install time, the installer should behave in the standard manner (further | ||
| 156 : | details follow the list of steps):</p> | ||
| 157 : | <ol> | ||
| 158 : | <li>warn user to exit all programs</li> | ||
| 159 : | <li>introduce the product to be installed</li> | ||
| 160 : | <li>if appropriate, ask the user for the name of the registered owner and for | ||
| 161 : | the license key</li> | ||
| 162 : | <li>display the product's licensing agreement and ask the user to accept</li> | ||
| 163 : | <li>recommend a location on the disk to install the product (but allow user to | ||
| 164 : | override this default)</li> | ||
| 165 : | <li>check that a product or extension is not already stored at the specified | ||
| 166 : | location</li> | ||
| 167 : | <li>ask user to confirm all details of the install</li> | ||
| 168 : | <li>create marker file to mark root of product install</li> | ||
| 169 : | <li>copy files to disk (see below)</li> | ||
| 170 : | <li>if appropriate, insert name of registered owner and license key into the "about | ||
| 171 : | " description</li> | ||
| 172 : | <li>create a desktop shortcut to run the product executable</li> | ||
| 173 : | <li>create an appropriate entry to allow the user to uninstall the product</li> | ||
| 174 : | <li>launch the product executable with -initialize option to perform all | ||
| 175 : | first-time processing</li> | ||
| 176 : | <li>offer to show the product release notes ("readme" file)</li> | ||
| 177 : | </ol> | ||
| 178 : | <p>If the location specified in step 5 is <<code><i>install</i></code>>, | ||
| 179 : | the installer copies all the files in the <<i><code>JRE</code></i>>, <code><<i>platform</i>>, </code> <<i><code>product</code></i>>, | ||
| 180 : | and <code><<i>product plug-ins</i>></code> directories into <<code><i>install</i></code>>.</p> | ||
| 181 : | <table border="1" width="50%"> | ||
| 182 : | <tr> | ||
| 183 : | <td width="50%">Input file</td> | ||
| 184 : | <td width="50%">Installed file</td> | ||
| 185 : | </tr> | ||
| 186 : | <tr> | ||
| 187 : | <td width="50%"><code><<i>JRE</i>>/*</code></td> | ||
| 188 : | <td width="50%"><code><<i>install</i>>/eclipse/*</code></td> | ||
| 189 : | </tr> | ||
| 190 : | <tr> | ||
| 191 : | <td width="50%"><code><<i>product head</i>>/*</code></td> | ||
| 192 : | <td width="50%"><code><<i>install</i>>/*</code></td> | ||
| 193 : | </tr> | ||
| 194 : | <tr> | ||
| 195 : | <td width="50%"><code><<i>product body</i>>/*</code></td> | ||
| 196 : | <td width="50%"><code><<i>install</i>>/*</code></td> | ||
| 197 : | </tr> | ||
| 198 : | <tr> | ||
| 199 : | <td width="50%"><code><<i>platform</i>>/*</code></td> | ||
| 200 : | <td width="50%"><code><<i>install</i>>/*</code></td> | ||
| 201 : | </tr> | ||
| 202 : | </table> | ||
| 203 : | <p>The marker file created in step 8 is <code><<i>install</i>>/</code><code>.eclipseproduct</code> | ||
| 204 : | is used to mark a directory into which an Eclipse-based product has been | ||
| 205 : | installed, primarily for extension installers to locate. This marker file is a <a href="http://java.sun.com/j2se/1.3/docs/api/java/util/Properties.html">java.io.Properties</a> | ||
| 206 : | format file (ISO 8859-1 character encoding with "\" escaping) and | ||
| 207 : | contains the following information that identifies the product to the user and distinguishes | ||
| 208 : | one Eclipse-based product from one another:</p> | ||
| 209 : | <blockquote> | ||
| 210 : | <p><code>name=<i>Acme Visual Tools Pro</i><br> | ||
| 211 : | id=<i>com.example.acme.acmefeature<br> | ||
| 212 : | </i>version=<i>1.0.0</i></code></p> | ||
| 213 : | </blockquote> | ||
| 214 : | <p>The values of the "id" and "version" property are inputs | ||
| 215 : | to the installer creation script; the name of the product is presumably known | ||
| 216 : | and hard-wired. (Products would not ordinarily access this marker file; only | ||
| 217 : | product and extension installers write or read it.)</p> | ||
| 218 : | <p>Step 6 requires checking for an existing <code><<i>install</i>>/eclipse/.eclipseproduct</code> | ||
| 219 : | or <code><<i>install</i>>/eclipse/.eclipseextension</code> file. A | ||
| 220 : | product cannot be installed in exactly the same place as another product or extension.</p> | ||
| 221 : | <p>After installing all files, the top-level structure of the install directory | ||
| 222 : | would contain the following files and subdirectories (and perhaps others):</p> | ||
| 223 : | <p><code><<i>install</i>>/<br> | ||
| 224 : | <i>acmeproduct</i>.exe<br> | ||
| 225 : | eclipse/<br> | ||
| 226 : | .eclipseproduct<br> | ||
| 227 : | eclipse.exe<br> | ||
| 228 : | startup.jar<br> | ||
| 229 : | features/<br> | ||
| 230 : | plugins/<br> | ||
| 231 : | jre/<br> | ||
| 232 : | <br> | ||
| 233 : | </code>If a product installer solicits license information from the user, such as | ||
| 234 : | the name of the registered owner and the license key, this information should | ||
| 235 : | make it into the product "about" dialog (step 10).</p> | ||
| 236 : | <p>This is done by recording the user responses in the "<code>about.mapping</code>" | ||
| 237 : | file in the primary feature's plug-in. For example, at <code><<i>install</i>>/plugins/<i>com.example.acme.acmefeature</i>_<i>1.0.0</i>/about.mapping</code>. | ||
| 238 : | The "<code>about.mapping</code>" file may be pre-existing in the <<i><code>product | ||
| 239 : | head</code></i>> | ||
| 240 : | input, or may need to be created by the installer at install time. | ||
| 241 : | The keys are numbers; the value of the "<i>n</i>" key is substituted | ||
| 242 : | for the substring "<code>{<i>n</i>}</code>" in the "<code>aboutText</code>" property. | ||
| 243 : | For example, if a license key was field number 0, an "<code>about.mapping</code>" | ||
| 244 : | file containing a line like "<code>0=T42-24T-ME4U-U4ME</code>" should | ||
| 245 : | be created.</p> | ||
| 246 : | <p>N.B. | ||
| 247 : | The "<code>about.mapping</code>" file is a <a href="http://java.sun.com/j2se/1.3/docs/api/java/util/Properties.html">java.io.Properties</a> | ||
| 248 : | format file (ISO 8859-1 character encoding with "\" escaping). | ||
| 249 : | When the native character encoding at install time is different from ISO 8859-1, | ||
| 250 : | the installer is responsible for converting the native character encoding to | ||
| 251 : | Unicode and for adding "\" escapes where required. Escaping is required | ||
| 252 : | when the strings contain special characters (such as "\") or non-Latin characters. For example, field number 1 containing the first 3 letters of the Greek | ||
| 253 : | alphabet would be written "<code>1=\u03B1\u03B2\u03B3</code>".</p> | ||
| 254 : | <p>At step 12, the product installer launches the product executable,<code> <<i>install</i>>/<i>acmeproduct</i>.exe</code>, | ||
| 255 : | with the special -initialize option [exact details TBD]. This causes the Eclipse platform to quietly | ||
| 256 : | perform all time-consuming first-time processing and cache the results, so that | ||
| 257 : | when the user starts the product it comes up promptly in an open-for-business | ||
| 258 : | state.</p> | ||
| 259 : | <h3>Uninstaller behavior</h3> | ||
| 260 : | <p>At uninstall time, the uninstaller should behave in the standard manner:</p> | ||
| 261 : | <ol> | ||
| 262 : | <li>warn user to exit all programs, especially the product being uninstalled</li> | ||
| 263 : | <li>ask user to confirm that the product is to be uninstalled</li> | ||
| 264 : | <li>remove all installed files from the <<i><code>install</code></i>> | ||
| 265 : | directory, and <b>all</b> files in <<i><code>install</code></i>><code>/eclipse/features</code> | ||
| 266 : | and <<i><code>install</code></i>><code>/eclipse/plugins</code> including ones put there by parties other than | ||
| 267 : | this installer (e.g., by the Eclipse update manager)</li> | ||
| 268 : | <li>remove desktop shortcut for the product executable</li> | ||
| 269 : | <li>remove entry for product uninstaller</li> | ||
| 270 : | <li>inform user of any files that were not removed</li> | ||
| 271 : | </ol> | ||
| 272 : | <p>When the product is uninstalled, files deposited at | ||
| 273 : | install time should be deleted, along with updated features and plug-ins created | ||
| 274 : | by the Eclipse update manager. <b>Important:</b> At uninstall time, there may be | ||
| 275 : | other directories and files in the <code><<i>install</i>></code> | ||
| 276 : | directory, notably <code><<i>install</i>>/eclipse/workspace/</code>, | ||
| 277 : | <code><<i>install</i>>/eclipse/links/</code>, and <code><<i>install</i>>/eclipse/platform.cfg</code>, | ||
| 278 : | that contain important data | ||
| 279 : | which must be retained when the product is uninstalled. The user must be able to | ||
| 280 : | uninstall and reinstall a product at the same location without losing important | ||
| 281 : | data.</p> | ||
| 282 : | <h3>Installer behavior when product already installed</h3> | ||
| 283 : | <p>When the product is already installed on the user's computer, the installer | ||
| 284 : | should allow a service update or version upgrade to be applied to the installed | ||
| 285 : | product.</p> | ||
| 286 : | <p>At install time, the installer should behave in the standard manner:</p> | ||
| 287 : | <ol> | ||
| 288 : | <li>warn user to exit all programs, especially the product being updated</li> | ||
| 289 : | <li>locate the installed product to be updated, if necessary by searching the | ||
| 290 : | disk for an existing product install or by allowing the user to locate it</li> | ||
| 291 : | <li> determine where this installer is a compatible update</li> | ||
| 292 : | <li>if appropriate, ask the user for the name of the registered owner and for | ||
| 293 : | the license key</li> | ||
| 294 : | <li>display the product's updated licensing agreement and ask the user to accept</li> | ||
| 295 : | <li>ask user to confirm all details of the update</li> | ||
| 296 : | <li>update files to disk (see below)</li> | ||
| 297 : | <li>if required, alter the desktop shortcut to run the product executable</li> | ||
| 298 : | <li>should add modified or newly added files to the list of ones to be removed at uninstall | ||
| 299 : | time (where feasible)</li> | ||
| 300 : | <li>offer to show the product release notes ("readme" file)</li> | ||
| 301 : | </ol> | ||
| 302 : | <p>In step 2, an installed product can be recognized by the presence of an "<code>eclipse</code>" | ||
| 303 : | directory immediately containing a file named "<code>.eclipseproduct</code>". | ||
| 304 : | The parent of the "<code>eclipse</code>" directory is a product's install | ||
| 305 : | directory; i.e., <code><<i>install</i>>/eclipse/.eclipseproduct</code>. | ||
| 306 : | The information contained within this marker file should be shown to the user for | ||
| 307 : | confirmation that the correct product is being updated (there may be several | ||
| 308 : | Eclipse-based product on the user's computer).</p> | ||
| 309 : | <p>The installer should perform compatibility checks in step 3 by simple pattern | ||
| 310 : | matching against subdirectories in the <code><<i>install</i>>/eclipse/features</code> | ||
| 311 : | directory. For example, the presence of a folder matching "<code><i>com.example.acme.otherfeature</i>_<i>1.0.1</i></code>" | ||
| 312 : | would ensure that a certain service update had been applied to the installed | ||
| 313 : | product.</p> | ||
| 314 : | <p>For step 7, the installer may delete or replace any of the files that it | ||
| 315 : | originally installed, and add more files. <b>Important:</b> Several files and directories, | ||
| 316 : | including <code><<i>install</i>>/eclipse/workspace/</code>, <code><<i>install</i>>/eclipse/platform.cfg</code>, | ||
| 317 : | may be co-located with the install and contain important data files | ||
| 318 : | which need to be retained | ||
| 319 : | when the product is upgraded. </p> | ||
| 320 : | <p>In upgrade situations, there is a good chance that most of the files below <code><<i>install</i>>/eclipse/plugins/</code> | ||
| 321 : | are the same (likewise for <code><<i>install</i>>/eclipse/features/</code>). | ||
| 322 : | There is significant opportunity for optimization in <code><<i>install</i>>/eclipse/plugins/</code> | ||
| 323 : | since the subdirectory name, which embeds the plug-in (or fragment) version | ||
| 324 : | number, changes if and only iff any of the files below it change. In other | ||
| 325 : | words, there is no need to touch any files in <code><<i>install</i>>/eclipse/plugins/org.eclipse.ui_2.0.0</code>/ | ||
| 326 : | if this subdirectory should also exist after the upgrade; if any of the plug-in's | ||
| 327 : | files were to change, the plug-in's version number is revised, causing the files | ||
| 328 : | for the upgraded plug-in to be installed in a parallel directory <code><<i>install</i>>/eclipse/plugins/org.eclipse.ui_2.0.1</code>/. </p> | ||
| 329 : | <p>Note also that the product executable must not be launched with -initialize | ||
| 330 : | in the reinstall case, as this would lose important user configuration data.</p> | ||
| 331 : | <h3>Associating a JRE installed elsewhere</h3> | ||
| 332 : | <p>The JRE is expected to be located at <code><<i>install</i>>/eclipse/jre/bin/javaw.exe</code>. | ||
| 333 : | If it is located elsewhere, the absolute path should be specified using the <code>-vm</code> | ||
| 334 : | option on the command line; e.g.,<code> -vm <a href="file:///c:/j2jre1.3.0/jre/bin/javaw.exe">C:\j2jre1.3.0\jre\bin\javaw.exe</a></code>. | ||
| 335 : | In which case, the installer should add this option to the command line of the desktop shortcut | ||
| 336 : | it creates.</p> | ||
| 337 : | <h2>Extension installer creation script</h2> | ||
| 338 : | |||
| 339 : | <p>By extension we mean a separately installable set of features and their plug-ins that | ||
| 340 : | can be associated with, and used from, one ore more Eclipse-based products installed on the | ||
| 341 : | same computer. In contrast to a product, an extension is not self-contained; an extension does not include | ||
| 342 : | a product executable, the Eclipse platform, a JRE.</p> | ||
| 343 : | <p>Without loss of generality, assume that an extension consists of a single | ||
| 344 : | feature. The first input to the installer creation script is a directory, <<code><i>extension</i></code>>, | ||
| 345 : | containing its feature and plug-ins. We are assuming that an extension has no | ||
| 346 : | files that are related to Eclipse; if it did, they would go in <code><<i>extension</i>>/</code>, | ||
| 347 : | and not in <code><<i>extension</i>>/eclipse/</code>. For reference, the skeletal | ||
| 348 : | structure of this directory would look like:</p> | ||
| 349 : | <p><code><<i>extension</i>>/<br> | ||
| 350 : | eclipse/<br> | ||
| 351 : | features/<br> | ||
| 352 : | <i>com.example.wiley.anvilfeature</i>_<i>1.0.0</i>/<br> | ||
| 353 : | feature.xml<br> | ||
| 354 : | plugins/<br> | ||
| 355 : | </code> <code> <i>com.example.wiley.anvilfeature</i>_<i>1.0.0</i>/<br> | ||
| 356 : | plugin.xml<br> | ||
| 357 : | about.ini<br> | ||
| 358 : | about.properties<br> | ||
| 359 : | about.mappings<br> | ||
| 360 : | </code> <code> <i>com.example.wiley.mainplugin</i>_<i>1.0.0</i>/<br> | ||
| 361 : | </code> <code> <i>com.example.wiley.otherplugin</i>_<i>1.0.0</i>/ | ||
| 362 : | </code></p> | ||
| 363 : | <p>The exact contents of the <<i><code>extension</code></i>> input | ||
| 364 : | directory determines what files | ||
| 365 : | will eventually be installed on the end user's computer.</p> | ||
| 366 : | <p>The final inputs to the installer creation script are the id and version | ||
| 367 : | strings for the extension's feature; e.g., "<i><code>com.example.wiley.anvil</code></i>" | ||
| 368 : | and "<code><i>1.0.0</i></code>". These strings have special | ||
| 369 : | significance to the installer, appearing in file and directory names, and in the | ||
| 370 : | contents of marker files created at install time.</p> | ||
| 371 : | <p>An extension installer is similar to a product installer in most respects. | ||
| 372 : | The areas where it differs are highlighted below:</p> | ||
| 373 : | <p>At install time, the installer behaves in the standard manner:</p> | ||
| 374 : | <ol> | ||
| 375 : | <li>warn user to exit all programs</li> | ||
| 376 : | <li>introduce the extension to be installed</li> | ||
| 377 : | <li>if appropriate, ask the user for the name of the registered owner and for | ||
| 378 : | the license key</li> | ||
| 379 : | <li>display the extension's licensing agreement and ask the user to accept</li> | ||
| 380 : | <li>recommend a location on the disk to install the extension (but allow user to | ||
| 381 : | override this default)</li> | ||
| 382 : | <li>check that a product or a different extension is not already stored at the specified | ||
| 383 : | location</li> | ||
| 384 : | <li> ask user which product(s) to are to use this extension (search disk; | ||
| 385 : | browse; or skip) | ||
| 386 : | </li> | ||
| 387 : | <li>optionally, determine if extension is compatible with selected products</li> | ||
| 388 : | <li>ask user to confirm all details of the install</li> | ||
| 389 : | <li>create marker file to mark root of extension install</li> | ||
| 390 : | <li>copy files to disk (see below)</li> | ||
| 391 : | <li>insert name of registered owner and license key into the "about | ||
| 392 : | " description</li> | ||
| 393 : | <li>create an appropriate entry to allow the user to uninstall the extension</li> | ||
| 394 : | <li>write link file in each of the selected products to associate extension | ||
| 395 : | with product</li> | ||
| 396 : | <li>offer to show the extension release notes ("readme" file)</li> | ||
| 397 : | </ol> | ||
| 398 : | <p>If the location specified in step 5 is <<code><i>install</i></code>>, | ||
| 399 : | the installer copies all the files in the <code><<i>extension</i>> </code>directory | ||
| 400 : | into <<code><i>install</i></code>> in step 11.</p> | ||
| 401 : | <table border="1" width="50%"> | ||
| 402 : | <tr> | ||
| 403 : | <td width="50%">Input file</td> | ||
| 404 : | <td width="50%">Installed file</td> | ||
| 405 : | </tr> | ||
| 406 : | <tr> | ||
| 407 : | <td width="50%"><code><<i>extension</i>>/*</code></td> | ||
| 408 : | <td width="50%"><code><<i>install</i>>/*</code></td> | ||
| 409 : | </tr> | ||
| 410 : | </table> | ||
| 411 : | <p>For step 7, any Eclipse product might be a candidate. Eclipse-based product | ||
| 412 : | can be recognized by the presence of a <code><<i>product install</i>>/eclipse/.eclipseproduct</code> | ||
| 413 : | file; the user should be able to request a limited disk search for installed | ||
| 414 : | products (a "search for installed products" button), or would navigate | ||
| 415 : | to a directory containing a product (i.e., a "browse" button).</p> | ||
| 416 : | <p>The installer should perform compatibility checks in step 8 by simple pattern | ||
| 417 : | matching against subdirectories in the <code><<i>product install</i>>/eclipse/features</code> | ||
| 418 : | directory. For example, the presence of a folder matching "<code>org.eclipse.jdt_2.*</code>" | ||
| 419 : | means that JDT is included in the installed product. </p> | ||
| 420 : | <p>The marker file created in step 10 is <code><<i>install</i>>/eclipse/.eclipseextension</code> | ||
| 421 : | is used to mark a directory into which an Eclipse-based extension has been | ||
| 422 : | installed, primarily for extension installers to locate | ||
| 423 : | (analogous to a product's <code>.eclipseproduct</code> marker file). This | ||
| 424 : | marker file is a <a href="http://java.sun.com/j2se/1.3/docs/api/java/util/Properties.html">java.io.Properties</a> | ||
| 425 : | format file (ISO 8859-1 character encoding with "\" escaping) and | ||
| 426 : | contains the following information that identifies the extension to the user and distinguishes | ||
| 427 : | one Eclipse-based extension from one another:</p> | ||
| 428 : | <blockquote> | ||
| 429 : | <p><code>name=<i>Wiley Anvil Enterprise Edition</i><br> | ||
| 430 : | id=<i>com.example.wiley.anvilfeature<br> | ||
| 431 : | </i>version=<i>1.0.0</i></code></p> | ||
| 432 : | </blockquote> | ||
| 433 : | <p>The values of the "id" and "version" property are inputs | ||
| 434 : | to the installer creation script; the name of the extension is presumably known | ||
| 435 : | and hard-wired. (Products would not ordinarily access this marker file; only | ||
| 436 : | product and extension installers write or read it.)</p> | ||
| 437 : | <p>After installing all files, the top-level structure of the install directory | ||
| 438 : | would contain the following files and subdirectories:</p> | ||
| 439 : | <p><code><<i>install</i>>/<br> | ||
| 440 : | eclipse/<br> | ||
| 441 : | .eclipseextension<br> | ||
| 442 : | features/<br> | ||
| 443 : | plugins/</code></p> | ||
| 444 : | <p>The only significant difference from a product installer is that an extension | ||
| 445 : | installer also creates link files in other Eclipse-based products already | ||
| 446 : | installed on the user's computer. (This saves the user from having to manually | ||
| 447 : | associate the new extension from within each product using the Eclipse update | ||
| 448 : | manager.) </p> | ||
| 449 : | <p>The link file created in step 14 is <code><<i>product install</i>>/eclipse/links/<i>com.example.wiley.anvilfeature.</i>link</code>; | ||
| 450 : | that is, the file has the same name of as the extension's feature directory less | ||
| 451 : | the version number suffix. A link file is a <a href="http://java.sun.com/j2se/1.3/docs/api/java/util/Properties.html">java.io.Properties</a> | ||
| 452 : | format file (ISO 8859-1 character encoding with "\" escaping). | ||
| 453 : | The key is "path" and the value is the absolute path of the installed | ||
| 454 : | extension, <code><<i>install</i>></code>; e.g., an entry might looks like "<code>path=<a href="file:///c:/Program">C:\\Program</a> | ||
| 455 : | Files\\Wiley\\Anvil</code>"<code>.</code> The installer is responsible for converting | ||
| 456 : | from native character | ||
| 457 : | encoding to Unicode and adding "\" escapes where required. Escaping is | ||
| 458 : | usually required since <code><<i>install</i>></code> | ||
| 459 : | typically contains special characters (such as "\") | ||
| 460 : | and may mention directories with non-Latin characters in their names. The product reads | ||
| 461 : | link files when it starts up. The installer keeps a record of any link | ||
| 462 : | files it creates so that they can be located when the extension is updated or | ||
| 463 : | uninstalled.</p> | ||
| 464 : | <h3>Uninstaller behavior</h3> | ||
| 465 : | <p>At un install time, the un installer should behave in the standard manner:</p> | ||
| 466 : | <ol> | ||
| 467 : | <li>warn user to exit all programs, especially products using the extension | ||
| 468 : | being uninstalled</li> | ||
| 469 : | <li>ask user to confirm that the extension is to be un installed</li> | ||
| 470 : | <li>remove all installed files from the <<i><code>install</code></i>> | ||
| 471 : | directory, and <b>all</b> files in <<i><code>install</code></i>><code>/eclipse/features</code> | ||
| 472 : | and <<i><code>install</code></i>><code>/eclipse/plugins</code> including ones put there by parties other than | ||
| 473 : | this installer (e.g., by the Eclipse update manager)</li> | ||
| 474 : | <li>if feasible, remove the link file from any products to which it had been | ||
| 475 : | added </li> | ||
| 476 : | <li>remove entry for extension uninstaller</li> | ||
| 477 : | <li>inform user of any files that were not removed</li> | ||
| 478 : | </ol> | ||
| 479 : | <p>When an extension is uninstalled, all plug-in and feature files should be deleted; there are no | ||
| 480 : | important data files to be kept in these subdirectories. This allows the user to uninstall an extension | ||
| 481 : | completely, including any updates applied by the Eclipse update manager.</p> | ||
| 482 : | <h3>Installer behavior when extension already installed</h3> | ||
| 483 : | <p>When the extension is already installed on the user's computer, the installer | ||
| 484 : | should allow a service update or version upgrade to be applied to the installed | ||
| 485 : | extension.</p> | ||
| 486 : | <p>At install time, the installer should behave in the standard manner:</p> | ||
| 487 : | <ol> | ||
| 488 : | <li>warn user to exit all programs, especially products using the extension | ||
| 489 : | being updated</li> | ||
| 490 : | <li>locate the installed extension to be updated, if necessary by searching | ||
| 491 : | the disk for an existing extension install or by allowing the user to locate | ||
| 492 : | it</li> | ||
| 493 : | <li> determine where this installer is a compatible update</li> | ||
| 494 : | <li>if appropriate, ask the user for the name of the registered owner and for | ||
| 495 : | the license key</li> | ||
| 496 : | <li>display the product's updated licensing agreement and ask the user to accept</li> | ||
| 497 : | <li>ask user to confirm all details of the update</li> | ||
| 498 : | <li>update files on disk (see below)</li> | ||
| 499 : | <li>should add modified or newly added files to the list of ones to be removed at uninstall | ||
| 500 : | time (where feasible)</li> | ||
| 501 : | <li>offer to show the extension release notes ("readme" file)</li> | ||
| 502 : | </ol> | ||
| 503 : | <p>In step 2, an installed extension can be recognized by the presence of an "<code>eclipse</code>" | ||
| 504 : | directory immediately containing a file named "<code>.eclipseextension</code>". | ||
| 505 : | The parent of the "<code>eclipse</code>" directory is an extension's install | ||
| 506 : | directory; i.e., <code><<i>install</i>>/eclipse/.eclipseextension</code>. | ||
| 507 : | The information contained within this marker file should be shown to the user for | ||
| 508 : | confirmation that the correct extension is being updated (there may be several | ||
| 509 : | Eclipse-based extension on the user's computer).</p> | ||
| 510 : | <p>For step 7, the installer should not delete or overwrite any of the files | ||
| 511 : | that it originally installed; rather, it should only add the files for new | ||
| 512 : | versions of features and plug-in, and possibly rewrite the marker file <code><<i>install</i>>/eclipse/.eclipseextension</code>. Leaving the old versions around gives the user | ||
| 513 : | the option to back out of the update. As with upgrading a product install, there | ||
| 514 : | is no need to touch any files in <code><<i>install</i>>/eclipse/plugins/<i>com.example.wiley.otherplugin</i>_<i>1.0.0</i></code>/ | ||
| 515 : | if this subdirectory should also exist after the upgrade; if any of the plug-in's | ||
| 516 : | files were to change, the plug-in's version number is revised, causing the files | ||
| 517 : | for the upgraded plug-in to be installed in a parallel directory <code><<i>install</i>>/eclipse/plugins/<i>com.example.wiley.otherplugin</i>_<i>1.0.1</i></code>/. </p> | ||
| 518 : | |||
| 519 : | </body> | ||
| 520 : | |||
| 521 : | </html> |
| help@eclipse.org | ViewVC Help |
| Powered by ViewVC 1.0.3 |