How to start with OSGi

Solution 1:

update To address this question better, I've written a booklet & videos that allows you to get inside OSGi quickly. It is very interactive, using Bndtools and the OSGi Gogo shell. You can find it here.

updated text for readability & current state

I can understand the confusion ... there are a plethora of build tools and they nowadays all support OSGi. Since you sometimes need combinations of tools, the space is complex.

bnd

To use OSGi you need to build bundles. A bundle is a JAR file, the default format of Java libraries/executables. They are bundles when the manifest in the JAR file contains OSGi metadata. This metadata provides information to tooling and the OSGi framework what capabilities it requires from the runtime and what capabilities it provides to the runtime. This information is used to assemble runtimes as well as verify during runtime that things are compatible.

Maintaining this information by hand is a lot of nauseating work. For this reason bnd was developed by me, already about 19 years ago. bnd is currently the primary library in the industry to create this metadata, simplify decorating the metadata, and verifying the validity of the metadata. It does extensive analysis and annotations of the bundle to minimize the manual work.

In the bnd case, it also supports the OSGi standard build annotations for Declarative Services, Manifest annotations, and more. (Many OSGi standards originated in bnd.)

IDE & Continuous Integration

IDEs are the preferred to tools to read, write and debug code. However, without a continuous integration solution that runs on a remote server, you cannot rely on the results since your IDE might depend on the information that you only have on your laptop. For professional development, it is, therefore, a must to have some server that builds your software from scratch without using caches.

Clearly, it is paramount that when you develop software on your laptop the results are identical when you build on the server. For this reason, bnd provides a library that can be used in the IDEs and different build tools. Although there are a myriad of combinations feasible with bnd, there are few most popular ones.

Models

Maven Only

Maven is a popular build tool for Java applications. It defines all build information in POM (Project Object Model) files, which are XML files. POMs can inherit from other POMs. Each POM (and artifact) is identified by a group id, an artifact id, and an opaque version. Maven has a pretty fixed structure for a project. All build work is done via plugins that get their configuration from the POM.

There are two Maven plugins, based on bnd, that provide the necessary OSGi metadata generation.

• Apache Felix Maven Plugin
• Bnd Maven Plugins

In this model, bnd is only used for providing the metadata in the bundle. All dependencies must be in Maven repositories.

There is a third plugin, Tycho, that builds bundles using the Eclipse PDE model. I hear few people recommending going to PDE/Tycho today, it has not been a painless development and many PDE users are looking at alternatives. This plugin must bridge a very large semantic gap between PDE and Maven.

Gradle Only

Although Gradle is also relying on plugins for all the low-level work it heavily relies on Groovy to provide the build actions.

The bndtools group provides a plugin that makes it trivial to generate the OSGi metadata in the normal Java build:

• bnd Gradle plugin

In this model, all dependencies must be stored in repositories accessible by Gradle, which are generally Maven repositories.

Eclipse, M2E, Maven, and Bndtools

In this quartet, Eclipse is the basic IDE, M2E is a plugin that teaches Eclipse how to build the bundles according to a maven specification (pom file). In this quartet, bnd runs inside Maven as a plugin. Bndtools provides some bonus OSGi IDE functionality that M2E is lacking. This is mainly focused on creating assemblies for OSGi runtimes and viewing bundles.

In this model, all build information is stored in Maven POMs. This is the model that BJ Hargrave in another answer to this question posted.

In this model, bnd is only used for providing the metadata in the bundle. All dependencies must be in Maven repositories.

Eclipse, Bndtools, Gradle

The other model, which was developed specifically for OSGi/bnd, is the bnd workspace model. In this model, a workspace is a directory with the OSGi bundle projects, a special directory (cnf) holds workspace wide information. All build information is stored in bnd files which are good old Java property files.

Eclipse/Bndtools and Gradle (and for that matter Ant!) have plugins that read the information in the workspace and project directories and teach their respective build tools where the sources are, where the binaries should be stored, etc. The plugins for these tools that use bnd go out of their way to ensure the build results are identical.

The original archived OSGi enRoute was based on this model. Although it is archived, it is still the primary model for Bndtools and used by many companies. At EclipseCon 2018 there are several presentations about this model:

• How OSGi drives cross-sector energy management – Fully based on the v2Archive OSGi enRoute model
• How we used OSGi to build open liberty – Build with Bndtools and Gradle
• Migrating from PDE to Bndtools in Practice – Migrated recently from PDE (the original Eclipse bundle build model) to Bndtools

This is also the model that OSGi uses itself to build the specification JARs, Reference Implementations, and the Compliance Test suites.

The bnd workspace model is the only model that supports all repository standards. This includes Maven repositories (Maven Central!), OSGi repository standard, Eclipse P2 repositories, directory-based repositories, and even POM based repositories. The support for external repositories in the bnd workspace model is extraordinarily flexible.

Where to Start?

Generally, developers that start in OSGi already have Java experience. This generally drives their choice for a tool since there is already a legacy.

If you can start with a blank slate then my personal preference is the bnd workspace model. It puts the priority on the IDE, which is where you spent most of your time while having an extremely good fidelity with the continuous integration build. In the last 2 years, I've helped two companies, one to start with OSGi from scratch, the other having 8 years experience with PDE. Both are now based on this workspace model and I am quite impressed by how they've been able to reap the benefits of OSGi without any prior experience much faster than I'd ever seen before.

An interactive tutorial, using Bndtools and the OSGi Gogo shell can be found here. With videos!

Solution 2:

Start with OSGi enRoute. It will discuss using Bndtools as an IDE. It already uses the Bnd maven plugins to build bundles and demonstrates using Declarative Services to code providing and using services.