Wednesday, May 28, 2014

Running bndtools OSGi builds with Maven - bnd-maven-plugin now released!

The bndtools.org project provides some really great tooling for building OSGi bundles. This includes help for generating the bundle manifest, templates for working with Declarative Services, testing support and more. There's tooling for resolving deployments against repositories, and last but certainly not least - automatic semantic versioning. The tooling for semantic versioning will tell you whether the version of your exported packages is correct, by comparing the content of your APIs with the previous release of the bundle.
I won't go into the full feature set of bndtools here, have a look at the bndtools website for all the goodness. Another thing to say about bndtools is that it has a really active community, which is always a good thing to know when you're deciding on using an opensource project.

Example IDE screen, taken from bndtools.org
The bndtools project itself focuses on providing an Eclipse-based graphical IDE for developing OSGi bundles. However you normally also want to be able to build your bundles in a headless build. For example as part of a Jenkins/Hudson process or simply to build it from the command-line yourself.
The bndtools project provides headless build options using Ant and Gradle, but for many people being able to use Maven for builds is essential.

Most OSGi development in Maven is done these days using the maven-bundle-plugin or using Eclipse Tycho. Tycho focuses on building OSGi bundles using a manifest-first approach which is supported by the Eclipse PDE tooling. 
The maven-bundle-plugin uses the pom.xml file as the source of information for the bundle and while it uses bnd under the covers, just like the bndtools project, maven-bundle-plugin is a little different in that it uses the pom.xml as the source of information for the build. The bndtools IDE uses bnd.bnd files for this.

This is where the bnd-maven-plugin comes in. Toni Menzel started it a while ago, Peter Kriens worked on it, and I have been putting bits and pieces in recently. The bnd-maven-plugin basically builds a bndtools project exactly like the bndtools IDE would build it, but then from Maven. As of today the first version of the bnd-maven-plugin  (called 1.0.2 - mea culpa ;) has been released to Maven Central, so you can easily use it in your Maven builds.

Precise instructions on how to use it can be found in the project readme, but you can easily try it out by looking at the bnd-maven-plugin samples in github. They show what your pom should look like. The samples contain the following test projects:
TestBundle - this is a simple default-layout bndtools project that can be built with Maven.
TestBundle2 - a bndtools project that follows Maven conventions for directory locations of source and output files. It can be built using Maven and the bndtools IDE. This project also contains an example unit test.
TestBundle3 - this project contains an OSGi Framework integration test, which can be run both from Maven and Bndtools.
Additionally, the sample structure contains
ParentPom - a module that contains a parent pom used by all the other submodules.
MBPBundle - a module that builds a bundle using the maven-bundle-plugin, showing that it can be used alongside the bnd-maven-plugin, although within a single module you need to choose one or the other.

To run it with Maven you can simply go into the parent directory and execute mvn install:
$ .../samples/sample-projects $ mvn install
... lots of maven output ...
[INFO] --- maven-surefire-plugin:2.17:test (default-test) @ TestBundle2 ---
[INFO] Surefire report directory: /Users/David/clones/bnd/bnd-maven-plugin-parent/samples/sample-projects/TestBundle2/target/surefire-reports
-------------------------------------------------------
 T E S T S
-------------------------------------------------------
Running org.foo.bar.UnitTest
Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.003 sec - in org.foo.bar.UnitTest
Results :
Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
...
[INFO] --- bnd-maven-plugin:1.0.2:integration-test (default-integration-test) @ TestBundle3 ---
[INFO] Running the Bnd OSGi integration tests
Tests run  : 1
Passed     : 1
Errors     : 0
Failures   : 0
No Errors
...
[INFO] Finished running the Bnd OSGi integration tests
[INFO] ----------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO]
[INFO] ParentPom ......................................... SUCCESS [0.185s]
[INFO] TestBundle ........................................ SUCCESS [4.134s]
[INFO] TestBundle2 ....................................... SUCCESS [0.361s]
[INFO] TestBundle3 ....................................... SUCCESS [1.041s]
[INFO] MBPBundle ......................................... SUCCESS [0.842s]
[INFO] sample-projects ................................... SUCCESS [0.041s]
[INFO] ----------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ----------------------------------------------------------------------
[INFO] Total time: 11.707s

The above has built all modules, ran the unit tests in TestBundle2 and the integration tests in TestBundle3.

Use them with the bndtools IDE!

As the TestBundle, TestBundle2 and TestBundle3 projects are bndtools Eclipse projects, they can be imported via File -> Import -> Existing Projects into Workspace (along with the bnd cnf project):

Then you can use the IDE for all your dev needs, e.g. to execute the OSGi integration tests:


This is only the first release, but should be good enough to start playing with it. See if it works for you. Give us feedback! Help developing it further! You can fork, file issues and patches in the bndtools/bnd project on github. Enjoy :)