Saturday, 16 November 2013

Getting started with OSGi and Bnd

There are many tutorials and books about OSGi, about what it is good for, why (and when) it is important to modularize your software and how OSGi can help you with that.

Many of those tutorials start with some interface / implementation example and guide you through the steps of how to create the necessary bundles in some IDE (often eclipse) and run them.

This is definitely a good approach to teach someone about OSGi, how it looks and feels like and about what modularity is good for. But I have the impression that there is a gap or lack of tutorials and documentation when it comes to bigger, more real life examples. You do not only want to create some "Hello World" bundle and let it run inside your IDE. If you want to let your OSGi project become real, you want to automatically build and test it, you want to have test coverage and a build pipeline (even continuous delivery!), and, what was the biggest challenge for me at least, you somehow want to mange all the bundles, yours, the ones you depend on (build- and runtime), and, not to forget, you somehow have to deal with those third-party jars which are not OSGi bundles yet.

I was using maven a long time to get my bundles built; the pom.xml files contained a section like this

and a matching file like this (osgi.bnd)

(If you want to use this, please note that there is an minus sign before the name of the bnd file in the pom.xml!)

This approach was working well, but it lacked all tooling help. What I mean is, that I was in full control of everything, being able to define whatever I needed in the osgi.bnd file. I could give a package a version and the maven-bundle-plugin would reliably pick it up, create the bundle jar and a matching manifest entry.

But it was a pain to figure out which version to use for that package. OSGi has the powerful concept of semantic versioning (you can find some details about this here). Problem is, that if you make mistakes with the version you define, the concept gets much less powerful, and sooner or later you have broken backwards compatibility.

Another problem with the maven-bundle-plugin approach was integration testing. I was using pax-exam, which is, no doubt, a great tool. But my pom files became huge. And I had to write glue code to setup testing, that is to make the test find the proper bundles in my maven repository. Testing can be fun, and it should be. Writing tons of code just to get the proper initial setup is no fun. 

Enter bndtools.

Reading this book convinced me to try bndtools once more. I had tried it years ago and had run into problems I cannot recall. What I didn't like about it was that it would tie me to eclipse as it is a eclipse plugin. But, ok. And it was awesome! No issues with versioning no more (bndtools supports baselining, that is, it will inspect your code and compare it to a previous version to determine which new version numbers to give to your packages). And, OSGi integration testing became as easy as it can possibly get.

But, still... with this new approach, I would force fellow code contributors to use eclipse. And how about the headless build?

Well, no harm done - the build chain can be invoked from good old ant, and, if you were using a different IDE, you could still easily just use the ant targets to build your bundles. You would not get the nice bndtools editors, but, hey, you are using a different IDE.

Enter bnd, the "Swiss army knife of OSGi".

Reading about bndtools and checking the ant targets and the code I understood that the heavy lifting under the hood was all done by the bnd tool - the same software which is used in the maven-bundle-plugin (and some more OSGi tools) as well.

So, getting curious, I started to dig into the bnd code and decided to start a blog series about this tool.

tl;dr: If you are serious about writing OSGi applications, you should definitely know how bnd works.

There is a lot of documentation on the bnd web page, but - at least to me - it seems that you have to know a lot about OSGi and even bnd in the first place before you can really understand what the documentation talks about. This is a big impediment for beginners of OSGi and I'd like to change that by writing about my insights and experiences with bnd.

If you are interested, stay tuned.