From HerzbubeWiki
Jump to: navigation, search

About this page

During November 2007 I started to work on a small educational project for an MAS course at the Hochschule Luzern (Lucerne University of Applied Sciences and Arts). The goal of the project was to learn more about the OSGi specification, and specifically plugin development with and for Eclipse. Besides gaining knowledge, the more or less :-) tangible product of the project was the fledgling version of an Eclipse plugin which I dubbed doxystub.

This page tries to give an overview about what I learned. Its main purpose is to serve as a reference point that I can come back to in the future, when I will take up again with enhancing doxystub, or developing some other plugin or software in Eclipse.

Introductory reading

I found the following reading material useful in order to get an introduction to OSGi and how it relates to Eclipse. I present an ordered list because I found the reading order appropriate:

  1. OSGi Basics [1]
  2. OSGi Technical Whitepaper [2]
  3. OSGi and Eclipse [3]
  4. Equinox Quickstart [4]
  5. OSGi Console of Eclipse [5]

Other documentation

  • Eclipse Resources: A number of useful articles of varying depth [6]
  • The Official Eclipse FAQs: Not merely one FAQ, but a multitude of them. These are useful at least to get an overview of the main structure of the project. [7]

Update Sites

The online help provides information about the different project types required to set up an update site. [8]

Feature project

  • File -> New -> Project -> Plugin Development -> Feature Project
  • give the project a useful name, e.g. ch.herzbube.doxystub.feature
  • fill any other details of your choice
  • select "initialize from the plugins list"
  • select the plugin(s) for which you want to have an Update Site
  • in the resulting new project, double-click the feature.xml file
    • this opens the "Feature Manifest Editor"
    • help for this editor is available under "Plug-in Development Environment Guide" -> Tools -> Editors -> Feature Manifest Editor
  • go to the "overview" tab and enter values for the "update site URL" and "update site name" fields; for instance
  • go to the "plug-ins" tab, select each plugin and make sure that its "version" field is set to the value "0.0.0" (should be the case)
    • "0.0.0" is a special value that will be replaced by the actual version of the plugin when the feature is exported (i.e. when the update site is built)
    • this should work by default; if it doesn't, click the "versions..." button for the plugin and make sure that in the next dialog the "synchronize versions on build" radio button is selected
  • go to the "dependencies" tab, then select "Compute" to let Eclipse automatically calculate dependencies for the new plugin; edit the dependencies if the information is not specific enough

Update project

  • File -> New -> Project -> Plugin Development -> Update Site Project
  • give the project a useful name, e.g. ch.herzbube.doxystub.update
  • in the resulting new project, double-click the site.xml file
    • this opens the "Site Manifest Editor"
    • help for this editor is available under "Plug-in Development Environment Guide" -> Tools -> Editors -> Site Manifest Editor
  • go to the "site map" tab, then click the "add feature..." button
  • select the feature project created above
  • go to the "archives" tab, then fill in the fields with appropriate values; for instance
  • go back to the "site map" tab, then click the "build all" button to build all features

Publish the update site

  • push the site.xml file and the folders features and plugins to a location where users can reach it through your web server
  • choose the same location that you entered for the "update site URL" in the feature project

Note: Plugins and features can be exported manually without an update site project. This happens through File -> Export -> Plugin Development -> Deployable Features / Deployable plugins and fragments. The exported files can be imported by their counterpart importers.

Helpful resources:

OSGi / Equinox

The console

The following command brings up the pure OSGi console of Eclipse in a terminal (example is for Ganymede SR2, replace the .jar file name by something appropriate):

java -jar /Applications/Eclipse/plugins/org.eclipse.osgi_3.4.3.R34x_v20081215-1030.jar -console

The following command also displays an OSGi console, but actually tries to launch the Eclipse application in parallel. This one is good to debug problems with plugins that prevent Eclipse from launching. The -noExit argument prevents the OSGi console from quitting after the Eclipse GUI terminates (e.g. after you have confirmed the GUI error message box that tells you that something went wrong).

/Applications/Eclipse/Eclipse.app/Contents/MacOS/eclipse -console -noExit

A couple of useful commands:

  • help
  • close: terminate the console in a controlled fashion; exit also does this, but is more forceful
  • ss: displays installed bundles ("short status")
  • diag nnn: prints diagnostics about bundle nnn (nnn is the numeric reference to the bundle; you get this when you issue the ss command)
  • bundle nnn: prints interesting details about bundle nnn
  • sl nnn: prints the start level of bundle nnn (or of the OSGi framework if no bundle ID is specified)
  • uninstall nnn: uninstalls bundle nnn; remains uninstalled when you run the application the next time


Eclipse terms:

Rich Client Platform
Eclipse Modeling Framework
Graphical Editor Framework
Plugin for task-focused development
Web Standard Tools
Plugin Development Environment
Eclipse Communication Framework
Dynamic Languages Toolkit
Web Tools Platform
Remote System Explorer, which is a part of the "Target Management" project (which in its own turn is a subproject of the DSDP project)
Data Tools Platform (part of JEE and Reporting packages)
Java Development Tools
C/C++ Development Tools
PHP Development Tools
Device Software Development Platform
Usage Data Collector
The Standard Widget Toolkit
The eclipse.org Wiki
Eclipse Project 
Quoting from Eclipsepedia: "The unfortunately named "Eclipse Project" is the project dedicated to producing the Eclipse SDK. This name made sense back when there were only two or three projects at Eclipse, but now it is frequently referred to as the "Eclipse top-level project" to reduce confusion (or just "The Platform" when we're feeling grandiose). This project in turn is composed of four sub-projects: Platform, Java development tools (JDT), Plug-in Development Environment (PDE), and Eclipse/Incubator. Until the Ganymede release, the Eclipse project also contained the Equinox subproject, but this project has since moved to the RT top level project. There is a proposed fifth sub-project, code-named e4, exploring technologies for the next generation of the Eclipse platform."
Eclipse Project SDK 
An entry that can be seen in "The Eclipse Project Updates" update site for Ganymede. I don't know what this is. The information dialog shows the identifier org.eclipse.sdk.feature.group
Eclipse Platform SDK 
An entry that can be seen in "The Eclipse Project Updates" update site for Ganymede. I don't know what this is. The information dialog shows the identifier org.eclipse.platform.sdk
Eclipse SDK 
An entry that can be seen in "The Eclipse Project Updates" update site for Ganymede. I don't know what this is. The information dialog shows the identifier org.eclipse.sdk.ide
Quoting from the FAQ: "JFace is a Java application framework based on SWT. The goal of JFace is to provide a set of reusable components that make it easier to write a Java-based GUI application. Among the components JFace provides are such familiar GUI concepts as wizards, preference pages, actions, and dialogs. [...] JFace does not make use of such Eclipse-specific concepts as extensions and extension points."


  • EasyEclipse: Eclipse distribution that promises stability (using plugin versions that go together), simple installation & upgrade

Plugin notes



Install the Eclipse SDK examples

  • Using the update site "The Eclipse Project Updates"
  • Install "Uncategorized -> Eclipse SDK Examples"

After installation the examples are available through

  • Window->Show View->Other->SWT Examples->SWT Example Launcher


  1. OSGi Basics: http://www.osgi.org/osgi_technology/
  2. OSGi Technical Whitepaper: http://www.osgi.org/documents/collateral/OSGiTechnicalWhitePaper.pdf
  3. OSGi and Eclipse: http://www.ibm.com/developerworks/opensource/library/os-ecl-osgi/
  4. Equinox Quickstart: http://www.eclipse.org/equinox/documents/quickstart.php
  5. OSGi Console of Eclipse: http://www-128.ibm.com/developerworks/opensource/library/os-ecl-osgiconsole/
  6. Eclipse Resources: http://www.eclipse.org/resources/
  7. The Official Eclipse FAQs: http://wiki.eclipse.org/The_Official_Eclipse_FAQs
  8. Plug-in Development Environment Guide -> Tools -> New Project Creation Wizards