platform-update-home/doc/products-and-extension.html

Parent Directory Parent Directory | Revision Log Revision Log

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

1 : droberts 1.4 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2 : vlad 1.1 <html>
3 :     <head>
4 : celek 1.5
5 :     <meta http-equiv="Content-Language" content="en-us">
6 :    
7 :     <meta http-equiv="Content-Type"
8 :     content="text/html; charset=windows-1252">
9 :    
10 :     <meta name="GENERATOR" content="Microsoft FrontPage 4.0">
11 :    
12 :     <meta name="ProgId" content="FrontPage.Editor.Document">
13 :     <title>Eclipse-based Products and Extensions</title>
14 : vlad 1.1 </head>
15 : celek 1.5 <body>
16 :    
17 : vlad 1.1 <h1> Eclipse-based Products and Extensions</h1>
18 : celek 1.5
19 :     <p>Last modified 16:00 Friday December 06, 2002<br>
20 :     </p>
21 :     <p><b>Change History:</b> </p>
22 :    
23 :     <ul>
24 :     <li><small>2.0.1</small><small><br>
25 :     </small>
26 :     <ul>
27 :     <li><small>added: <big><code>feature.default.plugin.id</code></big></small></li>
28 :     </ul>
29 :     </li>
30 :     </ul>
31 :    
32 :     <p>Eclipse technology is the foundation of, and provides building blocks
33 :     for, products aimed at the software development tools market. Commercial
34 :     software vendors are expected to build, brand, and package products using
35 :     the Eclipse platform as the nucleus, to sell these products into the development
36 :     tools marketplace, and to support them once in the field.</p>
37 :    
38 :     <p>The Eclipse platform itself is not a "product" in any of these senses.
39 :     Eclipse is an open source project that provides raw ingredients without box,
40 :     label, or price tag. The closest that the Eclipse project gets to a packaged
41 :     form is the Eclipse SDK, which can be downloaded from <a
42 :     href="http://www.eclipse.org">eclipse.org</a>, installed, and used as a
43 :     full-service Java IDE which also happens to include special support for developing
44 :     Eclipse plug-ins (PDE).</p>
45 :    
46 :     <p>This note describes how the Eclipse platform is designed to be turned
47 :     into products. The license governing the Eclipse platform gives a software
48 :     vendor almost complete freedom over how to built a product. So anyone building
49 :     a product is free to ignore this advice. However, as is often the case with
50 :     standards, adhering to the same rules as everyone else has its rewards: it
51 :     fosters greater interoperability between products, and makes it easier for
52 :     the end user because different products behave in similar ways.</p>
53 :    
54 :     <p>Eclipse plug-ins are intended to packaged and delivered to the customer
55 :     into one of two forms: either as self-contained Eclipse-based products, or
56 :     as add-on extensions to Eclipse-based products. We'll first explain what
57 :     we mean by Eclipse-based product since it is the more basic notion.</p>
58 :    
59 : vlad 1.1 <h2>Eclipse-based products</h2>
60 : celek 1.5
61 :     <p>An Eclipse-based <b>product</b> is a stand-alone program build with Eclipse.
62 :     Products are self-contained in that all code and plug-ins needed to get up
63 :     and running are included; this includes a Java runtime environment (JRE),
64 :     and the code for the Eclipse platform itself. After installing a product
65 :     on a computer with a conventional native installer, the user launches the
66 :     product (via its product executable) and is presented with an Eclipse workbench
67 :     configured appropriately for the purposes that product was designed to support
68 :     (be it developing enterprise web servers, developing C++ programs, or developing
69 :     whatever). Products are intended to be updated, either with a conventional
70 :     native installer, or with the build-in Eclipse update manager, which is always
71 :     available to the user from the Eclipse workbench ("Update Manager" on the
72 :     "Help" menu).</p>
73 :    
74 :     <p>If we looked more closely at how the Eclipse parts of the product are organized,
75 :     we would see that all plug-ins that go into a product are grouped into <b>features</b>.
76 :     "Feature" is an Eclipse update manager notion: a feature is the smallest
77 :     unit of separately downloadable and installable functionality. Features also
78 :     play a secondary role in how the Eclipse platform runs.</p>
79 :    
80 :     <p>To make things a bit more concrete, the top level structure of an installed
81 :     Eclipse-based product looks like this (italics indicate product-specific
82 :     file names): </p>
83 :    
84 : vlad 1.1 <p><code>&lt;<i>install</i>&gt;/<br>
85 : celek 1.5   <i>acmeproduct</i>.exe      </code>product executable<code><br>
86 :       eclipse/             </code>container for installed Eclipse files<code><br>
87 :         .eclipseproduct        </code>marker for Eclipse product install<code><br>
88 :         eclipse.exe            </code>Eclipse executable launcher<code><br>
89 :         startup.jar            </code>Eclipse Java launcher<code><br>
90 :         install.ini            </code>install info<code><br>
91 :         .config/               </code>install info (computed at install time
92 :     with -initialize option)<code><br>
93 :            platform.cfg           </code>default platform configuration<code><br>
94 :         jre/                   </code>Java runtime environment (JRE)<code><br>
95 :         features/                               </code>installed feature versions<code><br>
96 :           <i>com.example.acme.acmefeature</i>_<i>1.0.0</i>/        </code>primary
97 :     feature for product<code><br>
98 :             feature.xml                                </code>feature manifest
99 :     file<code><br>
100 :           org.eclipse.platform_2.0.0/                </code>feature for Eclipse
101 :     platform<code><br>
102 :           org.eclipse.platform.win32_2.0.0/          </code>feature for Eclipse
103 :     platform<code><br>
104 :         plugins/                                </code>installed plug-ins and
105 :     fragment versions<code><br>
106 :     </code> <code>     <i>com.example.acme.acmefeature</i>_<i>1.0.0</i>/        
107 : vlad 1.1 </code>product-specific plug-in<code><br>
108 : celek 1.5         plugin.xml                                  </code>plug-in manifest
109 :     file<code><br>
110 :             about.ini                                   </code>about info for
111 :     product<code><br>
112 :             <i>acme</i>.gif                                    </code>window
113 :     icon for product<code><br>
114 :             plugin_customization.ini                    </code>about info for
115 :     product<code><br>
116 :             splash.png                                  </code>product splash
117 :     screen<code><br>
118 :     </code>  <code>     <i>com.example.acme.myplugin</i>_<i>1.0.0</i>/          
119 : vlad 1.1 </code>product-specific plug-in <code><br>
120 : celek 1.5         plugin.xml                                  </code>plug-in manifest
121 :     file <code><br>
122 :             <i>myplugin</i>.jar                                </code>code for
123 :     product-specific plug-in<code><br>
124 :           org.eclipse.platform_2.0.0/                </code>Eclipse platform
125 :     plug-in<code><br>
126 :           org.eclipse.platform.win32_2.0.0/          </code>Eclipse platform
127 :     plug-in<code><br>
128 :           org.eclipse.core.boot_2.0.0/               </code>Eclipse platform
129 :     plug-in<code><br>
130 :           org.eclipse.core.runtime_2.0.0/            </code>Eclipse platform
131 :     plug-in<code><br>
132 :           org.eclipse.core.resources_2.0.0/          </code>Eclipse platform
133 :     plug-in<code><br>
134 :           org.eclipse.ui_2.0.0/                      </code>Eclipse platform
135 :     plug-in<code><br>
136 :           (more org.eclipse.* plug-in directories)<br>
137 :         links/                                   </code>links to extensions
138 :     (see next section)<code><br>
139 :           <i>com.example.wiley.anvilfeature</i>.link        </code>link to separately-installed
140 :     extension<code><br>
141 :     </code></p>
142 :    
143 :     <p>Each product should partition its own plug-ins into one or more features.
144 :     The Eclipse platform itself is partitioned into three major features, Platform,
145 :     JDT, and PDE. There are also a bunch of lesser features, including documentation,
146 :     examples, and OS-dependent portions of Platform. The binary distribution
147 :     of the Eclipse 2.0 release makes each of these features available as a separate
148 :     zip. This allow a product packager to download and unzip just the pieces
149 :     needed for a particular product offering.</p>
150 :    
151 :     <p>To the user, an installed product usually shows up on the desktop as a
152 :     shortcut. Opening the shortcut starts the product. For a simple product that
153 :     does nothing other than run an Eclipse workbench, the shortcut target is
154 :     the Eclipse executable launcher (<code>&lt;<i>install</i>&gt;/eclipse/eclipse.exe</code>).
155 :     For products that have other things to do as well, the shortcut targets the
156 :     product's own executable (<code>&lt;<i>install</i>&gt;/<i>acmeproduct</i>.exe</code>),
157 : vlad 1.1 which invokes <code>eclipse.exe</code> at some point.</p>
158 : celek 1.5 Whenever the Eclipse platform is run, exactly one feature gets to control
159 :     the overall personality of the Eclipse platform. This is the called the product's
160 :     <b>primary feature</b>, and it controls highly visible things including the
161 :     splash screen, window branding images, the about box, the welcome page, the
162 :     default perspective, and customization of the default settings of plug-in
163 :     preferences. The typical product has just one eligible primary feature, and
164 :     it is determined by the "<code>feature.default.id</code>" property of the
165 :     product's <code>install.ini</code> file. If there are multiple eligible primary
166 :     features, the <code>-feature</code> command line option to <code>eclipse.exe</code>
167 :     overrides the choice made in the <code>install.ini</code>. If the property
168 :     "<code>feature.default.plugin.id</code>" exists, it declares the identifier
169 :     of the primary plugin. If the property does not exist, the primary plugin
170 :     must have the exact same identifier as the primary feature.
171 : vlad 1.1 <p>Summary of characteristics of products:</p>
172 : celek 1.5
173 : vlad 1.1 <ul>
174 : celek 1.5 <li>a product is installed in a single directory tree</li>
175 :     <li>a product includes copies of the org.eclipse.* plug-ins that it needs</li>
176 :     <li>OS-dependent code for multiple operating environment can sit side-by-side
177 : vlad 1.1 in a product install</li>
178 : celek 1.5 <li>a products is installed and uninstalled by a native installer only</li>
179 :     <li>more than one product may be installed on the same computer</li>
180 :     <li>a product is installed, updated, and uninstalled independently of
181 :     other Eclipse-based products</li>
182 :     <li>a product is updated by a native installer or by the Eclipse update
183 : vlad 1.1 manager</li>
184 : celek 1.5 <li>a product can have one or more primary features, and any number of
185 :     other features</li>
186 :     <li>a primary feature determines the Eclipse workbench overall appearance
187 :     and personality</li>
188 :     <li>the default primary feature is specified in the product-specific
189 :     install.ini file</li>
190 :     <li>the update manager can update the features and plug-ins installed
191 :     with the product</li>
192 :     <li>the update manager can install and configure additional features and
193 : vlad 1.1 plug-ins into the product</li>
194 : celek 1.5
195 : vlad 1.1 </ul>
196 : celek 1.5
197 : vlad 1.1 <h2>Extensions to Eclipse-based products</h2>
198 : celek 1.5
199 :     <p>An <b>extension</b> is bundle of Eclipse-based features designed to be
200 :     installed separately and used with any Eclipse-based product. In contrast
201 :     to a product, an extension includes neither eligible primary features, nor
202 :     a copy of the Eclipse platform, nor its own JRE.</p>
203 :    
204 :     <p>The same installed base of files for an extension can be used from several
205 :     Eclipse-based products. This means an extension only needs to be updated
206 :     in one place, while having the updated features available to all products
207 :     linked to that extension.</p>
208 :    
209 :     <p>To keep things concrete, the top level structure of an installed Eclipse-based
210 :     extension looks like this: </p>
211 :    
212 : vlad 1.1 <p><code>&lt;<i>extension install</i>&gt;/<br>
213 : celek 1.5   eclipse/             </code>container for installed Eclipse files<code><br>
214 :         .eclipseextension      </code>marker for Eclipse extension install<code><br>
215 :         features/                               </code>installed feature versions<code><br>
216 :           <i>com.example.wiley.anvilfeature</i>_<i>1.0.0</i>/        </code>feature
217 :     for extension<code><br>
218 :             feature.xml                                </code>feature manifest
219 :     file<code><br>
220 :         plugins/                                </code>installed plug-ins and
221 :     fragment versions<code><br>
222 :     </code> <code>     <i>com.example.wiley.anvilfeature</i>_<i>1.0.0</i>/        
223 : vlad 1.1 </code>extension-specific plug-in<code><br>
224 : celek 1.5         plugin.xml                                  </code>plug-in manifest
225 :     file<code><br>
226 :             about.ini                                   </code>about info for
227 :     feature<code><br>
228 :     </code>  <code>     <i>com.example.wiley.otherplugin</i>_<i>1.0.0</i>/         
229 : vlad 1.1 </code>extension-specific plug-in <code><br>
230 : celek 1.5         plugin.xml                                  </code>plug-in manifest
231 :     file <code><br>
232 :             <i>otherplugin</i>.jar                             </code>code for
233 :     extension-specific plug-in</p>
234 :    
235 : vlad 1.1 <p>Characteristics of extensions:</p>
236 : celek 1.5
237 : vlad 1.1 <ul>
238 : celek 1.5 <li>an extension is installed in a single directory tree (separate from
239 : vlad 1.1 products or other extensions)</li>
240 : celek 1.5 <li>an extension does not include a copy of the Eclipse platform plug-ins,
241 :     a JRE, or an executable</li>
242 :     <li>OS-dependent code for multiple operating environment can sit side-by-side
243 : vlad 1.1 in an extension install</li>
244 : celek 1.5 <li>an extension is installed and uninstalled by a native installer only</li>
245 :     <li>more than one extension may be installed on the same computer</li>
246 :     <li>an extension is installed, updated, and uninstalled independently
247 :     of other Eclipse-based products</li>
248 :     <li>an extension is updated by a native installer or by the Eclipse update
249 : vlad 1.1 manager</li>
250 : celek 1.5 <li>a product can have one or more features</li>
251 :     <li>an extension does not define primary features</li>
252 :     <li>to be useful, an extension must be associated with an Eclipse-based
253 : vlad 1.1 product</li>
254 : celek 1.5 <li>an extension can be associated with one or more products at the time
255 :     the extension is installed</li>
256 :     <li>an extension can be associated with a product via the update manager</li>
257 :     <li>the update manager can update the features and plug-ins installed
258 :     with the extension</li>
259 :     <li>the update manager can install and configure additional features and
260 : vlad 1.1 plug-ins into the extension</li>
261 : celek 1.5
262 : vlad 1.1 </ul>
263 : celek 1.5 <br>
264 : vlad 1.1 </body>
265 : celek 1.5 </html>