bnd – the Swiss army knife of OSGi

bnd is the engine behind many popular OSGi development tools, including Eclipse (Bndtools), Maven, Gradle, and the bnd CLI. Its primary function is generating OSGi metadata by analyzing Java class files.

bnd overview

Quick Start Examples

bnd makes it easy to add OSGi metadata to JARs, whether wrapping existing libraries or building your own projects.

# Install bnd CLI (precondition for the other examples)
curl -Lk -o ~/biz.aQute.bnd.jar \
  https://bndtools.jfrog.io/artifactory/update-latest/biz/aQute/bnd/biz.aQute.bnd/7.2.1/biz.aQute.bnd-7.2.1.jar

# create alias for easy use via 'bnd'
alias bnd='java -jar ~/biz.aQute.bnd.jar'

# display bnd version to verify installation
bnd version

This installs the bnd CLI and makes the bnd command available in your shell.

Reference: bnd CLI installation | bnd CLI documentation

# Quick wrap - automatically generates OSGi metadata
# download an example jar to wrap
curl -L -o activation.jar \
  https://repo1.maven.org/maven2/javax/activation/activation/1.1.1/activation-1.1.1.jar
# run bnd to wrap as bundle with OSGi metadata
bnd wrap activation.jar

The result is a new jar file with OSGi metadata (META-INF/MANIFEST.MF).

Reference: bnd wrap command documentation

# Use a bnd file for more control
# download an example jar to wrap
curl -L -o activation.jar \
  https://repo1.maven.org/maven2/javax/activation/activation/1.1.1/activation-1.1.1.jar

# a activation.bnd file to specify OSGi metadata
cat > activation.bnd <<EOF
-classpath: activation.jar
Export-Package: *;version=1.1.1
Bundle-Version: 1.1.1
EOF

# Generate the OSGi bundle
bnd activation.bnd

The result is a new jar file with OSGi metadata (META-INF/MANIFEST.MF).

Reference: bnd CLI advanced JAR wrapping tutorial

# Create a new workspace with templates
bnd add workspace -f demo-webapp -f osgi myworkspace

# Navigate to the workspace
cd myworkspace

# Start a live-coding / hot reload dev server
bnd dev launch.bndrun

# or alternatively just build and run without hot-reloading:
bnd build
bnd run launch.bndrun

This creates a complete bnd workspace that works identically across Eclipse, Gradle, Maven, and the command line.

Learn more: Workspace and Projects Tour

Reference: bnd add | bnd build | bnd dev | bnd run

<plugin>
  <groupId>biz.aQute.bnd</groupId>
  <artifactId>bnd-maven-plugin</artifactId>
  <version>7.1.0</version>
  <executions>
    <execution>
      <goals>
        <goal>bnd-process</goal>
      </goals>
    </execution>
  </executions>
</plugin>

This automatically generates OSGi metadata (META-INF/MANIFEST.MF) during the Maven build.

Reference: Maven plugin documentation

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

jar {
  bundle {
    bnd '''
-exportcontents: com.acme.api.*
-sources: true
'''
  }
}

This automatically generates OSGi metadata (META-INF/MANIFEST.MF) during the Gradle build.

Reference: Gradle plugin documentation

The bndtools plugin for Eclipse provides tight integration with the bnd build system. It allows you to create, build, and run OSGi projects directly from within Eclipse.

Reference: Bndtools Plugin documentation

Get started: Bndtools Workspace tutorial

What is bnd?

bnd consists of two major parts:

  1. Manifest generation – Excellent at creating JARs with OSGi metadata based on instructions and the information in class files. Used by Maven, Gradle, Ant, and other build tools.

  2. Workspace model – An IDE/build-tool-independent model of a workspace with projects that works identically across Eclipse, Maven, Gradle, and the command line.

“If you want to teach people a new way of thinking, don’t bother trying to teach them. Instead, give them a tool, the use of which will lead to new ways of thinking.” — R. Buckminster Fuller

How to get started?

The most feature-rich option is the Bndtools Eclipse plugin. There are tutorial videos and an OSGi Starter guide available.

For Maven users, start with the Maven plugins README.

For Gradle users, see the Gradle Plugins README.

The bnd CLI is great for exploration — especially the shell command.

Table of Contents