bnd and bndtools: the OSGi toolchain that writes your manifests

One library with a plugin in every build tool

Bnd and bndtools is described as a swiss army knife for OSGi, and the list of what it does in a single sentence is unusually complete. It creates manifest headers for you based on analyzing the class code, it verifies your settings, it manages project dependencies, it diffs jars, and much more. At the core is a library with all the functions, and that library is then used across many subsystems to provide the core functionality to the rest of the world. The subsystem list is what makes bnd unusual among Java tools. There is bndlib and friends, the core library plus repository and resolve. There is a full set of maven plugins that make bnd useful for maven users. There is the Eclipse plug-in, which is the plugin for Eclipse providing full GUI support for bnd, distributed as a p2 repository. There is bnd, a command line utility with a hodgepodge of sometimes extremely useful functions that can even be used instead of a build tool, available through a Homebrew formula. There is a gradle plugin suite, a bnd workspace plugin that builds identically to Eclipse's bndtool plus a gradle plugin for bnd support in non-workspace projects. And there is ant, described with a flatly resigned ellipsis. The consequence for a user is that bnd can be adopted without changing your build system, because it has a plugin for the build system you already use.

The manifest is derived from the code, not typed by hand

The reason bnd exists at all is the OSGi manifest header problem. A bundle declares what it exports, what it requires, what version it is and which packages are visible, and hand-maintaining that list means every refactoring is a chance to leave a stale entry behind. Bnd's answer is to analyse the class code and derive the headers from what is actually there, which is why the first thing on the list of what it does is creating manifest headers based on analyzing the class code. That inversion is the whole idea, and it is why bnd is described as a tool that works on the artefact after the compiler rather than as a compiler plugin that has to be configured. The second capability, verifying your settings, follows from the first, since if the headers are computed then a mismatch between what you declared and what the code contains is detectable, and the baselining tool mentioned later in the API section is what makes that comparison automatic across versions. The other pieces fit around it. The repository module is an OSGi repository implementation, the resolve module is a resolver, and the difference and diff jars capability is what lets you see what changed between two builds of a bundle, which is a routine question once you are shipping many of them.

Backward compatibility is enforced by a baselining tool

The API section is short and it is the strongest thing the project says about itself. They go out of their way to be backward compatible, there are thousands of extensive test cases, and they use their own baselining tool to verify that they do not make gratuitious changes. Because that tool is part of Bndtools itself, the project often finds out early enough that there are alternatives to breaking changes. They strictly follow OSGi semantic versioning, which means that exported packages are marked with a package version. The consequence is that the version of a package tells you what changed, which is the property an OSGi consumer depends on when it resolves against a repository of many bundles. The project also tries to keep major versions to a minimum but sometimes must, and a major release number clearly marks that. The current state is that the master branch is release 7 and the Java release version is 17. Because some libraries are used in the embedded world with a slower uptake of the Java release train, they keep a classic branch that continues a major release 6 on Java 1.8, and that classic branch does not include the plugins. That last detail matters when you choose a branch, since the plugin-based integration is not available on the old line.

Adding it to a Maven or Gradle build

The stable release is what the README tells you to use for normal development, and it is distributed through Maven Central under the group id biz.aQute.bnd, and through the Bndtools Eclipse plug-in p2 update site. The Maven integration is a plugin declaration.

<plugin>
  <groupId>biz.aQute.bnd</groupId>
  <artifactId>bnd-maven-plugin</artifactId>
  <version></version>
</plugin>

The Gradle integration is the builder plugin.

plugins {
  id "biz.aQute.bnd.builder" version "7.4.0"
}

Note the version in the Gradle snippet is the bnd version itself, 7.4.0, which matches the current release tag, so the plugin and the tooling move together. The Maven snippet leaves the version empty in the README, which means you supply it, and the same applies to the configuration of both plugins, since bnd is configured through its own bnd file and the plugin simply invokes it. The repository structure at the top level shows how the pieces are packaged, with separate directories for the Maven, Ant, Eclipse, launchpad, repository, resolve, tester, launcher and remote modules, plus a build.gradle at the root and a cnf/ directory for the OSGi configuration, and a demo/ directory holding a bnd.bnd file and several .bndrun launch configurations. The .bndrun files are worth a look, since they are how a bundle is launched and debugged under bnd rather than inside Eclipse.

How the project is maintained, and what that means for you

The README is unusually direct about process, and the details are a good proxy for what working with bnd is like. Feedback is handled through issues on GitHub, with the request that you provide the smallest possible example as a GitHub repo, because if the bug is consistent they tend to fix it really fast, and at least specify the environment where it appears. There is a discourse site that is open for any topic even remotely associated with bnd, and the maintainers say they like to hear how people use the product. Pull requests are the most valued contribution, and the documentation of bnd is fully included in the workspace, so a typo fix or an essay both go through the same route. The branch model is strict, with master where the work for the next release takes place and where pushes release to the snapshot repository, classic as the continuation of 6.4 on Java 1.8, and next as the release branch to Maven Central used during the release process. The project generally does not use other branches, and issues and features are handled through pull requests from forked repos. Open issues are the ones actively scheduled into the next milestones, all other issues will be closed, and the ones closed for lack of interested contributors are explicitly marked with a help wanted label so they can be picked up. Release cadence is planned with milestones, and they try to have a release every three to six months, which matches the tag history of 7.4.0 in August 2026, 7.3.0 in June and 7.2.3 in March. The verification is automated too, with CodeQL and the contribution rules checked, and pull requests requiring approval when they do not come from a known contributor.

Where bnd is the wrong choice

The first limit is scope. If you ship plain jars, the OSGi manifest is a solved problem that the jar tool already handles, and adopting bnd buys you header generation you did not need, a DSL to learn, and a dependency on the tool's own version alignment. The second is the learning curve, which the README does not minimise. The configuration is a bnd file with its own syntax, the tool has a large number of subcommands, the README calls the command line utility a hodgepodge of sometimes extremely useful functions, and the Eclipse plug-in is the reference experience, so a team without Eclipse in its workflow is starting from the less documented end. The third is the version matrix, and it is a real operational cost. Release 7 needs Java 17, the classic branch keeps release 6 on Java 1.8 but does not include the plugins, so a team on an older Java is choosing between the plugin integration and the modern release, and a team spanning both needs two lines of tooling. The fourth is that the build-tool choice is a commitment, because a bnd-based build is a bnd build with a build tool in front of it, and migrating away later means untangling the bnd configuration from the plugin configuration. And the fifth is that the most valuable parts of the tool are the ones with the least documentation. The library is documented with a bnd cheatsheet, and the documentation of bnd is fully included in the workspace, but the workflows an OSGi developer actually performs, resolving a repository, baselining against a previous release, wiring a bundle into a launcher, are where the documentation thins and where the discourse forum becomes the practical support channel.

Editorial conclusion

Adopt bnd if you build OSGi bundles, Eclipse plug-ins or modular Java and want manifest headers derived from the code rather than maintained by hand, and you are prepared to learn the bnd DSL. Skip it if you ship plain jars, where the manifest is a solved problem, and skip it if you need a tool that follows your existing build without configuration. Verify first which branch matches your Java version, since the classic branch exists for Java 8 and the current master needs Java 17, and that the version of the plugin you add matches the bnd release your build uses.

Frequently asked questions

Official sources

1. bndtools/bnd on GitHub
2. Issues
3. Project website
4. README
5. Releases