platform-update-home/doc/eclipse_update_packaging.html

Revision 1.16 - (view) (download) (as text)

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

help@eclipse.org	ViewVC Help
Powered by ViewVC 1.0.3

Eclipse

platform-update-home/doc/eclipse_update_packaging.html