OSGi Getting Started

By Michael N. Lipp

View GitHub Project

Introduction

Part 1: The container

Part 2: Simplest Bundle

Part 3: Simple Bundle

Part 4: Eclipse (OSGi) Plugin

Part 5: Bndtools

Part 6: Shift in Perspective

Part 7: Modules and Services

Part 8: Accessing a Service

Part 9: Tracking a Service

Part 10: Using a Service

Interlude: Cleaning up

Part 11: Service Component

Bndtools

Bndtools is an Eclipse plugin that integrates the (command line) tool bnd in Eclipse and provides “continuous build” for bundles. Install it now.

The tool bnd takes a different perspective on defining bundles. From bnd’s point of view, MANIFEST.MF is the source of information about the bundle at runtime only. While developing the bundle, you need closely related, but sometimes slightly different information and additional information. So, to bnd, MANIFEST.MF is an artifact that is generated during build time from information contained in a file called bnd.bnd. The eclipse plugin bndtools provides a GUI for editing bnd.bnd (again with the possibility to edit the source directly) and components that make the information from bnd.bnd available to Eclipse’s continuous build.

There is a tutorial for Bndtools, which I found (at the time of this writing) to be rather confusing. It addresses developers with some OSGi experience rather than users who want to get an (Eclipse based) environment for writing their first bundle. So let’s simply once more focus on our Simple Bundle and port it to a Bndtools project.

Create a new “Bndtools OSGi Project” in Eclipse using the wizard. Choose the Bndtools/Empty template, use SimpleBundle-bnd as project name. In order to be able to really work with Bndtools, you also need a configuration project. Using the wizard again, create a “Bndtools OSGi Workspace” (New/Other/Bndtools). Choose “bndtools/workspace” as workspace template. You’ll see two new projects in Eclipse now. The SimpleBundle-bnd, which was to be expected, and a project cnf. Ignore the latter for the time being.

Have a look at the generated folder in SimpleBundle-bnd. Double-click on SimpleBundle-bnd.jar and then – in the “Jar File Viewer” that appears – double-click on MANIFEST.MF. Looks a bit familiar but much more verbose than what we have written so far1:

Jar File Viewer

Copy our source package into the src folder of the new project. Open Activator.java and have a look at the error. Looks familiar. Regrettably, there’s no quick fix this time. Open bnd.bnd and select the “Build” tab. In the “Build Path sub-window use “+” to add osgi.core. Save the file and see the error disappear. If you switch to the “JAR File Viewer” again, you can see that the jar is still empty (apart from the MANIFEST.MF, of course). Bndtools doesn’t include Java sources just because they are there. Rather, you have to add them to the “Private Packages” in bnd.bnd, tab “Content”. Do this, save, and you can see the project’s classes in the jar file now.

On tab “Content”, you can also add the bundle’s activator. At the time of this writing, using Bndtools 3.2.0, content assist didn’t work. So you have to type (or copy paste) the class name into the field. Save again, and you can see the Bundle-Activator header having been added to the generated MANIFEST.MF. You can also see it on the “Source” tab of bnd.bnd. The basic idea about the format of bnd.bnd is that entries that are to be copied to MANIFEST.MF look just like the headers in MANIFEST.MF (well, sometimes they are processed a bit). Entries that control the behavior of the bnd tool start with a dash2.

Add version “1.0.3” in the “Content” tab of bnd.bnd. Save, and you can immediately install and start the bundle (the jar) in felix as with our previous projects. If you want to have a build time stamp as with the PDE plugin, add ${tstamp} to the version number (“1.0.3.${tstamp}”). This macro will be replaced with the build time by bnd.

If you want to continue using Bndtools, you should have a look at the bnd documentation after reading the remaining parts of my introduction (at least up to “Cleaning up” – there are still some parts of the puzzle missing). I recommend to start with “Introduction”, proceed with “Concepts” and read the rest as required when you encounter problems with your projects.

When you create a “Bndtools OSGi workspace”, the required files for a gradle built (which is completely independent from Bndtools) are automatically added in the directory that contains your project. It’s added there because more often than not an OSGi based project consists of several bundles. From gradle’s point of view, all bundles are sub-projects in their respective folders. The generated build configuration uses bnd’s gradle plugins. Don’t try to develop OSGi bundles with the plugin from the gradle project. As one of the gradle developers remarked in a discussion: “The existing OSGi plugin is one of the oldest Gradle plugins. My opinion is that the best thing to do here would be to start again.”3 The plugins bundled with bnd actually represent this “fresh start”.

To make absolutely sure that the dependencies are clear, let me summarize again. At the center of the build is the bnd command line tool. Its “gradle module” provides the necessary plugins to adapt gradle (via build.gradle) in such a way that it takes the project specific build information from bnd.bnd, thus making bnd.bnd the primary source of information for the gradle build.

Bndtools integrates bnd into Eclipse. It provides plugins for Eclipse that use the information from bnd.bnd to provide a class path container and other information for the continuous Eclipse build. The results from the Eclipse build and the gradle build are exactly the same. Using Bndtools therefore does not make your project depend on Eclipse.


  1. Probably this is really the simplest bundle that you can have. 

  2. Comparing this with PDE’s approach as shown in the previous part, you could say that bnd.bnd combines the information maintained by PDE in MANIFEST.MF and build.properties

  3. I only wish they had put that in the gradle documentation of the plugin. Would have saved me half a day.