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

Parent Directory Parent Directory | Revision Log Revision Log

Revision 1.5 - (download) (as text) (annotate)
Fri Dec 6 21:22:53 2002 UTC (6 years, 11 months ago) by celek
Branch: MAIN
CVS Tags: v20050526, R3_0, R3_1, v20040514, v20040219, HEAD
Changes since 1.4: +236 -213 lines 
*** empty log message ***

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
 
  <meta http-equiv="Content-Language" content="en-us">
 
  <meta http-equiv="Content-Type"
 content="text/html; charset=windows-1252">
 
  <meta name="GENERATOR" content="Microsoft FrontPage 4.0">
 
  <meta name="ProgId" content="FrontPage.Editor.Document">
  <title>Eclipse-based Products and Extensions</title>
</head>
   <body>
  
<h1> Eclipse-based Products and Extensions</h1>
 
<p>Last modified 16:00 Friday December 06, 2002<br>
</p>
<p><b>Change History:</b> </p>
   
<ul>
  <li><small>2.0.1</small><small><br>
    </small>
    <ul>
      <li><small>added: <big><code>feature.default.plugin.id</code></big></small></li>
    </ul>
  </li>
</ul>
 
<p>Eclipse technology is the foundation of, and provides building blocks
for, products aimed at the software development tools market. Commercial
software vendors are expected to build, brand, and package products using
the Eclipse platform as the nucleus, to sell these products into the development
tools marketplace, and to support them once in the field.</p>
 
<p>The Eclipse platform itself is not a "product" in any of these senses.
Eclipse is an open source project that provides raw ingredients without box,
label, or price tag. The closest that the Eclipse project gets to a packaged
form is the Eclipse SDK, which can be downloaded from <a
 href="http://www.eclipse.org">eclipse.org</a>, installed, and used as a
full-service Java IDE which also happens to include special support for developing
Eclipse plug-ins (PDE).</p>
 
<p>This note describes how the Eclipse platform is designed to be turned
into products. The license governing the Eclipse platform gives a software
vendor almost complete freedom over how to built a product. So anyone building
a product is free to ignore this advice. However, as is often the case with
standards, adhering to the same rules as everyone else has its rewards: it
fosters greater interoperability between products, and makes it easier for
the end user because different products behave in similar ways.</p>
 
<p>Eclipse plug-ins are intended to packaged and delivered to the customer
into one of two forms: either as self-contained Eclipse-based products, or
as add-on extensions to Eclipse-based products. We'll first explain what
we mean by Eclipse-based product since it is the more basic notion.</p>
 
<h2>Eclipse-based products</h2>
 
<p>An Eclipse-based <b>product</b> is a stand-alone program build with Eclipse. 
Products are self-contained in that all code and plug-ins needed to get up
and running are included; this includes a Java runtime environment (JRE),
and the code for the Eclipse platform itself. After installing a product
on a computer with a conventional native installer, the user launches the
product (via its product executable) and is presented with an Eclipse workbench
configured appropriately for the purposes that product was designed to support
(be it developing enterprise web servers, developing C++ programs, or developing 
whatever). Products are intended to be updated, either with a conventional 
native installer, or with the build-in Eclipse update manager, which is always 
available to the user from the Eclipse workbench ("Update Manager" on the
"Help" menu).</p>
 
<p>If we looked more closely at how the Eclipse parts of the product are organized,
we would see that all plug-ins that go into a product are grouped into <b>features</b>.
"Feature" is an Eclipse update manager notion: a feature is the smallest
unit of separately downloadable and installable functionality. Features also
play a secondary role in how the Eclipse platform runs.</p>
 
<p>To make things a bit more concrete, the top level structure of an installed 
Eclipse-based product looks like this (italics indicate product-specific
file names): </p>
 
<p><code>&lt;<i>install</i>&gt;/<br>
   <i>acmeproduct</i>.exe      </code>product executable<code><br>
   eclipse/             </code>container for installed Eclipse files<code><br>
     .eclipseproduct        </code>marker for Eclipse product install<code><br>
     eclipse.exe            </code>Eclipse executable launcher<code><br>
     startup.jar            </code>Eclipse Java launcher<code><br>
     install.ini            </code>install info<code><br>
     .config/               </code>install info (computed at install time
with -initialize option)<code><br>
        platform.cfg           </code>default platform configuration<code><br>
     jre/                   </code>Java runtime environment (JRE)<code><br>
     features/                               </code>installed feature versions<code><br>
       <i>com.example.acme.acmefeature</i>_<i>1.0.0</i>/        </code>primary
feature for product<code><br>
         feature.xml                                </code>feature manifest
file<code><br>
       org.eclipse.platform_2.0.0/                </code>feature for Eclipse
platform<code><br>
       org.eclipse.platform.win32_2.0.0/          </code>feature for Eclipse
platform<code><br>
     plugins/                                </code>installed plug-ins and
fragment versions<code><br>
 </code> <code>     <i>com.example.acme.acmefeature</i>_<i>1.0.0</i>/         
</code>product-specific plug-in<code><br>
         plugin.xml                                  </code>plug-in manifest
file<code><br>
         about.ini                                   </code>about info for
product<code><br>
         <i>acme</i>.gif                                    </code>window
icon for product<code><br>
         plugin_customization.ini                    </code>about info for
product<code><br>
         splash.png                                  </code>product splash
screen<code><br>
 </code>  <code>     <i>com.example.acme.myplugin</i>_<i>1.0.0</i>/           
</code>product-specific plug-in <code><br>
         plugin.xml                                  </code>plug-in manifest
file <code><br>
         <i>myplugin</i>.jar                                </code>code for
product-specific plug-in<code><br>
       org.eclipse.platform_2.0.0/                </code>Eclipse platform
plug-in<code><br>
       org.eclipse.platform.win32_2.0.0/          </code>Eclipse platform
plug-in<code><br>
       org.eclipse.core.boot_2.0.0/               </code>Eclipse platform
plug-in<code><br>
       org.eclipse.core.runtime_2.0.0/            </code>Eclipse platform
plug-in<code><br>
       org.eclipse.core.resources_2.0.0/          </code>Eclipse platform
plug-in<code><br>
       org.eclipse.ui_2.0.0/                      </code>Eclipse platform
plug-in<code><br>
       (more org.eclipse.* plug-in directories)<br>
     links/                                   </code>links to extensions
(see next section)<code><br>
       <i>com.example.wiley.anvilfeature</i>.link        </code>link to separately-installed
extension<code><br>
 </code></p>
 
<p>Each product should partition its own plug-ins into one or more features.
The Eclipse platform itself is partitioned into three major features, Platform,
JDT, and PDE. There are also a bunch of lesser features, including documentation, 
examples, and OS-dependent portions of Platform. The binary distribution
of the Eclipse 2.0 release makes each of these features available as a separate
zip. This allow a product packager to download and unzip just the pieces
needed for a particular product offering.</p>
 
<p>To the user, an installed product usually shows up on the desktop as a 
shortcut. Opening the shortcut starts the product. For a simple product that 
does nothing other than run an Eclipse workbench, the shortcut target is
the Eclipse executable launcher (<code>&lt;<i>install</i>&gt;/eclipse/eclipse.exe</code>). 
For products that have other things to do as well, the shortcut targets the 
product's own executable (<code>&lt;<i>install</i>&gt;/<i>acmeproduct</i>.exe</code>), 
which invokes <code>eclipse.exe</code> at some point.</p>
 Whenever the Eclipse platform is run, exactly one feature gets to control
the overall personality of the Eclipse platform. This is the called the product's
<b>primary feature</b>, and it controls highly visible things including the
splash screen, window branding images, the about box, the welcome page, the
default perspective, and customization of the default settings of plug-in
preferences. The typical product has just one eligible primary feature, and
it is determined by the "<code>feature.default.id</code>" property of the
product's <code>install.ini</code> file. If there are multiple eligible primary
features, the <code>-feature</code> command line option to <code>eclipse.exe</code>
overrides the choice made in the <code>install.ini</code>. If the property
"<code>feature.default.plugin.id</code>" exists, it declares the identifier
of the primary plugin. If the property does not exist, the primary plugin
must have the exact same identifier as the primary feature. 
<p>Summary of characteristics of products:</p>
 
<ul>
   <li>a product is installed in a single directory tree</li>
   <li>a product includes copies of the org.eclipse.* plug-ins that it needs</li>
   <li>OS-dependent code for multiple operating environment can sit side-by-side 
    in a product install</li>
   <li>a products is installed and uninstalled by a native installer only</li>
   <li>more than one product may be installed on the same computer</li>
   <li>a product is installed, updated, and uninstalled independently of
other     Eclipse-based products</li>
   <li>a product is updated by a native installer or by the Eclipse update 
    manager</li>
   <li>a product can have one or more primary features, and any number of
other     features</li>
   <li>a primary feature determines the Eclipse workbench overall appearance
and     personality</li>
   <li>the default primary feature is specified in the product-specific 
   install.ini file</li>
   <li>the update manager can update the features and plug-ins installed
with the     product</li>
   <li>the update manager can install and configure additional features and 
    plug-ins into the product</li>
 
</ul>
 
<h2>Extensions to Eclipse-based products</h2>
 
<p>An <b>extension</b> is bundle of Eclipse-based features designed to be 
installed separately and used with any Eclipse-based product. In contrast
to a product, an extension includes neither eligible primary features, nor
a copy of the Eclipse platform, nor its own JRE.</p>
 
<p>The same installed base of files for an extension can be used from several 
Eclipse-based products. This means an extension only needs to be updated
in one place, while having the updated features available to all products
linked to that extension.</p>
 
<p>To keep things concrete, the top level structure of an installed Eclipse-based
extension looks like this: </p>
 
<p><code>&lt;<i>extension install</i>&gt;/<br>
   eclipse/             </code>container for installed Eclipse files<code><br>
     .eclipseextension      </code>marker for Eclipse extension install<code><br>
     features/                               </code>installed feature versions<code><br>
       <i>com.example.wiley.anvilfeature</i>_<i>1.0.0</i>/        </code>feature
for extension<code><br>
         feature.xml                                </code>feature manifest
file<code><br>
     plugins/                                </code>installed plug-ins and
fragment versions<code><br>
 </code> <code>     <i>com.example.wiley.anvilfeature</i>_<i>1.0.0</i>/         
</code>extension-specific plug-in<code><br>
         plugin.xml                                  </code>plug-in manifest
file<code><br>
         about.ini                                   </code>about info for
feature<code><br>
 </code>  <code>     <i>com.example.wiley.otherplugin</i>_<i>1.0.0</i>/          
</code>extension-specific plug-in <code><br>
         plugin.xml                                  </code>plug-in manifest
file <code><br>
         <i>otherplugin</i>.jar                             </code>code for
extension-specific plug-in</p>
 
<p>Characteristics of extensions:</p>
 
<ul>
   <li>an extension is installed in a single directory tree (separate from 
    products or other extensions)</li>
   <li>an extension does not include a copy of the Eclipse platform plug-ins,
a     JRE, or an executable</li>
   <li>OS-dependent code for multiple operating environment can sit side-by-side 
    in an extension install</li>
   <li>an extension is installed and uninstalled by a native installer only</li>
   <li>more than one extension may be installed on the same computer</li>
   <li>an extension is installed, updated, and uninstalled independently
of other     Eclipse-based products</li>
   <li>an extension is updated by a native installer or by the Eclipse update 
    manager</li>
   <li>a product can have one or more features</li>
   <li>an extension does not define primary features</li>
   <li>to be useful, an extension must be associated with an Eclipse-based 
    product</li>
   <li>an extension can be associated with one or more products at the time
the     extension is installed</li>
   <li>an extension can be associated with a product via the update manager</li>
   <li>the update manager can update the features and plug-ins installed
with the     extension</li>
   <li>the update manager can install and configure additional features and 
    plug-ins into the extension</li>
 
</ul>
  <br>
</body>
</html>