platform-update-home/doc/eclipse_update_packaging.html

Parent Directory | Revision Log | Patch

-revision 1.11, Thu Jan  2 14:05:51 2003 UTC
+revision 1.12, Thu Jan  2 14:10:27 2003 UTC
 Line 14
  <h1> Eclipse Platform<br>
      Update Packaging Conventions</h1>
-     <font size="-1">Revision Date: 12/09/2002 8:56AM - Version: 2.0.15</font><br>
+      <font size="-1">Revision Date: 01/02/2003 9:33AM - Version: 2.0.16</font><br>
     <a href="../../../../../hglegal.htm"><img src="ngibmcpy.gif"
   border="0" height="12" width="195">
     </a>
 Line 26
      <ul>
        <li><small>added &lt;site&gt;&lt;feature&gt; os,arch,nl,ws support
  "*"</small></li>
      </ul>
    </li>
    <li><small>2.0.15</small>
      <ul>
        <li><small>added &lt;site&gt;&lt;feature&gt; os,arch,nl,ws,patch tag</small></li>
      </ul>
                        </li>
     <li><small>2.0.14<br>
-Line 78
+Line 80
    <ul>
      <li> <font size="-1">&lt;site&gt; &lt;feature&gt; changes - additional
-  markup to optionally expose feature identification information to speed
+  markup to optionally expose feature identification information to speed up
- up  searches</font></li>
+  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
-Line 189
+Line 191
  <ul>
      <li> <b>extendable framework</b></li>
       <br>
-    In R2.0 Eclipse defines an extendable framework for installation and update,
+     In R2.0 Eclipse defines an extendable framework for installation and
-  allowing the support for alternate packaging and site management schemes.
+ update,   allowing the support for alternate packaging and site management
-  R2.0 supplies a default concrete implementation of this framework. <li>
+ schemes.   R2.0 supplies a default concrete implementation of this framework.
-    <b>  feature support</b></li>
+   <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
+ merged  into <i>feature</i>. Features define the packaging structure for a
- a group of related plug-ins, plug-in fragments, and optionally non-plug-in
+ group of related plug-ins, plug-in fragments, and optionally non-plug-in files.
- files. Features are treated purely as an installation and packaging construct.
+ Features are treated purely as an installation and packaging construct. They
- They do not play a role during Eclipse plug-in execution. Features do not
+ do not play a role during Eclipse plug-in execution. Features do not nest.
- nest. They are simply an inclusive "manifest" of the plug-ins, fragments
+ They are simply an inclusive "manifest" of the plug-ins, fragments and other
- and other files that make up that feature. If features are logically made
+ files that make up that feature. If features are logically made up of plug-ins
- up of plug-ins from "sub-features", the top-level feature "manifest" must
+ from "sub-features", the top-level feature "manifest" must be fully resolved
- be fully resolved at packaging time. <li> <b>default feature archive format</b></li>
+ 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
-Line 221
+Line 223
   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
+ the  built-in installation and update support. Some products may instead choose
- choose  to use native installer technology (eg. MSI, RPM, etc) to deliver
+  to use native installer technology (eg. MSI, RPM, etc) to deliver Eclipse
- Eclipse  features. However, native installers do not implement the required
+  features. However, native installers do not implement the required support
- support  for understanding the Eclipse installation structure. In particular,
+  for understanding the Eclipse installation structure. In particular, the
- the native uninstallers will, by default, remove plug-in files that were
+ native uninstallers will, by default, remove plug-in files that were installed
- installed using the native installer without regard to these plug-ins being
+ using the native installer without regard to these plug-ins being needed
- needed by other features. As a result, features installed using native installers
+ by other features. As a result, features installed using native installers
- must be written into private product-specific installation location and not
+  must be written into private product-specific installation location and
- the shared Eclipse installation location. The shared Eclipse is made aware
+ not  the shared Eclipse installation location. The shared Eclipse is made
- of the produce-specific location via an installed "link file". <li> <b>custom
+ aware  of the produce-specific location via an installed "link file". <li>
- install handling</b></li>
+     <b>custom  install handling</b></li>
-      <br>
+       <br>
-    In many cases the standard installation handling supplied by Eclipse is
+     In many cases the standard installation handling supplied by Eclipse
-  not be sufficient to handle various custom requirements. To accommodate
+ is  not be sufficient to handle various custom requirements. To accommodate
- this,  R2.0 Eclipse supports custom install handlers packaged as part of
+ this,  R2.0 Eclipse supports custom install handlers packaged as part of the
- the feature  and executed during the feature installation. <li> <b>path naming
+ 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
+     R1.0 mandated the use of the various identifiers and versions inside
-  packaged archives (eg. directory path names for plug-ins). This approach
+ 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
-Line 253
+Line 255
      <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.
+ not exposed to users that select function during installation or update. The
- The reason is that plug-in boundaries are established by developers for development
+ 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),
-Line 262
+Line 264
    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
+   from a .jar (requires an extra step to create the .jar and we all know developers
- developers  hate extra steps). Also, at this stage the developer does not
+  hate extra steps). Also, at this stage the developer does not pay particular
- pay particular  attention to plug-in versioning information, because the
+  attention to plug-in versioning information, because the plug-in is continually
- plug-in is continually  changing. </p>
+  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
-Line 278
+Line 280
     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
+  code.  At runtime, fragments are logically merged into the base plug-in.
- a packaging point of view, the install and update support does not really
+ 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
+  is used to deliver some user function. A feature can also include other features.
- features.  Features are exposed to users as part of the packaging and installation
+  Features are exposed to users as part of the packaging and installation
- process,  because they represent a unit of function selection. Features also
+  process,  because they represent a unit of function selection. Features
- represent  a unit of installation. Features carry a version identifier.</p>
+ 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
+   plug-in fragments and optional non-plug-in files. The feature archives
-  placed on an update server for download and installation by the Eclipse update
+ are   placed on an update server for download and installation by the Eclipse
-  manager, or they can be used as the input into a formal packaging process
+ update  manager, or they can be used as the input into a formal packaging
-  using one of the "traditional" installer technologies. The format of the
+ process  using one of the "traditional" installer technologies. The format
- feature archive is described later. </p>
+ 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
-Line 314
+Line 316
   perform other custom processing allowed by the framework.</li>
  </ul>
-     Eclipse provides default implementations of feature and site. These are
+      Eclipse provides default implementations of feature and site. These
-  described in the rest of this document. <br>
+ are  described in the rest of this document. <br>
     &nbsp;
  <table border="1" cols="1" width="100%">
      <tbody>
         <tr>
-     <td><b>Note: <i>The reminder of this document describes the default concrete
+      <td><b>Note: <i>The reminder of this document describes the default
-   implementation of the framework delivered with Eclipse. It specifies the
+ concrete   implementation of the framework delivered with Eclipse. It specifies
-  structure of the default feature implementation, as well as the default
+ 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&nbsp; parts or
   all of the default Eclipse implementation. This includes providing a mechanism
-Line 384
+Line 386
  <p><tt>&lt;?xml encoding="ISO-8859-1"?&gt;</tt> </p>
- <p><tt>&lt;!ELEMENT feature (install-handler?, description?, copyright?,
+ <p><tt>&lt;!ELEMENT feature (install-handler?, description?, copyright?, license?,
- license?, url?, includes*, requires?, plugin*, data*)&gt;</tt> <br>
+ url?, includes*, requires?, plugin*, data*)&gt;</tt> <br>
     <tt>&lt;!ATTLIST feature</tt> <br>
     <tt>&nbsp;&nbsp;&nbsp; id&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
    CDATA #REQUIRED</tt> <br>
-Line 543
+Line 545
   . 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
+ hint by the installation and update support (user can force installation of
- of feature regardless of this setting).</li>
+ 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,
+   be installed on one of the specified systems. If this attribute is not
-  the feature can be installed on all systems (portable implementation). This
+ specified,   the feature can be installed on all systems (portable implementation).
-  information is used as a hint by the installation and update support (user
+ This   information is used as a hint by the installation and update support
-  can force installation of feature regardless of this setting).</li>
+ (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
+ hint by the installation and update support (user can force installation of
- of feature regardless of this setting).</li>
+ feature regardless of this setting).</li>
-      <li> nl - optional locale specification. A comma-separated list of locale
+       <li> nl - optional locale specification. A comma-separated list of
-  designators defined by Java. Indicates this feature should only be installed
+ locale   designators defined by Java. Indicates this feature should only
-  on a system running with a compatible locale (using Java locale-matching
+ 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
+  rules). If this attribute is not specified, the feature can be installed
- all systems (language-neutral implementation). This information is used as
+ on all systems (language-neutral implementation). This information is used
- 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
  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
+       <li> primary - optional indication specifying whether this feature
-  be used as a <a href="#Dominant_Feature">primary feature</a> . Default if
+ can   be used as a <a href="#Dominant_Feature">primary feature</a> . Default
-        <i>false</i> (not a primary feature).</li>
+ 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
-Line 584
+Line 586
       <li> &lt;install-handler&gt;</li>
    <ul>
-     <li> library - optional .jar library containing the install handler classes.
+      <li> library - optional .jar library containing the install handler
-   If specified, the referenced .jar must be contained in the feature archive.
+ classes.   If specified, the referenced .jar must be contained in the feature
-   It is specified as a path within the feature archive, relative to the feature.xml
+ archive.   It is specified as a path within the feature archive, relative
-   entry. If not specified, the feature archive itself is used to load the
+ to the feature.xml   entry. If not specified, the feature archive itself
- install handler classes. This attribute is only interpreted if <i>class</i>
+ is used to load the install handler classes. This attribute is only interpreted
- attribute is also specified</li>
+ 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
+  is  interpreted depending on the value of the <i>library</i> attribute.
-       <i>  library</i> is specified,&nbsp; the value is interpreted as a fully
+ If        <i>  library</i> is specified,&nbsp; the value is interpreted as
- qualified  name of a class contained in the specified <i>library</i>. If
+ a fully qualified  name of a class contained in the specified <i>library</i>.
-       <i>library</i>   is not specified, the value is is interpreted as an
+ If       <i>library</i>   is not specified, the value is is interpreted as
- extension identifier  of an extension registered in the <i>org.eclipse.update.installHandlers</i>
+ 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
+ and called at specific points during feature processing. The handler has visibility
- visibility to the API classes from the update plug-in, and Eclipse plug-ins
+ to the API classes from the update plug-in, and Eclipse plug-ins required
- required by the update plugin.</li>
+ by the update plugin.</li>
    </ul>
       <li> &lt;description&gt; - brief component description as simple text.
-Line 608
+Line 610
    <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
+  be  specified as absolute of relative. If relative, it is assumed to be
-  to (and packaged in) the feature archive. Note, that for NL handling the
+ relative   to (and packaged in) the feature archive. Note, that for NL handling
- URL value should be separated to allow alternate URLs to be specified for
+ the  URL value should be separated to allow alternate URLs to be specified
- each national language.</li>
+ for  each national language.</li>
    </ul>
       <li> &lt;copyright&gt; - feature copyright as simple text. Intended
-Line 619
+Line 621
    <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
+  be  specified as absolute of relative. If relative, it is assumed to be
-  to (and packaged in) the feature archive. Note, that for NL handling the
+ relative   to (and packaged in) the feature archive. Note, that for NL handling
- URL value should be separated to allow alternate URLs to be specified for
+ the  URL value should be separated to allow alternate URLs to be specified
- each national language.</li>
+ for  each national language.</li>
    </ul>
       <li> &lt;license&gt; - 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
+   [Reject] actions during the download/ installation process. Note, that
-   license must be specified for any feature that will be selected for installation
+ click-through   license must be specified for any feature that will be selected
-   or update using the Eclipse update manager. When using nested features,
+ for installation   or update using the Eclipse update manager. When using
- only the nesting parent (ie. the feature selected for installation or update)
+ nested features, only the nesting parent (ie. the feature selected for installation
- must have click-through license text defined. The license text is required
+ or update) must have click-through license text defined. The license text
- even if the optional <i>url</i> attribute is specified.</li>
+ 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
+  be  specified as absolute of relative. If relative, it is assumed to be
-  to (and packaged in) the feature archive. Note, that for NL handling the
+ relative   to (and packaged in) the feature archive. Note, that for NL handling
- URL value should be separated to allow alternate URLs to be specified for
+ the  URL value should be separated to allow alternate URLs to be specified
- each national language. Note, that the "content" of this URL is <b>not</b>
+ 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>&lt;license&gt;</i>
    element (eg. <tt>&lt;license&gt;click through text&lt;/license&gt;</tt>)</li>
    </ul>
-      <li> &lt;url&gt; - optional URL specifying site(s) contain feature updates,
+       <li> &lt;url&gt; - optional URL specifying site(s) contain feature
-  or new features</li>
+ updates,   or new features</li>
    <ul>
      <li> &lt;update&gt; - URL to go to for updates to this feature</li>
-Line 684
+Line 686
   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
+         <samp>compatible</samp> also allows minor part to be included in
-  consideration, while <samp>greaterOrEqual</samp> simply allows any version
+ the   consideration, while <samp>greaterOrEqual</samp> simply allows any
-  that is more recent or identical to the one specified).</li>
+ version   that is more recent or identical to the one specified).</li>
-        <li>search_location&nbsp; - optional. Indicates whether the "New Updates"
+         <li>search_location&nbsp; - optional. Indicates whether the "New
-  action should search the update location determined by the nesting root feature
+ Updates"   action should search the update location determined by the nesting
-  (<tt>root</tt>, is the default), or the location defined by the nested feature
+ root feature  (<tt>root</tt>, is the default), or the location defined by
-  (<tt>self</tt>), or search both (<tt>both</tt>) in that order (root first,
+ the nested feature  (<tt>self</tt>), or search both (<tt>both</tt>) in that
-  self if nothing is found).</li>
+ order (root first,  self if nothing is found).</li>
    </ul>
       <li> &lt;requires&gt; - optional feature dependency information. Is
-Line 705
+Line 707
      <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
+   are specified, plugin takes precedence upon feature. Feature or plugin
-  be specified.</li>
+ 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
+  a  patch of the dependant feature. Default is "false". If patch is true,
-  must be specified. If patch is true, only feature must be specified. If
+ version  must be specified. If patch is true, only feature must be specified.
- patch  is true, and match is specified, it must be 'perfect'.<br>
+ 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)
+      <li> if version attribute is not specified, the match attribute (if
-   is ignored.</li>
+ 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
-Line 727
+Line 729
       <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
+  least  at the version specified, or at a higher service level (major and
- version  levels must equal the specified version).</li>
+ 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
+       <li> <b><i>greaterOrEqual</i></b> - dependent plug-in version must
-  at least at the version specified, or at a higher service, minor or major
+ be  at least at the version specified, or at a higher service, minor or major
   level.</li>
        </ul>
-Line 746
+Line 748
    <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
+       <li> fragment - optional specification indicating if this entry is
- plug-in  fragment. Default is "false"</li>
+ 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
+   . Indicates this entry should only be installed on one of the specified
-  systems. If this attribute is not specified, the entry can be installed
+ os  systems. If this attribute is not specified, the entry can be installed
-  on all systems (portable implementation). This information is used as a
+  on all systems (portable implementation). This information is used as a hint
- hint  by the installation and update support (user can force installation
+  by the installation and update support (user can force installation of entry
- of entry  regardless of this setting).</li>
+  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,
+   be installed on one of the specified systems. If this attribute is not
-  the feature can be installed on all systems (portable implementation). This
+ specified,   the feature can be installed on all systems (portable implementation).
-  information is used as a hint by the installation and update support (user
+ This   information is used as a hint by the installation and update support
-  can force installation of feature regardless of this setting).</li>
+ (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
+   . Indicates this entry should only be installed on one of the specified
-  systems. If this attribute is not specified, the entry can be installed
+ ws  systems. If this attribute is not specified, the entry can be installed
-  on all systems (portable implementation). This information is used as a
+  on all systems (portable implementation). This information is used as a hint
- hint  by the installation and update support (user can force installation
+  by the installation and update support (user can force installation of entry
- of entry  regardless of this setting).</li>
+  regardless of this setting).</li>
-      <li> nl - optional locale specification. A comma-separated list of locale
+       <li> nl - optional locale specification. A comma-separated list of
-  designators defined by Java. Indicates this entry should only be installed
+ locale   designators defined by Java. Indicates this entry should only be
-  on a system running with a compatible locale (using Java locale-matching
+ 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
+  all systems (language-neutral implementation). This information is used
- 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
  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.
-Line 786
+Line 788
  the implementation   needs to distinguish between "not known" and 0 size)</li>
    </ul>
-      <li> &lt;data&gt; - identifies non-plugin data that is part of the feature</li>
+       <li> &lt;data&gt; - identifies non-plugin data that is part of the
+ feature</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
+   . Indicates this entry should only be installed on one of the specified
-  systems. If this attribute is not specified, the entry can be installed
+ os  systems. If this attribute is not specified, the entry can be installed
-  on all systems (portable implementation). This information is used as a
+  on all systems (portable implementation). This information is used as a hint
- hint  by the installation and update support (user can force installation
+  by the installation and update support (user can force installation of entry
- of entry  regardless of this setting).</li>
+  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,
+   be installed on one of the specified systems. If this attribute is not
-  the feature can be installed on all systems (portable implementation). This
+ specified,   the feature can be installed on all systems (portable implementation).
-  information is used as a hint by the installation and update support (user
+ This   information is used as a hint by the installation and update support
-  can force installation of feature regardless of this setting).</li>
+ (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
+   . Indicates this entry should only be installed on one of the specified
-  systems. If this attribute is not specified, the entry can be installed
+ ws  systems. If this attribute is not specified, the entry can be installed
-  on all systems (portable implementation). This information is used as a
+  on all systems (portable implementation). This information is used as a hint
- hint  by the installation and update support (user can force installation
+  by the installation and update support (user can force installation of entry
- of entry  regardless of this setting).</li>
+  regardless of this setting).</li>
-      <li> nl - optional locale specification. A comma-separated list of locale
+       <li> nl - optional locale specification. A comma-separated list of
-  designators defined by Java. Indicates this entry should only be installed
+ locale   designators defined by Java. Indicates this entry should only be
-  on a system running with a compatible locale (using Java locale-matching
+ 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
+  all systems (language-neutral implementation). This information is used
- 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
  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
+  indicating  the download size in KBytes of the referenced data archive.
- 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>
  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
-Line 837
+Line 840
   implementation supplied by Eclipse constructs the path identifiers as follows:
  <ul>
-     <li> <tt>&lt;plugin&gt;</tt> element results in a path entry in the form
+      <li> <tt>&lt;plugin&gt;</tt> element results in a path entry in the
-  "<tt>plugins/&lt;pluginId&gt;_&lt;pluginVersion&gt;.jar</tt>" (for example,
+ form   "<tt>plugins/&lt;pluginId&gt;_&lt;pluginVersion&gt;.jar</tt>" (for
-  "<tt>plugins/org.eclipse.core.boot_1.0.3.jar</tt>")</li>
+ example,   "<tt>plugins/org.eclipse.core.boot_1.0.3.jar</tt>")</li>
       <li> <tt>&lt;data&gt;</tt> element results in a path entry in the form
   "<tt>features/&lt;featureId&gt;_&lt;featureVersion&gt;/&lt;dataId&gt;</tt>
   " (for example, "f<tt>eatures/com.xyz.tools_2.3.1/examples.zip</tt>")</li>
-Line 850
+Line 853
  <p><tt>&lt;?xml version="1.0" encoding="UTF-8"?&gt;</tt> </p>
  <p>Translatable text contained in the feature.xml can be separated into feature&lt;_locale&gt;.properties
-  files using Java property bundle conventions. Note that the translated strings
+   files using Java property bundle conventions. Note that the translated
-  are used at installation time (ie. do not employ the plug-in fragment runtime
+ strings   are used at installation time (ie. do not employ the plug-in fragment
-  mechanism). </p>
+ 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
-Line 864
+Line 867
  <p>Where <tt>&lt;id&gt;</tt> is the plug-in or fragment identifier and <tt>
   &lt;version&gt;</tt> is the full version identifier contained in the respective
-  plugin.xml or fragment.xml. Note that this is a recommended convention that
+   plugin.xml or fragment.xml. Note that this is a recommended convention
-  minimizes chance of collisions, but is not required by the Eclipse architecture.
+ that   minimizes chance of collisions, but is not required by the Eclipse
-   For example, the following are valid plug-in archive names </p>
+ 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
+ <p>Internally, each plug-in archive packages all the relevant plug-in or fragment
- fragment files relative to its plug-in or fragment directory (but not including
+ files relative to its plug-in or fragment directory (but not including the
- the directory path element). The archive has the following structure </p>
+ 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>
-Line 896
+Line 900
  <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
+  update client to select the correctly localized strings from the update server.
- server.  This section specifically does not describe localization of individual
+  This section specifically does not describe localization of individual plug-ins.
- 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
+   Strings beginning with % up to the first space are treated as resource identifier
- identifier  keys (without the %) and looked up in a properties file. For
+  keys (without the %) and looked up in a properties file. For example </p>
- 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
+   If no property files are supplied, or the key is not found the default string
- string  value (following the %key) is used. </p>
+  value (following the %key) is used. </p>
  <p>The property files are named as feature_&lt;locale&gt;.properties using
    the Java resource bundle naming conventions. Within the feature archive
-Line 918
+Line 921
  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
+   installation and update code should create a class loader for accessing
-  translated string. This way, the standard locale lookup algorithm implemented
+ the  translated string. This way, the standard locale lookup algorithm implemented
    by Java is automatically used. </p>
  <p><tt>ResourceBundle b;</tt> <br>
-Line 938
+Line 941
  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
+      No change from 1.0. Target-specific plug-in support (os, ws) should
-  packaged as plug-in fragments.
+ 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
-Line 962
+Line 965
   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
+ <p><b>Implementation Note:</b> the detailed list of visible prerequisite plug-ins
- plug-ins is still evolving. It is expected to include <tt>org.eclipse.core.boot
+ is still evolving. It is expected to include <tt>org.eclipse.core.boot </tt>
- </tt> and <tt>org.eclipse.core.runtime</tt> in all cases, plus <tt>org.eclipse.ui</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
+    and <tt>org.eclipse.swt</tt> when running with full workbench (ie. not
-  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>
    so that build scripts can be used as part of the install handler implementation.
    </p>
-Line 977
+Line 980
  <ul>
      <li> install-initiated - the install handler is called after a feature
-  was selected for installation, but before any files were downloaded. It
+  was selected for installation, but before any files were downloaded. It is
- is  intended  to implement any custom click-through or user registration
+  intended  to implement any custom click-through or user registration dialogs.
- dialogs.  The base implementation of this method supplied with the abstract
+  The base implementation of this method supplied with the abstract class
- class <tt>BaseInstallHandler       </tt>performs the default click-through
+     <tt>BaseInstallHandler       </tt>performs the default click-through processing
- processing using the license  text supplied as part of the feature manifest.
+ using the license  text supplied as part of the feature manifest. On return
- On return this method indicates  success (installation continues) of failure
+ this method indicates  success (installation continues) of failure (installation
- (installation is aborted).</li>
+ 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
-Line 991
+Line 994
   other pre-install processing.&nbsp; 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
+   information and the plug-ins were installed. It is expected to complete
-  installation of any non-plug-in data that was part of the feature. On return
+ the  installation of any non-plug-in data that was part of the feature. On
-  this method indicates success (returns custom install log) or failure (installation
+ return  this method indicates success (returns custom install log) or failure
-  is aborted). On failure, the install handler is expected to perform any
+ (installation  is aborted). On failure, the install handler is expected to
- required cleanup.</li>
+ 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
-Line 1036
+Line 1039
   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
+      The default Eclipse update server is any URL-accessible server. The
-   implementation assumes a fixed-layout server. The content of the server
+ default   implementation assumes a fixed-layout server. The content of the
- (in terms of available features and plug-ins) is described in a site map
+ server (in terms of available features and plug-ins) is described in a site
- file, <i>site.xml</i>. This file can be manually maintained, or can be dynamically
+ map file, <i>site.xml</i>. This file can be manually maintained, or can be
-  computed by the server.
+ 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
-Line 1114
+Line 1117
      <li> &lt;site&gt; - defines the site map</li>
    <ul>
-     <li> type - optional site type specification. The value refers to a type
+      <li> type - optional site type specification. The value refers to a
-  string registered via the <a href="#Framework">install framework</a>  extension
+ type   string registered via the <a href="#Framework">install framework</a>
-  point. If not specified, the type is assumed to be the default Eclipse site
+  extension  point. If not specified, the type is assumed to be the default
-  type (as specified in this document).</li>
+ Eclipse site  type (as specified in this document).</li>
       <li> url - optional URL defining the update site baseline URL (used
  to  determine individual &lt;feature&gt; and &lt;archive&gt; location).&nbsp;
   Can be relative or absolute. If relative, is relative to site.xml. If not
-Line 1141
+Line 1144
      <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,
+   feature type for the site. If the site type is the default Eclipse site
-  the default feature type is the packaged feature type (as specified in this
+ type,  the default feature type is the packaged feature type (as specified
-  document).</li>
+ 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
+ performance   optimization to speed up searches for features. Must match the
- the identifier   specified in the feature.xml of the referenced archive (the
+ identifier   specified in the feature.xml of the referenced archive (the url
- url attribute).   If specified, the version attribute must also be specified.</li>
+ 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
+ the  version specified in the feature.xml of the referenced archive (the url
- url attribute).  If specified, the id attribute must also be specified.</li>
+ 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
+  file.       <b>Note</b>: the default site implementation allows features
- be accessed without being explicitly declared using a &lt;feature&gt; entry.
+ to be accessed without being explicitly declared using a &lt;feature&gt;
- By default, an undeclared features reference is interpreted as "features/&lt;id&gt;_&lt;version&gt;.jar"</li>
+ entry. By default, an undeclared features reference is interpreted as "features/&lt;id&gt;_&lt;version&gt;.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>
-Line 1179
+Line 1182
   . Indicates this feature should only be installed on one of the specified
    ws systems. If this attribute&nbsp;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&nbsp;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> 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&nbsp;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".&nbsp;</li>
    </ul>
       <li> &lt;archive&gt; - identifies referenced "storage" archive (the
  actual  files referenced via the <tt>&lt;plugin&gt;</tt> or <tt>&lt;data&gt;</tt>
-   elements in the feature manifest). The site simply manages archives as a
+    elements in the feature manifest). The site simply manages archives as
-  path-to-URL map. The default Eclipse site implementation does not require
+ a  path-to-URL map. The default Eclipse site implementation does not require
-  the &lt;archive&gt; section to be included in the site map (site.xml). Any
+   the &lt;archive&gt; section to be included in the site map (site.xml).
-  archive reference not explicitly defined as part of an &lt;archive&gt; section
+ Any   archive reference not explicitly defined as part of an &lt;archive&gt;
-  is assumed to be mapped to a url in the form "&lt;archivePath&gt;" relative
+ section   is assumed to be mapped to a url in the form "&lt;archivePath&gt;"
-  to the location of the site.xml file.</li>
+ relative   to the location of the site.xml file.</li>
    <ul>
-     <li> path - required archive path identifier. This is a string that is
+      <li> path - required archive path identifier. This is a string that
-  determined  by the <a href="#Feature_Archive_Mapping_Id_To_Path">feature</a>
+ 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
+    referencing this archive and is not otherwise interpreted by the site
-  than as a lookup token).</li>
+ (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>
-Line 1233
+Line 1236
  <p><tt>&lt;?xml version="1.0" encoding="UTF-8"?&gt;</tt> </p>
  <p>Translatable text contained in the site.xml can be separated into site&lt;_locale&gt;.properties
-   files using Java property bundle conventions. Note that the translated
+   files using Java property bundle conventions. Note that the translated strings
- strings  are used at installation time (ie. do not employ the plug-in fragment
+  are used at installation time (ie. do not employ the plug-in fragment runtime
- runtime  mechanism). The property bundles are located relative to the site.xml
+  mechanism). The property bundles are located relative to the site.xml location.
- location.   </p>
+   </p>
  <h3> <a name="Default_Site_Layout"></a> Default Site Layout</h3>
      <tt>&lt;site root&gt;/</tt> <br>
-Line 1262
+Line 1265
   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>&lt;site
+  (installed  on the client machine, update server specified <tt>&lt;site type=""&gt;</tt>
- type=""&gt;</tt>  ). The custom concrete site implementation, together with
+  ). The custom concrete site implementation, together with any server-side
- any server-side   logic support the required control mechanisms.</li>
+   logic support the required control mechanisms.</li>
  </ul>
      Eclipse provides an example demonstrating an implementation of an access
-Line 1295
+Line 1298
     <tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  META_INF/</tt>   </p>
- <p><b>Implementation Note:</b> we will go back to the original design of
+ <p><b>Implementation Note:</b> we will go back to the original design of not
- not splitting out fragments (ie. plugin and fragments go into the same install
+ 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
+  of a feature (eg. developer unzipping plug-in archive directly into the Eclipse
- Eclipse  file tree).
+  file tree).
- <p>Eclipse runtime recognizes these plugins during startup and loads the
+ <p>Eclipse runtime recognizes these plugins during startup and loads the plug-in
- plug-in information into the runtime registry following the standard plug-in
+ information into the runtime registry following the standard plug-in binding
- binding rules. The update support also recognizes the presence of this new
+ rules. The update support also recognizes the presence of this new plug-in,
- plug-in, but since this plug-in is not part of any feature it cannot be updated
+ but since this plug-in is not part of any feature it cannot be updated using
- using the update support (hence "unmanaged"). Unmanaged plug-in that become
+ the update support (hence "unmanaged"). Unmanaged plug-in that become referenced
- referenced by a feature as a result of some future installation or update
+ by a feature as a result of some future installation or update action become
- action become "managed" (can be updated as part of the feature). </p>
+ "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
+      The Eclipse installation contains plugins that can be shared across
-   features. When installing and uninstalling features using the Eclipse installation
+ multiple   features. When installing and uninstalling features using the
-   and update support, these relationship are correctly maintained. Only one
+ Eclipse installation   and update support, these relationship are correctly
-   copy of any version of a plug-in is used.
+ 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
+  The subdirectory structure is the same as defined for base Eclipse. The private
- private  root directory is logically linked into the shared Eclipse installation
+  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>&lt;configRoot&gt;/links/</tt>. The <tt>&lt;configRoot&gt;
  </tt>  location is computed by Eclipse relative to the launch <a
-Line 1345
+Line 1348
  <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
+   install paths. The property value <tt>install-path</tt> is a full file path
- path  to the installation directory root, specified in local OS format. The
+  to the installation directory root, specified in local OS format. The optional
- optional  annotation <tt>r</tt> or <tt>rw</tt> indicates whether Eclipse
+  annotation <tt>r</tt> or <tt>rw</tt> indicates whether Eclipse update support
- update support  should allow the specified location to be used for updates.
+  should allow the specified location to be used for updates. Default is to
- Default is to  allow updates&nbsp; (w). </p>
+  allow updates&nbsp; (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
+   for uninstalling the link when the corresponding directory is removed.
-  runtime ignores any links that cannot be resolved. <br>
+ Eclipse   runtime ignores any links that cannot be resolved. <br>
     &nbsp; </p>
     <br>
    <br>
   <br>
+  <br>
  </body>
  </html>

 Legend:



Removed from v.1.11
 


changed lines


 
Added in v.1.12
 Legend:



Removed from v.1.11
 


changed lines


 
Added in v.1.12
-Removed from v.1.11
+Added in v.1.12

help@eclipse.org	ViewVC Help
Powered by ViewVC 1.0.3