platform-update-home/doc/eclipse_update_packaging.html
Parent Directory
| 
Revision Log
Revision 1.18 -
(download)
(as text)
(annotate)
Mon Jan 27 13:29:44 2003 UTC (6 years, 9 months ago) by celek
Branch: MAIN
Changes since 1.17: +1217 -1194 lines
Mon Jan 27 13:29:44 2003 UTC (6 years, 9 months ago) by celek
Branch: MAIN
Changes since 1.17: +1217 -1194 lines
*** empty log message ***
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type"
content="text/html; charset=iso-8859-1">
<meta name="Author" content="Lab User">
<meta name="GENERATOR" content="Microsoft FrontPage 4.0">
<title>Eclipse Platform: Installation and Update</title>
</head>
<body>
<h1> Eclipse Platform<br>
Update Packaging Conventions</h1>
<font size="-1">Revision Date: 01/27/2003 9:00AM - Version:
2.0.19</font><br>
<a href="../../../../../hglegal.htm"><img
src="ngibmcpy.gif" border="0" height="12" width="195">
</a>
<p><b>Change History:</b> </p>
<ul>
<li><small>2.0.19</small><small><br>
</small>
<ul>
<li><small>added <feature discovery type></small></li>
</ul>
</li>
<li><small>2.0.18</small></li>
<ul>
<li><small>added <feature plugin=""></small></li>
</ul>
<li><small>2.0.17</small></li>
<ul>
<li><small>added $os$,$ws$,$arch$ and $nl$ for copyright, description
and license URL tag in feature.<br>
</small></li>
</ul>
<li><small>2.0.16</small> <small><br>
</small>
<ul>
<li><small>added <site><feature> os,arch,nl,ws
support "*"</small></li>
</ul>
</li>
<li><small>2.0.15</small>
<ul>
<li><small>added <site><feature> os,arch,nl,ws,patch
tag</small></li>
</ul>
</li>
<li><small>2.0.14<br>
</small>
<ul>
<li><small>added <site><feature> label tag</small><br>
</li>
</ul>
</li>
<li><small>2.0.13<br>
</small> </li>
<ul>
<li><small>added <includes name,optional,match,search-location</small>
></li>
<li><small>added <import feature,patch></small></li>
</ul>
<li><small>2.0.12<br>
</small></li>
<ul>
<li> <font size="-1">added reference to the <a
href="http://www.eclipse.org/legal/updatemanager.html"> Eclipse.org Update
Manager Agreement</a> </font></li>
</ul>
<li> <font size="-1">2.0.11</font></li>
<ul>
<li> <font size="-1"><feature> <license> is required</font></li>
</ul>
<li> <font size="-1">2.0.10</font></li>
<ul>
<li> <font size="-1"><feature colocation-affinity=""></font></li>
</ul>
<li> <font size="-1">2.0.9</font></li>
<ul>
<li> <font size="-1"><site> <feature> changes -
additional markup to optionally expose feature identification information
to speed up searches</font></li>
<li> <font size="-1">removed obsolete text</font></li>
<li> <font size="-1">web-triggered update not in 2.0</font></li>
<li> <font size="-1">no assist in 2.0 for license/ "key file"
handling (individual application/ plugin responsibility)</font></li>
</ul>
<li> <font size="-1">2.0.8</font></li>
<ul>
<li> <font size="-1"><feature> <includes></font></li>
</ul>
<li> <font size="-1">2.0.7</font></li>
<ul>
<li> <font size="-1">support explicit xml markup for primary
features</font></li>
</ul>
<li> <font size="-1">2.0.6</font></li>
<ul>
<li> <font size="-1">install handler markup changes</font></li>
</ul>
<li> <font size="-1">2.0.5</font></li>
<ul>
<li> <font size="-1">updates to security section</font></li>
</ul>
<li> <font size="-1">2.0.4</font></li>
<ul>
<li> <font size="-1">general text cleanup</font></li>
<li> <font size="-1"><feature><group> support
removed (will not be in Eclipse 2.0)</font></li>
<li> <font size="-1">arch= support added to <feature>
and <feature><plugin></font></li>
<li> <font size="-1">os=/ arch=/ ws=/ nl= added to <fetaure><data></font></li>
<li> <font size="-1"><site url=""> new semantics</font></li>
<li> <font size="-1">corrected errors in native installer
link support</font></li>
<li> <font size="-1">defined callback query strings for browser-triggered
processing</font></li>
</ul>
</ul>
<h3> <font size="+2">Table of Contents</font></h3>
<a href="#Introduction">Introduction</a> <br>
<a
href="#Changes_from_R1.0">Changes from 1.0</a> <br>
<a href="#Concepts">Concepts</a>
<br>
<a href="#Framework">Framework</a>
<br>
<a href="#Packaging_Conventions">Packaging Conventions</a>
<br>
<a
href="#Feature_Archive">Feature Archive</a> <br>
<a
href="#Plug-In_Archive">Plug-In Archive</a> <br>
<a
href="#Packaging_NL">Packaging NL</a> <br>
<a href="#Translated_Feature_Information"> Translated Feature Information</a>
<br>
<a href="#Translated_Plug-In_Information"> Translated Plug-In Information</a>
<br>
<a
href="#Packaging_Target-Specific_Support"> Packaging Target-Specific Support</a>
<br>
<a
href="#Packaging_Attribution_Information"> Packaging Attribution Information</a>
<br>
<a
href="#Packaging_Attribution_Information"> Packaging Non-Plug-In Files</a>
<br>
<a
href="#Packaging_Attribution_Information"> Custom Install Handling</a>
<br>
<a
href="#Security_Considerations">Security Considerations</a> <br>
<a href="#Update_Server">Update Server</a> <br>
<a href="#Site_Map">Site
Map</a> <br>
<a
href="#Default_Site_Layout">Default Site Layout</a> <br>
<a
href="#Controlling_Access">Controlling Access</a> <br>
<a href="#Eclipse_Install">Eclipse Install</a> <br>
<a
href="#Default_Install_Layout">Default Install Layout</a> <br>
<a
href="#Unmanaged_Plugins">"Unmanaged" Plug-Ins</a> <br>
<a
href="#Using_Native_Platform_Installers"> Using Native Platform Installers</a>
<h2> <a name="Introduction"></a> Introduction</h2>
This document outlines the support for managing the delivery
of function within the Eclipse platform. Also refer to the "<a
href="http://www.eclipse.org/legal/updatemanager.html"> Eclipse.org Update
Manager Agreement</a> " for additional legal information governing
the use of the Eclipse update manager function.
<h3> <a name="Changes_from_R1.0"></a> Changes from R1.0</h3>
This section describes the major design changes from the R1.0
Installation and Update support and supplies rationale for each design
change.
<ul>
<li> <b>extendable framework</b></li>
<br>
In R2.0 Eclipse defines an extendable framework for installation
and update, allowing the support for alternate packaging and site management
schemes. R2.0 supplies a default concrete implementation of this framework.
<li> <b> feature support</b></li>
<br>
In R2.0 the concept of a <i>component</i> and <i>configuration</i>
is merged into <i>feature</i>. Features define the packaging structure
for a group of related plug-ins, plug-in fragments, and optionally non-plug-in
files. Features are treated purely as an installation and packaging construct.
They do not play a role during Eclipse plug-in execution. Features do
not nest. They are simply an inclusive "manifest" of the plug-ins, fragments
and other files that make up that feature. If features are logically made
up of plug-ins from "sub-features", the top-level feature "manifest" must
be fully resolved at packaging time. <li> <b>default feature archive format</b></li>
<br>
R1.0 components were packaged as a single Java .jar containing
the component manifest as well as the actual plug-in files. The problem
with this approach is lack of granularity at download time. In R2.0,
the feature archive consists of multiple separate .jars - one .jar per
plug-in and fragment, plus one .jar for the actual feature information.
The Installation and Update support selectively downloads only those
jars required for the installation. <li> <b>site map</b></li>
<br>
Default Eclipse update server must contain a <i>site map</i>
file (site.xml). This is an evolution of the R1.0 install.index support.
The rationale for using a structured site defined by the map rather
than a "free form" web site, is the ability to present a consistent installation
experience for the user. Also, this provides the necessary structure
for discovery of available updates. Additional support for "free form"
browsing may be considered in future work. <li> <b>using native install/
uninstall</b></li>
<br>
The primary mechanism for installing and updating Eclipse features
is the built-in installation and update support. Some products may instead
choose to use native installer technology (eg. MSI, RPM, etc) to deliver
Eclipse features. However, native installers do not implement the required
support for understanding the Eclipse installation structure. In particular,
the native uninstallers will, by default, remove plug-in files that were
installed using the native installer without regard to these plug-ins
being needed by other features. As a result, features installed using
native installers must be written into private product-specific installation
location and not the shared Eclipse installation location. The shared
Eclipse is made aware of the produce-specific location via an installed
"link file". <li> <b>custom install handling</b></li>
<br>
In many cases the standard installation handling supplied by
Eclipse is not be sufficient to handle various custom requirements. To
accommodate this, R2.0 Eclipse supports custom install handlers packaged
as part of the feature and executed during the feature installation. <li>
<b>path naming conventions</b></li>
<br>
R1.0 mandated the use of the various identifiers and versions
inside the packaged archives (eg. directory path names for plug-ins).
This approach has proven to be ackward and error prone. In 2.0, the
packaging requirements no longer mandate that path names of packaged
files precisely reflect the contained identifiers and versions. The properly
identified install subdirectories are created by the Eclipse support
during the installation and update process based on the archive content
(rather than explicit jar path structure set up at packaging time)
</ul>
<h3> <a name="Concepts"></a> Concepts</h3>
<b>Plug-in</b> <br>
Eclipse developers build plug-ins. Plug-ins are the base units
of execution recognized by the Eclipse runtime environment. In general,
plug-ins are not exposed to users that select function during installation
or update. The reason is that plug-in boundaries are established by developers
for development reasons (like function reuse) and present the wrong
level of granularity in terms of what the user sees as the unit of function.
<p>While plug-ins are being developed (ie. are frequently being changed),
their internal file structure will reflect what is convenient to the
developer. This will generally depend on the particular development
tool being used. Typically, however, the developer will likely setup
the plug-in to execute from a directory tree containing exposed .class
files, rather than executing from a .jar (requires an extra step to
create the .jar and we all know developers hate extra steps). Also, at
this stage the developer does not pay particular attention to plug-in
versioning information, because the plug-in is continually changing. </p>
<p>However, when the plug-in is ready to be packaged, it needs to be converted
to a form suitable for packaging and installation. Typically it means
creation of the runtime .jar(s) and removing any development-time files
(source, exposed .class files, etc). It also means updating the plugin.xml
manifest with the formal plug-in version and reflecting the version in
the plug-in directory name (see "Concurrent Plug-In Version Support" for
details). </p>
<p><b>Plug-in Fragment</b> <br>
Plug-in Fragments (or simply Fragments) allow independent packaging
of certain aspects of the base plug-in. This includes (but may not
be limited to) translated resources for the plug-in, OS-specific or
windowing-system-specific code. At runtime, fragments are logically
merged into the base plug-in. From a packaging point of view, the install
and update support does not really differentiate between plug-ins and
their related fragments. </p>
<p><b>Feature</b> <br>
A feature is an installation packaging mechanism used to define
a group of versioned plug-ins and/or plug-in fragments plus non-plug-in
files that is used to deliver some user function. A feature can also
include other features. Features are exposed to users as part of the
packaging and installation process, because they represent a unit of
function selection. Features also represent a unit of installation. Features
carry a version identifier.</p>
<p>Features are packaged as a feature archive, referencing the required plug-ins,
plug-in fragments and optional non-plug-in files. The feature archives
are placed on an update server for download and installation by the Eclipse
update manager, or they can be used as the input into a formal packaging
process using one of the "traditional" installer technologies. The format
of the feature archive is described later. </p>
<h3> <a name="Framework"></a> Framework</h3>
The 2.0 installation and update support is provided as a framework
that allows custom implementations to be supplied for its key elements.
In particular, the following can be supplied:
<ul>
<li> concrete implementations of feature (IFeature interface)
that can be used to support alternate packaging schemes. New concrete
feature types are registere via the "org.eclipse.update.featureTypes"
extension point.</li>
<li> concrete implementations of site (ISite interface) that
can be used to support alternate site layout, or site behavior. New concrete
site types are registered via the "org.eclipse.update.siteTypes" extension
point.</li>
<li> each feature can specify a custom install handler as
part of its feature manifest. Install handlers (IInstallHandler interface)
are dynamically invoked as part of the installation process to handle
non-plugin data, plus perform other custom processing allowed by the framework.</li>
</ul>
Eclipse provides default implementations of feature and site.
These are described in the rest of this document. <br>
<table border="1" cols="1" width="100%">
<tbody>
<tr>
<td><b>Note: <i>The reminder of this document describes the
default concrete implementation of the framework delivered with Eclipse.
It specifies the structure of the default feature implementation, as well
as the default site implementation, plus the corresponding xml files (feature.xml
and site.xml). Providers of alternate concrete implementations can extend
parts or all of the default Eclipse implementation. This includes providing
a mechanism for dynamic computation of the site map (site.xml)</i></b></td>
</tr>
</tbody>
</table>
<h2> <a name="Packaging_Conventions"></a> Packaging Conventions</h2>
Default feature packages consist of several related files:
<ul>
<li> exactly one jar containing the feature manifest and related
files. This one is refered to as the "<b>feature archive</b>"</li>
<li> zero or more jars containing the feature plug-ins. These
are refered to as the "<b>plug-in archives</b>"</li>
<li> zero or more non-plug-in files associated with the feature.
They are used by feature custom install handlers and contain data not
interpreted by Eclipse</li>
</ul>
<h3> <a name="Feature_Archive"></a> Feature Archive</h3>
The feature packaging information is placed into a separate
Java .jar. Standard Java jar facilities are used for constructing feature
archives. Feature archives reference separately packaged plug-in archives
(see next section) and non-plug-in files.
<p>Features are identified using a structured identifier based on the provider
internet domain name. For example, organization eclipse.org may produce
feature org.eclipse.javatooling. The character set used for feature
identifiers is as specified for plug-in identifiers (see reference information
describing the plug-in manifest). </p>
<p>The recommended convention for naming the feature archives is <br>
<tt><id>_<version>.jar</tt> </p>
<p>Where <tt><id></tt> is the feature identifier and <tt><version></tt>
is the full version identifier contained in the respective feature.xml.
Note that this is a recommended convention that minimizes chance of
collisions, but is not required by the Eclipse architecture. For example,
the following are valid feature archive names </p>
<p><tt>org.eclipse.javatooling_1.0.3.jar</tt> <br>
<tt>org.eclipse.pde_2.0.jar</tt> <br>
<tt>my_feature.jar</tt> </p>
<p>Internally, each feature archive is packaged relative to its feature directory
(but not including the directory path element). The archive has the
following structure </p>
<p><tt>feature.xml</tt> <br>
<tt>feature<_locale>.properties (see "Translated Feature
Information")</tt> <br>
<tt>other feature files and subdirectories (TBD)</tt> <br>
<tt>META-INF/</tt> <br>
<tt> Java jar manifest and security files</tt>
</p>
<p>The feature install.xml format is defined by the following dtd: </p>
<p><tt><?xml encoding="ISO-8859-1"?></tt> </p>
<p><tt><!ELEMENT feature (install-handler?, description?, copyright?,
license?, url?, includes*, requires?, plugin*, data*)></tt> <br>
<tt><!ATTLIST feature</tt> <br>
<tt> id
CDATA #REQUIRED</tt> <br>
<tt> version
CDATA #REQUIRED</tt> <br>
<tt> label
CDATA #IMPLIED</tt> <br>
<tt> provider-name CDATA #IMPLIED</tt> <br>
<tt> image
CDATA #IMPLIED</tt> <br>
<tt> os
CDATA #IMPLIED</tt> <br>
<tt> arch
CDATA #IMPLIED</tt> <br>
<tt> ws
CDATA #IMPLIED</tt> <br>
<tt> nl
CDATA #IMPLIED</tt> <br>
<tt> colocation-affinity</tt> <br>
<tt>
CDATA #IMPLIED</tt> <br>
<tt> primary
(true | false) "false"</tt> <br>
<tt> application CDATA #IMPLIED<br>
</tt> <tt>plugin
CDATA #IMPLIED</tt><br>
<tt>></tt> </p>
<p><tt><!ELEMENT install-handler EMPTY></tt> <br>
<tt><!ATTLIST install-handler</tt> <br>
<tt> library
CDATA #IMPLIED</tt> <br>
<tt> handler
CDATA #IMPLIED</tt> <br>
<tt>></tt> </p>
<p><tt><!ELEMENT description (#PCDATA)></tt> <br>
<tt><!ATTLIST description</tt> <br>
<tt> url
CDATA #IMPLIED</tt> <br>
<tt>></tt> </p>
<p><tt><!ELEMENT copyright (#PCDATA)></tt> <br>
<tt><!ATTLIST copyright</tt> <br>
<tt> url
CDATA #IMPLIED</tt> <br>
<tt>></tt> </p>
<p><tt><!ELEMENT license (#PCDATA)></tt> <br>
<tt><!ATTLIST license</tt> <br>
<tt> url
CDATA #IMPLIED</tt> <br>
<tt>></tt> </p>
<p><tt><!ELEMENT url (update?, discovery*)></tt> </p>
<p><tt><!ELEMENT update EMPTY></tt> <br>
<tt><!ATTLIST update</tt> <br>
<tt> url
CDATA #REQUIRED</tt> <br>
<tt> label
CDATA #IMPLIED</tt> <br>
<tt>></tt> </p>
<p><tt><!ELEMENT discovery EMPTY></tt> <br>
<tt><!ATTLIST discovery</tt> <br>
<tt> url
CDATA #REQUIRED</tt> <br>
<tt> label
CDATA #IMPLIED</tt> <br>
<tt> type
(update|web) "update"</tt><tt><br>
></tt> </p>
<p> </p>
<p><tt><!ELEMENT includes EMPTY></tt> <br>
<tt><!ATTLIST includes</tt> <br>
<tt> id
CDATA #REQUIRED</tt> <br>
<tt> version
CDATA #REQUIRED</tt> <br>
<tt> name
CDATA #IMPLIED</tt> <br>
<tt> optional </tt><tt>
(true | false) "false"</tt><tt> <br>
</tt><tt> match
(perfect | equivalent | compatible | greaterOrEqual)
"compatible"</tt><tt> </tt><br>
<tt> search-location </tt><tt>(</tt><font
color="#000000"><tt> root | self | both) "root"</tt></font><br>
<tt>></tt> </p>
<p><tt><!ELEMENT requires (import+)></tt> </p>
<p><tt><!ELEMENT import EMPTY></tt> <br>
<tt><!ATTLIST import</tt> <br>
<tt> plugin
CDATA #IMPLIED</tt><br>
<tt> feature
CDATA #IMPLIED</tt><br>
<tt> version
CDATA #IMPLIED</tt> <br>
<tt> match
(perfect | equivalent | compatible | greaterOrEqual) "compatible"</tt> <br>
<tt> patch </tt><tt>
(true | false) "false"</tt><tt> </tt><tt><br>
></tt><br>
</p>
<p><tt><!ELEMENT plugin EMPTY></tt> <br>
<tt><!ATTLIST plugin</tt> <br>
<tt> id
CDATA #REQUIRED</tt> <br>
<tt> version
CDATA #REQUIRED</tt> <br>
<tt> fragment
(true | false) "false"</tt> <br>
<tt> os
CDATA #IMPLIED</tt> <br>
<tt> arch
CDATA #IMPLIED</tt> <br>
<tt> ws
CDATA #IMPLIED</tt> <br>
<tt> nl
CDATA #IMPLIED</tt> <br>
<tt> download-size CDATA #IMPLIED</tt> <br>
<tt> install-size CDATA #IMPLIED</tt>
<br>
<tt>></tt> </p>
<p><tt><!ELEMENT data EMPTY></tt> <br>
<tt><!ATTLIST data</tt> <br>
<tt> id
CDATA #REQUIRED</tt> <br>
<tt> os
CDATA #IMPLIED</tt> <br>
<tt> arch
CDATA #IMPLIED</tt> <br>
<tt> ws
CDATA #IMPLIED</tt> <br>
<tt> nl
CDATA #IMPLIED</tt> <br>
<tt> download-size CDATA #IMPLIED</tt> <br>
<tt> install-size CDATA #IMPLIED</tt>
<br>
<tt>></tt> </p>
<p>The element and attribute definitions are as follows: </p>
<ul>
<li> <feature> - defines the feature</li>
<ul>
<li> id - required feature identifier (eg. com.xyz.myfeature)</li>
<li> version - required component version (eg. 1.0.3)</li>
<li> label - optional displayable label (name). Intended to
be translated.</li>
<li> provider-name - optional display label identifying the
organization providing this component. Intended to be translated.</li>
<li> image - optional image to use when displaying information
about the feature. Specified relative to the feature.xml.</li>
<li> os - optional operating system specification. A comma-separated
list of os designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt>
. Indicates this feature should only be installed on one of the specified
os systems. If this attribute is not specified, the feature can be
installed on all systems (portable implementation). This information
is used as a hint by the installation and update support (user can force
installation of feature regardless of this setting).</li>
<li> arch - optional machine architecture specification. A
comma-separated list of architecture designators defined by Eclipse
(see Javadoc for <tt> org.eclipse.core.boot.BootLoader)</tt>. Indicates
this feature should only be installed on one of the specified systems.
If this attribute is not specified, the feature can be installed on all
systems (portable implementation). This information is used as a hint
by the installation and update support (user can force installation of
feature regardless of this setting).</li>
<li> ws - optional windowing system specification. A comma-separated
list of ws designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt>
. Indicates this feature should only be installed on one of the specified
ws systems. If this attribute is not specified, the feature can be
installed on all systems (portable implementation). This information
is used as a hint by the installation and update support (user can force
installation of feature regardless of this setting).</li>
<li> nl - optional locale specification. A comma-separated
list of locale designators defined by Java. Indicates this feature should
only be installed on a system running with a compatible locale (using
Java locale-matching rules). If this attribute is not specified, the feature
can be installed on all systems (language-neutral implementation). This
information is used as a hint by the installation and update support (user
can force installation of feature regardless of this setting).</li>
<li> colocation-affinity - optional reference to another feature
identifier used to select the default installation location for this
feature. When this feature is being installed as a new feature (no other
versions of it are installed), an attempt is made to install this feature
in the same installation location as the referenced feature.</li>
<li> primary - optional indication specifying whether this
feature can be used as a <a href="#Dominant_Feature">primary feature</a>
. Default if <i>false</i> (not a primary feature).</li>
<li> application - optional identifier of the Eclipse application
that is to be used during startup when the declaring feature is the
<a href="#Dominant_Feature"> primary feature</a> . The application
identifier must represent a valid application registered in the <tt>org.eclipse.core.runtime.applications</tt>
extension point. Default is <tt>org.eclipse.ui.workbench</tt>.</li>
<li> plugin- optional identifier of the primary plugin associated
with this <a
href="file:///C:/OTI/workspace/plugins/platform-update-home/doc/eclipse_update_packaging.html#Dominant_Feature">primary
feature</a>. The primary plugin carries branding information. If the plugin
attribute is not declared, the primary plugin identifier used will be the
same as the feature identifier. </li>
</ul>
<li> <install-handler></li>
<ul>
<li> library - optional .jar library containing the install
handler classes. If specified, the referenced .jar must be contained
in the feature archive. It is specified as a path within the feature
archive, relative to the feature.xml entry. If not specified, the feature
archive itself is used to load the install handler classes. This attribute
is only interpreted if <i>class</i> attribute is also specified</li>
<li> handler - optional identifier of the install handler.
The value is interpreted depending on the value of the <i>library</i>
attribute. If <i> library</i> is specified, the value is
interpreted as a fully qualified name of a class contained in the specified
<i>library</i>. If <i>library</i> is not specified, the
value is is interpreted as an extension identifier of an extension registered
in the <i>org.eclipse.update.installHandlers</i> extension point. In
either case, the resulting class must implement the <i> IInstallHandler</i>
interface. The class is dynamically loaded and called at specific points
during feature processing. The handler has visibility to the API classes
from the update plug-in, and Eclipse plug-ins required by the update plugin.</li>
</ul>
<li> <description> - brief component description as
simple text. Intended to be translated.</li>
<ul>
<li> url - optional URL for the full description as HTML. The
URL can be specified as absolute of relative. If relative, it is assumed
to be relative to (and packaged in) the feature archive. Note, that for
NL handling the URL value should be separated to allow alternate URLs to
be specified for each national language. URL support keywords $os$,$ws$,$arch$
and $nl$ that will be replaced by the appropriate operating system, windowing
system, operating architecture or national language value.</li>
</ul>
<li> <copyright> - feature copyright as simple text.
Intended to be translated.</li>
<ul>
<li> url - optional URL for the full description as HTML. The
URL can be specified as absolute of relative. If relative, it is assumed
to be relative to (and packaged in) the feature archive. Note, that for
NL handling the URL value should be separated to allow alternate URLs to
be specified for each national language. URL support keywords $os$,$ws$,$arch$
and $nl$ that will be replaced by the appropriate operating system, windowing
system, operating architecture or national language value.</li>
</ul>
<li> <license> - feature "click-through" license as
simple text. Intended to be translated. It is displayed in a standard
dialog with [Accept] [Reject] actions during the download/ installation
process. Note, that click-through license must be specified for any feature
that will be selected for installation or update using the Eclipse update
manager. When using nested features, only the nesting parent (ie. the feature
selected for installation or update) must have click-through license text
defined. The license text is required even if the optional <i>url</i> attribute
is specified.</li>
<ul>
<li> url - optional URL for the full description as HTML. The
URL can be specified as absolute of relative. If relative, it is assumed
to be relative to (and packaged in) the feature archive. Note, that for
NL handling the URL value should be separated to allow alternate URLs to
be specified for each national language. Note, that the "content" of this
URL is <b>not</b> what is presented as the click-through license during
installation processing. The click-through license is the actual value
of the <i><license></i> element (eg. <tt><license>click
through text</license></tt>). URL support keywords $os$,$ws$,$arch$
and $nl$ that will be replaced by the appropriate operating system, windowing
system, operating architecture or national language value.</li>
</ul>
<li> <url> - optional URL specifying site(s) contain
feature updates, or new features</li>
<ul>
<li> <update> - URL to go to for updates to this feature</li>
<ul>
<li> url - actual URL</li>
<li> label - displayable label (name) for the referenced site</li>
</ul>
<li> <discovery> - URL to go to for new features. In
general, a provider can use this element to reference its own site(s),
or site(s) of partners that offer complementary features. Eclipse uses
this element simply as a way to distribute new site URLs to the clients</li>
<ul>
<li> url - actual URL</li>
<li> label - displayable label (name) for the referenced site</li>
<li>type - whether the site is an regular update site or a web site.
The web site may be a web-triggered-install web site. (<tt>update</tt> is
the default)<br>
</li>
</ul>
</ul>
<li> <includes> - optional reference to a nested feature
that is considered to be part of this feature. Nested features must be
located on the same update site as this feature</li>
<ul>
<li> id - required nested feature identifier</li>
<li> version - required nested feature version</li>
<li> name- optional displayable label (name). Intended to
be translated.</li>
<li>optional - optional specification indicating if this
included feature can be optionally installed. Default is "false"<br>
</li>
<li>match - optional rule that will be applied when
resolving the feature reference. A <samp>perfect</samp> match (the
default that matches the 2.0.1 behavior) requires that the feature has
exactly the version specified by the version attribute. Other choices
progressively relax the rule (<samp> equivalent</samp> allows only service
part of the version to be more recent, <samp>compatible</samp>
also allows minor part to be included in the consideration, while <samp>greaterOrEqual</samp>
simply allows any version that is more recent or identical to the one
specified).</li>
<li>search-location - optional. Indicates whether
the "New Updates" action should search the update location determined
by the nesting root feature (<tt>root</tt>, is the default), or the location
defined by the nested feature (<tt>self</tt>), or search both (<tt>both</tt>)
in that order (root first, self if nothing is found).</li>
</ul>
<li> <requires> - optional feature dependency information.
Is expressed in terms of plug-in dependencies. If specified, is enforced
by the installation and update support at the time of installation</li>
<ul>
<li> <import> - dependency entry. Specification and processing
is a subset of the <import> specification in plugin.xml</li>
<ul>
<li> plugin - identifier of dependent plug-in.</li>
<li> feature - identifier of dependent feature. If plugin
and feature are specified, plugin takes precedence upon feature. Feature
or plugin must be specified.</li>
<li> version - optional plug-in/feature version specification</li>
<li>patch - optional specification indicating if this
feature is a patch of the dependant feature. Default is "false". If
patch is true, version must be specified. If patch is true, only feature
must be specified. If patch is true, and match is specified, it must
be 'perfect'.<br>
</li>
<li> match - optional matching rule. Valid values and processing
are as follows:</li>
<ul>
<li> if version attribute is not specified, the match attribute
(if specified) is ignored.</li>
<li>if version is specified, match defaults to compatible.<br>
</li>
<li>if patch is true, and match is not specified, match
defaults to perfect.<br>
</li>
<li> <b><i>perfect</i></b> - dependent plug-in version must
match exactly the specified version.</li>
<li> <b><i>equivalent</i></b> - dependent plug-in version
must be at least at the version specified, or at a higher service level
(major and minor version levels must equal the specified version).</li>
<li> <b><i>compatible</i></b> - dependent plug-in version
must be at least at the version specified, or at a higher service level
or minor level (major version level must equal the specified version).</li>
<li> <b><i>greaterOrEqual</i></b> - dependent plug-in version
must be at least at the version specified, or at a higher service, minor
or major level.</li>
</ul>
</ul>
</ul>
<li> <plugin> - identifies referenced plug-in</li>
<ul>
<li> id - required plug-in identifier (from plugin.xml)</li>
<li> version - required plug-in version (from plugin.xml)</li>
<li> fragment - optional specification indicating if this
entry is a plug-in fragment. Default is "false"</li>
<li> os - optional operating system specification. A comma-separated
list of os designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt>
. Indicates this entry should only be installed on one of the specified
os systems. If this attribute is not specified, the entry can be installed
on all systems (portable implementation). This information is used
as a hint by the installation and update support (user can force installation
of entry regardless of this setting).</li>
<li> arch - optional machine architecture specification. A
comma-separated list of architecture designators defined by Eclipse
(see Javadoc for <tt> org.eclipse.core.boot.BootLoader)</tt>. Indicates
this feature should only be installed on one of the specified systems.
If this attribute is not specified, the feature can be installed on all
systems (portable implementation). This information is used as a hint
by the installation and update support (user can force installation of
feature regardless of this setting).</li>
<li> ws - optional windowing system specification. A comma-separated
list of ws designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt>
. Indicates this entry should only be installed on one of the specified
ws systems. If this attribute is not specified, the entry can be installed
on all systems (portable implementation). This information is used
as a hint by the installation and update support (user can force installation
of entry regardless of this setting).</li>
<li> nl - optional locale specification. A comma-separated
list of locale designators defined by Java. Indicates this entry should
only be installed on a system running with a compatible locale (using
Java locale-matching rules). If this attribute is not specified, the entry
can be installed on all systems (language-neutral implementation). This
information is used as a hint by the installation and update support (user
can force installation of entry regardless of this setting).</li>
<li> download-size - optional hint supplied by the feature
packager, indicating the download size in KBytes of the referenced plug-in
archive.The size should not contain decimal. If not specified, the download
size is not known (<b>Implementation Note:</b> the implementation needs
to distinguish between "not known" and 0 size)</li>
<li> install-size - optional hint supplied by the feature
packager, indicating the install size in KBytes of the referenced
plug-in archive. The size should not contain decimal. If not specified,
the install size is not known (<b>Implementation Note:</b> the implementation
needs to distinguish between "not known" and 0 size)</li>
</ul>
<li> <data> - identifies non-plugin and non-feature
data that is part of the feature. Generally, data are post-install processed
using feature Install handler. Feature files like feature.properties are
not considered data.</li>
<ul>
<li> id - required data identifier in the form of a relative
path.</li>
<li> os - optional operating system specification. A comma-separated
list of os designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt>
. Indicates this entry should only be installed on one of the specified
os systems. If this attribute is not specified, the entry can be installed
on all systems (portable implementation). This information is used
as a hint by the installation and update support (user can force installation
of entry regardless of this setting).</li>
<li> arch - optional machine architecture specification. A
comma-separated list of architecture designators defined by Eclipse
(see Javadoc for <tt> org.eclipse.core.boot.BootLoader)</tt>. Indicates
this feature should only be installed on one of the specified systems.
If this attribute is not specified, the feature can be installed on all
systems (portable implementation). This information is used as a hint
by the installation and update support (user can force installation of
feature regardless of this setting).</li>
<li> ws - optional windowing system specification. A comma-separated
list of ws designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt>
. Indicates this entry should only be installed on one of the specified
ws systems. If this attribute is not specified, the entry can be installed
on all systems (portable implementation). This information is used
as a hint by the installation and update support (user can force installation
of entry regardless of this setting).</li>
<li> nl - optional locale specification. A comma-separated
list of locale designators defined by Java. Indicates this entry should
only be installed on a system running with a compatible locale (using
Java locale-matching rules). If this attribute is not specified, the entry
can be installed on all systems (language-neutral implementation). This
information is used as a hint by the installation and update support (user
can force installation of entry regardless of this setting).</li>
<li> download-size - optional hint supplied by the feature
packager, indicating the download size in KBytes of the referenced data
archive. If not specified, the download size is not known (<b>Implementation
Note:</b> the implementation needs to distinguish between "not known"
and 0 size)</li>
<li> install-size - optional hint supplied by the feature
packager, indicating the install size in KBytes of the referenced
data archive. If not specified, the install size is not known (<b>Implementation
Note:</b> the implementation needs to distinguish between "not known"
and 0 size)</li>
</ul>
</ul>
<a name="Feature_Archive_Mapping_Id_To_Path"></a> When interacting
with the update site, the feature implementation maps the <tt><plugin></tt>
and <tt><data></tt> elements into path identifiers used by the
site to determine the actual files to download and install. The default
feature implementation supplied by Eclipse constructs the path identifiers
as follows:
<ul>
<li> <tt><plugin></tt> element results in a path entry
in the form "<tt>plugins/<pluginId>_<pluginVersion>.jar</tt>"
(for example, "<tt>plugins/org.eclipse.core.boot_1.0.3.jar</tt>")</li>
<li> <tt><data></tt> element results in a path entry
in the form "<tt>features/<featureId>_<featureVersion>/<dataId></tt>
" (for example, "f<tt>eatures/com.xyz.tools_2.3.1/examples.zip</tt>")</li>
</ul>
Note, that in general the feature.xml manifest documents
should specify UTF-8 encoding. For example
<p><tt><?xml version="1.0" encoding="UTF-8"?></tt> </p>
<p>Translatable text contained in the feature.xml can be separated into feature<_locale>.properties
files using Java property bundle conventions. Note that the translated
strings are used at installation time (ie. do not employ the plug-in
fragment runtime mechanism). </p>
<h3> <a name="Plug-In_Archive"></a> Plug-In Archive</h3>
Plug-ins and plug-in fragments are individually packaged as
separate Java .jars. Standard Java jar facilities are used for constructing
plug-in archives. There is no distinction made between a plug-in archive
containing a plug-in and one containing a plug-in fragment.
<p>The recommended convention for naming the plug-in archives is <br>
<tt><id>_<version>.jar</tt> </p>
<p>Where <tt><id></tt> is the plug-in or fragment identifier and <tt>
<version></tt> is the full version identifier contained in the
respective plugin.xml or fragment.xml. Note that this is a recommended
convention that minimizes chance of collisions, but is not required by
the Eclipse architecture. For example, the following are valid plug-in
archive names </p>
<p><tt>org.eclipse.platform_1.0.3.jar</tt> <br>
<tt>org.eclipse.ui.nl_2.0.jar</tt> <br>
<tt>my_plugin.jar</tt> </p>
<p>Internally, each plug-in archive packages all the relevant plug-in or
fragment files relative to its plug-in or fragment directory (but not including
the directory path element). The archive has the following structure </p>
<p><tt>plugin.xml *OR* fragment.xml</tt> <br>
<tt>other plug-in or feature files and subdirectories</tt> <br>
<tt>META-INF/</tt> <br>
<tt> Java jar manifest and security files</tt>
</p>
<h3> <a name="Packaging_NL"></a> Packaging NL</h3>
In Eclipse, translated plug-in information is packaged either
together with the base plug-in, or as a plug-in fragment. At runtime,
Eclipse locates the translations for the required locale. The use of
fragments allows translations to be added to the runtime without the need
to repackage the base plug-ins.
<p>This mechanism cannot be used for translating the actual packaging information
that is part of the installation xml files. Consequently the standard
Java translation conventions are used for the packaging information,
and all necessary translations must be available at the time the feature
is packaged. </p>
<h4> <a name="Translated_Feature_Information"></a> Translated Feature Information</h4>
<b>Note:</b> This section describes the conventions used for
translating the information contained within the feature manifest.
It allows for the update client to select the correctly localized strings
from the update server. This section specifically does not describe
localization of individual plug-ins.
<p>Several of the attributes within the feature manifest are strings intended
for display through user interfaces. To facilitate translation, these
attribute values use the convention defined for translatable attributes
of plugin.xml. Strings beginning with % up to the first space are treated
as resource identifier keys (without the %) and looked up in a properties
file. For example </p>
<p><tt>label="%cfg Tool Feature for Linux"</tt> </p>
<p>results in a resource lookup in the correct property file with key "cfg".
If no property files are supplied, or the key is not found the default
string value (following the %key) is used. </p>
<p>The property files are named as feature_<locale>.properties using
the Java resource bundle naming conventions. Within the feature archive
.jar they are placed in the same directory as their corresponding feature.xml
file. </p>
<p><b>Implementation Note</b>: When accessing the resource bundles the Eclipse
installation and update code should create a class loader for accessing
the translated string. This way, the standard locale lookup algorithm
implemented by Java is automatically used. </p>
<p><tt>ResourceBundle b;</tt> <br>
<tt>ClassLoader l;</tt> <br>
<tt>l = new URLClassLoader(new URL[] {<targetDirectoryURL>},
null);</tt> <br>
<tt>b = ResourceBundle.getBundle("feature",Locale.getDefault(),l);</tt>
</p>
<p>The resulting resource bundle can be used in <tt>IPluginDescriptor.getResourceString(String,ResourceBundle)</tt>
to actually return the correct translated string for the manifest attribute.
</p>
<h4> <a name="Translated_Plug-In_Information"></a> Translated Plug-In Information</h4>
No change from 1.0. Translated plug-in information should be
packaged as plug-in fragments.
<h3> <a name="Packaging_Target-Specific_Support"></a> Packaging Target-Specific
Support</h3>
No change from 1.0. Target-specific plug-in support (os, ws)
should be packaged as plug-in fragments.
<h3> <a name="Packaging_Attribution_Information"></a> Packaging Attribution
Information</h3>
This topic is covered in separate documents available on the
eclipse.org development resources page of the Update component.
<h3> <a name="Packaging_Non_Plug_In_Files"></a> Packaging Non-Plug-In Files</h3>
Arbitrary non-plug-in files can be included as part of the
feature definition using the <tt><data></tt> elements. Non-plug-in
files typically also requires specification of a custom install handler.
In general, the Eclipse support only downloads the referenced non-plug-in
files and calls the custom install handler to perform any actual installation
steps.
<p>Eclipse does not specify the format of the non-plug-in files. </p>
<h3> <a name="Custom_Install_Handling"></a> Custom Install Handling</h3>
Custom install handlers are written as a Java class and are
packaged as part of the <a href="#Feature_Archive">feature archive</a>
. The installer must implement the <tt>IInstallHandler</tt> interface
(in most cases will extend the <tt>BaseInstallHandler</tt> abstract helper
class which implements <tt>IInstallHandler</tt>). When required, the
install handler is dynamically loaded by the installation and update
code, and is called at specific points during its processing. The install
handler code has visibility to classes from the installation and update
support plug-in, and its prerequisite plug-ins.
<p><b>Implementation Note:</b> the detailed list of visible prerequisite
plug-ins is still evolving. It is expected to include <tt>org.eclipse.core.boot
</tt> and <tt>org.eclipse.core.runtime</tt> in all cases, plus <tt>org.eclipse.ui</tt>
and <tt>org.eclipse.swt</tt> when running with full workbench (ie.
not "headless mode"). Also, it would be useful to always expose <tt>org.eclipse.core.ant</tt>
so that build scripts can be used as part of the install handler implementation.
</p>
<p>The IInstallHandler interface supports the following methods [<b>Implementation
Note:</b> the detailed definition of the IInstallHandler interface
is still evolving. The description below is not an API specification
(simply a functional description)]: </p>
<ul>
<li> install-initiated - the install handler is called after
a feature was selected for installation, but before any files were
downloaded. It is intended to implement any custom click-through or
user registration dialogs. The base implementation of this method supplied
with the abstract class <tt>BaseInstallHandler </tt>performs
the default click-through processing using the license text supplied
as part of the feature manifest. On return this method indicates success
(installation continues) of failure (installation is aborted).</li>
<li> install-downloaded - the install handler is called after
all the required feature files were downloaded (feature, plugins,
data) but before the actual installation is performed. The install
handler is expected to perform verification of the non-plug-in data
files (eg. security), or any other pre-install processing. On
return this method indicates success (installation continues) or failure
(installation is aborted).</li>
<li> install-completion - the install handler is called after
the feature information and the plug-ins were installed. It is expected
to complete the installation of any non-plug-in data that was part of
the feature. On return this method indicates success (returns custom install
log) or failure (installation is aborted). On failure, the install handler
is expected to perform any required cleanup.</li>
<li> uninstall-initiated - the install handler is called when
a feature is selected for removal, but before any of the standard uninstall
processing has taken place. It is passed the custom install log created
by the install handler install-completion step.</li>
<li> uninstall-completion - the install handler is called
on completion of the standard uninstall steps. It is passed the custom
install log created by the install handler install-completion step.</li>
</ul>
Note, that as a general practice, install handlers should be
provided in their own jars (even though they could be just exposed
in the feature archive jar). The jar should be signed, and sealed.
<h3> <a name="Security_Considerations"></a> Security Considerations</h3>
The general approach is to use base Java jar signing for the
feature and plug-in archive .jars.
<p>Features are verified as follows: </p>
<ul>
<li> download and verify the feature archive (use base Java
jar verification)</li>
<li> for each plug-in archive</li>
<ul>
<li> verify the archive jar content (use base Java jar verification)</li>
<li> verify plug-in id and version from <tt><plugin></tt>
entry in feature manifest matches downloaded plugin.xml</li>
</ul>
<li> for each non-plugin file</li>
<ul>
<li> call install handler to verify file</li>
</ul>
</ul>
In general, when processing signed jars, the user will be prompted
for each unrecognized certificate. The response choices will include
aborting the installation (originator is not trusted), continuing the
installation (originator is trusted for this installation).
<h2> <a name="Update_Server"></a> Update Server</h2>
The default Eclipse update server is any URL-accessible server.
The default implementation assumes a fixed-layout server. The content
of the server (in terms of available features and plug-ins) is described
in a site map file, <i>site.xml</i>. This file can be manually maintained,
or can be dynamically computed by the server.
<h3> <a name="Site_Map"></a> Site Map</h3>
The update server URL can be specified as a full URL to the
site map file, or a URL of a directory path containing the site map
file (similar to index.html processing). The site map site.xml format
is defined by the following dtd:
<p><tt><?xml encoding="ISO-8859-1"?></tt> </p>
<p><tt><!ELEMENT site (description?, feature*, archive*, category-def*)></tt>
<br>
<tt><!ATTLIST site</tt> <br>
<tt> type
CDATA #IMPLIED</tt> <br>
<tt> url
CDATA #IMPLIED</tt> <br>
<tt>></tt> </p>
<p><tt><!ELEMENT description (#PCDATA)></tt> <br>
<tt><!ATTLIST description</tt> <br>
<tt> url
CDATA #IMPLIED</tt> <br>
<tt>></tt> </p>
<p><tt><!ELEMENT feature (category*)></tt> <br>
<tt><!ATTLIST feature</tt> <br>
<tt> type
CDATA #IMPLIED</tt> <br>
<tt> id
CDATA #IMPLIED</tt> <br>
<tt> version
CDATA #IMPLIED</tt> <br>
<tt> url
CDATA #REQUIRED<br>
label
CDATA #IMPLIED<br>
</tt><tt> os
CDATA #IMPLIED</tt> <br>
<tt> arch
CDATA #IMPLIED</tt> <br>
<tt> ws
CDATA #IMPLIED</tt> <br>
<tt> nl
CDATA #IMPLIED</tt><br>
<tt> patch </tt><tt>
(true | false) "false"</tt><br>
<tt> ></tt> </p>
<p><tt><!ELEMENT archive EMPTY></tt> <br>
<tt><!ATTLIST archive</tt> <br>
<tt> path
CDATA #REQUIRED</tt> <br>
<tt> url
CDATA #REQUIRED</tt> <br>
<tt>></tt> </p>
<p><tt><!ELEMENT category EMPTY></tt> <br>
<tt><!ATTLIST category</tt> <br>
<tt> name
CDATA #REQUIRED</tt> <br>
<tt>></tt> </p>
<p><tt><!ELEMENT category-def (description?)></tt> <br>
<tt><!ATTLIST category-def</tt> <br>
<tt> name
CDATA #REQUIRED</tt> <br>
<tt> label
CDATA #REQUIRED</tt> <br>
<tt>></tt> </p>
<p>The element and attribute definitions are as follows: </p>
<ul>
<li> <site> - defines the site map</li>
<ul>
<li> type - optional site type specification. The value refers
to a type string registered via the <a href="#Framework">install framework</a>
extension point. If not specified, the type is assumed to be the default
Eclipse site type (as specified in this document).</li>
<li> url - optional URL defining the update site baseline
URL (used to determine individual <feature> and <archive>
location). Can be relative or absolute. If relative, is relative
to site.xml. If not specified, the default is the URL location of the
site.xml file.</li>
</ul>
<li> <description> - brief description as simple text.
Intended to be translated.</li>
<ul>
<li> url - optional URL for the full description as HTML. The
URL can be specified as absolute of relative. If relative, If relative,
is relative to site.xml.</li>
<br>
Note, that for NL handling the URL value should be separated
to allow alternate URLs to be specified for each national language.
</ul>
<li> <feature> - identifies referenced feature archive</li>
<ul>
<li> type - optional feature type specification. The value
refers to a type string registered via the <a href="#Framework">install
framework</a> extension point. If not specified, the type is assumed
to be the default feature type for the site. If the site type is the
default Eclipse site type, the default feature type is the packaged
feature type (as specified in this document).</li>
<li> id - optional feature identifier. The information is
used as a performance optimization to speed up searches for features.
Must match the identifier specified in the feature.xml of the referenced
archive (the url attribute). If specified, the version attribute must
also be specified.</li>
<li> version - optional feature version. The information is
used as a performance optimization to speed up searches for features.
Must match the version specified in the feature.xml of the referenced
archive (the url attribute). If specified, the id attribute must also be
specified.</li>
<li> url - required URL reference to the feature archive.
Can be relative or absolute. If relative, it is relative to the location
of the site.xml file. <b>Note</b>: the default site implementation
allows features to be accessed without being explicitly declared using
a <feature> entry. By default, an undeclared features reference is
interpreted as "features/<id>_<version>.jar"</li>
<li>label - optional feature label. The value is used for
optimization when browsing the site from the update manager. Intended
to be translated.<br>
</li>
<li> os - optional operating system specification. A comma-separated
list of os designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt>
. Indicates this feature should only be installed on one of the specified
os systems. If this attribute is "*", the feature can be installed
on all systems (portable implementation). This information is used as
a hint by the installation and update support (user can force installation
of feature regardless of this setting).</li>
<li> arch - optional machine architecture specification. A
comma-separated list of architecture designators defined by Eclipse
(see Javadoc for <tt> org.eclipse.core.boot.BootLoader)</tt>. Indicates
this feature should only be installed on one of the specified systems.
If this attribute is "*", the feature can be installed on all systems
(portable implementation). This information is used as a hint by the
installation and update support (user can force installation of feature
regardless of this setting).</li>
<li> ws - optional windowing system specification. A comma-separated
list of ws designators defined by Eclipse (see Javadoc for <tt>org.eclipse.core.boot.BootLoader)</tt>
. Indicates this feature should only be installed on one of the specified
ws systems. If this attribute is "*", the feature can be installed
on all systems (portable implementation). This information is used
as a hint by the installation and update support (user can force installation
of feature regardless of this setting).</li>
<li> nl - optional locale specification. A comma-separated
list of locale designators defined by Java. Indicates this feature should
only be installed on a system running with a compatible locale (using
Java locale-matching rules). If this attribute is "*", the feature
can be installed on all systems (language-neutral implementation). This
information is used as a hint by the installation and update support (user
can force installation of feature regardless of this setting).</li>
<li>patch - optional specification indicating if this feature
is a patch. Default is "false". </li>
</ul>
<li> <archive> - identifies referenced "storage" archive
(the actual files referenced via the <tt><plugin></tt> or <tt><data></tt>
elements in the feature manifest). The site simply manages archives
as a path-to-URL map. The default Eclipse site implementation does not
require the <archive> section to be included in the site map (site.xml).
Any archive reference not explicitly defined as part of an <archive>
section is assumed to be mapped to a url in the form "<archivePath>"
relative to the location of the site.xml file.</li>
<ul>
<li> path - required archive path identifier. This is a string
that is determined by the <a
href="#Feature_Archive_Mapping_Id_To_Path">feature</a> referencing
this archive and is not otherwise interpreted by the site (other than
as a lookup token).</li>
<li> url - required URL reference to the archive. Can be relative
or absolute. If relative, it is relative to the location of the site.xml
file.</li>
</ul>
<li> <category-def> - an optional definition of a category
that can be used by installation and update support to hierarchicaly
organize features</li>
<ul>
<li> name - category name. Is specified as a path of name tokens
separated by /</li>
<li> label - displayable label. Intended to be translated.</li>
</ul>
<li> <category> - actual category specification for
a feature entry</li>
<ul>
name - category name
</ul>
</ul>
Note, that in general the feature.xml manifest documents
should specify UTF-8 encoding. For example
<p><tt><?xml version="1.0" encoding="UTF-8"?></tt> </p>
<p>Translatable text contained in the site.xml can be separated into site<_locale>.properties
files using Java property bundle conventions. Note that the translated
strings are used at installation time (ie. do not employ the plug-in
fragment runtime mechanism). The property bundles are located relative
to the site.xml location. </p>
<h3> <a name="Default_Site_Layout"></a> Default Site Layout</h3>
<tt><site root>/</tt> <br>
<tt> site.xml</tt> <br>
<tt> features/</tt> <br>
<tt> feature archives
(eg. org.eclipse.javatools_1.0.1.jar)</tt> <br>
<tt> <featureId>_<featureVersion>/
(optional)</tt> <br>
<tt>
non-plug-in files for feature</tt> <br>
<tt> plugins/</tt> <br>
<tt> plug-in argives
(eg. org.eclipse.ui_1.0.3.jar)</tt>
<h3> <a name="Controlling_Access"></a> Controlling Access</h3>
The default Eclipse site implementation provides support for
http access with basic user authentication (userid and password).
<p>Custom access control mechanisms can be added to base Eclipse in one of
2 ways: </p>
<ul>
<li> by supplying server-side logic on the update server (eg.
implementing servlets that compute the site.xml map, and control access
to individual archives based on some user criteria)</li>
<li> by supplying a custom concrete implementation of the
site object (installed on the client machine, update server specified
<tt><site type=""></tt> ). The custom concrete site implementation,
together with any server-side logic support the required control mechanisms.</li>
</ul>
Eclipse provides an example demonstrating an implementation
of an access mechanism based on feature key files.
<h2> <a name="Eclipse_Install"></a> Eclipse Install</h2>
<h3> <a name="Default_Install_Layout"></a> Default Install Layout</h3>
<tt><install root>/</tt> <br>
<tt> install/</tt> <br>
<tt> features/</tt>
<br>
<tt>
<featureId>_<version>/</tt> <br>
<tt>
feature.xml</tt> <br>
<tt>
other feature files</tt> <br>
<tt>
META-INF/</tt> <br>
<tt>
META-INF-ECLIPSE/</tt>
<p><tt> plugins/</tt> <br>
<tt> <pluginORfragmentId>_<version>/</tt>
<br>
<tt>
plugin.xml or fragment.xml</tt> <br>
<tt>
other plugin or fragment files</tt> <br>
<tt>
META_INF/</tt> </p>
<p><b>Implementation Note:</b> we will go back to the original design of
not splitting out fragments (ie. plugin and fragments go into the same install
location) </p>
<h3> <a name="Unmanaged_Plugins"></a> "Unmanaged" Plug-Ins</h3>
Eclipse supports a concept of "unmanaged" plug-ins. These are
plug-ins that were directly installed into the Eclipse file tree without
being part of a feature (eg. developer unzipping plug-in archive directly
into the Eclipse file tree).
<p>Eclipse runtime recognizes these plugins during startup and loads the
plug-in information into the runtime registry following the standard plug-in
binding rules. The update support also recognizes the presence of this new
plug-in, but since this plug-in is not part of any feature it cannot be updated
using the update support (hence "unmanaged"). Unmanaged plug-in that become
referenced by a feature as a result of some future installation or update
action become "managed" (can be updated as part of the feature). </p>
<p>Unmanaged plug-ins are not displayed as part of the installation and update
UI. </p>
<h3> <a name="Using_Native_Platform_Installers"></a> Using Native Platform
Installers</h3>
The Eclipse installation contains plugins that can be shared
across multiple features. When installing and uninstalling features
using the Eclipse installation and update support, these relationship
are correctly maintained. Only one copy of any version of a plug-in is
used.
<p>However, when using native platform installers, performing native uninstall
creates problems because plug-ins would be removed without regard
to any sharing relationships. As a result, Eclipse <b>does not allow</b>
plug-ins to be installed using native installers into the shared installation
tree. Instead, native installers must establish their own installation
root directory. The subdirectory structure is the same as defined for
base Eclipse. The private root directory is logically linked into the shared
Eclipse installation via a link file installed by the native installer.
The file path for the link file is <tt><configRoot>/links/</tt>.
The <tt><configRoot> </tt> location is computed by Eclipse relative
to the launch <a href="#Multiple%20Launch%20Points"> configuration file</a>
. By default, this is the <tt>install/</tt> directory in the shared
Eclipse installation tree. </p>
<p>The name of the link file is not specified by Eclipse. The name is determined
by the native installer. To minimize the potential for naming collisions,
it is recommended that the file name contain the identifier and version
of the feature being installed by the native installer. For example,
<tt><featureId>_<featureVersion>.properties</tt> . The file
content is in the form of a Java properties file, with the following
properties defined: </p>
<p><tt>path=[r|rw] install-path[,[r|rw] install-path]*</tt> </p>
<p>The property <tt>path</tt> is a comma-separated list of optionally annotated
install paths. The property value <tt>install-path</tt> is a full
file path to the installation directory root, specified in local OS
format. The optional annotation <tt>r</tt> or <tt>rw</tt> indicates whether
Eclipse update support should allow the specified location to be used
for updates. Default is to allow updates (w). </p>
<p>Eclipse does not manage the linked directories in any way. It simply detects
their existence by the presence of the link files, and includes the
linked plug-ins during the platform startup. The native installer is
responsible for uninstalling the link when the corresponding directory
is removed. Eclipse runtime ignores any links that cannot be resolved.
<br>
</p>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
</body>
</html>
| help@eclipse.org | ViewVC Help |
| Powered by ViewVC 1.0.3 |