platform-update-home/doc/eclipse_update_packaging.html
Parent Directory
| 
Revision Log
Revision 1.18 - (view) (download) (as text)
| 1 : | droberts | 1.6 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| 2 : | vlad | 1.1 | <html> |
| 3 : | <head> | ||
| 4 : | celek | 1.18 | |
| 5 : | celek | 1.9 | <meta http-equiv="Content-Type" |
| 6 : | content="text/html; charset=iso-8859-1"> | ||
| 7 : | celek | 1.18 | |
| 8 : | celek | 1.7 | <meta name="Author" content="Lab User"> |
| 9 : | celek | 1.18 | |
| 10 : | celek | 1.7 | <meta name="GENERATOR" content="Microsoft FrontPage 4.0"> |
| 11 : | <title>Eclipse Platform: Installation and Update</title> | ||
| 12 : | vlad | 1.1 | </head> |
| 13 : | celek | 1.7 | <body> |
| 14 : | celek | 1.18 | |
| 15 : | celek | 1.7 | <h1> Eclipse Platform<br> |
| 16 : | celek | 1.18 | Update Packaging Conventions</h1> |
| 17 : | <font size="-1">Revision Date: 01/27/2003 9:00AM - Version: | ||
| 18 : | 2.0.19</font><br> | ||
| 19 : | <a href="../../../../../hglegal.htm"><img | ||
| 20 : | src="ngibmcpy.gif" border="0" height="12" width="195"> | ||
| 21 : | </a> | ||
| 22 : | celek | 1.9 | <p><b>Change History:</b> </p> |
| 23 : | celek | 1.18 | |
| 24 : | celek | 1.7 | <ul> |
| 25 : | celek | 1.18 | <li><small>2.0.19</small><small><br> |
| 26 : | </small> | ||
| 27 : | <ul> | ||
| 28 : | <li><small>added <feature discovery type></small></li> | ||
| 29 : | </ul> | ||
| 30 : | </li> | ||
| 31 : | <li><small>2.0.18</small></li> | ||
| 32 : | |||
| 33 : | celek | 1.14 | <ul> |
| 34 : | celek | 1.18 | <li><small>added <feature plugin=""></small></li> |
| 35 : | |||
| 36 : | celek | 1.15 | </ul> |
| 37 : | celek | 1.18 | <li><small>2.0.17</small></li> |
| 38 : | |||
| 39 : | celek | 1.15 | <ul> |
| 40 : | celek | 1.18 | <li><small>added $os$,$ws$,$arch$ and $nl$ for copyright, description |
| 41 : | and license URL tag in feature.<br> | ||
| 42 : | </small></li> | ||
| 43 : | |||
| 44 : | celek | 1.14 | </ul> |
| 45 : | celek | 1.18 | <li><small>2.0.16</small> <small><br> |
| 46 : | </small> | ||
| 47 : | celek | 1.11 | <ul> |
| 48 : | celek | 1.18 | <li><small>added <site><feature> os,arch,nl,ws |
| 49 : | support "*"</small></li> | ||
| 50 : | |||
| 51 : | celek | 1.11 | </ul> |
| 52 : | celek | 1.18 | </li> |
| 53 : | <li><small>2.0.15</small> | ||
| 54 : | |||
| 55 : | celek | 1.12 | <ul> |
| 56 : | celek | 1.18 | <li><small>added <site><feature> os,arch,nl,ws,patch |
| 57 : | tag</small></li> | ||
| 58 : | |||
| 59 : | celek | 1.12 | </ul> |
| 60 : | celek | 1.18 | </li> |
| 61 : | <li><small>2.0.14<br> | ||
| 62 : | </small> | ||
| 63 : | |||
| 64 : | celek | 1.10 | <ul> |
| 65 : | celek | 1.18 | <li><small>added <site><feature> label tag</small><br> |
| 66 : | </li> | ||
| 67 : | |||
| 68 : | celek | 1.17 | </ul> |
| 69 : | celek | 1.18 | </li> |
| 70 : | <li><small>2.0.13<br> | ||
| 71 : | </small> </li> | ||
| 72 : | |||
| 73 : | celek | 1.17 | <ul> |
| 74 : | celek | 1.18 | <li><small>added <includes name,optional,match,search-location</small> |
| 75 : | celek | 1.17 | ></li> |
| 76 : | celek | 1.18 | <li><small>added <import feature,patch></small></li> |
| 77 : | |||
| 78 : | celek | 1.17 | </ul> |
| 79 : | celek | 1.18 | <li><small>2.0.12<br> |
| 80 : | </small></li> | ||
| 81 : | |||
| 82 : | <ul> | ||
| 83 : | <li> <font size="-1">added reference to the <a | ||
| 84 : | href="http://www.eclipse.org/legal/updatemanager.html"> Eclipse.org Update | ||
| 85 : | Manager Agreement</a> </font></li> | ||
| 86 : | |||
| 87 : | celek | 1.16 | </ul> |
| 88 : | celek | 1.18 | <li> <font size="-1">2.0.11</font></li> |
| 89 : | |||
| 90 : | celek | 1.16 | <ul> |
| 91 : | celek | 1.18 | <li> <font size="-1"><feature> <license> is required</font></li> |
| 92 : | |||
| 93 : | celek | 1.16 | </ul> |
| 94 : | celek | 1.18 | <li> <font size="-1">2.0.10</font></li> |
| 95 : | |||
| 96 : | celek | 1.16 | <ul> |
| 97 : | celek | 1.18 | <li> <font size="-1"><feature colocation-affinity=""></font></li> |
| 98 : | |||
| 99 : | celek | 1.16 | </ul> |
| 100 : | celek | 1.18 | <li> <font size="-1">2.0.9</font></li> |
| 101 : | |||
| 102 : | celek | 1.16 | <ul> |
| 103 : | celek | 1.18 | <li> <font size="-1"><site> <feature> changes - |
| 104 : | additional markup to optionally expose feature identification information | ||
| 105 : | celek | 1.17 | to speed up searches</font></li> |
| 106 : | celek | 1.18 | <li> <font size="-1">removed obsolete text</font></li> |
| 107 : | <li> <font size="-1">web-triggered update not in 2.0</font></li> | ||
| 108 : | <li> <font size="-1">no assist in 2.0 for license/ "key file" | ||
| 109 : | handling (individual application/ plugin responsibility)</font></li> | ||
| 110 : | |||
| 111 : | celek | 1.16 | </ul> |
| 112 : | celek | 1.18 | <li> <font size="-1">2.0.8</font></li> |
| 113 : | |||
| 114 : | celek | 1.16 | <ul> |
| 115 : | celek | 1.18 | <li> <font size="-1"><feature> <includes></font></li> |
| 116 : | |||
| 117 : | celek | 1.16 | </ul> |
| 118 : | celek | 1.18 | <li> <font size="-1">2.0.7</font></li> |
| 119 : | |||
| 120 : | celek | 1.16 | <ul> |
| 121 : | celek | 1.18 | <li> <font size="-1">support explicit xml markup for primary |
| 122 : | features</font></li> | ||
| 123 : | |||
| 124 : | celek | 1.16 | </ul> |
| 125 : | celek | 1.18 | <li> <font size="-1">2.0.6</font></li> |
| 126 : | |||
| 127 : | celek | 1.16 | <ul> |
| 128 : | celek | 1.18 | <li> <font size="-1">install handler markup changes</font></li> |
| 129 : | |||
| 130 : | celek | 1.16 | </ul> |
| 131 : | celek | 1.18 | <li> <font size="-1">2.0.5</font></li> |
| 132 : | |||
| 133 : | celek | 1.16 | <ul> |
| 134 : | celek | 1.18 | <li> <font size="-1">updates to security section</font></li> |
| 135 : | |||
| 136 : | celek | 1.16 | </ul> |
| 137 : | celek | 1.18 | <li> <font size="-1">2.0.4</font></li> |
| 138 : | |||
| 139 : | celek | 1.16 | <ul> |
| 140 : | celek | 1.18 | <li> <font size="-1">general text cleanup</font></li> |
| 141 : | <li> <font size="-1"><feature><group> support | ||
| 142 : | removed (will not be in Eclipse 2.0)</font></li> | ||
| 143 : | <li> <font size="-1">arch= support added to <feature> | ||
| 144 : | and <feature><plugin></font></li> | ||
| 145 : | <li> <font size="-1">os=/ arch=/ ws=/ nl= added to <fetaure><data></font></li> | ||
| 146 : | <li> <font size="-1"><site url=""> new semantics</font></li> | ||
| 147 : | <li> <font size="-1">corrected errors in native installer | ||
| 148 : | link support</font></li> | ||
| 149 : | <li> <font size="-1">defined callback query strings for browser-triggered | ||
| 150 : | celek | 1.17 | processing</font></li> |
| 151 : | celek | 1.18 | |
| 152 : | celek | 1.10 | </ul> |
| 153 : | celek | 1.18 | |
| 154 : | celek | 1.7 | </ul> |
| 155 : | celek | 1.18 | |
| 156 : | celek | 1.7 | <h3> <font size="+2">Table of Contents</font></h3> |
| 157 : | celek | 1.18 | <a href="#Introduction">Introduction</a> <br> |
| 158 : | <a | ||
| 159 : | celek | 1.14 | href="#Changes_from_R1.0">Changes from 1.0</a> <br> |
| 160 : | celek | 1.18 | <a href="#Concepts">Concepts</a> |
| 161 : | <br> | ||
| 162 : | <a href="#Framework">Framework</a> | ||
| 163 : | celek | 1.17 | <br> |
| 164 : | celek | 1.18 | <a href="#Packaging_Conventions">Packaging Conventions</a> |
| 165 : | <br> | ||
| 166 : | <a | ||
| 167 : | celek | 1.15 | href="#Feature_Archive">Feature Archive</a> <br> |
| 168 : | celek | 1.18 | <a |
| 169 : | celek | 1.15 | href="#Plug-In_Archive">Plug-In Archive</a> <br> |
| 170 : | celek | 1.18 | <a |
| 171 : | href="#Packaging_NL">Packaging NL</a> <br> | ||
| 172 : | | ||
| 173 : | <a href="#Translated_Feature_Information"> Translated Feature Information</a> | ||
| 174 : | celek | 1.17 | <br> |
| 175 : | celek | 1.18 | |
| 176 : | <a href="#Translated_Plug-In_Information"> Translated Plug-In Information</a> | ||
| 177 : | celek | 1.17 | <br> |
| 178 : | celek | 1.18 | <a |
| 179 : | href="#Packaging_Target-Specific_Support"> Packaging Target-Specific Support</a> | ||
| 180 : | celek | 1.17 | <br> |
| 181 : | celek | 1.18 | <a |
| 182 : | href="#Packaging_Attribution_Information"> Packaging Attribution Information</a> | ||
| 183 : | celek | 1.17 | <br> |
| 184 : | celek | 1.18 | <a |
| 185 : | href="#Packaging_Attribution_Information"> Packaging Non-Plug-In Files</a> | ||
| 186 : | celek | 1.17 | <br> |
| 187 : | celek | 1.18 | <a |
| 188 : | href="#Packaging_Attribution_Information"> Custom Install Handling</a> | ||
| 189 : | <br> | ||
| 190 : | <a | ||
| 191 : | celek | 1.11 | href="#Security_Considerations">Security Considerations</a> <br> |
| 192 : | celek | 1.18 | <a href="#Update_Server">Update Server</a> <br> |
| 193 : | <a href="#Site_Map">Site | ||
| 194 : | Map</a> <br> | ||
| 195 : | <a | ||
| 196 : | celek | 1.14 | href="#Default_Site_Layout">Default Site Layout</a> <br> |
| 197 : | celek | 1.18 | <a |
| 198 : | celek | 1.14 | href="#Controlling_Access">Controlling Access</a> <br> |
| 199 : | celek | 1.18 | <a href="#Eclipse_Install">Eclipse Install</a> <br> |
| 200 : | <a | ||
| 201 : | celek | 1.11 | href="#Default_Install_Layout">Default Install Layout</a> <br> |
| 202 : | celek | 1.18 | <a |
| 203 : | celek | 1.14 | href="#Unmanaged_Plugins">"Unmanaged" Plug-Ins</a> <br> |
| 204 : | celek | 1.18 | <a |
| 205 : | href="#Using_Native_Platform_Installers"> Using Native Platform Installers</a> | ||
| 206 : | |||
| 207 : | celek | 1.9 | <h2> <a name="Introduction"></a> Introduction</h2> |
| 208 : | celek | 1.18 | This document outlines the support for managing the delivery |
| 209 : | of function within the Eclipse platform. Also refer to the "<a | ||
| 210 : | href="http://www.eclipse.org/legal/updatemanager.html"> Eclipse.org Update | ||
| 211 : | Manager Agreement</a> " for additional legal information governing | ||
| 212 : | the use of the Eclipse update manager function. | ||
| 213 : | celek | 1.9 | <h3> <a name="Changes_from_R1.0"></a> Changes from R1.0</h3> |
| 214 : | celek | 1.18 | This section describes the major design changes from the R1.0 |
| 215 : | Installation and Update support and supplies rationale for each design | ||
| 216 : | change. | ||
| 217 : | celek | 1.7 | <ul> |
| 218 : | celek | 1.18 | <li> <b>extendable framework</b></li> |
| 219 : | <br> | ||
| 220 : | In R2.0 Eclipse defines an extendable framework for installation | ||
| 221 : | and update, allowing the support for alternate packaging and site management | ||
| 222 : | schemes. R2.0 supplies a default concrete implementation of this framework. | ||
| 223 : | celek | 1.17 | <li> <b> feature support</b></li> |
| 224 : | celek | 1.18 | <br> |
| 225 : | In R2.0 the concept of a <i>component</i> and <i>configuration</i> | ||
| 226 : | is merged into <i>feature</i>. Features define the packaging structure | ||
| 227 : | for a group of related plug-ins, plug-in fragments, and optionally non-plug-in | ||
| 228 : | files. Features are treated purely as an installation and packaging construct. | ||
| 229 : | They do not play a role during Eclipse plug-in execution. Features do | ||
| 230 : | not nest. They are simply an inclusive "manifest" of the plug-ins, fragments | ||
| 231 : | and other files that make up that feature. If features are logically made | ||
| 232 : | up of plug-ins from "sub-features", the top-level feature "manifest" must | ||
| 233 : | be fully resolved at packaging time. <li> <b>default feature archive format</b></li> | ||
| 234 : | <br> | ||
| 235 : | R1.0 components were packaged as a single Java .jar containing | ||
| 236 : | the component manifest as well as the actual plug-in files. The problem | ||
| 237 : | with this approach is lack of granularity at download time. In R2.0, | ||
| 238 : | the feature archive consists of multiple separate .jars - one .jar per | ||
| 239 : | plug-in and fragment, plus one .jar for the actual feature information. | ||
| 240 : | The Installation and Update support selectively downloads only those | ||
| 241 : | celek | 1.17 | jars required for the installation. <li> <b>site map</b></li> |
| 242 : | celek | 1.18 | <br> |
| 243 : | Default Eclipse update server must contain a <i>site map</i> | ||
| 244 : | file (site.xml). This is an evolution of the R1.0 install.index support. | ||
| 245 : | The rationale for using a structured site defined by the map rather | ||
| 246 : | than a "free form" web site, is the ability to present a consistent installation | ||
| 247 : | experience for the user. Also, this provides the necessary structure | ||
| 248 : | for discovery of available updates. Additional support for "free form" | ||
| 249 : | browsing may be considered in future work. <li> <b>using native install/ | ||
| 250 : | uninstall</b></li> | ||
| 251 : | <br> | ||
| 252 : | The primary mechanism for installing and updating Eclipse features | ||
| 253 : | is the built-in installation and update support. Some products may instead | ||
| 254 : | choose to use native installer technology (eg. MSI, RPM, etc) to deliver | ||
| 255 : | Eclipse features. However, native installers do not implement the required | ||
| 256 : | support for understanding the Eclipse installation structure. In particular, | ||
| 257 : | the native uninstallers will, by default, remove plug-in files that were | ||
| 258 : | installed using the native installer without regard to these plug-ins | ||
| 259 : | being needed by other features. As a result, features installed using | ||
| 260 : | native installers must be written into private product-specific installation | ||
| 261 : | location and not the shared Eclipse installation location. The shared | ||
| 262 : | Eclipse is made aware of the produce-specific location via an installed | ||
| 263 : | "link file". <li> <b>custom install handling</b></li> | ||
| 264 : | <br> | ||
| 265 : | In many cases the standard installation handling supplied by | ||
| 266 : | Eclipse is not be sufficient to handle various custom requirements. To | ||
| 267 : | accommodate this, R2.0 Eclipse supports custom install handlers packaged | ||
| 268 : | as part of the feature and executed during the feature installation. <li> | ||
| 269 : | celek | 1.17 | <b>path naming conventions</b></li> |
| 270 : | celek | 1.18 | <br> |
| 271 : | R1.0 mandated the use of the various identifiers and versions | ||
| 272 : | inside the packaged archives (eg. directory path names for plug-ins). | ||
| 273 : | This approach has proven to be ackward and error prone. In 2.0, the | ||
| 274 : | packaging requirements no longer mandate that path names of packaged | ||
| 275 : | files precisely reflect the contained identifiers and versions. The properly | ||
| 276 : | identified install subdirectories are created by the Eclipse support | ||
| 277 : | during the installation and update process based on the archive content | ||
| 278 : | (rather than explicit jar path structure set up at packaging time) | ||
| 279 : | |||
| 280 : | celek | 1.7 | </ul> |
| 281 : | celek | 1.18 | |
| 282 : | celek | 1.9 | <h3> <a name="Concepts"></a> Concepts</h3> |
| 283 : | celek | 1.18 | <b>Plug-in</b> <br> |
| 284 : | Eclipse developers build plug-ins. Plug-ins are the base units | ||
| 285 : | of execution recognized by the Eclipse runtime environment. In general, | ||
| 286 : | plug-ins are not exposed to users that select function during installation | ||
| 287 : | or update. The reason is that plug-in boundaries are established by developers | ||
| 288 : | for development reasons (like function reuse) and present the wrong | ||
| 289 : | level of granularity in terms of what the user sees as the unit of function. | ||
| 290 : | |||
| 291 : | <p>While plug-ins are being developed (ie. are frequently being changed), | ||
| 292 : | their internal file structure will reflect what is convenient to the | ||
| 293 : | developer. This will generally depend on the particular development | ||
| 294 : | tool being used. Typically, however, the developer will likely setup | ||
| 295 : | the plug-in to execute from a directory tree containing exposed .class | ||
| 296 : | files, rather than executing from a .jar (requires an extra step to | ||
| 297 : | create the .jar and we all know developers hate extra steps). Also, at | ||
| 298 : | this stage the developer does not pay particular attention to plug-in | ||
| 299 : | versioning information, because the plug-in is continually changing. </p> | ||
| 300 : | |||
| 301 : | <p>However, when the plug-in is ready to be packaged, it needs to be converted | ||
| 302 : | to a form suitable for packaging and installation. Typically it means | ||
| 303 : | creation of the runtime .jar(s) and removing any development-time files | ||
| 304 : | (source, exposed .class files, etc). It also means updating the plugin.xml | ||
| 305 : | manifest with the formal plug-in version and reflecting the version in | ||
| 306 : | the plug-in directory name (see "Concurrent Plug-In Version Support" for | ||
| 307 : | details). </p> | ||
| 308 : | |||
| 309 : | celek | 1.7 | <p><b>Plug-in Fragment</b> <br> |
| 310 : | celek | 1.18 | Plug-in Fragments (or simply Fragments) allow independent packaging |
| 311 : | of certain aspects of the base plug-in. This includes (but may not | ||
| 312 : | be limited to) translated resources for the plug-in, OS-specific or | ||
| 313 : | windowing-system-specific code. At runtime, fragments are logically | ||
| 314 : | merged into the base plug-in. From a packaging point of view, the install | ||
| 315 : | and update support does not really differentiate between plug-ins and | ||
| 316 : | their related fragments. </p> | ||
| 317 : | |||
| 318 : | celek | 1.7 | <p><b>Feature</b> <br> |
| 319 : | celek | 1.18 | A feature is an installation packaging mechanism used to define |
| 320 : | a group of versioned plug-ins and/or plug-in fragments plus non-plug-in | ||
| 321 : | files that is used to deliver some user function. A feature can also | ||
| 322 : | include other features. Features are exposed to users as part of the | ||
| 323 : | packaging and installation process, because they represent a unit of | ||
| 324 : | function selection. Features also represent a unit of installation. Features | ||
| 325 : | carry a version identifier.</p> | ||
| 326 : | |||
| 327 : | <p>Features are packaged as a feature archive, referencing the required plug-ins, | ||
| 328 : | plug-in fragments and optional non-plug-in files. The feature archives | ||
| 329 : | are placed on an update server for download and installation by the Eclipse | ||
| 330 : | update manager, or they can be used as the input into a formal packaging | ||
| 331 : | process using one of the "traditional" installer technologies. The format | ||
| 332 : | of the feature archive is described later. </p> | ||
| 333 : | |||
| 334 : | celek | 1.9 | <h3> <a name="Framework"></a> Framework</h3> |
| 335 : | celek | 1.18 | The 2.0 installation and update support is provided as a framework |
| 336 : | that allows custom implementations to be supplied for its key elements. | ||
| 337 : | In particular, the following can be supplied: | ||
| 338 : | vlad | 1.1 | <ul> |
| 339 : | celek | 1.18 | <li> concrete implementations of feature (IFeature interface) |
| 340 : | that can be used to support alternate packaging schemes. New concrete | ||
| 341 : | feature types are registere via the "org.eclipse.update.featureTypes" | ||
| 342 : | celek | 1.17 | extension point.</li> |
| 343 : | celek | 1.18 | <li> concrete implementations of site (ISite interface) that |
| 344 : | can be used to support alternate site layout, or site behavior. New concrete | ||
| 345 : | site types are registered via the "org.eclipse.update.siteTypes" extension | ||
| 346 : | point.</li> | ||
| 347 : | <li> each feature can specify a custom install handler as | ||
| 348 : | part of its feature manifest. Install handlers (IInstallHandler interface) | ||
| 349 : | are dynamically invoked as part of the installation process to handle | ||
| 350 : | non-plugin data, plus perform other custom processing allowed by the framework.</li> | ||
| 351 : | |||
| 352 : | celek | 1.7 | </ul> |
| 353 : | celek | 1.18 | Eclipse provides default implementations of feature and site. |
| 354 : | celek | 1.17 | These are described in the rest of this document. <br> |
| 355 : | celek | 1.18 | |
| 356 : | celek | 1.7 | <table border="1" cols="1" width="100%"> |
| 357 : | celek | 1.18 | <tbody> |
| 358 : | <tr> | ||
| 359 : | <td><b>Note: <i>The reminder of this document describes the | ||
| 360 : | default concrete implementation of the framework delivered with Eclipse. | ||
| 361 : | It specifies the structure of the default feature implementation, as well | ||
| 362 : | as the default site implementation, plus the corresponding xml files (feature.xml | ||
| 363 : | and site.xml). Providers of alternate concrete implementations can extend | ||
| 364 : | parts or all of the default Eclipse implementation. This includes providing | ||
| 365 : | a mechanism for dynamic computation of the site map (site.xml)</i></b></td> | ||
| 366 : | </tr> | ||
| 367 : | |||
| 368 : | </tbody> | ||
| 369 : | vlad | 1.1 | </table> |
| 370 : | celek | 1.18 | |
| 371 : | celek | 1.9 | <h2> <a name="Packaging_Conventions"></a> Packaging Conventions</h2> |
| 372 : | celek | 1.18 | Default feature packages consist of several related files: |
| 373 : | |||
| 374 : | celek | 1.7 | <ul> |
| 375 : | celek | 1.18 | <li> exactly one jar containing the feature manifest and related |
| 376 : | files. This one is refered to as the "<b>feature archive</b>"</li> | ||
| 377 : | <li> zero or more jars containing the feature plug-ins. These | ||
| 378 : | are refered to as the "<b>plug-in archives</b>"</li> | ||
| 379 : | <li> zero or more non-plug-in files associated with the feature. | ||
| 380 : | They are used by feature custom install handlers and contain data not | ||
| 381 : | celek | 1.17 | interpreted by Eclipse</li> |
| 382 : | celek | 1.18 | |
| 383 : | celek | 1.9 | </ul> |
| 384 : | celek | 1.18 | |
| 385 : | celek | 1.9 | <h3> <a name="Feature_Archive"></a> Feature Archive</h3> |
| 386 : | celek | 1.18 | The feature packaging information is placed into a separate |
| 387 : | Java .jar. Standard Java jar facilities are used for constructing feature | ||
| 388 : | archives. Feature archives reference separately packaged plug-in archives | ||
| 389 : | (see next section) and non-plug-in files. | ||
| 390 : | <p>Features are identified using a structured identifier based on the provider | ||
| 391 : | internet domain name. For example, organization eclipse.org may produce | ||
| 392 : | feature org.eclipse.javatooling. The character set used for feature | ||
| 393 : | identifiers is as specified for plug-in identifiers (see reference information | ||
| 394 : | describing the plug-in manifest). </p> | ||
| 395 : | |||
| 396 : | celek | 1.7 | <p>The recommended convention for naming the feature archives is <br> |
| 397 : | celek | 1.18 | <tt><id>_<version>.jar</tt> </p> |
| 398 : | |||
| 399 : | <p>Where <tt><id></tt> is the feature identifier and <tt><version></tt> | ||
| 400 : | is the full version identifier contained in the respective feature.xml. | ||
| 401 : | Note that this is a recommended convention that minimizes chance of | ||
| 402 : | collisions, but is not required by the Eclipse architecture. For example, | ||
| 403 : | the following are valid feature archive names </p> | ||
| 404 : | |||
| 405 : | celek | 1.7 | <p><tt>org.eclipse.javatooling_1.0.3.jar</tt> <br> |
| 406 : | celek | 1.18 | <tt>org.eclipse.pde_2.0.jar</tt> <br> |
| 407 : | <tt>my_feature.jar</tt> </p> | ||
| 408 : | |||
| 409 : | <p>Internally, each feature archive is packaged relative to its feature directory | ||
| 410 : | (but not including the directory path element). The archive has the | ||
| 411 : | celek | 1.17 | following structure </p> |
| 412 : | celek | 1.18 | |
| 413 : | celek | 1.7 | <p><tt>feature.xml</tt> <br> |
| 414 : | celek | 1.18 | <tt>feature<_locale>.properties (see "Translated Feature |
| 415 : | celek | 1.17 | Information")</tt> <br> |
| 416 : | celek | 1.18 | <tt>other feature files and subdirectories (TBD)</tt> <br> |
| 417 : | <tt>META-INF/</tt> <br> | ||
| 418 : | <tt> Java jar manifest and security files</tt> | ||
| 419 : | celek | 1.17 | </p> |
| 420 : | celek | 1.18 | |
| 421 : | celek | 1.7 | <p>The feature install.xml format is defined by the following dtd: </p> |
| 422 : | celek | 1.18 | |
| 423 : | celek | 1.7 | <p><tt><?xml encoding="ISO-8859-1"?></tt> </p> |
| 424 : | celek | 1.18 | |
| 425 : | <p><tt><!ELEMENT feature (install-handler?, description?, copyright?, | ||
| 426 : | license?, url?, includes*, requires?, plugin*, data*)></tt> <br> | ||
| 427 : | <tt><!ATTLIST feature</tt> <br> | ||
| 428 : | <tt> id | ||
| 429 : | CDATA #REQUIRED</tt> <br> | ||
| 430 : | <tt> version | ||
| 431 : | celek | 1.17 | CDATA #REQUIRED</tt> <br> |
| 432 : | celek | 1.18 | <tt> label |
| 433 : | CDATA #IMPLIED</tt> <br> | ||
| 434 : | <tt> provider-name CDATA #IMPLIED</tt> <br> | ||
| 435 : | <tt> image | ||
| 436 : | CDATA #IMPLIED</tt> <br> | ||
| 437 : | <tt> os | ||
| 438 : | CDATA #IMPLIED</tt> <br> | ||
| 439 : | <tt> arch | ||
| 440 : | CDATA #IMPLIED</tt> <br> | ||
| 441 : | <tt> ws | ||
| 442 : | CDATA #IMPLIED</tt> <br> | ||
| 443 : | <tt> nl | ||
| 444 : | CDATA #IMPLIED</tt> <br> | ||
| 445 : | <tt> colocation-affinity</tt> <br> | ||
| 446 : | <tt> | ||
| 447 : | CDATA #IMPLIED</tt> <br> | ||
| 448 : | <tt> primary | ||
| 449 : | celek | 1.17 | (true | false) "false"</tt> <br> |
| 450 : | celek | 1.18 | <tt> application CDATA #IMPLIED<br> |
| 451 : | </tt> <tt>plugin | ||
| 452 : | celek | 1.17 | CDATA #IMPLIED</tt><br> |
| 453 : | celek | 1.18 | <tt>></tt> </p> |
| 454 : | |||
| 455 : | celek | 1.7 | <p><tt><!ELEMENT install-handler EMPTY></tt> <br> |
| 456 : | celek | 1.18 | <tt><!ATTLIST install-handler</tt> <br> |
| 457 : | <tt> library | ||
| 458 : | celek | 1.17 | CDATA #IMPLIED</tt> <br> |
| 459 : | celek | 1.18 | <tt> handler |
| 460 : | celek | 1.17 | CDATA #IMPLIED</tt> <br> |
| 461 : | celek | 1.18 | <tt>></tt> </p> |
| 462 : | |||
| 463 : | celek | 1.7 | <p><tt><!ELEMENT description (#PCDATA)></tt> <br> |
| 464 : | celek | 1.18 | <tt><!ATTLIST description</tt> <br> |
| 465 : | <tt> url | ||
| 466 : | CDATA #IMPLIED</tt> <br> | ||
| 467 : | <tt>></tt> </p> | ||
| 468 : | |||
| 469 : | celek | 1.7 | <p><tt><!ELEMENT copyright (#PCDATA)></tt> <br> |
| 470 : | celek | 1.18 | <tt><!ATTLIST copyright</tt> <br> |
| 471 : | <tt> url | ||
| 472 : | CDATA #IMPLIED</tt> <br> | ||
| 473 : | <tt>></tt> </p> | ||
| 474 : | |||
| 475 : | celek | 1.7 | <p><tt><!ELEMENT license (#PCDATA)></tt> <br> |
| 476 : | celek | 1.18 | <tt><!ATTLIST license</tt> <br> |
| 477 : | <tt> url | ||
| 478 : | CDATA #IMPLIED</tt> <br> | ||
| 479 : | <tt>></tt> </p> | ||
| 480 : | |||
| 481 : | celek | 1.7 | <p><tt><!ELEMENT url (update?, discovery*)></tt> </p> |
| 482 : | celek | 1.18 | |
| 483 : | celek | 1.7 | <p><tt><!ELEMENT update EMPTY></tt> <br> |
| 484 : | celek | 1.18 | <tt><!ATTLIST update</tt> <br> |
| 485 : | <tt> url | ||
| 486 : | CDATA #REQUIRED</tt> <br> | ||
| 487 : | <tt> label | ||
| 488 : | CDATA #IMPLIED</tt> <br> | ||
| 489 : | <tt>></tt> </p> | ||
| 490 : | |||
| 491 : | celek | 1.7 | <p><tt><!ELEMENT discovery EMPTY></tt> <br> |
| 492 : | celek | 1.18 | <tt><!ATTLIST discovery</tt> <br> |
| 493 : | <tt> url | ||
| 494 : | CDATA #REQUIRED</tt> <br> | ||
| 495 : | <tt> label | ||
| 496 : | CDATA #IMPLIED</tt> <br> | ||
| 497 : | <tt> type | ||
| 498 : | (update|web) "update"</tt><tt><br> | ||
| 499 : | ></tt> </p> | ||
| 500 : | <p> </p> | ||
| 501 : | |||
| 502 : | celek | 1.7 | <p><tt><!ELEMENT includes EMPTY></tt> <br> |
| 503 : | celek | 1.18 | <tt><!ATTLIST includes</tt> <br> |
| 504 : | <tt> id | ||
| 505 : | CDATA #REQUIRED</tt> <br> | ||
| 506 : | <tt> version | ||
| 507 : | celek | 1.17 | CDATA #REQUIRED</tt> <br> |
| 508 : | celek | 1.18 | <tt> name |
| 509 : | CDATA #IMPLIED</tt> <br> | ||
| 510 : | <tt> optional </tt><tt> | ||
| 511 : | celek | 1.17 | (true | false) "false"</tt><tt> <br> |
| 512 : | celek | 1.18 | </tt><tt> match |
| 513 : | (perfect | equivalent | compatible | greaterOrEqual) | ||
| 514 : | "compatible"</tt><tt> </tt><br> | ||
| 515 : | <tt> search-location </tt><tt>(</tt><font | ||
| 516 : | celek | 1.9 | color="#000000"><tt> root | self | both) "root"</tt></font><br> |
| 517 : | celek | 1.18 | <tt>></tt> </p> |
| 518 : | |||
| 519 : | celek | 1.7 | <p><tt><!ELEMENT requires (import+)></tt> </p> |
| 520 : | celek | 1.18 | |
| 521 : | celek | 1.7 | <p><tt><!ELEMENT import EMPTY></tt> <br> |
| 522 : | celek | 1.18 | <tt><!ATTLIST import</tt> <br> |
| 523 : | <tt> plugin | ||
| 524 : | CDATA #IMPLIED</tt><br> | ||
| 525 : | <tt> feature | ||
| 526 : | CDATA #IMPLIED</tt><br> | ||
| 527 : | <tt> version | ||
| 528 : | celek | 1.17 | CDATA #IMPLIED</tt> <br> |
| 529 : | celek | 1.18 | <tt> match |
| 530 : | celek | 1.17 | (perfect | equivalent | compatible | greaterOrEqual) "compatible"</tt> <br> |
| 531 : | celek | 1.18 | <tt> patch </tt><tt> |
| 532 : | celek | 1.17 | (true | false) "false"</tt><tt> </tt><tt><br> |
| 533 : | celek | 1.18 | ></tt><br> |
| 534 : | </p> | ||
| 535 : | |||
| 536 : | celek | 1.7 | <p><tt><!ELEMENT plugin EMPTY></tt> <br> |
| 537 : | celek | 1.18 | <tt><!ATTLIST plugin</tt> <br> |
| 538 : | <tt> id | ||
| 539 : | CDATA #REQUIRED</tt> <br> | ||
| 540 : | <tt> version | ||
| 541 : | celek | 1.17 | CDATA #REQUIRED</tt> <br> |
| 542 : | celek | 1.18 | <tt> fragment |
| 543 : | (true | false) "false"</tt> <br> | ||
| 544 : | <tt> os | ||
| 545 : | CDATA #IMPLIED</tt> <br> | ||
| 546 : | <tt> arch | ||
| 547 : | CDATA #IMPLIED</tt> <br> | ||
| 548 : | <tt> ws | ||
| 549 : | CDATA #IMPLIED</tt> <br> | ||
| 550 : | <tt> nl | ||
| 551 : | CDATA #IMPLIED</tt> <br> | ||
| 552 : | <tt> download-size CDATA #IMPLIED</tt> <br> | ||
| 553 : | <tt> install-size CDATA #IMPLIED</tt> | ||
| 554 : | <br> | ||
| 555 : | <tt>></tt> </p> | ||
| 556 : | |||
| 557 : | celek | 1.7 | <p><tt><!ELEMENT data EMPTY></tt> <br> |
| 558 : | celek | 1.18 | <tt><!ATTLIST data</tt> <br> |
| 559 : | <tt> id | ||
| 560 : | CDATA #REQUIRED</tt> <br> | ||
| 561 : | <tt> os | ||
| 562 : | CDATA #IMPLIED</tt> <br> | ||
| 563 : | <tt> arch | ||
| 564 : | CDATA #IMPLIED</tt> <br> | ||
| 565 : | <tt> ws | ||
| 566 : | CDATA #IMPLIED</tt> <br> | ||
| 567 : | <tt> nl | ||
| 568 : | CDATA #IMPLIED</tt> <br> | ||
| 569 : | <tt> download-size CDATA #IMPLIED</tt> <br> | ||
| 570 : | <tt> install-size CDATA #IMPLIED</tt> | ||
| 571 : | <br> | ||
| 572 : | <tt>></tt> </p> | ||
| 573 : | |||
| 574 : | celek | 1.7 | <p>The element and attribute definitions are as follows: </p> |
| 575 : | celek | 1.18 | |
| 576 : | celek | 1.7 | <ul> |
| 577 : | celek | 1.18 | <li> <feature> - defines the feature</li> |
| 578 : | |||
| 579 : | celek | 1.7 | <ul> |
| 580 : | celek | 1.18 | <li> id - required feature identifier (eg. com.xyz.myfeature)</li> |
| 581 : | <li> version - required component version (eg. 1.0.3)</li> | ||
| 582 : | <li> label - optional displayable label (name). Intended to | ||
| 583 : | be translated.</li> | ||
| 584 : | <li> provider-name - optional display label identifying the | ||
| 585 : | organization providing this component. Intended to be translated.</li> | ||
| 586 : | <li> image - optional image to use when displaying information | ||
| 587 : | celek | 1.17 | about the feature. Specified relative to the feature.xml.</li> |
| 588 : | celek | 1.18 | <li> os - optional operating system specification. A comma-separated |
| 589 : | list of os designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt> | ||
| 590 : | . Indicates this feature should only be installed on one of the specified | ||
| 591 : | os systems. If this attribute is not specified, the feature can be | ||
| 592 : | installed on all systems (portable implementation). This information | ||
| 593 : | is used as a hint by the installation and update support (user can force | ||
| 594 : | installation of feature regardless of this setting).</li> | ||
| 595 : | <li> arch - optional machine architecture specification. A | ||
| 596 : | comma-separated list of architecture designators defined by Eclipse | ||
| 597 : | (see Javadoc for <tt> org.eclipse.core.boot.BootLoader)</tt>. Indicates | ||
| 598 : | this feature should only be installed on one of the specified systems. | ||
| 599 : | If this attribute is not specified, the feature can be installed on all | ||
| 600 : | systems (portable implementation). This information is used as a hint | ||
| 601 : | by the installation and update support (user can force installation of | ||
| 602 : | feature regardless of this setting).</li> | ||
| 603 : | <li> ws - optional windowing system specification. A comma-separated | ||
| 604 : | list of ws designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt> | ||
| 605 : | . Indicates this feature should only be installed on one of the specified | ||
| 606 : | ws systems. If this attribute is not specified, the feature can be | ||
| 607 : | installed on all systems (portable implementation). This information | ||
| 608 : | is used as a hint by the installation and update support (user can force | ||
| 609 : | installation of feature regardless of this setting).</li> | ||
| 610 : | <li> nl - optional locale specification. A comma-separated | ||
| 611 : | list of locale designators defined by Java. Indicates this feature should | ||
| 612 : | only be installed on a system running with a compatible locale (using | ||
| 613 : | Java locale-matching rules). If this attribute is not specified, the feature | ||
| 614 : | can be installed on all systems (language-neutral implementation). This | ||
| 615 : | information is used as a hint by the installation and update support (user | ||
| 616 : | can force installation of feature regardless of this setting).</li> | ||
| 617 : | <li> colocation-affinity - optional reference to another feature | ||
| 618 : | identifier used to select the default installation location for this | ||
| 619 : | feature. When this feature is being installed as a new feature (no other | ||
| 620 : | versions of it are installed), an attempt is made to install this feature | ||
| 621 : | celek | 1.17 | in the same installation location as the referenced feature.</li> |
| 622 : | celek | 1.18 | <li> primary - optional indication specifying whether this |
| 623 : | feature can be used as a <a href="#Dominant_Feature">primary feature</a> | ||
| 624 : | celek | 1.17 | . Default if <i>false</i> (not a primary feature).</li> |
| 625 : | celek | 1.18 | <li> application - optional identifier of the Eclipse application |
| 626 : | that is to be used during startup when the declaring feature is the | ||
| 627 : | <a href="#Dominant_Feature"> primary feature</a> . The application | ||
| 628 : | identifier must represent a valid application registered in the <tt>org.eclipse.core.runtime.applications</tt> | ||
| 629 : | extension point. Default is <tt>org.eclipse.ui.workbench</tt>.</li> | ||
| 630 : | <li> plugin- optional identifier of the primary plugin associated | ||
| 631 : | with this <a | ||
| 632 : | href="file:///C:/OTI/workspace/plugins/platform-update-home/doc/eclipse_update_packaging.html#Dominant_Feature">primary | ||
| 633 : | feature</a>. The primary plugin carries branding information. If the plugin | ||
| 634 : | attribute is not declared, the primary plugin identifier used will be the | ||
| 635 : | celek | 1.17 | same as the feature identifier. </li> |
| 636 : | celek | 1.18 | |
| 637 : | celek | 1.17 | </ul> |
| 638 : | celek | 1.18 | <li> <install-handler></li> |
| 639 : | |||
| 640 : | celek | 1.17 | <ul> |
| 641 : | celek | 1.18 | <li> library - optional .jar library containing the install |
| 642 : | handler classes. If specified, the referenced .jar must be contained | ||
| 643 : | in the feature archive. It is specified as a path within the feature | ||
| 644 : | archive, relative to the feature.xml entry. If not specified, the feature | ||
| 645 : | archive itself is used to load the install handler classes. This attribute | ||
| 646 : | celek | 1.17 | is only interpreted if <i>class</i> attribute is also specified</li> |
| 647 : | celek | 1.18 | <li> handler - optional identifier of the install handler. |
| 648 : | The value is interpreted depending on the value of the <i>library</i> | ||
| 649 : | attribute. If <i> library</i> is specified, the value is | ||
| 650 : | interpreted as a fully qualified name of a class contained in the specified | ||
| 651 : | <i>library</i>. If <i>library</i> is not specified, the | ||
| 652 : | value is is interpreted as an extension identifier of an extension registered | ||
| 653 : | in the <i>org.eclipse.update.installHandlers</i> extension point. In | ||
| 654 : | either case, the resulting class must implement the <i> IInstallHandler</i> | ||
| 655 : | interface. The class is dynamically loaded and called at specific points | ||
| 656 : | during feature processing. The handler has visibility to the API classes | ||
| 657 : | celek | 1.17 | from the update plug-in, and Eclipse plug-ins required by the update plugin.</li> |
| 658 : | celek | 1.18 | |
| 659 : | celek | 1.17 | </ul> |
| 660 : | celek | 1.18 | <li> <description> - brief component description as |
| 661 : | simple text. Intended to be translated.</li> | ||
| 662 : | |||
| 663 : | <ul> | ||
| 664 : | <li> url - optional URL for the full description as HTML. The | ||
| 665 : | URL can be specified as absolute of relative. If relative, it is assumed | ||
| 666 : | to be relative to (and packaged in) the feature archive. Note, that for | ||
| 667 : | NL handling the URL value should be separated to allow alternate URLs to | ||
| 668 : | be specified for each national language. URL support keywords $os$,$ws$,$arch$ | ||
| 669 : | and $nl$ that will be replaced by the appropriate operating system, windowing | ||
| 670 : | system, operating architecture or national language value.</li> | ||
| 671 : | |||
| 672 : | celek | 1.17 | </ul> |
| 673 : | celek | 1.18 | <li> <copyright> - feature copyright as simple text. |
| 674 : | celek | 1.17 | Intended to be translated.</li> |
| 675 : | celek | 1.18 | |
| 676 : | celek | 1.17 | <ul> |
| 677 : | celek | 1.18 | <li> url - optional URL for the full description as HTML. The |
| 678 : | URL can be specified as absolute of relative. If relative, it is assumed | ||
| 679 : | to be relative to (and packaged in) the feature archive. Note, that for | ||
| 680 : | NL handling the URL value should be separated to allow alternate URLs to | ||
| 681 : | be specified for each national language. URL support keywords $os$,$ws$,$arch$ | ||
| 682 : | and $nl$ that will be replaced by the appropriate operating system, windowing | ||
| 683 : | system, operating architecture or national language value.</li> | ||
| 684 : | |||
| 685 : | celek | 1.16 | </ul> |
| 686 : | celek | 1.18 | <li> <license> - feature "click-through" license as |
| 687 : | simple text. Intended to be translated. It is displayed in a standard | ||
| 688 : | dialog with [Accept] [Reject] actions during the download/ installation | ||
| 689 : | process. Note, that click-through license must be specified for any feature | ||
| 690 : | that will be selected for installation or update using the Eclipse update | ||
| 691 : | manager. When using nested features, only the nesting parent (ie. the feature | ||
| 692 : | selected for installation or update) must have click-through license text | ||
| 693 : | defined. The license text is required even if the optional <i>url</i> attribute | ||
| 694 : | is specified.</li> | ||
| 695 : | |||
| 696 : | <ul> | ||
| 697 : | <li> url - optional URL for the full description as HTML. The | ||
| 698 : | URL can be specified as absolute of relative. If relative, it is assumed | ||
| 699 : | to be relative to (and packaged in) the feature archive. Note, that for | ||
| 700 : | NL handling the URL value should be separated to allow alternate URLs to | ||
| 701 : | be specified for each national language. Note, that the "content" of this | ||
| 702 : | URL is <b>not</b> what is presented as the click-through license during | ||
| 703 : | installation processing. The click-through license is the actual value | ||
| 704 : | of the <i><license></i> element (eg. <tt><license>click | ||
| 705 : | through text</license></tt>). URL support keywords $os$,$ws$,$arch$ | ||
| 706 : | and $nl$ that will be replaced by the appropriate operating system, windowing | ||
| 707 : | celek | 1.16 | system, operating architecture or national language value.</li> |
| 708 : | celek | 1.18 | |
| 709 : | celek | 1.14 | </ul> |
| 710 : | celek | 1.18 | <li> <url> - optional URL specifying site(s) contain |
| 711 : | celek | 1.17 | feature updates, or new features</li> |
| 712 : | celek | 1.18 | |
| 713 : | celek | 1.13 | <ul> |
| 714 : | celek | 1.18 | <li> <update> - URL to go to for updates to this feature</li> |
| 715 : | celek | 1.17 | |
| 716 : | celek | 1.18 | |
| 717 : | celek | 1.7 | <ul> |
| 718 : | celek | 1.18 | <li> url - actual URL</li> |
| 719 : | <li> label - displayable label (name) for the referenced site</li> | ||
| 720 : | celek | 1.17 | |
| 721 : | celek | 1.18 | |
| 722 : | celek | 1.7 | </ul> |
| 723 : | celek | 1.18 | <li> <discovery> - URL to go to for new features. In |
| 724 : | general, a provider can use this element to reference its own site(s), | ||
| 725 : | or site(s) of partners that offer complementary features. Eclipse uses | ||
| 726 : | celek | 1.17 | this element simply as a way to distribute new site URLs to the clients</li> |
| 727 : | |||
| 728 : | celek | 1.18 | |
| 729 : | celek | 1.7 | <ul> |
| 730 : | celek | 1.18 | <li> url - actual URL</li> |
| 731 : | <li> label - displayable label (name) for the referenced site</li> | ||
| 732 : | <li>type - whether the site is an regular update site or a web site. | ||
| 733 : | The web site may be a web-triggered-install web site. (<tt>update</tt> is | ||
| 734 : | the default)<br> | ||
| 735 : | </li> | ||
| 736 : | celek | 1.17 | |
| 737 : | celek | 1.18 | |
| 738 : | celek | 1.11 | </ul> |
| 739 : | celek | 1.18 | |
| 740 : | celek | 1.7 | </ul> |
| 741 : | celek | 1.18 | <li> <includes> - optional reference to a nested feature |
| 742 : | that is considered to be part of this feature. Nested features must be | ||
| 743 : | located on the same update site as this feature</li> | ||
| 744 : | |||
| 745 : | <ul> | ||
| 746 : | <li> id - required nested feature identifier</li> | ||
| 747 : | <li> version - required nested feature version</li> | ||
| 748 : | <li> name- optional displayable label (name). Intended to | ||
| 749 : | be translated.</li> | ||
| 750 : | <li>optional - optional specification indicating if this | ||
| 751 : | celek | 1.17 | included feature can be optionally installed. Default is "false"<br> |
| 752 : | celek | 1.18 | </li> |
| 753 : | <li>match - optional rule that will be applied when | ||
| 754 : | resolving the feature reference. A <samp>perfect</samp> match (the | ||
| 755 : | default that matches the 2.0.1 behavior) requires that the feature has | ||
| 756 : | exactly the version specified by the version attribute. Other choices | ||
| 757 : | progressively relax the rule (<samp> equivalent</samp> allows only service | ||
| 758 : | part of the version to be more recent, <samp>compatible</samp> | ||
| 759 : | also allows minor part to be included in the consideration, while <samp>greaterOrEqual</samp> | ||
| 760 : | simply allows any version that is more recent or identical to the one | ||
| 761 : | celek | 1.17 | specified).</li> |
| 762 : | celek | 1.18 | <li>search-location - optional. Indicates whether |
| 763 : | the "New Updates" action should search the update location determined | ||
| 764 : | by the nesting root feature (<tt>root</tt>, is the default), or the location | ||
| 765 : | defined by the nested feature (<tt>self</tt>), or search both (<tt>both</tt>) | ||
| 766 : | celek | 1.17 | in that order (root first, self if nothing is found).</li> |
| 767 : | celek | 1.18 | |
| 768 : | celek | 1.17 | </ul> |
| 769 : | celek | 1.18 | <li> <requires> - optional feature dependency information. |
| 770 : | Is expressed in terms of plug-in dependencies. If specified, is enforced | ||
| 771 : | celek | 1.17 | by the installation and update support at the time of installation</li> |
| 772 : | celek | 1.18 | |
| 773 : | celek | 1.14 | <ul> |
| 774 : | celek | 1.18 | <li> <import> - dependency entry. Specification and processing |
| 775 : | is a subset of the <import> specification in plugin.xml</li> | ||
| 776 : | celek | 1.17 | |
| 777 : | celek | 1.18 | |
| 778 : | celek | 1.7 | <ul> |
| 779 : | celek | 1.18 | <li> plugin - identifier of dependent plug-in.</li> |
| 780 : | <li> feature - identifier of dependent feature. If plugin | ||
| 781 : | and feature are specified, plugin takes precedence upon feature. Feature | ||
| 782 : | or plugin must be specified.</li> | ||
| 783 : | <li> version - optional plug-in/feature version specification</li> | ||
| 784 : | <li>patch - optional specification indicating if this | ||
| 785 : | feature is a patch of the dependant feature. Default is "false". If | ||
| 786 : | patch is true, version must be specified. If patch is true, only feature | ||
| 787 : | must be specified. If patch is true, and match is specified, it must | ||
| 788 : | be 'perfect'.<br> | ||
| 789 : | </li> | ||
| 790 : | <li> match - optional matching rule. Valid values and processing | ||
| 791 : | celek | 1.17 | are as follows:</li> |
| 792 : | celek | 1.14 | |
| 793 : | celek | 1.18 | |
| 794 : | celek | 1.7 | <ul> |
| 795 : | celek | 1.18 | <li> if version attribute is not specified, the match attribute |
| 796 : | celek | 1.17 | (if specified) is ignored.</li> |
| 797 : | celek | 1.18 | <li>if version is specified, match defaults to compatible.<br> |
| 798 : | </li> | ||
| 799 : | <li>if patch is true, and match is not specified, match | ||
| 800 : | defaults to perfect.<br> | ||
| 801 : | </li> | ||
| 802 : | <li> <b><i>perfect</i></b> - dependent plug-in version must | ||
| 803 : | match exactly the specified version.</li> | ||
| 804 : | <li> <b><i>equivalent</i></b> - dependent plug-in version | ||
| 805 : | must be at least at the version specified, or at a higher service level | ||
| 806 : | (major and minor version levels must equal the specified version).</li> | ||
| 807 : | <li> <b><i>compatible</i></b> - dependent plug-in version | ||
| 808 : | must be at least at the version specified, or at a higher service level | ||
| 809 : | or minor level (major version level must equal the specified version).</li> | ||
| 810 : | <li> <b><i>greaterOrEqual</i></b> - dependent plug-in version | ||
| 811 : | must be at least at the version specified, or at a higher service, minor | ||
| 812 : | or major level.</li> | ||
| 813 : | celek | 1.14 | |
| 814 : | celek | 1.18 | |
| 815 : | celek | 1.12 | </ul> |
| 816 : | celek | 1.17 | |
| 817 : | celek | 1.18 | |
| 818 : | celek | 1.11 | </ul> |
| 819 : | celek | 1.18 | |
| 820 : | celek | 1.7 | </ul> |
| 821 : | celek | 1.18 | <li> <plugin> - identifies referenced plug-in</li> |
| 822 : | |||
| 823 : | celek | 1.7 | <ul> |
| 824 : | celek | 1.18 | <li> id - required plug-in identifier (from plugin.xml)</li> |
| 825 : | <li> version - required plug-in version (from plugin.xml)</li> | ||
| 826 : | <li> fragment - optional specification indicating if this | ||
| 827 : | entry is a plug-in fragment. Default is "false"</li> | ||
| 828 : | <li> os - optional operating system specification. A comma-separated | ||
| 829 : | list of os designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt> | ||
| 830 : | . Indicates this entry should only be installed on one of the specified | ||
| 831 : | os systems. If this attribute is not specified, the entry can be installed | ||
| 832 : | on all systems (portable implementation). This information is used | ||
| 833 : | as a hint by the installation and update support (user can force installation | ||
| 834 : | of entry regardless of this setting).</li> | ||
| 835 : | <li> arch - optional machine architecture specification. A | ||
| 836 : | comma-separated list of architecture designators defined by Eclipse | ||
| 837 : | (see Javadoc for <tt> org.eclipse.core.boot.BootLoader)</tt>. Indicates | ||
| 838 : | this feature should only be installed on one of the specified systems. | ||
| 839 : | If this attribute is not specified, the feature can be installed on all | ||
| 840 : | systems (portable implementation). This information is used as a hint | ||
| 841 : | by the installation and update support (user can force installation of | ||
| 842 : | feature regardless of this setting).</li> | ||
| 843 : | <li> ws - optional windowing system specification. A comma-separated | ||
| 844 : | list of ws designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt> | ||
| 845 : | . Indicates this entry should only be installed on one of the specified | ||
| 846 : | ws systems. If this attribute is not specified, the entry can be installed | ||
| 847 : | on all systems (portable implementation). This information is used | ||
| 848 : | as a hint by the installation and update support (user can force installation | ||
| 849 : | of entry regardless of this setting).</li> | ||
| 850 : | <li> nl - optional locale specification. A comma-separated | ||
| 851 : | list of locale designators defined by Java. Indicates this entry should | ||
| 852 : | only be installed on a system running with a compatible locale (using | ||
| 853 : | Java locale-matching rules). If this attribute is not specified, the entry | ||
| 854 : | can be installed on all systems (language-neutral implementation). This | ||
| 855 : | information is used as a hint by the installation and update support (user | ||
| 856 : | can force installation of entry regardless of this setting).</li> | ||
| 857 : | <li> download-size - optional hint supplied by the feature | ||
| 858 : | packager, indicating the download size in KBytes of the referenced plug-in | ||
| 859 : | archive.The size should not contain decimal. If not specified, the download | ||
| 860 : | size is not known (<b>Implementation Note:</b> the implementation needs | ||
| 861 : | to distinguish between "not known" and 0 size)</li> | ||
| 862 : | <li> install-size - optional hint supplied by the feature | ||
| 863 : | packager, indicating the install size in KBytes of the referenced | ||
| 864 : | plug-in archive. The size should not contain decimal. If not specified, | ||
| 865 : | the install size is not known (<b>Implementation Note:</b> the implementation | ||
| 866 : | needs to distinguish between "not known" and 0 size)</li> | ||
| 867 : | |||
| 868 : | celek | 1.16 | </ul> |
| 869 : | celek | 1.18 | <li> <data> - identifies non-plugin and non-feature |
| 870 : | data that is part of the feature. Generally, data are post-install processed | ||
| 871 : | using feature Install handler. Feature files like feature.properties are | ||
| 872 : | celek | 1.17 | not considered data.</li> |
| 873 : | celek | 1.18 | |
| 874 : | celek | 1.16 | <ul> |
| 875 : | celek | 1.18 | <li> id - required data identifier in the form of a relative |
| 876 : | path.</li> | ||
| 877 : | <li> os - optional operating system specification. A comma-separated | ||
| 878 : | list of os designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt> | ||
| 879 : | . Indicates this entry should only be installed on one of the specified | ||
| 880 : | os systems. If this attribute is not specified, the entry can be installed | ||
| 881 : | on all systems (portable implementation). This information is used | ||
| 882 : | as a hint by the installation and update support (user can force installation | ||
| 883 : | of entry regardless of this setting).</li> | ||
| 884 : | <li> arch - optional machine architecture specification. A | ||
| 885 : | comma-separated list of architecture designators defined by Eclipse | ||
| 886 : | (see Javadoc for <tt> org.eclipse.core.boot.BootLoader)</tt>. Indicates | ||
| 887 : | this feature should only be installed on one of the specified systems. | ||
| 888 : | If this attribute is not specified, the feature can be installed on all | ||
| 889 : | systems (portable implementation). This information is used as a hint | ||
| 890 : | by the installation and update support (user can force installation of | ||
| 891 : | feature regardless of this setting).</li> | ||
| 892 : | <li> ws - optional windowing system specification. A comma-separated | ||
| 893 : | list of ws designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt> | ||
| 894 : | . Indicates this entry should only be installed on one of the specified | ||
| 895 : | ws systems. If this attribute is not specified, the entry can be installed | ||
| 896 : | on all systems (portable implementation). This information is used | ||
| 897 : | as a hint by the installation and update support (user can force installation | ||
| 898 : | of entry regardless of this setting).</li> | ||
| 899 : | <li> nl - optional locale specification. A comma-separated | ||
| 900 : | list of locale designators defined by Java. Indicates this entry should | ||
| 901 : | only be installed on a system running with a compatible locale (using | ||
| 902 : | Java locale-matching rules). If this attribute is not specified, the entry | ||
| 903 : | can be installed on all systems (language-neutral implementation). This | ||
| 904 : | information is used as a hint by the installation and update support (user | ||
| 905 : | can force installation of entry regardless of this setting).</li> | ||
| 906 : | <li> download-size - optional hint supplied by the feature | ||
| 907 : | packager, indicating the download size in KBytes of the referenced data | ||
| 908 : | archive. If not specified, the download size is not known (<b>Implementation | ||
| 909 : | Note:</b> the implementation needs to distinguish between "not known" | ||
| 910 : | and 0 size)</li> | ||
| 911 : | <li> install-size - optional hint supplied by the feature | ||
| 912 : | packager, indicating the install size in KBytes of the referenced | ||
| 913 : | data archive. If not specified, the install size is not known (<b>Implementation | ||
| 914 : | Note:</b> the implementation needs to distinguish between "not known" | ||
| 915 : | celek | 1.17 | and 0 size)</li> |
| 916 : | celek | 1.18 | |
| 917 : | celek | 1.10 | </ul> |
| 918 : | celek | 1.18 | |
| 919 : | celek | 1.9 | </ul> |
| 920 : | celek | 1.18 | <a name="Feature_Archive_Mapping_Id_To_Path"></a> When interacting |
| 921 : | with the update site, the feature implementation maps the <tt><plugin></tt> | ||
| 922 : | and <tt><data></tt> elements into path identifiers used by the | ||
| 923 : | site to determine the actual files to download and install. The default | ||
| 924 : | feature implementation supplied by Eclipse constructs the path identifiers | ||
| 925 : | as follows: | ||
| 926 : | celek | 1.7 | <ul> |
| 927 : | celek | 1.18 | <li> <tt><plugin></tt> element results in a path entry |
| 928 : | in the form "<tt>plugins/<pluginId>_<pluginVersion>.jar</tt>" | ||
| 929 : | celek | 1.17 | (for example, "<tt>plugins/org.eclipse.core.boot_1.0.3.jar</tt>")</li> |
| 930 : | celek | 1.18 | <li> <tt><data></tt> element results in a path entry |
| 931 : | in the form "<tt>features/<featureId>_<featureVersion>/<dataId></tt> | ||
| 932 : | celek | 1.17 | " (for example, "f<tt>eatures/com.xyz.tools_2.3.1/examples.zip</tt>")</li> |
| 933 : | celek | 1.18 | |
| 934 : | celek | 1.7 | </ul> |
| 935 : | celek | 1.18 | Note, that in general the feature.xml manifest documents |
| 936 : | should specify UTF-8 encoding. For example | ||
| 937 : | celek | 1.7 | <p><tt><?xml version="1.0" encoding="UTF-8"?></tt> </p> |
| 938 : | celek | 1.18 | |
| 939 : | <p>Translatable text contained in the feature.xml can be separated into feature<_locale>.properties | ||
| 940 : | files using Java property bundle conventions. Note that the translated | ||
| 941 : | strings are used at installation time (ie. do not employ the plug-in | ||
| 942 : | celek | 1.17 | fragment runtime mechanism). </p> |
| 943 : | celek | 1.18 | |
| 944 : | celek | 1.9 | <h3> <a name="Plug-In_Archive"></a> Plug-In Archive</h3> |
| 945 : | celek | 1.18 | Plug-ins and plug-in fragments are individually packaged as |
| 946 : | separate Java .jars. Standard Java jar facilities are used for constructing | ||
| 947 : | plug-in archives. There is no distinction made between a plug-in archive | ||
| 948 : | containing a plug-in and one containing a plug-in fragment. | ||
| 949 : | |||
| 950 : | celek | 1.7 | <p>The recommended convention for naming the plug-in archives is <br> |
| 951 : | celek | 1.18 | <tt><id>_<version>.jar</tt> </p> |
| 952 : | |||
| 953 : | <p>Where <tt><id></tt> is the plug-in or fragment identifier and <tt> | ||
| 954 : | <version></tt> is the full version identifier contained in the | ||
| 955 : | respective plugin.xml or fragment.xml. Note that this is a recommended | ||
| 956 : | convention that minimizes chance of collisions, but is not required by | ||
| 957 : | the Eclipse architecture. For example, the following are valid plug-in | ||
| 958 : | celek | 1.17 | archive names </p> |
| 959 : | celek | 1.18 | |
| 960 : | celek | 1.7 | <p><tt>org.eclipse.platform_1.0.3.jar</tt> <br> |
| 961 : | celek | 1.18 | <tt>org.eclipse.ui.nl_2.0.jar</tt> <br> |
| 962 : | <tt>my_plugin.jar</tt> </p> | ||
| 963 : | |||
| 964 : | <p>Internally, each plug-in archive packages all the relevant plug-in or | ||
| 965 : | fragment files relative to its plug-in or fragment directory (but not including | ||
| 966 : | the directory path element). The archive has the following structure </p> | ||
| 967 : | |||
| 968 : | celek | 1.7 | <p><tt>plugin.xml *OR* fragment.xml</tt> <br> |
| 969 : | celek | 1.18 | <tt>other plug-in or feature files and subdirectories</tt> <br> |
| 970 : | <tt>META-INF/</tt> <br> | ||
| 971 : | <tt> Java jar manifest and security files</tt> | ||
| 972 : | celek | 1.17 | </p> |
| 973 : | celek | 1.18 | |
| 974 : | celek | 1.9 | <h3> <a name="Packaging_NL"></a> Packaging NL</h3> |
| 975 : | celek | 1.18 | In Eclipse, translated plug-in information is packaged either |
| 976 : | together with the base plug-in, or as a plug-in fragment. At runtime, | ||
| 977 : | Eclipse locates the translations for the required locale. The use of | ||
| 978 : | fragments allows translations to be added to the runtime without the need | ||
| 979 : | to repackage the base plug-ins. | ||
| 980 : | <p>This mechanism cannot be used for translating the actual packaging information | ||
| 981 : | that is part of the installation xml files. Consequently the standard | ||
| 982 : | Java translation conventions are used for the packaging information, | ||
| 983 : | and all necessary translations must be available at the time the feature | ||
| 984 : | is packaged. </p> | ||
| 985 : | |||
| 986 : | celek | 1.9 | <h4> <a name="Translated_Feature_Information"></a> Translated Feature Information</h4> |
| 987 : | celek | 1.18 | <b>Note:</b> This section describes the conventions used for |
| 988 : | translating the information contained within the feature manifest. | ||
| 989 : | It allows for the update client to select the correctly localized strings | ||
| 990 : | from the update server. This section specifically does not describe | ||
| 991 : | localization of individual plug-ins. | ||
| 992 : | <p>Several of the attributes within the feature manifest are strings intended | ||
| 993 : | for display through user interfaces. To facilitate translation, these | ||
| 994 : | attribute values use the convention defined for translatable attributes | ||
| 995 : | of plugin.xml. Strings beginning with % up to the first space are treated | ||
| 996 : | as resource identifier keys (without the %) and looked up in a properties | ||
| 997 : | file. For example </p> | ||
| 998 : | |||
| 999 : | celek | 1.7 | <p><tt>label="%cfg Tool Feature for Linux"</tt> </p> |
| 1000 : | celek | 1.18 | |
| 1001 : | <p>results in a resource lookup in the correct property file with key "cfg". | ||
| 1002 : | If no property files are supplied, or the key is not found the default | ||
| 1003 : | string value (following the %key) is used. </p> | ||
| 1004 : | |||
| 1005 : | <p>The property files are named as feature_<locale>.properties using | ||
| 1006 : | the Java resource bundle naming conventions. Within the feature archive | ||
| 1007 : | .jar they are placed in the same directory as their corresponding feature.xml | ||
| 1008 : | file. </p> | ||
| 1009 : | |||
| 1010 : | <p><b>Implementation Note</b>: When accessing the resource bundles the Eclipse | ||
| 1011 : | installation and update code should create a class loader for accessing | ||
| 1012 : | the translated string. This way, the standard locale lookup algorithm | ||
| 1013 : | celek | 1.17 | implemented by Java is automatically used. </p> |
| 1014 : | celek | 1.18 | |
| 1015 : | celek | 1.7 | <p><tt>ResourceBundle b;</tt> <br> |
| 1016 : | celek | 1.18 | <tt>ClassLoader l;</tt> <br> |
| 1017 : | <tt>l = new URLClassLoader(new URL[] {<targetDirectoryURL>}, | ||
| 1018 : | celek | 1.17 | null);</tt> <br> |
| 1019 : | celek | 1.18 | <tt>b = ResourceBundle.getBundle("feature",Locale.getDefault(),l);</tt> |
| 1020 : | </p> | ||
| 1021 : | |||
| 1022 : | <p>The resulting resource bundle can be used in <tt>IPluginDescriptor.getResourceString(String,ResourceBundle)</tt> | ||
| 1023 : | to actually return the correct translated string for the manifest attribute. | ||
| 1024 : | </p> | ||
| 1025 : | |||
| 1026 : | celek | 1.9 | <h4> <a name="Translated_Plug-In_Information"></a> Translated Plug-In Information</h4> |
| 1027 : | celek | 1.18 | No change from 1.0. Translated plug-in information should be |
| 1028 : | packaged as plug-in fragments. | ||
| 1029 : | <h3> <a name="Packaging_Target-Specific_Support"></a> Packaging Target-Specific | ||
| 1030 : | Support</h3> | ||
| 1031 : | No change from 1.0. Target-specific plug-in support (os, ws) | ||
| 1032 : | should be packaged as plug-in fragments. | ||
| 1033 : | <h3> <a name="Packaging_Attribution_Information"></a> Packaging Attribution | ||
| 1034 : | Information</h3> | ||
| 1035 : | This topic is covered in separate documents available on the | ||
| 1036 : | eclipse.org development resources page of the Update component. | ||
| 1037 : | |||
| 1038 : | celek | 1.9 | <h3> <a name="Packaging_Non_Plug_In_Files"></a> Packaging Non-Plug-In Files</h3> |
| 1039 : | celek | 1.18 | Arbitrary non-plug-in files can be included as part of the |
| 1040 : | feature definition using the <tt><data></tt> elements. Non-plug-in | ||
| 1041 : | files typically also requires specification of a custom install handler. | ||
| 1042 : | In general, the Eclipse support only downloads the referenced non-plug-in | ||
| 1043 : | files and calls the custom install handler to perform any actual installation | ||
| 1044 : | steps. | ||
| 1045 : | celek | 1.7 | <p>Eclipse does not specify the format of the non-plug-in files. </p> |
| 1046 : | celek | 1.18 | |
| 1047 : | celek | 1.9 | <h3> <a name="Custom_Install_Handling"></a> Custom Install Handling</h3> |
| 1048 : | celek | 1.18 | Custom install handlers are written as a Java class and are |
| 1049 : | packaged as part of the <a href="#Feature_Archive">feature archive</a> | ||
| 1050 : | . The installer must implement the <tt>IInstallHandler</tt> interface | ||
| 1051 : | (in most cases will extend the <tt>BaseInstallHandler</tt> abstract helper | ||
| 1052 : | class which implements <tt>IInstallHandler</tt>). When required, the | ||
| 1053 : | install handler is dynamically loaded by the installation and update | ||
| 1054 : | code, and is called at specific points during its processing. The install | ||
| 1055 : | handler code has visibility to classes from the installation and update | ||
| 1056 : | support plug-in, and its prerequisite plug-ins. | ||
| 1057 : | <p><b>Implementation Note:</b> the detailed list of visible prerequisite | ||
| 1058 : | plug-ins is still evolving. It is expected to include <tt>org.eclipse.core.boot | ||
| 1059 : | </tt> and <tt>org.eclipse.core.runtime</tt> in all cases, plus <tt>org.eclipse.ui</tt> | ||
| 1060 : | and <tt>org.eclipse.swt</tt> when running with full workbench (ie. | ||
| 1061 : | not "headless mode"). Also, it would be useful to always expose <tt>org.eclipse.core.ant</tt> | ||
| 1062 : | so that build scripts can be used as part of the install handler implementation. | ||
| 1063 : | </p> | ||
| 1064 : | |||
| 1065 : | <p>The IInstallHandler interface supports the following methods [<b>Implementation | ||
| 1066 : | Note:</b> the detailed definition of the IInstallHandler interface | ||
| 1067 : | is still evolving. The description below is not an API specification | ||
| 1068 : | (simply a functional description)]: </p> | ||
| 1069 : | |||
| 1070 : | celek | 1.7 | <ul> |
| 1071 : | celek | 1.18 | <li> install-initiated - the install handler is called after |
| 1072 : | a feature was selected for installation, but before any files were | ||
| 1073 : | downloaded. It is intended to implement any custom click-through or | ||
| 1074 : | user registration dialogs. The base implementation of this method supplied | ||
| 1075 : | with the abstract class <tt>BaseInstallHandler </tt>performs | ||
| 1076 : | the default click-through processing using the license text supplied | ||
| 1077 : | as part of the feature manifest. On return this method indicates success | ||
| 1078 : | (installation continues) of failure (installation is aborted).</li> | ||
| 1079 : | <li> install-downloaded - the install handler is called after | ||
| 1080 : | all the required feature files were downloaded (feature, plugins, | ||
| 1081 : | data) but before the actual installation is performed. The install | ||
| 1082 : | handler is expected to perform verification of the non-plug-in data | ||
| 1083 : | files (eg. security), or any other pre-install processing. On | ||
| 1084 : | return this method indicates success (installation continues) or failure | ||
| 1085 : | (installation is aborted).</li> | ||
| 1086 : | <li> install-completion - the install handler is called after | ||
| 1087 : | the feature information and the plug-ins were installed. It is expected | ||
| 1088 : | to complete the installation of any non-plug-in data that was part of | ||
| 1089 : | the feature. On return this method indicates success (returns custom install | ||
| 1090 : | log) or failure (installation is aborted). On failure, the install handler | ||
| 1091 : | is expected to perform any required cleanup.</li> | ||
| 1092 : | <li> uninstall-initiated - the install handler is called when | ||
| 1093 : | a feature is selected for removal, but before any of the standard uninstall | ||
| 1094 : | processing has taken place. It is passed the custom install log created | ||
| 1095 : | by the install handler install-completion step.</li> | ||
| 1096 : | <li> uninstall-completion - the install handler is called | ||
| 1097 : | on completion of the standard uninstall steps. It is passed the custom | ||
| 1098 : | celek | 1.17 | install log created by the install handler install-completion step.</li> |
| 1099 : | celek | 1.18 | |
| 1100 : | celek | 1.7 | </ul> |
| 1101 : | celek | 1.18 | Note, that as a general practice, install handlers should be |
| 1102 : | provided in their own jars (even though they could be just exposed | ||
| 1103 : | in the feature archive jar). The jar should be signed, and sealed. | ||
| 1104 : | |||
| 1105 : | celek | 1.9 | <h3> <a name="Security_Considerations"></a> Security Considerations</h3> |
| 1106 : | celek | 1.18 | The general approach is to use base Java jar signing for the |
| 1107 : | feature and plug-in archive .jars. | ||
| 1108 : | celek | 1.7 | <p>Features are verified as follows: </p> |
| 1109 : | celek | 1.18 | |
| 1110 : | celek | 1.7 | <ul> |
| 1111 : | celek | 1.18 | <li> download and verify the feature archive (use base Java |
| 1112 : | celek | 1.17 | jar verification)</li> |
| 1113 : | celek | 1.18 | <li> for each plug-in archive</li> |
| 1114 : | |||
| 1115 : | celek | 1.14 | <ul> |
| 1116 : | celek | 1.18 | <li> verify the archive jar content (use base Java jar verification)</li> |
| 1117 : | <li> verify plug-in id and version from <tt><plugin></tt> | ||
| 1118 : | entry in feature manifest matches downloaded plugin.xml</li> | ||
| 1119 : | |||
| 1120 : | celek | 1.7 | </ul> |
| 1121 : | celek | 1.18 | <li> for each non-plugin file</li> |
| 1122 : | |||
| 1123 : | celek | 1.7 | <ul> |
| 1124 : | celek | 1.18 | <li> call install handler to verify file</li> |
| 1125 : | |||
| 1126 : | celek | 1.10 | </ul> |
| 1127 : | celek | 1.18 | |
| 1128 : | celek | 1.9 | </ul> |
| 1129 : | celek | 1.18 | In general, when processing signed jars, the user will be prompted |
| 1130 : | for each unrecognized certificate. The response choices will include | ||
| 1131 : | aborting the installation (originator is not trusted), continuing the | ||
| 1132 : | installation (originator is trusted for this installation). | ||
| 1133 : | |||
| 1134 : | celek | 1.9 | <h2> <a name="Update_Server"></a> Update Server</h2> |
| 1135 : | celek | 1.18 | The default Eclipse update server is any URL-accessible server. |
| 1136 : | The default implementation assumes a fixed-layout server. The content | ||
| 1137 : | of the server (in terms of available features and plug-ins) is described | ||
| 1138 : | in a site map file, <i>site.xml</i>. This file can be manually maintained, | ||
| 1139 : | or can be dynamically computed by the server. | ||
| 1140 : | celek | 1.9 | <h3> <a name="Site_Map"></a> Site Map</h3> |
| 1141 : | celek | 1.18 | The update server URL can be specified as a full URL to the |
| 1142 : | site map file, or a URL of a directory path containing the site map | ||
| 1143 : | file (similar to index.html processing). The site map site.xml format | ||
| 1144 : | is defined by the following dtd: | ||
| 1145 : | celek | 1.7 | <p><tt><?xml encoding="ISO-8859-1"?></tt> </p> |
| 1146 : | celek | 1.18 | |
| 1147 : | <p><tt><!ELEMENT site (description?, feature*, archive*, category-def*)></tt> | ||
| 1148 : | celek | 1.17 | <br> |
| 1149 : | celek | 1.18 | <tt><!ATTLIST site</tt> <br> |
| 1150 : | <tt> type | ||
| 1151 : | CDATA #IMPLIED</tt> <br> | ||
| 1152 : | <tt> url | ||
| 1153 : | CDATA #IMPLIED</tt> <br> | ||
| 1154 : | <tt>></tt> </p> | ||
| 1155 : | |||
| 1156 : | celek | 1.7 | <p><tt><!ELEMENT description (#PCDATA)></tt> <br> |
| 1157 : | celek | 1.18 | <tt><!ATTLIST description</tt> <br> |
| 1158 : | <tt> url | ||
| 1159 : | CDATA #IMPLIED</tt> <br> | ||
| 1160 : | <tt>></tt> </p> | ||
| 1161 : | |||
| 1162 : | celek | 1.7 | <p><tt><!ELEMENT feature (category*)></tt> <br> |
| 1163 : | celek | 1.18 | <tt><!ATTLIST feature</tt> <br> |
| 1164 : | <tt> type | ||
| 1165 : | CDATA #IMPLIED</tt> <br> | ||
| 1166 : | <tt> id | ||
| 1167 : | CDATA #IMPLIED</tt> <br> | ||
| 1168 : | <tt> version | ||
| 1169 : | celek | 1.17 | CDATA #IMPLIED</tt> <br> |
| 1170 : | celek | 1.18 | <tt> url |
| 1171 : | CDATA #REQUIRED<br> | ||
| 1172 : | label | ||
| 1173 : | CDATA #IMPLIED<br> | ||
| 1174 : | </tt><tt> os | ||
| 1175 : | CDATA #IMPLIED</tt> <br> | ||
| 1176 : | <tt> arch | ||
| 1177 : | CDATA #IMPLIED</tt> <br> | ||
| 1178 : | <tt> ws | ||
| 1179 : | CDATA #IMPLIED</tt> <br> | ||
| 1180 : | <tt> nl | ||
| 1181 : | CDATA #IMPLIED</tt><br> | ||
| 1182 : | <tt> patch </tt><tt> | ||
| 1183 : | celek | 1.17 | (true | false) "false"</tt><br> |
| 1184 : | celek | 1.18 | <tt> ></tt> </p> |
| 1185 : | |||
| 1186 : | celek | 1.7 | <p><tt><!ELEMENT archive EMPTY></tt> <br> |
| 1187 : | celek | 1.18 | <tt><!ATTLIST archive</tt> <br> |
| 1188 : | <tt> path | ||
| 1189 : | CDATA #REQUIRED</tt> <br> | ||
| 1190 : | <tt> url | ||
| 1191 : | CDATA #REQUIRED</tt> <br> | ||
| 1192 : | <tt>></tt> </p> | ||
| 1193 : | |||
| 1194 : | celek | 1.7 | <p><tt><!ELEMENT category EMPTY></tt> <br> |
| 1195 : | celek | 1.18 | <tt><!ATTLIST category</tt> <br> |
| 1196 : | <tt> name | ||
| 1197 : | CDATA #REQUIRED</tt> <br> | ||
| 1198 : | <tt>></tt> </p> | ||
| 1199 : | |||
| 1200 : | celek | 1.7 | <p><tt><!ELEMENT category-def (description?)></tt> <br> |
| 1201 : | celek | 1.18 | <tt><!ATTLIST category-def</tt> <br> |
| 1202 : | <tt> name | ||
| 1203 : | CDATA #REQUIRED</tt> <br> | ||
| 1204 : | <tt> label | ||
| 1205 : | CDATA #REQUIRED</tt> <br> | ||
| 1206 : | <tt>></tt> </p> | ||
| 1207 : | |||
| 1208 : | celek | 1.7 | <p>The element and attribute definitions are as follows: </p> |
| 1209 : | celek | 1.18 | |
| 1210 : | celek | 1.7 | <ul> |
| 1211 : | celek | 1.18 | <li> <site> - defines the site map</li> |
| 1212 : | |||
| 1213 : | celek | 1.7 | <ul> |
| 1214 : | celek | 1.18 | <li> type - optional site type specification. The value refers |
| 1215 : | to a type string registered via the <a href="#Framework">install framework</a> | ||
| 1216 : | extension point. If not specified, the type is assumed to be the default | ||
| 1217 : | celek | 1.17 | Eclipse site type (as specified in this document).</li> |
| 1218 : | celek | 1.18 | <li> url - optional URL defining the update site baseline |
| 1219 : | URL (used to determine individual <feature> and <archive> | ||
| 1220 : | location). Can be relative or absolute. If relative, is relative | ||
| 1221 : | to site.xml. If not specified, the default is the URL location of the | ||
| 1222 : | site.xml file.</li> | ||
| 1223 : | |||
| 1224 : | celek | 1.17 | </ul> |
| 1225 : | celek | 1.18 | <li> <description> - brief description as simple text. |
| 1226 : | celek | 1.17 | Intended to be translated.</li> |
| 1227 : | celek | 1.18 | |
| 1228 : | celek | 1.17 | <ul> |
| 1229 : | celek | 1.18 | <li> url - optional URL for the full description as HTML. The |
| 1230 : | URL can be specified as absolute of relative. If relative, If relative, | ||
| 1231 : | celek | 1.17 | is relative to site.xml.</li> |
| 1232 : | celek | 1.18 | <br> |
| 1233 : | Note, that for NL handling the URL value should be separated | ||
| 1234 : | to allow alternate URLs to be specified for each national language. | ||
| 1235 : | |||
| 1236 : | </ul> | ||
| 1237 : | <li> <feature> - identifies referenced feature archive</li> | ||
| 1238 : | |||
| 1239 : | <ul> | ||
| 1240 : | <li> type - optional feature type specification. The value | ||
| 1241 : | refers to a type string registered via the <a href="#Framework">install | ||
| 1242 : | framework</a> extension point. If not specified, the type is assumed | ||
| 1243 : | to be the default feature type for the site. If the site type is the | ||
| 1244 : | default Eclipse site type, the default feature type is the packaged | ||
| 1245 : | feature type (as specified in this document).</li> | ||
| 1246 : | <li> id - optional feature identifier. The information is | ||
| 1247 : | used as a performance optimization to speed up searches for features. | ||
| 1248 : | Must match the identifier specified in the feature.xml of the referenced | ||
| 1249 : | archive (the url attribute). If specified, the version attribute must | ||
| 1250 : | celek | 1.17 | also be specified.</li> |
| 1251 : | celek | 1.18 | <li> version - optional feature version. The information is |
| 1252 : | used as a performance optimization to speed up searches for features. | ||
| 1253 : | Must match the version specified in the feature.xml of the referenced | ||
| 1254 : | archive (the url attribute). If specified, the id attribute must also be | ||
| 1255 : | specified.</li> | ||
| 1256 : | <li> url - required URL reference to the feature archive. | ||
| 1257 : | Can be relative or absolute. If relative, it is relative to the location | ||
| 1258 : | of the site.xml file. <b>Note</b>: the default site implementation | ||
| 1259 : | allows features to be accessed without being explicitly declared using | ||
| 1260 : | a <feature> entry. By default, an undeclared features reference is | ||
| 1261 : | celek | 1.17 | interpreted as "features/<id>_<version>.jar"</li> |
| 1262 : | celek | 1.18 | <li>label - optional feature label. The value is used for |
| 1263 : | optimization when browsing the site from the update manager. Intended | ||
| 1264 : | celek | 1.17 | to be translated.<br> |
| 1265 : | celek | 1.18 | </li> |
| 1266 : | <li> os - optional operating system specification. A comma-separated | ||
| 1267 : | list of os designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt> | ||
| 1268 : | . Indicates this feature should only be installed on one of the specified | ||
| 1269 : | os systems. If this attribute is "*", the feature can be installed | ||
| 1270 : | on all systems (portable implementation). This information is used as | ||
| 1271 : | a hint by the installation and update support (user can force installation | ||
| 1272 : | of feature regardless of this setting).</li> | ||
| 1273 : | <li> arch - optional machine architecture specification. A | ||
| 1274 : | comma-separated list of architecture designators defined by Eclipse | ||
| 1275 : | (see Javadoc for <tt> org.eclipse.core.boot.BootLoader)</tt>. Indicates | ||
| 1276 : | this feature should only be installed on one of the specified systems. | ||
| 1277 : | If this attribute is "*", the feature can be installed on all systems | ||
| 1278 : | (portable implementation). This information is used as a hint by the | ||
| 1279 : | installation and update support (user can force installation of feature | ||
| 1280 : | regardless of this setting).</li> | ||
| 1281 : | <li> ws - optional windowing system specification. A comma-separated | ||
| 1282 : | list of ws designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt> | ||
| 1283 : | . Indicates this feature should only be installed on one of the specified | ||
| 1284 : | ws systems. If this attribute is "*", the feature can be installed | ||
| 1285 : | on all systems (portable implementation). This information is used | ||
| 1286 : | as a hint by the installation and update support (user can force installation | ||
| 1287 : | of feature regardless of this setting).</li> | ||
| 1288 : | <li> nl - optional locale specification. A comma-separated | ||
| 1289 : | list of locale designators defined by Java. Indicates this feature should | ||
| 1290 : | only be installed on a system running with a compatible locale (using | ||
| 1291 : | Java locale-matching rules). If this attribute is "*", the feature | ||
| 1292 : | can be installed on all systems (language-neutral implementation). This | ||
| 1293 : | information is used as a hint by the installation and update support (user | ||
| 1294 : | can force installation of feature regardless of this setting).</li> | ||
| 1295 : | <li>patch - optional specification indicating if this feature | ||
| 1296 : | is a patch. Default is "false". </li> | ||
| 1297 : | |||
| 1298 : | celek | 1.16 | </ul> |
| 1299 : | celek | 1.18 | <li> <archive> - identifies referenced "storage" archive |
| 1300 : | (the actual files referenced via the <tt><plugin></tt> or <tt><data></tt> | ||
| 1301 : | elements in the feature manifest). The site simply manages archives | ||
| 1302 : | as a path-to-URL map. The default Eclipse site implementation does not | ||
| 1303 : | require the <archive> section to be included in the site map (site.xml). | ||
| 1304 : | Any archive reference not explicitly defined as part of an <archive> | ||
| 1305 : | section is assumed to be mapped to a url in the form "<archivePath>" | ||
| 1306 : | celek | 1.17 | relative to the location of the site.xml file.</li> |
| 1307 : | celek | 1.18 | |
| 1308 : | celek | 1.14 | <ul> |
| 1309 : | celek | 1.18 | <li> path - required archive path identifier. This is a string |
| 1310 : | that is determined by the <a | ||
| 1311 : | href="#Feature_Archive_Mapping_Id_To_Path">feature</a> referencing | ||
| 1312 : | this archive and is not otherwise interpreted by the site (other than | ||
| 1313 : | as a lookup token).</li> | ||
| 1314 : | <li> url - required URL reference to the archive. Can be relative | ||
| 1315 : | or absolute. If relative, it is relative to the location of the site.xml | ||
| 1316 : | file.</li> | ||
| 1317 : | |||
| 1318 : | celek | 1.16 | </ul> |
| 1319 : | celek | 1.18 | <li> <category-def> - an optional definition of a category |
| 1320 : | that can be used by installation and update support to hierarchicaly | ||
| 1321 : | celek | 1.17 | organize features</li> |
| 1322 : | celek | 1.18 | |
| 1323 : | celek | 1.16 | <ul> |
| 1324 : | celek | 1.18 | <li> name - category name. Is specified as a path of name tokens |
| 1325 : | separated by /</li> | ||
| 1326 : | <li> label - displayable label. Intended to be translated.</li> | ||
| 1327 : | |||
| 1328 : | celek | 1.16 | </ul> |
| 1329 : | celek | 1.18 | <li> <category> - actual category specification for |
| 1330 : | a feature entry</li> | ||
| 1331 : | |||
| 1332 : | celek | 1.9 | <ul> |
| 1333 : | celek | 1.18 | name - category name |
| 1334 : | celek | 1.13 | </ul> |
| 1335 : | celek | 1.18 | |
| 1336 : | celek | 1.7 | </ul> |
| 1337 : | celek | 1.18 | Note, that in general the feature.xml manifest documents |
| 1338 : | should specify UTF-8 encoding. For example | ||
| 1339 : | celek | 1.7 | <p><tt><?xml version="1.0" encoding="UTF-8"?></tt> </p> |
| 1340 : | celek | 1.18 | |
| 1341 : | <p>Translatable text contained in the site.xml can be separated into site<_locale>.properties | ||
| 1342 : | files using Java property bundle conventions. Note that the translated | ||
| 1343 : | strings are used at installation time (ie. do not employ the plug-in | ||
| 1344 : | fragment runtime mechanism). The property bundles are located relative | ||
| 1345 : | to the site.xml location. </p> | ||
| 1346 : | |||
| 1347 : | celek | 1.9 | <h3> <a name="Default_Site_Layout"></a> Default Site Layout</h3> |
| 1348 : | celek | 1.18 | <tt><site root>/</tt> <br> |
| 1349 : | <tt> site.xml</tt> <br> | ||
| 1350 : | <tt> features/</tt> <br> | ||
| 1351 : | <tt> feature archives | ||
| 1352 : | (eg. org.eclipse.javatools_1.0.1.jar)</tt> <br> | ||
| 1353 : | <tt> <featureId>_<featureVersion>/ | ||
| 1354 : | (optional)</tt> <br> | ||
| 1355 : | <tt> | ||
| 1356 : | celek | 1.17 | non-plug-in files for feature</tt> <br> |
| 1357 : | celek | 1.18 | <tt> plugins/</tt> <br> |
| 1358 : | <tt> plug-in argives | ||
| 1359 : | (eg. org.eclipse.ui_1.0.3.jar)</tt> | ||
| 1360 : | celek | 1.9 | <h3> <a name="Controlling_Access"></a> Controlling Access</h3> |
| 1361 : | celek | 1.18 | The default Eclipse site implementation provides support for |
| 1362 : | http access with basic user authentication (userid and password). | ||
| 1363 : | |||
| 1364 : | <p>Custom access control mechanisms can be added to base Eclipse in one of | ||
| 1365 : | celek | 1.17 | 2 ways: </p> |
| 1366 : | celek | 1.18 | |
| 1367 : | celek | 1.7 | <ul> |
| 1368 : | celek | 1.18 | <li> by supplying server-side logic on the update server (eg. |
| 1369 : | implementing servlets that compute the site.xml map, and control access | ||
| 1370 : | celek | 1.17 | to individual archives based on some user criteria)</li> |
| 1371 : | celek | 1.18 | <li> by supplying a custom concrete implementation of the |
| 1372 : | site object (installed on the client machine, update server specified | ||
| 1373 : | <tt><site type=""></tt> ). The custom concrete site implementation, | ||
| 1374 : | together with any server-side logic support the required control mechanisms.</li> | ||
| 1375 : | |||
| 1376 : | vlad | 1.1 | </ul> |
| 1377 : | celek | 1.18 | Eclipse provides an example demonstrating an implementation |
| 1378 : | of an access mechanism based on feature key files. | ||
| 1379 : | celek | 1.9 | <h2> <a name="Eclipse_Install"></a> Eclipse Install</h2> |
| 1380 : | celek | 1.18 | |
| 1381 : | celek | 1.9 | <h3> <a name="Default_Install_Layout"></a> Default Install Layout</h3> |
| 1382 : | celek | 1.18 | <tt><install root>/</tt> <br> |
| 1383 : | <tt> install/</tt> <br> | ||
| 1384 : | <tt> features/</tt> | ||
| 1385 : | <br> | ||
| 1386 : | <tt> | ||
| 1387 : | celek | 1.17 | <featureId>_<version>/</tt> <br> |
| 1388 : | celek | 1.18 | <tt> |
| 1389 : | feature.xml</tt> <br> | ||
| 1390 : | <tt> | ||
| 1391 : | other feature files</tt> <br> | ||
| 1392 : | <tt> | ||
| 1393 : | META-INF/</tt> <br> | ||
| 1394 : | <tt> | ||
| 1395 : | META-INF-ECLIPSE/</tt> | ||
| 1396 : | celek | 1.7 | <p><tt> plugins/</tt> <br> |
| 1397 : | celek | 1.18 | <tt> <pluginORfragmentId>_<version>/</tt> |
| 1398 : | celek | 1.17 | <br> |
| 1399 : | celek | 1.18 | <tt> |
| 1400 : | celek | 1.17 | plugin.xml or fragment.xml</tt> <br> |
| 1401 : | celek | 1.18 | <tt> |
| 1402 : | celek | 1.17 | other plugin or fragment files</tt> <br> |
| 1403 : | celek | 1.18 | <tt> |
| 1404 : | celek | 1.17 | META_INF/</tt> </p> |
| 1405 : | celek | 1.18 | |
| 1406 : | <p><b>Implementation Note:</b> we will go back to the original design of | ||
| 1407 : | not splitting out fragments (ie. plugin and fragments go into the same install | ||
| 1408 : | celek | 1.17 | location) </p> |
| 1409 : | celek | 1.18 | |
| 1410 : | celek | 1.9 | <h3> <a name="Unmanaged_Plugins"></a> "Unmanaged" Plug-Ins</h3> |
| 1411 : | celek | 1.18 | Eclipse supports a concept of "unmanaged" plug-ins. These are |
| 1412 : | plug-ins that were directly installed into the Eclipse file tree without | ||
| 1413 : | being part of a feature (eg. developer unzipping plug-in archive directly | ||
| 1414 : | into the Eclipse file tree). | ||
| 1415 : | <p>Eclipse runtime recognizes these plugins during startup and loads the | ||
| 1416 : | plug-in information into the runtime registry following the standard plug-in | ||
| 1417 : | binding rules. The update support also recognizes the presence of this new | ||
| 1418 : | plug-in, but since this plug-in is not part of any feature it cannot be updated | ||
| 1419 : | using the update support (hence "unmanaged"). Unmanaged plug-in that become | ||
| 1420 : | referenced by a feature as a result of some future installation or update | ||
| 1421 : | action become "managed" (can be updated as part of the feature). </p> | ||
| 1422 : | |||
| 1423 : | <p>Unmanaged plug-ins are not displayed as part of the installation and update | ||
| 1424 : | celek | 1.17 | UI. </p> |
| 1425 : | celek | 1.18 | |
| 1426 : | <h3> <a name="Using_Native_Platform_Installers"></a> Using Native Platform | ||
| 1427 : | Installers</h3> | ||
| 1428 : | The Eclipse installation contains plugins that can be shared | ||
| 1429 : | across multiple features. When installing and uninstalling features | ||
| 1430 : | using the Eclipse installation and update support, these relationship | ||
| 1431 : | are correctly maintained. Only one copy of any version of a plug-in is | ||
| 1432 : | used. | ||
| 1433 : | <p>However, when using native platform installers, performing native uninstall | ||
| 1434 : | creates problems because plug-ins would be removed without regard | ||
| 1435 : | to any sharing relationships. As a result, Eclipse <b>does not allow</b> | ||
| 1436 : | plug-ins to be installed using native installers into the shared installation | ||
| 1437 : | tree. Instead, native installers must establish their own installation | ||
| 1438 : | root directory. The subdirectory structure is the same as defined for | ||
| 1439 : | base Eclipse. The private root directory is logically linked into the shared | ||
| 1440 : | Eclipse installation via a link file installed by the native installer. | ||
| 1441 : | The file path for the link file is <tt><configRoot>/links/</tt>. | ||
| 1442 : | The <tt><configRoot> </tt> location is computed by Eclipse relative | ||
| 1443 : | to the launch <a href="#Multiple%20Launch%20Points"> configuration file</a> | ||
| 1444 : | . By default, this is the <tt>install/</tt> directory in the shared | ||
| 1445 : | Eclipse installation tree. </p> | ||
| 1446 : | |||
| 1447 : | <p>The name of the link file is not specified by Eclipse. The name is determined | ||
| 1448 : | by the native installer. To minimize the potential for naming collisions, | ||
| 1449 : | it is recommended that the file name contain the identifier and version | ||
| 1450 : | of the feature being installed by the native installer. For example, | ||
| 1451 : | <tt><featureId>_<featureVersion>.properties</tt> . The file | ||
| 1452 : | content is in the form of a Java properties file, with the following | ||
| 1453 : | properties defined: </p> | ||
| 1454 : | |||
| 1455 : | celek | 1.7 | <p><tt>path=[r|rw] install-path[,[r|rw] install-path]*</tt> </p> |
| 1456 : | celek | 1.18 | |
| 1457 : | <p>The property <tt>path</tt> is a comma-separated list of optionally annotated | ||
| 1458 : | install paths. The property value <tt>install-path</tt> is a full | ||
| 1459 : | file path to the installation directory root, specified in local OS | ||
| 1460 : | format. The optional annotation <tt>r</tt> or <tt>rw</tt> indicates whether | ||
| 1461 : | Eclipse update support should allow the specified location to be used | ||
| 1462 : | for updates. Default is to allow updates (w). </p> | ||
| 1463 : | |||
| 1464 : | <p>Eclipse does not manage the linked directories in any way. It simply detects | ||
| 1465 : | their existence by the presence of the link files, and includes the | ||
| 1466 : | linked plug-ins during the platform startup. The native installer is | ||
| 1467 : | responsible for uninstalling the link when the corresponding directory | ||
| 1468 : | is removed. Eclipse runtime ignores any links that cannot be resolved. | ||
| 1469 : | celek | 1.17 | <br> |
| 1470 : | celek | 1.18 | </p> |
| 1471 : | <br> | ||
| 1472 : | celek | 1.17 | <br> |
| 1473 : | celek | 1.16 | <br> |
| 1474 : | celek | 1.15 | <br> |
| 1475 : | celek | 1.14 | <br> |
| 1476 : | <br> | ||
| 1477 : | celek | 1.18 | <br> |
| 1478 : | <br> | ||
| 1479 : | celek | 1.17 | <br> |
| 1480 : | celek | 1.16 | <br> |
| 1481 : | vlad | 1.1 | </body> |
| 1482 : | </html> |
| help@eclipse.org | ViewVC Help |
| Powered by ViewVC 1.0.3 |