| 22 |
|
|
| 23 |
<ul> |
<ul> |
| 24 |
<li><small>2.0.18</small></li> |
<li><small>2.0.18</small></li> |
| 25 |
|
|
| 26 |
<ul> |
<ul> |
| 27 |
<li><small>added <feature plugin=""></small></li> |
<li><small>added <feature plugin=""></small></li> |
| 28 |
|
|
| 29 |
</ul> |
</ul> |
| 30 |
<li><small>2.0.17</small></li> |
<li><small>2.0.17</small></li> |
| 31 |
|
|
| 38 |
<li><small>2.0.16</small> <small><br> |
<li><small>2.0.16</small> <small><br> |
| 39 |
</small> |
</small> |
| 40 |
<ul> |
<ul> |
| 41 |
<li><small>added <site><feature> os,arch,nl,ws support |
<li><small>added <site><feature> os,arch,nl,ws |
| 42 |
"*"</small></li> |
support "*"</small></li> |
| 43 |
|
|
| 44 |
</ul> |
</ul> |
| 45 |
</li> |
</li> |
| 46 |
<li><small>2.0.15</small> |
<li><small>2.0.15</small> |
| 47 |
|
|
| 48 |
<ul> |
<ul> |
| 49 |
<li><small>added <site><feature> os,arch,nl,ws,patch |
<li><small>added <site><feature> os,arch,nl,ws,patch |
| 50 |
tag</small></li> |
tag</small></li> |
| 110 |
<li> <font size="-1">2.0.7</font></li> |
<li> <font size="-1">2.0.7</font></li> |
| 111 |
|
|
| 112 |
<ul> |
<ul> |
| 113 |
<li> <font size="-1">support explicit xml markup for primary features</font></li> |
<li> <font size="-1">support explicit xml markup for primary |
| 114 |
|
features</font></li> |
| 115 |
|
|
| 116 |
</ul> |
</ul> |
| 117 |
<li> <font size="-1">2.0.6</font></li> |
<li> <font size="-1">2.0.6</font></li> |
| 132 |
<li> <font size="-1">general text cleanup</font></li> |
<li> <font size="-1">general text cleanup</font></li> |
| 133 |
<li> <font size="-1"><feature><group> support removed |
<li> <font size="-1"><feature><group> support removed |
| 134 |
(will not be in Eclipse 2.0)</font></li> |
(will not be in Eclipse 2.0)</font></li> |
| 135 |
<li> <font size="-1">arch= support added to <feature> and |
<li> <font size="-1">arch= support added to <feature> |
| 136 |
<feature><plugin></font></li> |
and <feature><plugin></font></li> |
| 137 |
<li> <font size="-1">os=/ arch=/ ws=/ nl= added to <fetaure><data></font></li> |
<li> <font size="-1">os=/ arch=/ ws=/ nl= added to <fetaure><data></font></li> |
| 138 |
<li> <font size="-1"><site url=""> new semantics</font></li> |
<li> <font size="-1"><site url=""> new semantics</font></li> |
| 139 |
<li> <font size="-1">corrected errors in native installer link |
<li> <font size="-1">corrected errors in native installer link |
| 181 |
<a |
<a |
| 182 |
href="#Security_Considerations">Security Considerations</a> <br> |
href="#Security_Considerations">Security Considerations</a> <br> |
| 183 |
<a href="#Update_Server">Update Server</a> <br> |
<a href="#Update_Server">Update Server</a> <br> |
| 184 |
<a href="#Site_Map">Site Map</a> |
<a href="#Site_Map">Site |
| 185 |
<br> |
Map</a> <br> |
| 186 |
<a |
<a |
| 187 |
href="#Default_Site_Layout">Default Site Layout</a> <br> |
href="#Default_Site_Layout">Default Site Layout</a> <br> |
| 188 |
<a |
<a |
| 196 |
href="#Using_Native_Platform_Installers"> Using Native Platform Installers</a> |
href="#Using_Native_Platform_Installers"> Using Native Platform Installers</a> |
| 197 |
|
|
| 198 |
<h2> <a name="Introduction"></a> Introduction</h2> |
<h2> <a name="Introduction"></a> Introduction</h2> |
| 199 |
This document outlines the support for managing the delivery of |
This document outlines the support for managing the delivery |
| 200 |
function within the Eclipse platform. Also refer to the "<a |
of function within the Eclipse platform. Also refer to the "<a |
| 201 |
href="http://www.eclipse.org/legal/updatemanager.html"> Eclipse.org Update |
href="http://www.eclipse.org/legal/updatemanager.html"> Eclipse.org Update |
| 202 |
Manager Agreement</a> " for additional legal information governing the |
Manager Agreement</a> " for additional legal information governing the |
| 203 |
use of the Eclipse update manager function. |
use of the Eclipse update manager function. |
| 217 |
is merged into <i>feature</i>. Features define the packaging structure |
is merged into <i>feature</i>. Features define the packaging structure |
| 218 |
for a group of related plug-ins, plug-in fragments, and optionally non-plug-in |
for a group of related plug-ins, plug-in fragments, and optionally non-plug-in |
| 219 |
files. Features are treated purely as an installation and packaging construct. |
files. Features are treated purely as an installation and packaging construct. |
| 220 |
They do not play a role during Eclipse plug-in execution. Features do not |
They do not play a role during Eclipse plug-in execution. Features do |
| 221 |
nest. They are simply an inclusive "manifest" of the plug-ins, fragments |
not nest. They are simply an inclusive "manifest" of the plug-ins, fragments |
| 222 |
and other files that make up that feature. If features are logically made |
and other files that make up that feature. If features are logically made |
| 223 |
up of plug-ins from "sub-features", the top-level feature "manifest" must |
up of plug-ins from "sub-features", the top-level feature "manifest" must |
| 224 |
be fully resolved at packaging time. <li> <b>default feature archive format</b></li> |
be fully resolved at packaging time. <li> <b>default feature archive format</b></li> |
| 228 |
with this approach is lack of granularity at download time. In R2.0, |
with this approach is lack of granularity at download time. In R2.0, |
| 229 |
the feature archive consists of multiple separate .jars - one .jar per |
the feature archive consists of multiple separate .jars - one .jar per |
| 230 |
plug-in and fragment, plus one .jar for the actual feature information. |
plug-in and fragment, plus one .jar for the actual feature information. |
| 231 |
The Installation and Update support selectively downloads only those |
The Installation and Update support selectively downloads only those jars |
| 232 |
jars required for the installation. <li> <b>site map</b></li> |
required for the installation. <li> <b>site map</b></li> |
| 233 |
<br> |
<br> |
| 234 |
Default Eclipse update server must contain a <i>site map</i> file |
Default Eclipse update server must contain a <i>site map</i> file |
| 235 |
(site.xml). This is an evolution of the R1.0 install.index support. The |
(site.xml). This is an evolution of the R1.0 install.index support. |
| 236 |
rationale for using a structured site defined by the map rather than a |
The rationale for using a structured site defined by the map rather than |
| 237 |
"free form" web site, is the ability to present a consistent installation |
a "free form" web site, is the ability to present a consistent installation |
| 238 |
experience for the user. Also, this provides the necessary structure for |
experience for the user. Also, this provides the necessary structure for |
| 239 |
discovery of available updates. Additional support for "free form" browsing |
discovery of available updates. Additional support for "free form" browsing |
| 240 |
may be considered in future work. <li> <b>using native install/ uninstall</b></li> |
may be considered in future work. <li> <b>using native install/ uninstall</b></li> |
| 246 |
support for understanding the Eclipse installation structure. In particular, |
support for understanding the Eclipse installation structure. In particular, |
| 247 |
the native uninstallers will, by default, remove plug-in files that were |
the native uninstallers will, by default, remove plug-in files that were |
| 248 |
installed using the native installer without regard to these plug-ins being |
installed using the native installer without regard to these plug-ins being |
| 249 |
needed by other features. As a result, features installed using native installers |
needed by other features. As a result, features installed using native |
| 250 |
must be written into private product-specific installation location and |
installers must be written into private product-specific installation |
| 251 |
not the shared Eclipse installation location. The shared Eclipse is made |
location and not the shared Eclipse installation location. The shared |
| 252 |
aware of the produce-specific location via an installed "link file". <li> |
Eclipse is made aware of the produce-specific location via an installed |
| 253 |
<b>custom install handling</b></li> |
"link file". <li> <b>custom install handling</b></li> |
| 254 |
<br> |
<br> |
| 255 |
In many cases the standard installation handling supplied by Eclipse |
In many cases the standard installation handling supplied by Eclipse |
| 256 |
is not be sufficient to handle various custom requirements. To accommodate |
is not be sufficient to handle various custom requirements. To accommodate |
| 257 |
this, R2.0 Eclipse supports custom install handlers packaged as part of |
this, R2.0 Eclipse supports custom install handlers packaged as part |
| 258 |
the feature and executed during the feature installation. <li> <b>path |
of the feature and executed during the feature installation. <li> <b>path |
| 259 |
naming conventions</b></li> |
naming conventions</b></li> |
| 260 |
<br> |
<br> |
| 261 |
R1.0 mandated the use of the various identifiers and versions inside |
R1.0 mandated the use of the various identifiers and versions |
| 262 |
the packaged archives (eg. directory path names for plug-ins). This |
inside the packaged archives (eg. directory path names for plug-ins). |
| 263 |
approach has proven to be ackward and error prone. In 2.0, the packaging |
This approach has proven to be ackward and error prone. In 2.0, the packaging |
| 264 |
requirements no longer mandate that path names of packaged files precisely |
requirements no longer mandate that path names of packaged files precisely |
| 265 |
reflect the contained identifiers and versions. The properly identified |
reflect the contained identifiers and versions. The properly identified |
| 266 |
install subdirectories are created by the Eclipse support during the installation |
install subdirectories are created by the Eclipse support during the installation |
| 279 |
|
|
| 280 |
<p>While plug-ins are being developed (ie. are frequently being changed), |
<p>While plug-ins are being developed (ie. are frequently being changed), |
| 281 |
their internal file structure will reflect what is convenient to the |
their internal file structure will reflect what is convenient to the |
| 282 |
developer. This will generally depend on the particular development tool |
developer. This will generally depend on the particular development |
| 283 |
being used. Typically, however, the developer will likely setup the plug-in |
tool being used. Typically, however, the developer will likely setup |
| 284 |
to execute from a directory tree containing exposed .class files, rather |
the plug-in to execute from a directory tree containing exposed .class |
| 285 |
than executing from a .jar (requires an extra step to create the .jar |
files, rather than executing from a .jar (requires an extra step to |
| 286 |
and we all know developers hate extra steps). Also, at this stage the developer |
create the .jar and we all know developers hate extra steps). Also, at |
| 287 |
does not pay particular attention to plug-in versioning information, because |
this stage the developer does not pay particular attention to plug-in |
| 288 |
the plug-in is continually changing. </p> |
versioning information, because the plug-in is continually changing. </p> |
| 289 |
|
|
| 290 |
<p>However, when the plug-in is ready to be packaged, it needs to be converted |
<p>However, when the plug-in is ready to be packaged, it needs to be converted |
| 291 |
to a form suitable for packaging and installation. Typically it means |
to a form suitable for packaging and installation. Typically it means |
| 292 |
creation of the runtime .jar(s) and removing any development-time files |
creation of the runtime .jar(s) and removing any development-time files |
| 293 |
(source, exposed .class files, etc). It also means updating the plugin.xml |
(source, exposed .class files, etc). It also means updating the plugin.xml |
| 294 |
manifest with the formal plug-in version and reflecting the version in the |
manifest with the formal plug-in version and reflecting the version in |
| 295 |
plug-in directory name (see "Concurrent Plug-In Version Support" for details). |
the plug-in directory name (see "Concurrent Plug-In Version Support" for |
| 296 |
</p> |
details). </p> |
| 297 |
|
|
| 298 |
<p><b>Plug-in Fragment</b> <br> |
<p><b>Plug-in Fragment</b> <br> |
| 299 |
Plug-in Fragments (or simply Fragments) allow independent packaging |
Plug-in Fragments (or simply Fragments) allow independent packaging |
| 306 |
<p><b>Feature</b> <br> |
<p><b>Feature</b> <br> |
| 307 |
A feature is an installation packaging mechanism used to define |
A feature is an installation packaging mechanism used to define |
| 308 |
a group of versioned plug-ins and/or plug-in fragments plus non-plug-in |
a group of versioned plug-ins and/or plug-in fragments plus non-plug-in |
| 309 |
files that is used to deliver some user function. A feature can also include |
files that is used to deliver some user function. A feature can also |
| 310 |
other features. Features are exposed to users as part of the packaging |
include other features. Features are exposed to users as part of the |
| 311 |
and installation process, because they represent a unit of function selection. |
packaging and installation process, because they represent a unit of |
| 312 |
Features also represent a unit of installation. Features carry a version |
function selection. Features also represent a unit of installation. Features |
| 313 |
identifier.</p> |
carry a version identifier.</p> |
| 314 |
|
|
| 315 |
<p>Features are packaged as a feature archive, referencing the required plug-ins, |
<p>Features are packaged as a feature archive, referencing the required plug-ins, |
| 316 |
plug-in fragments and optional non-plug-in files. The feature archives |
plug-in fragments and optional non-plug-in files. The feature archives |
| 345 |
<tbody> |
<tbody> |
| 346 |
<tr> |
<tr> |
| 347 |
<td><b>Note: <i>The reminder of this document describes the default |
<td><b>Note: <i>The reminder of this document describes the default |
| 348 |
concrete implementation of the framework delivered with Eclipse. It |
concrete implementation of the framework delivered with Eclipse. It specifies |
| 349 |
specifies the structure of the default feature implementation, as well |
the structure of the default feature implementation, as well as the default |
| 350 |
as the default site implementation, plus the corresponding xml files |
site implementation, plus the corresponding xml files (feature.xml and |
| 351 |
(feature.xml and site.xml). Providers of alternate concrete implementations |
site.xml). Providers of alternate concrete implementations can extend |
| 352 |
can extend parts or all of the default Eclipse implementation. This |
parts or all of the default Eclipse implementation. This includes providing |
| 353 |
includes providing a mechanism for dynamic computation of the site map |
a mechanism for dynamic computation of the site map (site.xml)</i></b></td> |
|
(site.xml)</i></b></td> |
|
| 354 |
</tr> |
</tr> |
| 355 |
|
|
| 356 |
</tbody> |
</tbody> |
| 372 |
|
|
| 373 |
<h3> <a name="Feature_Archive"></a> Feature Archive</h3> |
<h3> <a name="Feature_Archive"></a> Feature Archive</h3> |
| 374 |
The feature packaging information is placed into a separate Java |
The feature packaging information is placed into a separate Java |
| 375 |
.jar. Standard Java jar facilities are used for constructing feature archives. |
.jar. Standard Java jar facilities are used for constructing feature |
| 376 |
Feature archives reference separately packaged plug-in archives (see next |
archives. Feature archives reference separately packaged plug-in archives |
| 377 |
section) and non-plug-in files. |
(see next section) and non-plug-in files. |
| 378 |
<p>Features are identified using a structured identifier based on the provider |
<p>Features are identified using a structured identifier based on the provider |
| 379 |
internet domain name. For example, organization eclipse.org may produce |
internet domain name. For example, organization eclipse.org may produce |
| 380 |
feature org.eclipse.javatooling. The character set used for feature identifiers |
feature org.eclipse.javatooling. The character set used for feature identifiers |
| 386 |
|
|
| 387 |
<p>Where <tt><id></tt> is the feature identifier and <tt><version></tt> |
<p>Where <tt><id></tt> is the feature identifier and <tt><version></tt> |
| 388 |
is the full version identifier contained in the respective feature.xml. |
is the full version identifier contained in the respective feature.xml. |
| 389 |
Note that this is a recommended convention that minimizes chance of collisions, |
Note that this is a recommended convention that minimizes chance of |
| 390 |
but is not required by the Eclipse architecture. For example, the following |
collisions, but is not required by the Eclipse architecture. For example, |
| 391 |
are valid feature archive names </p> |
the following are valid feature archive names </p> |
| 392 |
|
|
| 393 |
<p><tt>org.eclipse.javatooling_1.0.3.jar</tt> <br> |
<p><tt>org.eclipse.javatooling_1.0.3.jar</tt> <br> |
| 394 |
<tt>org.eclipse.pde_2.0.jar</tt> <br> |
<tt>org.eclipse.pde_2.0.jar</tt> <br> |
| 395 |
<tt>my_feature.jar</tt> </p> |
<tt>my_feature.jar</tt> </p> |
| 396 |
|
|
| 397 |
<p>Internally, each feature archive is packaged relative to its feature directory |
<p>Internally, each feature archive is packaged relative to its feature directory |
| 398 |
(but not including the directory path element). The archive has the |
(but not including the directory path element). The archive has the following |
| 399 |
following structure </p> |
structure </p> |
| 400 |
|
|
| 401 |
<p><tt>feature.xml</tt> <br> |
<p><tt>feature.xml</tt> <br> |
| 402 |
<tt>feature<_locale>.properties (see "Translated Feature |
<tt>feature<_locale>.properties (see "Translated Feature |
| 410 |
|
|
| 411 |
<p><tt><?xml encoding="ISO-8859-1"?></tt> </p> |
<p><tt><?xml encoding="ISO-8859-1"?></tt> </p> |
| 412 |
|
|
| 413 |
<p><tt><!ELEMENT feature (install-handler?, description?, copyright?, license?, |
<p><tt><!ELEMENT feature (install-handler?, description?, copyright?, |
| 414 |
url?, includes*, requires?, plugin*, data*)></tt> <br> |
license?, url?, includes*, requires?, plugin*, data*)></tt> <br> |
| 415 |
<tt><!ATTLIST feature</tt> <br> |
<tt><!ATTLIST feature</tt> <br> |
| 416 |
<tt> id |
<tt> id |
| 417 |
CDATA #REQUIRED</tt> <br> |
CDATA #REQUIRED</tt> <br> |
| 507 |
<tt><!ATTLIST import</tt> <br> |
<tt><!ATTLIST import</tt> <br> |
| 508 |
<tt> plugin |
<tt> plugin |
| 509 |
CDATA #IMPLIED</tt><br> |
CDATA #IMPLIED</tt><br> |
| 510 |
<tt> feature CDATA |
<tt> feature |
| 511 |
#IMPLIED</tt><br> |
CDATA #IMPLIED</tt><br> |
| 512 |
<tt> version |
<tt> version |
| 513 |
CDATA #IMPLIED</tt> <br> |
CDATA #IMPLIED</tt> <br> |
| 514 |
<tt> match |
<tt> match |
| 524 |
CDATA #REQUIRED</tt> <br> |
CDATA #REQUIRED</tt> <br> |
| 525 |
<tt> version |
<tt> version |
| 526 |
CDATA #REQUIRED</tt> <br> |
CDATA #REQUIRED</tt> <br> |
| 527 |
<tt> fragment (true |
<tt> fragment |
| 528 |
| false) "false"</tt> <br> |
(true | false) "false"</tt> <br> |
| 529 |
<tt> os |
<tt> os |
| 530 |
CDATA #IMPLIED</tt> <br> |
CDATA #IMPLIED</tt> <br> |
| 531 |
<tt> arch |
<tt> arch |
| 535 |
<tt> nl |
<tt> nl |
| 536 |
CDATA #IMPLIED</tt> <br> |
CDATA #IMPLIED</tt> <br> |
| 537 |
<tt> download-size CDATA #IMPLIED</tt> <br> |
<tt> download-size CDATA #IMPLIED</tt> <br> |
| 538 |
<tt> install-size CDATA #IMPLIED</tt> <br> |
<tt> install-size CDATA #IMPLIED</tt> |
| 539 |
|
<br> |
| 540 |
<tt>></tt> </p> |
<tt>></tt> </p> |
| 541 |
|
|
| 542 |
<p><tt><!ELEMENT data EMPTY></tt> <br> |
<p><tt><!ELEMENT data EMPTY></tt> <br> |
| 552 |
<tt> nl |
<tt> nl |
| 553 |
CDATA #IMPLIED</tt> <br> |
CDATA #IMPLIED</tt> <br> |
| 554 |
<tt> download-size CDATA #IMPLIED</tt> <br> |
<tt> download-size CDATA #IMPLIED</tt> <br> |
| 555 |
<tt> install-size CDATA #IMPLIED</tt> <br> |
<tt> install-size CDATA #IMPLIED</tt> |
| 556 |
|
<br> |
| 557 |
<tt>></tt> </p> |
<tt>></tt> </p> |
| 558 |
|
|
| 559 |
<p>The element and attribute definitions are as follows: </p> |
<p>The element and attribute definitions are as follows: </p> |
| 564 |
<ul> |
<ul> |
| 565 |
<li> id - required feature identifier (eg. com.xyz.myfeature)</li> |
<li> id - required feature identifier (eg. com.xyz.myfeature)</li> |
| 566 |
<li> version - required component version (eg. 1.0.3)</li> |
<li> version - required component version (eg. 1.0.3)</li> |
| 567 |
<li> label - optional displayable label (name). Intended to be |
<li> label - optional displayable label (name). Intended to |
| 568 |
translated.</li> |
be translated.</li> |
| 569 |
<li> provider-name - optional display label identifying the organization |
<li> provider-name - optional display label identifying the |
| 570 |
providing this component. Intended to be translated.</li> |
organization providing this component. Intended to be translated.</li> |
| 571 |
<li> image - optional image to use when displaying information |
<li> image - optional image to use when displaying information |
| 572 |
about the feature. Specified relative to the feature.xml.</li> |
about the feature. Specified relative to the feature.xml.</li> |
| 573 |
<li> os - optional operating system specification. A comma-separated |
<li> os - optional operating system specification. A comma-separated |
| 574 |
list of os designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt> |
list of os designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt> |
| 575 |
. Indicates this feature should only be installed on one of the specified |
. Indicates this feature should only be installed on one of the specified |
| 576 |
os systems. If this attribute is not specified, the feature can be installed |
os systems. If this attribute is not specified, the feature can be |
| 577 |
on all systems (portable implementation). This information is used as |
installed on all systems (portable implementation). This information |
| 578 |
a hint by the installation and update support (user can force installation |
is used as a hint by the installation and update support (user can force |
| 579 |
of feature regardless of this setting).</li> |
installation of feature regardless of this setting).</li> |
| 580 |
<li> arch - optional machine architecture specification. A comma-separated |
<li> arch - optional machine architecture specification. A comma-separated |
| 581 |
list of architecture designators defined by Eclipse (see Javadoc for |
list of architecture designators defined by Eclipse (see Javadoc for |
| 582 |
<tt> org.eclipse.core.boot.BootLoader)</tt>. Indicates this feature |
<tt> org.eclipse.core.boot.BootLoader)</tt>. Indicates this feature |
| 588 |
<li> ws - optional windowing system specification. A comma-separated |
<li> ws - optional windowing system specification. A comma-separated |
| 589 |
list of ws designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt> |
list of ws 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 |
. Indicates this feature should only be installed on one of the specified |
| 591 |
ws systems. If this attribute is not specified, the feature can be installed |
ws systems. If this attribute is not specified, the feature can be |
| 592 |
on all systems (portable implementation). This information is used as |
installed on all systems (portable implementation). This information |
| 593 |
a hint by the installation and update support (user can force installation |
is used as a hint by the installation and update support (user can force |
| 594 |
of feature regardless of this setting).</li> |
installation of feature regardless of this setting).</li> |
| 595 |
<li> nl - optional locale specification. A comma-separated list |
<li> nl - optional locale specification. A comma-separated list |
| 596 |
of locale designators defined by Java. Indicates this feature should only |
of locale designators defined by Java. Indicates this feature should |
| 597 |
be installed on a system running with a compatible locale (using Java |
only be installed on a system running with a compatible locale (using |
| 598 |
locale-matching rules). If this attribute is not specified, the feature |
Java locale-matching rules). If this attribute is not specified, the feature |
| 599 |
can be installed on all systems (language-neutral implementation). This |
can be installed on all systems (language-neutral implementation). This |
| 600 |
information is used as a hint by the installation and update support (user |
information is used as a hint by the installation and update support (user |
| 601 |
can force installation of feature regardless of this setting).</li> |
can force installation of feature regardless of this setting).</li> |
| 608 |
can be used as a <a href="#Dominant_Feature">primary feature</a> . Default |
can be used as a <a href="#Dominant_Feature">primary feature</a> . Default |
| 609 |
if <i>false</i> (not a primary feature).</li> |
if <i>false</i> (not a primary feature).</li> |
| 610 |
<li> application - optional identifier of the Eclipse application |
<li> application - optional identifier of the Eclipse application |
| 611 |
that is to be used during startup when the declaring feature is the <a |
that is to be used during startup when the declaring feature is the |
| 612 |
href="#Dominant_Feature"> primary feature</a> . The application identifier |
<a href="#Dominant_Feature"> primary feature</a> . The application |
| 613 |
must represent a valid application registered in the <tt>org.eclipse.core.runtime.applications</tt> |
identifier must represent a valid application registered in the <tt>org.eclipse.core.runtime.applications</tt> |
| 614 |
extension point. Default is <tt>org.eclipse.ui.workbench</tt>.</li> |
extension point. Default is <tt>org.eclipse.ui.workbench</tt>.</li> |
| 615 |
<li> plugin- optional identifier of the primary plugin associated with |
<li> plugin- optional identifier of the primary plugin associated with |
| 616 |
this <a |
this <a |
| 624 |
|
|
| 625 |
<ul> |
<ul> |
| 626 |
<li> library - optional .jar library containing the install handler |
<li> library - optional .jar library containing the install handler |
| 627 |
classes. If specified, the referenced .jar must be contained in the |
classes. If specified, the referenced .jar must be contained in the feature |
| 628 |
feature archive. It is specified as a path within the feature archive, |
archive. It is specified as a path within the feature archive, relative |
| 629 |
relative to the feature.xml entry. If not specified, the feature archive |
to the feature.xml entry. If not specified, the feature archive itself |
| 630 |
itself is used to load the install handler classes. This attribute is only |
is used to load the install handler classes. This attribute is only interpreted |
| 631 |
interpreted if <i>class</i> attribute is also specified</li> |
if <i>class</i> attribute is also specified</li> |
| 632 |
<li> handler - optional identifier of the install handler. The |
<li> handler - optional identifier of the install handler. The |
| 633 |
value is interpreted depending on the value of the <i>library</i> attribute. |
value is interpreted depending on the value of the <i>library</i> attribute. |
| 634 |
If <i> library</i> is specified, the value is interpreted |
If <i> library</i> is specified, the value is interpreted |
| 636 |
If <i>library</i> is not specified, the value is is interpreted |
If <i>library</i> is not specified, the value is is interpreted |
| 637 |
as an extension identifier of an extension registered in the <i>org.eclipse.update.installHandlers</i> |
as an extension identifier of an extension registered in the <i>org.eclipse.update.installHandlers</i> |
| 638 |
extension point. In either case, the resulting class must implement |
extension point. In either case, the resulting class must implement |
| 639 |
the <i> IInstallHandler</i> interface. The class is dynamically |
the <i> IInstallHandler</i> interface. The class is dynamically loaded |
| 640 |
loaded and called at specific points during feature processing. The handler |
and called at specific points during feature processing. The handler has |
| 641 |
has visibility to the API classes from the update plug-in, and Eclipse plug-ins |
visibility to the API classes from the update plug-in, and Eclipse plug-ins |
| 642 |
required by the update plugin.</li> |
required by the update plugin.</li> |
| 643 |
|
|
| 644 |
</ul> |
</ul> |
| 675 |
will be selected for installation or update using the Eclipse update manager. |
will be selected for installation or update using the Eclipse update manager. |
| 676 |
When using nested features, only the nesting parent (ie. the feature selected |
When using nested features, only the nesting parent (ie. the feature selected |
| 677 |
for installation or update) must have click-through license text defined. |
for installation or update) must have click-through license text defined. |
| 678 |
The license text is required even if the optional <i>url</i> attribute |
The license text is required even if the optional <i>url</i> attribute is |
| 679 |
is specified.</li> |
specified.</li> |
| 680 |
|
|
| 681 |
<ul> |
<ul> |
| 682 |
<li> url - optional URL for the full description as HTML. The |
<li> url - optional URL for the full description as HTML. The |
| 686 |
be specified for each national language. Note, that the "content" of this |
be specified for each national language. Note, that the "content" of this |
| 687 |
URL is <b>not</b> what is presented as the click-through license during |
URL is <b>not</b> what is presented as the click-through license during |
| 688 |
installation processing. The click-through license is the actual value |
installation processing. The click-through license is the actual value |
| 689 |
of the <i><license></i> element (eg. <tt><license>click |
of the <i><license></i> element (eg. <tt><license>click through |
| 690 |
through text</license></tt>). URL support keywords $os$,$ws$,$arch$ |
text</license></tt>). URL support keywords $os$,$ws$,$arch$ and |
| 691 |
and $nl$ that will be replaced by the appropriate operating system, windowing |
$nl$ that will be replaced by the appropriate operating system, windowing |
| 692 |
system, operating architecture or national language value.</li> |
system, operating architecture or national language value.</li> |
| 693 |
|
|
| 694 |
</ul> |
</ul> |
| 722 |
<ul> |
<ul> |
| 723 |
<li> id - required nested feature identifier</li> |
<li> id - required nested feature identifier</li> |
| 724 |
<li> version - required nested feature version</li> |
<li> version - required nested feature version</li> |
| 725 |
<li> name- optional displayable label (name). Intended to be |
<li> name- optional displayable label (name). Intended to |
| 726 |
translated.</li> |
be translated.</li> |
| 727 |
<li>optional - optional specification indicating if this included |
<li>optional - optional specification indicating if this included |
| 728 |
feature can be optionally installed. Default is "false"<br> |
feature can be optionally installed. Default is "false"<br> |
| 729 |
</li> |
</li> |
| 730 |
<li>match - optional rule that will be applied when resolving |
<li>match - optional rule that will be applied when |
| 731 |
the feature reference. A <samp>perfect</samp> match (the default that |
resolving the feature reference. A <samp>perfect</samp> match (the default |
| 732 |
matches the 2.0.1 behavior) requires that the feature has exactly the version |
that matches the 2.0.1 behavior) requires that the feature has exactly |
| 733 |
specified by the version attribute. Other choices progressively relax |
the version specified by the version attribute. Other choices progressively |
| 734 |
the rule (<samp> equivalent</samp> allows only service part of the version |
relax the rule (<samp> equivalent</samp> allows only service part of the |
| 735 |
to be more recent, <samp>compatible</samp> also allows minor part |
version to be more recent, <samp>compatible</samp> also allows minor |
| 736 |
to be included in the consideration, while <samp>greaterOrEqual</samp> |
part to be included in the consideration, while <samp>greaterOrEqual</samp> |
| 737 |
simply allows any version that is more recent or identical to the one |
simply allows any version that is more recent or identical to the one |
| 738 |
specified).</li> |
specified).</li> |
| 739 |
<li>search_location - optional. Indicates whether the |
<li>search_location - optional. Indicates whether the |
| 740 |
"New Updates" action should search the update location determined by the |
"New Updates" action should search the update location determined by |
| 741 |
nesting root feature (<tt>root</tt>, is the default), or the location defined |
the nesting root feature (<tt>root</tt>, is the default), or the location |
| 742 |
by the nested feature (<tt>self</tt>), or search both (<tt>both</tt>) |
defined by the nested feature (<tt>self</tt>), or search both (<tt>both</tt>) |
| 743 |
in that order (root first, self if nothing is found).</li> |
in that order (root first, self if nothing is found).</li> |
| 744 |
|
|
| 745 |
</ul> |
</ul> |
| 758 |
or plugin must be specified.</li> |
or plugin must be specified.</li> |
| 759 |
<li> version - optional plug-in/feature version specification</li> |
<li> version - optional plug-in/feature version specification</li> |
| 760 |
<li>patch - optional specification indicating if this feature |
<li>patch - optional specification indicating if this feature |
| 761 |
is a patch of the dependant feature. Default is "false". If patch is true, |
is a patch of the dependant feature. Default is "false". If patch is |
| 762 |
version must be specified. If patch is true, only feature must be specified. |
true, version must be specified. If patch is true, only feature must be |
| 763 |
If patch is true, and match is specified, it must be 'perfect'.<br> |
specified. If patch is true, and match is specified, it must be 'perfect'.<br> |
| 764 |
</li> |
</li> |
| 765 |
<li> match - optional matching rule. Valid values and processing |
<li> match - optional matching rule. Valid values and processing |
| 766 |
are as follows:</li> |
are as follows:</li> |
| 774 |
<li>if patch is true, and match is not specified, match |
<li>if patch is true, and match is not specified, match |
| 775 |
defaults to perfect.<br> |
defaults to perfect.<br> |
| 776 |
</li> |
</li> |
| 777 |
<li> <b><i>perfect</i></b> - dependent plug-in version must match |
<li> <b><i>perfect</i></b> - dependent plug-in version must |
| 778 |
exactly the specified version.</li> |
match exactly the specified version.</li> |
| 779 |
<li> <b><i>equivalent</i></b> - dependent plug-in version must |
<li> <b><i>equivalent</i></b> - dependent plug-in version must |
| 780 |
be at least at the version specified, or at a higher service level (major |
be at least at the version specified, or at a higher service level (major |
| 781 |
and minor version levels must equal the specified version).</li> |
and minor version levels must equal the specified version).</li> |
| 824 |
<li> nl - optional locale specification. A comma-separated list |
<li> nl - optional locale specification. A comma-separated list |
| 825 |
of locale designators defined by Java. Indicates this entry should only |
of locale designators defined by Java. Indicates this entry should only |
| 826 |
be installed on a system running with a compatible locale (using Java |
be installed on a system running with a compatible locale (using Java |
| 827 |
locale-matching rules). If this attribute is not specified, the entry can |
locale-matching rules). If this attribute is not specified, the entry |
| 828 |
be installed on all systems (language-neutral implementation). This information |
can be installed on all systems (language-neutral implementation). This |
| 829 |
is used as a hint by the installation and update support (user can force |
information is used as a hint by the installation and update support (user |
| 830 |
installation of entry regardless of this setting).</li> |
can force installation of entry regardless of this setting).</li> |
| 831 |
<li> download-size - optional hint supplied by the feature packager, |
<li> download-size - optional hint supplied by the feature packager, |
| 832 |
indicating the download size in KBytes of the referenced plug-in archive. |
indicating the download size in KBytes of the referenced plug-in archive.The |
| 833 |
If not specified, the download size is not known (<b>Implementation |
size should not contain decimal. If not specified, the download size |
| 834 |
Note:</b> the implementation needs to distinguish between "not known" |
is not known (<b>Implementation Note:</b> the implementation needs to |
| 835 |
and 0 size)</li> |
distinguish between "not known" and 0 size)</li> |
| 836 |
<li> install-size - optional hint supplied by the feature packager, |
<li> install-size - optional hint supplied by the feature packager, |
| 837 |
indicating the install size in KBytes of the referenced plug-in archive. |
indicating the install size in KBytes of the referenced plug-in archive. |
| 838 |
If not specified, the install size is not known (<b>Implementation Note:</b> |
The size should not contain decimal. If not specified, the install |
| 839 |
the implementation needs to distinguish between "not known" and 0 size)</li> |
size is not known (<b>Implementation Note:</b> the implementation needs |
| 840 |
|
to distinguish between "not known" and 0 size)</li> |
| 841 |
|
|
| 842 |
</ul> |
</ul> |
| 843 |
<li> <data> - identifies non-plugin and non-feature data |
<li> <data> - identifies non-plugin and non-feature data |
| 844 |
that is part of the feature. Generally, data are post-install processed |
that is part of the feature. Generally, data are post-install processed |
| 845 |
using feature Install handler. Feature files like feature.properties are |
using feature Install handler. Feature files like feature.properties are not |
| 846 |
not considered data.</li> |
considered data.</li> |
| 847 |
|
|
| 848 |
<ul> |
<ul> |
| 849 |
<li> id - required data identifier in the form of a relative path.</li> |
<li> id - required data identifier in the form of a relative |
| 850 |
|
path.</li> |
| 851 |
<li> os - optional operating system specification. A comma-separated |
<li> os - optional operating system specification. A comma-separated |
| 852 |
list of os designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt> |
list of os designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt> |
| 853 |
. Indicates this entry should only be installed on one of the specified |
. Indicates this entry should only be installed on one of the specified |
| 873 |
<li> nl - optional locale specification. A comma-separated list |
<li> nl - optional locale specification. A comma-separated list |
| 874 |
of locale designators defined by Java. Indicates this entry should only |
of locale designators defined by Java. Indicates this entry should only |
| 875 |
be installed on a system running with a compatible locale (using Java |
be installed on a system running with a compatible locale (using Java |
| 876 |
locale-matching rules). If this attribute is not specified, the entry can |
locale-matching rules). If this attribute is not specified, the entry |
| 877 |
be installed on all systems (language-neutral implementation). This information |
can be installed on all systems (language-neutral implementation). This |
| 878 |
is used as a hint by the installation and update support (user can force |
information is used as a hint by the installation and update support (user |
| 879 |
installation of entry regardless of this setting).</li> |
can force installation of entry regardless of this setting).</li> |
| 880 |
<li> download-size - optional hint supplied by the feature packager, |
<li> download-size - optional hint supplied by the feature packager, |
| 881 |
indicating the download size in KBytes of the referenced data archive. |
indicating the download size in KBytes of the referenced data archive. |
| 882 |
If not specified, the download size is not known (<b>Implementation Note:</b> |
If not specified, the download size is not known (<b>Implementation Note:</b> |
| 891 |
</ul> |
</ul> |
| 892 |
<a name="Feature_Archive_Mapping_Id_To_Path"></a> When interacting |
<a name="Feature_Archive_Mapping_Id_To_Path"></a> When interacting |
| 893 |
with the update site, the feature implementation maps the <tt><plugin></tt> |
with the update site, the feature implementation maps the <tt><plugin></tt> |
| 894 |
and <tt><data></tt> elements into path identifiers used by the site |
and <tt><data></tt> elements into path identifiers used by the |
| 895 |
to determine the actual files to download and install. The default feature |
site to determine the actual files to download and install. The default |
| 896 |
implementation supplied by Eclipse constructs the path identifiers as |
feature implementation supplied by Eclipse constructs the path identifiers |
| 897 |
follows: |
as follows: |
| 898 |
<ul> |
<ul> |
| 899 |
<li> <tt><plugin></tt> element results in a path entry in |
<li> <tt><plugin></tt> element results in a path entry |
| 900 |
the form "<tt>plugins/<pluginId>_<pluginVersion>.jar</tt>" |
in the form "<tt>plugins/<pluginId>_<pluginVersion>.jar</tt>" |
| 901 |
(for example, "<tt>plugins/org.eclipse.core.boot_1.0.3.jar</tt>")</li> |
(for example, "<tt>plugins/org.eclipse.core.boot_1.0.3.jar</tt>")</li> |
| 902 |
<li> <tt><data></tt> element results in a path entry in |
<li> <tt><data></tt> element results in a path entry in |
| 903 |
the form "<tt>features/<featureId>_<featureVersion>/<dataId></tt> |
the form "<tt>features/<featureId>_<featureVersion>/<dataId></tt> |
| 910 |
|
|
| 911 |
<p>Translatable text contained in the feature.xml can be separated into feature<_locale>.properties |
<p>Translatable text contained in the feature.xml can be separated into feature<_locale>.properties |
| 912 |
files using Java property bundle conventions. Note that the translated |
files using Java property bundle conventions. Note that the translated |
| 913 |
strings are used at installation time (ie. do not employ the plug-in |
strings are used at installation time (ie. do not employ the plug-in fragment |
| 914 |
fragment runtime mechanism). </p> |
runtime mechanism). </p> |
| 915 |
|
|
| 916 |
<h3> <a name="Plug-In_Archive"></a> Plug-In Archive</h3> |
<h3> <a name="Plug-In_Archive"></a> Plug-In Archive</h3> |
| 917 |
Plug-ins and plug-in fragments are individually packaged as separate |
Plug-ins and plug-in fragments are individually packaged as separate |
| 918 |
Java .jars. Standard Java jar facilities are used for constructing plug-in |
Java .jars. Standard Java jar facilities are used for constructing |
| 919 |
archives. There is no distinction made between a plug-in archive containing |
plug-in archives. There is no distinction made between a plug-in archive |
| 920 |
a plug-in and one containing a plug-in fragment. |
containing a plug-in and one containing a plug-in fragment. |
| 921 |
|
|
| 922 |
<p>The recommended convention for naming the plug-in archives is <br> |
<p>The recommended convention for naming the plug-in archives is <br> |
| 923 |
<tt><id>_<version>.jar</tt> </p> |
<tt><id>_<version>.jar</tt> </p> |
| 924 |
|
|
| 933 |
<tt>org.eclipse.ui.nl_2.0.jar</tt> <br> |
<tt>org.eclipse.ui.nl_2.0.jar</tt> <br> |
| 934 |
<tt>my_plugin.jar</tt> </p> |
<tt>my_plugin.jar</tt> </p> |
| 935 |
|
|
| 936 |
<p>Internally, each plug-in archive packages all the relevant plug-in or fragment |
<p>Internally, each plug-in archive packages all the relevant plug-in or |
| 937 |
files relative to its plug-in or fragment directory (but not including the |
fragment files relative to its plug-in or fragment directory (but not including |
| 938 |
directory path element). The archive has the following structure </p> |
the directory path element). The archive has the following structure </p> |
| 939 |
|
|
| 940 |
<p><tt>plugin.xml *OR* fragment.xml</tt> <br> |
<p><tt>plugin.xml *OR* fragment.xml</tt> <br> |
| 941 |
<tt>other plug-in or feature files and subdirectories</tt> <br> |
<tt>other plug-in or feature files and subdirectories</tt> <br> |
| 946 |
<h3> <a name="Packaging_NL"></a> Packaging NL</h3> |
<h3> <a name="Packaging_NL"></a> Packaging NL</h3> |
| 947 |
In Eclipse, translated plug-in information is packaged either |
In Eclipse, translated plug-in information is packaged either |
| 948 |
together with the base plug-in, or as a plug-in fragment. At runtime, |
together with the base plug-in, or as a plug-in fragment. At runtime, |
| 949 |
Eclipse locates the translations for the required locale. The use of |
Eclipse locates the translations for the required locale. The use of fragments |
| 950 |
fragments allows translations to be added to the runtime without the |
allows translations to be added to the runtime without the need to repackage |
| 951 |
need to repackage the base plug-ins. |
the base plug-ins. |
| 952 |
<p>This mechanism cannot be used for translating the actual packaging information |
<p>This mechanism cannot be used for translating the actual packaging information |
| 953 |
that is part of the installation xml files. Consequently the standard |
that is part of the installation xml files. Consequently the standard |
| 954 |
Java translation conventions are used for the packaging information, and |
Java translation conventions are used for the packaging information, |
| 955 |
all necessary translations must be available at the time the feature is |
and all necessary translations must be available at the time the feature |
| 956 |
packaged. </p> |
is packaged. </p> |
| 957 |
|
|
| 958 |
<h4> <a name="Translated_Feature_Information"></a> Translated Feature Information</h4> |
<h4> <a name="Translated_Feature_Information"></a> Translated Feature Information</h4> |
| 959 |
<b>Note:</b> This section describes the conventions used for translating |
<b>Note:</b> This section describes the conventions used for |
| 960 |
the information contained within the feature manifest. It allows for |
translating the information contained within the feature manifest. |
| 961 |
the update client to select the correctly localized strings from the update |
It allows for the update client to select the correctly localized strings |
| 962 |
server. This section specifically does not describe localization of individual |
from the update server. This section specifically does not describe localization |
| 963 |
plug-ins. |
of individual plug-ins. |
| 964 |
<p>Several of the attributes within the feature manifest are strings intended |
<p>Several of the attributes within the feature manifest are strings intended |
| 965 |
for display through user interfaces. To facilitate translation, these |
for display through user interfaces. To facilitate translation, these |
| 966 |
attribute values use the convention defined for translatable attributes |
attribute values use the convention defined for translatable attributes |
| 996 |
</p> |
</p> |
| 997 |
|
|
| 998 |
<h4> <a name="Translated_Plug-In_Information"></a> Translated Plug-In Information</h4> |
<h4> <a name="Translated_Plug-In_Information"></a> Translated Plug-In Information</h4> |
| 999 |
No change from 1.0. Translated plug-in information should be packaged |
No change from 1.0. Translated plug-in information should be |
| 1000 |
as plug-in fragments. |
packaged as plug-in fragments. |
| 1001 |
<h3> <a name="Packaging_Target-Specific_Support"></a> Packaging Target-Specific |
<h3> <a name="Packaging_Target-Specific_Support"></a> Packaging Target-Specific |
| 1002 |
Support</h3> |
Support</h3> |
| 1003 |
No change from 1.0. Target-specific plug-in support (os, ws) should |
No change from 1.0. Target-specific plug-in support (os, ws) |
| 1004 |
be packaged as plug-in fragments. |
should be packaged as plug-in fragments. |
| 1005 |
<h3> <a name="Packaging_Attribution_Information"></a> Packaging Attribution |
<h3> <a name="Packaging_Attribution_Information"></a> Packaging Attribution |
| 1006 |
Information</h3> |
Information</h3> |
| 1007 |
This topic is covered in separate documents available on the eclipse.org |
This topic is covered in separate documents available on the |
| 1008 |
development resources page of the Update component. |
eclipse.org development resources page of the Update component. |
| 1009 |
|
|
| 1010 |
<h3> <a name="Packaging_Non_Plug_In_Files"></a> Packaging Non-Plug-In Files</h3> |
<h3> <a name="Packaging_Non_Plug_In_Files"></a> Packaging Non-Plug-In Files</h3> |
| 1011 |
Arbitrary non-plug-in files can be included as part of the feature |
Arbitrary non-plug-in files can be included as part of the feature |
| 1012 |
definition using the <tt><data></tt> elements. Non-plug-in files |
definition using the <tt><data></tt> elements. Non-plug-in files |
| 1013 |
typically also requires specification of a custom install handler. In |
typically also requires specification of a custom install handler. |
| 1014 |
general, the Eclipse support only downloads the referenced non-plug-in |
In general, the Eclipse support only downloads the referenced non-plug-in |
| 1015 |
files and calls the custom install handler to perform any actual installation |
files and calls the custom install handler to perform any actual installation |
| 1016 |
steps. |
steps. |
| 1017 |
<p>Eclipse does not specify the format of the non-plug-in files. </p> |
<p>Eclipse does not specify the format of the non-plug-in files. </p> |
| 1018 |
|
|
| 1019 |
<h3> <a name="Custom_Install_Handling"></a> Custom Install Handling</h3> |
<h3> <a name="Custom_Install_Handling"></a> Custom Install Handling</h3> |
| 1020 |
Custom install handlers are written as a Java class and are packaged |
Custom install handlers are written as a Java class and are packaged |
| 1021 |
as part of the <a href="#Feature_Archive">feature archive</a> . The installer |
as part of the <a href="#Feature_Archive">feature archive</a> . The |
| 1022 |
must implement the <tt>IInstallHandler</tt> interface (in most cases will |
installer must implement the <tt>IInstallHandler</tt> interface (in |
| 1023 |
extend the <tt>BaseInstallHandler</tt> abstract helper class which implements |
most cases will extend the <tt>BaseInstallHandler</tt> abstract helper |
| 1024 |
<tt>IInstallHandler</tt>). When required, the install handler is dynamically |
class which implements <tt>IInstallHandler</tt>). When required, the |
| 1025 |
loaded by the installation and update code, and is called at specific |
install handler is dynamically loaded by the installation and update |
| 1026 |
points during its processing. The install handler code has visibility |
code, and is called at specific points during its processing. The install |
| 1027 |
to classes from the installation and update support plug-in, and its prerequisite |
handler code has visibility to classes from the installation and update |
| 1028 |
plug-ins. |
support plug-in, and its prerequisite plug-ins. |
| 1029 |
<p><b>Implementation Note:</b> the detailed list of visible prerequisite plug-ins |
<p><b>Implementation Note:</b> the detailed list of visible prerequisite |
| 1030 |
is still evolving. It is expected to include <tt>org.eclipse.core.boot </tt> |
plug-ins is still evolving. It is expected to include <tt>org.eclipse.core.boot |
| 1031 |
and <tt>org.eclipse.core.runtime</tt> in all cases, plus <tt>org.eclipse.ui</tt> |
</tt> and <tt>org.eclipse.core.runtime</tt> in all cases, plus <tt>org.eclipse.ui</tt> |
| 1032 |
and <tt>org.eclipse.swt</tt> when running with full workbench (ie. |
and <tt>org.eclipse.swt</tt> when running with full workbench (ie. not |
| 1033 |
not "headless mode"). Also, it would be useful to always expose <tt>org.eclipse.core.ant</tt> |
"headless mode"). Also, it would be useful to always expose <tt>org.eclipse.core.ant</tt> |
| 1034 |
so that build scripts can be used as part of the install handler implementation. |
so that build scripts can be used as part of the install handler implementation. |
| 1035 |
</p> |
</p> |
| 1036 |
|
|
| 1037 |
<p>The IInstallHandler interface supports the following methods [<b>Implementation |
<p>The IInstallHandler interface supports the following methods [<b>Implementation |
| 1038 |
Note:</b> the detailed definition of the IInstallHandler interface is |
Note:</b> the detailed definition of the IInstallHandler interface |
| 1039 |
still evolving. The description below is not an API specification (simply |
is still evolving. The description below is not an API specification |
| 1040 |
a functional description)]: </p> |
(simply a functional description)]: </p> |
| 1041 |
|
|
| 1042 |
<ul> |
<ul> |
| 1043 |
<li> install-initiated - the install handler is called after a |
<li> install-initiated - the install handler is called after |
| 1044 |
feature was selected for installation, but before any files were downloaded. |
a feature was selected for installation, but before any files were downloaded. |
| 1045 |
It is intended to implement any custom click-through or user registration |
It is intended to implement any custom click-through or user registration |
| 1046 |
dialogs. The base implementation of this method supplied with the abstract |
dialogs. The base implementation of this method supplied with the abstract |
| 1047 |
class <tt>BaseInstallHandler </tt>performs the default click-through |
class <tt>BaseInstallHandler </tt>performs the default click-through |
| 1052 |
all the required feature files were downloaded (feature, plugins, data) |
all the required feature files were downloaded (feature, plugins, data) |
| 1053 |
but before the actual installation is performed. The install handler |
but before the actual installation is performed. The install handler |
| 1054 |
is expected to perform verification of the non-plug-in data files (eg. |
is expected to perform verification of the non-plug-in data files (eg. |
| 1055 |
security), or any other pre-install processing. On return this method |
security), or any other pre-install processing. On return this |
| 1056 |
indicates success (installation continues) or failure (installation is |
method indicates success (installation continues) or failure (installation |
| 1057 |
aborted).</li> |
is aborted).</li> |
| 1058 |
<li> install-completion - the install handler is called after |
<li> install-completion - the install handler is called after |
| 1059 |
the feature information and the plug-ins were installed. It is expected |
the feature information and the plug-ins were installed. It is expected |
| 1060 |
to complete the installation of any non-plug-in data that was part of the |
to complete the installation of any non-plug-in data that was part of |
| 1061 |
feature. On return this method indicates success (returns custom install |
the feature. On return this method indicates success (returns custom install |
| 1062 |
log) or failure (installation is aborted). On failure, the install handler |
log) or failure (installation is aborted). On failure, the install handler |
| 1063 |
is expected to perform any required cleanup.</li> |
is expected to perform any required cleanup.</li> |
| 1064 |
<li> uninstall-initiated - the install handler is called when |
<li> uninstall-initiated - the install handler is called when |
| 1066 |
processing has taken place. It is passed the custom install log created |
processing has taken place. It is passed the custom install log created |
| 1067 |
by the install handler install-completion step.</li> |
by the install handler install-completion step.</li> |
| 1068 |
<li> uninstall-completion - the install handler is called on |
<li> uninstall-completion - the install handler is called on |
| 1069 |
completion of the standard uninstall steps. It is passed the custom |
completion of the standard uninstall steps. It is passed the custom install |
| 1070 |
install log created by the install handler install-completion step.</li> |
log created by the install handler install-completion step.</li> |
| 1071 |
|
|
| 1072 |
</ul> |
</ul> |
| 1073 |
Note, that as a general practice, install handlers should be provided |
Note, that as a general practice, install handlers should be |
| 1074 |
in their own jars (even though they could be just exposed in the feature |
provided in their own jars (even though they could be just exposed in |
| 1075 |
archive jar). The jar should be signed, and sealed. |
the feature archive jar). The jar should be signed, and sealed. |
| 1076 |
|
|
| 1077 |
<h3> <a name="Security_Considerations"></a> Security Considerations</h3> |
<h3> <a name="Security_Considerations"></a> Security Considerations</h3> |
| 1078 |
The general approach is to use base Java jar signing for the feature |
The general approach is to use base Java jar signing for the |
| 1079 |
and plug-in archive .jars. |
feature and plug-in archive .jars. |
| 1080 |
<p>Features are verified as follows: </p> |
<p>Features are verified as follows: </p> |
| 1081 |
|
|
| 1082 |
<ul> |
<ul> |
| 1099 |
|
|
| 1100 |
</ul> |
</ul> |
| 1101 |
In general, when processing signed jars, the user will be prompted |
In general, when processing signed jars, the user will be prompted |
| 1102 |
for each unrecognized certificate. The response choices will include aborting |
for each unrecognized certificate. The response choices will include |
| 1103 |
the installation (originator is not trusted), continuing the installation |
aborting the installation (originator is not trusted), continuing the |
| 1104 |
(originator is trusted for this installation). |
installation (originator is trusted for this installation). |
| 1105 |
|
|
| 1106 |
<h2> <a name="Update_Server"></a> Update Server</h2> |
<h2> <a name="Update_Server"></a> Update Server</h2> |
| 1107 |
The default Eclipse update server is any URL-accessible server. |
The default Eclipse update server is any URL-accessible server. |
| 1108 |
The default implementation assumes a fixed-layout server. The content |
The default implementation assumes a fixed-layout server. The content |
| 1111 |
or can be dynamically computed by the server. |
or can be dynamically computed by the server. |
| 1112 |
<h3> <a name="Site_Map"></a> Site Map</h3> |
<h3> <a name="Site_Map"></a> Site Map</h3> |
| 1113 |
The update server URL can be specified as a full URL to the site |
The update server URL can be specified as a full URL to the site |
| 1114 |
map file, or a URL of a directory path containing the site map file (similar |
map file, or a URL of a directory path containing the site map file |
| 1115 |
to index.html processing). The site map site.xml format is defined by |
(similar to index.html processing). The site map site.xml format is |
| 1116 |
the following dtd: |
defined by the following dtd: |
| 1117 |
<p><tt><?xml encoding="ISO-8859-1"?></tt> </p> |
<p><tt><?xml encoding="ISO-8859-1"?></tt> </p> |
| 1118 |
|
|
| 1119 |
<p><tt><!ELEMENT site (description?, feature*, archive*, category-def*)></tt> |
<p><tt><!ELEMENT site (description?, feature*, archive*, category-def*)></tt> |
| 1141 |
CDATA #IMPLIED</tt> <br> |
CDATA #IMPLIED</tt> <br> |
| 1142 |
<tt> url |
<tt> url |
| 1143 |
CDATA #REQUIRED<br> |
CDATA #REQUIRED<br> |
| 1144 |
label CDATA |
label |
| 1145 |
#IMPLIED<br> |
CDATA #IMPLIED<br> |
| 1146 |
</tt><tt> os |
</tt><tt> os |
| 1147 |
CDATA #IMPLIED</tt> <br> |
CDATA #IMPLIED</tt> <br> |
| 1148 |
<tt> arch |
<tt> arch |
| 1219 |
match the identifier specified in the feature.xml of the referenced archive |
match the identifier specified in the feature.xml of the referenced archive |
| 1220 |
(the url attribute). If specified, the version attribute must also be |
(the url attribute). If specified, the version attribute must also be |
| 1221 |
specified.</li> |
specified.</li> |
| 1222 |
<li> version - optional feature version. The information is used |
<li> version - optional feature version. The information is |
| 1223 |
as a performance optimization to speed up searches for features. Must |
used as a performance optimization to speed up searches for features. |
| 1224 |
match the version specified in the feature.xml of the referenced archive |
Must match the version specified in the feature.xml of the referenced |
| 1225 |
(the url attribute). If specified, the id attribute must also be specified.</li> |
archive (the url attribute). If specified, the id attribute must also be |
| 1226 |
|
specified.</li> |
| 1227 |
<li> url - required URL reference to the feature archive. Can |
<li> url - required URL reference to the feature archive. Can |
| 1228 |
be relative or absolute. If relative, it is relative to the location of |
be relative or absolute. If relative, it is relative to the location |
| 1229 |
the site.xml file. <b>Note</b>: the default site implementation |
of the site.xml file. <b>Note</b>: the default site implementation |
| 1230 |
allows features to be accessed without being explicitly declared using |
allows features to be accessed without being explicitly declared using |
| 1231 |
a <feature> entry. By default, an undeclared features reference is |
a <feature> entry. By default, an undeclared features reference is |
| 1232 |
interpreted as "features/<id>_<version>.jar"</li> |
interpreted as "features/<id>_<version>.jar"</li> |
| 1237 |
list of os designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt> |
list of os designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt> |
| 1238 |
. Indicates this feature should only be installed on one of the specified |
. Indicates this feature should only be installed on one of the specified |
| 1239 |
os systems. If this attribute is "*", the feature can be installed |
os systems. If this attribute is "*", the feature can be installed |
| 1240 |
on all systems (portable implementation). This information is used as a |
on all systems (portable implementation). This information is used as |
| 1241 |
hint by the installation and update support (user can force installation |
a hint by the installation and update support (user can force installation |
| 1242 |
of feature regardless of this setting).</li> |
of feature regardless of this setting).</li> |
| 1243 |
<li> arch - optional machine architecture specification. A comma-separated |
<li> arch - optional machine architecture specification. A comma-separated |
| 1244 |
list of architecture designators defined by Eclipse (see Javadoc for |
list of architecture designators defined by Eclipse (see Javadoc for |
| 1251 |
list of ws designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt> |
list of ws designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt> |
| 1252 |
. Indicates this feature should only be installed on one of the specified |
. Indicates this feature should only be installed on one of the specified |
| 1253 |
ws systems. If this attribute is "*", the feature can be installed |
ws systems. If this attribute is "*", the feature can be installed |
| 1254 |
on all systems (portable implementation). This information is used as |
on all systems (portable implementation). This information is used |
| 1255 |
a hint by the installation and update support (user can force installation |
as a hint by the installation and update support (user can force installation |
| 1256 |
of feature regardless of this setting).</li> |
of feature regardless of this setting).</li> |
| 1257 |
<li> nl - optional locale specification. A comma-separated list |
<li> nl - optional locale specification. A comma-separated list |
| 1258 |
of locale designators defined by Java. Indicates this feature should only |
of locale designators defined by Java. Indicates this feature should |
| 1259 |
be installed on a system running with a compatible locale (using Java |
only be installed on a system running with a compatible locale (using |
| 1260 |
locale-matching rules). If this attribute is "*", the feature can |
Java locale-matching rules). If this attribute is "*", the feature |
| 1261 |
be installed on all systems (language-neutral implementation). This information |
can be installed on all systems (language-neutral implementation). This |
| 1262 |
is used as a hint by the installation and update support (user can force |
information is used as a hint by the installation and update support (user |
| 1263 |
installation of feature regardless of this setting).</li> |
can force installation of feature regardless of this setting).</li> |
| 1264 |
<li>patch - optional specification indicating if this feature |
<li>patch - optional specification indicating if this feature |
| 1265 |
is a patch. Default is "false". </li> |
is a patch. Default is "false". </li> |
| 1266 |
|
|
| 1277 |
<ul> |
<ul> |
| 1278 |
<li> path - required archive path identifier. This is a string |
<li> path - required archive path identifier. This is a string |
| 1279 |
that is determined by the <a |
that is determined by the <a |
| 1280 |
href="#Feature_Archive_Mapping_Id_To_Path">feature</a> referencing this |
href="#Feature_Archive_Mapping_Id_To_Path">feature</a> referencing |
| 1281 |
archive and is not otherwise interpreted by the site (other than as a |
this archive and is not otherwise interpreted by the site (other than |
| 1282 |
lookup token).</li> |
as a lookup token).</li> |
| 1283 |
<li> url - required URL reference to the archive. Can be relative |
<li> url - required URL reference to the archive. Can be relative |
| 1284 |
or absolute. If relative, it is relative to the location of the site.xml |
or absolute. If relative, it is relative to the location of the site.xml |
| 1285 |
file.</li> |
file.</li> |
| 1286 |
|
|
| 1287 |
</ul> |
</ul> |
| 1288 |
<li> <category-def> - an optional definition of a category |
<li> <category-def> - an optional definition of a category |
| 1289 |
that can be used by installation and update support to hierarchicaly |
that can be used by installation and update support to hierarchicaly organize |
| 1290 |
organize features</li> |
features</li> |
| 1291 |
|
|
| 1292 |
<ul> |
<ul> |
| 1293 |
<li> name - category name. Is specified as a path of name tokens |
<li> name - category name. Is specified as a path of name tokens |
| 1295 |
<li> label - displayable label. Intended to be translated.</li> |
<li> label - displayable label. Intended to be translated.</li> |
| 1296 |
|
|
| 1297 |
</ul> |
</ul> |
| 1298 |
<li> <category> - actual category specification for a feature |
<li> <category> - actual category specification for a |
| 1299 |
entry</li> |
feature entry</li> |
| 1300 |
|
|
| 1301 |
<ul> |
<ul> |
| 1302 |
name - category name |
name - category name |
| 1309 |
|
|
| 1310 |
<p>Translatable text contained in the site.xml can be separated into site<_locale>.properties |
<p>Translatable text contained in the site.xml can be separated into site<_locale>.properties |
| 1311 |
files using Java property bundle conventions. Note that the translated |
files using Java property bundle conventions. Note that the translated |
| 1312 |
strings are used at installation time (ie. do not employ the plug-in fragment |
strings are used at installation time (ie. do not employ the plug-in |
| 1313 |
runtime mechanism). The property bundles are located relative to the site.xml |
fragment runtime mechanism). The property bundles are located relative |
| 1314 |
location. </p> |
to the site.xml location. </p> |
| 1315 |
|
|
| 1316 |
<h3> <a name="Default_Site_Layout"></a> Default Site Layout</h3> |
<h3> <a name="Default_Site_Layout"></a> Default Site Layout</h3> |
| 1317 |
<tt><site root>/</tt> <br> |
<tt><site root>/</tt> <br> |
| 1327 |
<tt> plug-in argives |
<tt> plug-in argives |
| 1328 |
(eg. org.eclipse.ui_1.0.3.jar)</tt> |
(eg. org.eclipse.ui_1.0.3.jar)</tt> |
| 1329 |
<h3> <a name="Controlling_Access"></a> Controlling Access</h3> |
<h3> <a name="Controlling_Access"></a> Controlling Access</h3> |
| 1330 |
The default Eclipse site implementation provides support for http |
The default Eclipse site implementation provides support for |
| 1331 |
access with basic user authentication (userid and password). |
http access with basic user authentication (userid and password). |
| 1332 |
|
|
| 1333 |
<p>Custom access control mechanisms can be added to base Eclipse in one of |
<p>Custom access control mechanisms can be added to base Eclipse in one of |
| 1334 |
2 ways: </p> |
2 ways: </p> |
| 1339 |
to individual archives based on some user criteria)</li> |
to individual archives based on some user criteria)</li> |
| 1340 |
<li> by supplying a custom concrete implementation of the site |
<li> by supplying a custom concrete implementation of the site |
| 1341 |
object (installed on the client machine, update server specified <tt><site |
object (installed on the client machine, update server specified <tt><site |
| 1342 |
type=""></tt> ). The custom concrete site implementation, together with |
type=""></tt> ). The custom concrete site implementation, together |
| 1343 |
any server-side logic support the required control mechanisms.</li> |
with any server-side logic support the required control mechanisms.</li> |
| 1344 |
|
|
| 1345 |
</ul> |
</ul> |
| 1346 |
Eclipse provides an example demonstrating an implementation of |
Eclipse provides an example demonstrating an implementation of |
| 1350 |
<h3> <a name="Default_Install_Layout"></a> Default Install Layout</h3> |
<h3> <a name="Default_Install_Layout"></a> Default Install Layout</h3> |
| 1351 |
<tt><install root>/</tt> <br> |
<tt><install root>/</tt> <br> |
| 1352 |
<tt> install/</tt> <br> |
<tt> install/</tt> <br> |
| 1353 |
<tt> features/</tt> <br> |
<tt> features/</tt> |
| 1354 |
|
<br> |
| 1355 |
<tt> |
<tt> |
| 1356 |
<featureId>_<version>/</tt> <br> |
<featureId>_<version>/</tt> <br> |
| 1357 |
<tt> |
<tt> |
| 1372 |
<tt> |
<tt> |
| 1373 |
META_INF/</tt> </p> |
META_INF/</tt> </p> |
| 1374 |
|
|
| 1375 |
<p><b>Implementation Note:</b> we will go back to the original design of not |
<p><b>Implementation Note:</b> we will go back to the original design of |
| 1376 |
splitting out fragments (ie. plugin and fragments go into the same install |
not splitting out fragments (ie. plugin and fragments go into the same install |
| 1377 |
location) </p> |
location) </p> |
| 1378 |
|
|
| 1379 |
<h3> <a name="Unmanaged_Plugins"></a> "Unmanaged" Plug-Ins</h3> |
<h3> <a name="Unmanaged_Plugins"></a> "Unmanaged" Plug-Ins</h3> |
| 1381 |
plug-ins that were directly installed into the Eclipse file tree without |
plug-ins that were directly installed into the Eclipse file tree without |
| 1382 |
being part of a feature (eg. developer unzipping plug-in archive directly |
being part of a feature (eg. developer unzipping plug-in archive directly |
| 1383 |
into the Eclipse file tree). |
into the Eclipse file tree). |
| 1384 |
<p>Eclipse runtime recognizes these plugins during startup and loads the plug-in |
<p>Eclipse runtime recognizes these plugins during startup and loads the |
| 1385 |
information into the runtime registry following the standard plug-in binding |
plug-in information into the runtime registry following the standard plug-in |
| 1386 |
rules. The update support also recognizes the presence of this new plug-in, |
binding rules. The update support also recognizes the presence of this new |
| 1387 |
but since this plug-in is not part of any feature it cannot be updated using |
plug-in, but since this plug-in is not part of any feature it cannot be updated |
| 1388 |
the update support (hence "unmanaged"). Unmanaged plug-in that become referenced |
using the update support (hence "unmanaged"). Unmanaged plug-in that become |
| 1389 |
by a feature as a result of some future installation or update action become |
referenced by a feature as a result of some future installation or update |
| 1390 |
"managed" (can be updated as part of the feature). </p> |
action become "managed" (can be updated as part of the feature). </p> |
| 1391 |
|
|
| 1392 |
<p>Unmanaged plug-ins are not displayed as part of the installation and update |
<p>Unmanaged plug-ins are not displayed as part of the installation and update |
| 1393 |
UI. </p> |
UI. </p> |
| 1394 |
|
|
| 1395 |
<h3> <a name="Using_Native_Platform_Installers"></a> Using Native Platform |
<h3> <a name="Using_Native_Platform_Installers"></a> Using Native Platform |
| 1396 |
Installers</h3> |
Installers</h3> |
| 1397 |
The Eclipse installation contains plugins that can be shared across |
The Eclipse installation contains plugins that can be shared |
| 1398 |
multiple features. When installing and uninstalling features using the |
across multiple features. When installing and uninstalling features |
| 1399 |
Eclipse installation and update support, these relationship are correctly |
using the Eclipse installation and update support, these relationship |
| 1400 |
maintained. Only one copy of any version of a plug-in is used. |
are correctly maintained. Only one copy of any version of a plug-in is |
| 1401 |
|
used. |
| 1402 |
<p>However, when using native platform installers, performing native uninstall |
<p>However, when using native platform installers, performing native uninstall |
| 1403 |
creates problems because plug-ins would be removed without regard to |
creates problems because plug-ins would be removed without regard to |
| 1404 |
any sharing relationships. As a result, Eclipse <b>does not allow</b> plug-ins |
any sharing relationships. As a result, Eclipse <b>does not allow</b> |
| 1405 |
to be installed using native installers into the shared installation tree. |
plug-ins to be installed using native installers into the shared installation |
| 1406 |
Instead, native installers must establish their own installation root |
tree. Instead, native installers must establish their own installation |
| 1407 |
directory. The subdirectory structure is the same as defined for base |
root directory. The subdirectory structure is the same as defined for |
| 1408 |
Eclipse. The private root directory is logically linked into the shared |
base Eclipse. The private root directory is logically linked into the shared |
| 1409 |
Eclipse installation via a link file installed by the native installer. |
Eclipse installation via a link file installed by the native installer. |
| 1410 |
The file path for the link file is <tt><configRoot>/links/</tt>. |
The file path for the link file is <tt><configRoot>/links/</tt>. |
| 1411 |
The <tt><configRoot> </tt> location is computed by Eclipse relative |
The <tt><configRoot> </tt> location is computed by Eclipse relative |
| 1412 |
to the launch <a href="#Multiple%20Launch%20Points"> configuration file</a> |
to the launch <a href="#Multiple%20Launch%20Points"> configuration file</a> |
| 1413 |
. By default, this is the <tt>install/</tt> directory in the shared Eclipse |
. By default, this is the <tt>install/</tt> directory in the shared |
| 1414 |
installation tree. </p> |
Eclipse installation tree. </p> |
| 1415 |
|
|
| 1416 |
<p>The name of the link file is not specified by Eclipse. The name is determined |
<p>The name of the link file is not specified by Eclipse. The name is determined |
| 1417 |
by the native installer. To minimize the potential for naming collisions, |
by the native installer. To minimize the potential for naming collisions, |
| 1418 |
it is recommended that the file name contain the identifier and version |
it is recommended that the file name contain the identifier and version |
| 1419 |
of the feature being installed by the native installer. For example, <tt><featureId>_<featureVersion>.properties</tt> |
of the feature being installed by the native installer. For example, |
| 1420 |
. The file content is in the form of a Java properties file, with the |
<tt><featureId>_<featureVersion>.properties</tt> . The file |
| 1421 |
following properties defined: </p> |
content is in the form of a Java properties file, with the following |
| 1422 |
|
properties defined: </p> |
| 1423 |
|
|
| 1424 |
<p><tt>path=[r|rw] install-path[,[r|rw] install-path]*</tt> </p> |
<p><tt>path=[r|rw] install-path[,[r|rw] install-path]*</tt> </p> |
| 1425 |
|
|
| 1431 |
Default is to allow updates (w). </p> |
Default is to allow updates (w). </p> |
| 1432 |
|
|
| 1433 |
<p>Eclipse does not manage the linked directories in any way. It simply detects |
<p>Eclipse does not manage the linked directories in any way. It simply detects |
| 1434 |
their existence by the presence of the link files, and includes the |
their existence by the presence of the link files, and includes the linked |
| 1435 |
linked plug-ins during the platform startup. The native installer is |
plug-ins during the platform startup. The native installer is responsible |
| 1436 |
responsible for uninstalling the link when the corresponding directory |
for uninstalling the link when the corresponding directory is removed. |
| 1437 |
is removed. Eclipse runtime ignores any links that cannot be resolved. |
Eclipse runtime ignores any links that cannot be resolved. <br> |
|
<br> |
|
| 1438 |
</p> |
</p> |
| 1439 |
<br> |
<br> |
| 1440 |
<br> |
<br> |
| 1443 |
<br> |
<br> |
| 1444 |
<br> |
<br> |
| 1445 |
<br> |
<br> |
| 1446 |
|
<br> |
| 1447 |
</body> |
</body> |
| 1448 |
</html> |
</html> |
Parent Directory
| 
Revision Log
| 
Patch