PieroCampanelli.info

In this tutorial I propose a quick step-by-step guide to start developing your OSGi bundles using Eclipse IDE and a standalone Equinox implementation.

1. Download latest Equinox distribution and unpack it
2. Configure Eclipse Target Platform
3. Create an OSGi Project for your bundle
4. Develop your bundle
5. Run or Debug your bundle inside Eclipse
6. Deploy your bundle

Step 1. Download latest Equinox distribution and unpack it

Download latest Equinox release from: http://download.eclipse.org/eclipse/equinox/

• I suggest to unpack it into <your_root_dir> (default Equinox unpacked directory is called eclipse. I suggest to rename it in equinoxruntime).
• In my case I have unpacked in /home/pc/Documents/MySrc/equinoxruntime

pc@ubuntulaptop:~/Documents/MySrc/equinoxruntime/$ ls -la
total 44
drwxrwxr-x 4 pc pc  4096 2007-12-31 00:54 .
drwxrwxr-x 3 pc pc  4096 2007-12-30 22:42 ..
-rw-rw-r-- 1 pc pc 16536 2007-10-24 02:14 epl-v10.html
drwxrwxr-x 4 pc pc  4096 2007-12-30 22:38 features
-rw-rw-r-- 1 pc pc  6506 2007-10-24 02:14 notice.html
drwxrwxr-x 3 pc pc  4096 2007-12-30 22:38 plugins
pc@ubuntulaptop:~/Documents/MySrc/equinoxruntime/$

Step 2. Configure Eclipse Target Platform

A target platform specifies the Equinox version that should be used to compile and run your OSGi bundles. We want to develop components for the previously unpacked Equinox distribution (which at the moment is 3.1.1).

Under Window -> Preferences -> Plugin-Development -> Target Platform we point the location of Equinox binaries (in mycase are: /home/pc/Documents/MySrc/equinoxruntime)

Step 3. Create an OSGi Project for your bundle

In Eclipse create a new Plug-in Project (Plug-In Development->Plug-In Project) and assign it a name.

• I suggest using the same Eclipse convention of using package name as your bundle name (For example org.eclipse.runtime.core or org.eclipse.equinox.http). Change the target environment to Equinox.
• Generally Eclipse offers a set of template for assisting in Bundle creation. For the moment you can ignore them.
• In my case I have created a bundle called info.pierocampanelli.hello

Step 4. Develop your bundle

At this point you can code your bundle inserting your logic and your desired functionalities. OSGi API is not the focus of this tutorial. So for simplifying the process I created a trivial bundle that will print a message when it is started or stopped:

package info.pierocampanelli.hello;

import org.osgi.framework.BundleActivator;
import org.osgi.framework.BundleContext;

public class Activator implements BundleActivator {
  public void start(BundleContext context) throws Exception {
    System.out.println("Hello STARTED");
  }  

  public void stop(BundleContext context) throws Exception {
    System.out.println("Hello STOPPED");
  }
}

Crucial point is that you can exploit Eclipse facilities and tools to simplify development. In particular you can use:

• Editing support of the Manifest.FM file. You have not to write manually the Bundle specification file. Eclipse provides a set of textfields, comboboxes and listfields that help in editing Manifest.



• Dependency Tracking. Right clicking on a Bundle will automatically show all dependencies of that bundle. In the following screenshot for example Eclipse tells me about dependencies of the Jetty HTTP bundle (org.eclipse.equinox.http.jetty). Imagine for a moment what kind of benefits you can have with a large project of more than 50/100 bundles and an automatic dependency tracker that assists you…

Step 5. Run or Debug your bundle inside Eclipse

Now it's time to run the bundle.

• Choose “Run …” entry from Run menubar
• Create a new runtime configuration right clicking on Equinox OSGi Framework
• Select your bundle that you want to run
• Remember to click Add Required Plug-ins to automatically insert dependent bundles
• Run it !

Eclipse creates a new JVM process running an instance of Equinox running selected bundles. The same steps can be followd for debugging.

Step 6. Deploy your bundle

At end is the deployment step. Again eclipse offers you a wizard that assist in the creation and expor of coded bundle to a target directory.

• Right click on your bundle and select Export. Choose “Plug-in Development->Deployable Plugins and Fragments”.
• Select destination folder (for example /home/pc/Desktop)
• Click “Finish”

At end of the process you’ll find your bundle in /home/pc/Desktop/plugin. You can now copy your bundle in an OSGi compliant engine.