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 -L -o biz.aQute.bnd-7.1.0.jar \
	https://bndtools.jfrog.io/artifactory/update-latest/biz/aQute/bnd/biz.aQute.bnd/7.1.0/biz.aQute.bnd-7.1.0.jar
$ alias bnd='java -jar "$PWD/biz.aQute.bnd-7.1.0.jar"'

# 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
$ bnd wrap activation.jar

# 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

<!-- Generates OSGi metadata during build process -->
<!-- Adds manifest headers and processes annotations -->

<pluginRepositories>
    <pluginRepository>
        <id>bnd-releases</id>
        <url>https://bndtools.jfrog.io/bndtools/libs-release/</url>
        <layout>default</layout>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </pluginRepository>
</pluginRepositories>

<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>

// Extends the jar task to generate OSGi bundles
// Automatically calculates imports/exports from bytecode
plugins {
  id "biz.aQute.bnd.builder" version "7.1.0"
}

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

# 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 to run the application during development in an editor
$ bnd dev launch.bndrun

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

What is bnd?

“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

bnd is the engine behind a number of popular software development tools that support OSGi. It can be found in several maven plugins, ant, gradle, and of course Eclipse (bndtools). It actively seeks other build tool vendors to use bnd to improve the quality of the generated OSGi metadata.

bnd actually consists of 2 major parts, one part is really good in creating a JAR with OSGi meta data based on instructions and the information in the class files. Over time bnd has collected hundreds of heuristics that provide for good bundles. This part is therefore often used in build tools like maven or gradle that already generate JARs. They mainly use the manifest generation features of bnd.

The other part is a IDE/build tool independent model of a workspace with projects. This was the result of the frustration that certain things could be done very well in Eclipse but that other things are best done in a command line tool. Since IDEs are incremental and very event driven, command line tools tend to run everything from start to end. What was needed was an independent model that could work with Eclipse, maven, ant, gradle, and hopefully one day Intellij.

So to use bnd, look at the the descriptions of the tools that include bnd. Then when you want to find out what a certain command does, or how to call a macro, then use this manual.

How to get started?

There are several different ways to get started with bnd. The most elegant one is to start with Bndtools Eclipse IDE. There are a number of videos available that provide a gentle introduction. There is also an accompanying OSGi Starter that provides a lot of detail how to use bnd for larger projects. It includes a Gradle plugin out of the box that will build the Bndtools workspace identical to how things are build inside Eclipse for Continuous Integration with Github Actions or other build servers.

If you insist on using Maven, then you can start with the description of the Maven plugins.

There is also a Gradle plugin that is the preferred way to build OSGi bundles with plain old vanilla Gradle. This is described in the Gradle Plugins readme.

If you just want to figure out how different commands and macros work, the bnd commandline is your friend. Especially the shell command is very useful exploring it.

Last but not least, the whole source code is on GitHub. So feel free to explore it. And when you like, we're very actively taken outside PR's. There is a lot of activity going on.

Table of contents

1. Introduction
2. How to install bnd
3. Guided Tour Workspace & Projects
4. bnd / bndlib Features and JAR Wrapping Techniques
5. Concepts
6. Background
7. Best practices
8. Build
9. Project Setup
10. Generating JARs
11. Versioning
12. Baselining
13. Service Components
14. Metatype
15. Contracts
16. Bundle Annotations
17. Accessor Properties
18. SPI Annotations
19. Resolving Dependencies
20. Launching
21. Startlevels
22. Testing
23. Testing with Launchpad
24. Packaging Applications
25. JPMS Libraries
26. Wrapping Libraries to OSGi Bundles
27. Generating Documentation
28. bnd CLI Commands
29. For Developers
30. Templates for Workspaces
31. Tips for Windows users
32. Tools bound to bnd
33. Reference
34. Headers
35. Instruction Reference
36. Instruction Index
37. Macro Reference
38. Macro Index
39. Plugins
40. External Plugins
41. Settings
42. Errors
43. Warnings
44. FAQ - Frequently Asked Questions