README.md

bnd-run-maven-plugin

The bnd-run-maven-plugin is a bnd based plugin to run a framework from bndrun files.

What does the bnd-run-maven-plugin do?

Point the plugin to one bndrun file in the same project. The bndrun file should be resolved (using the bnd-resolver-maven-plugin). This plugin will launch it using bnd's project launching mechanism.

This plugin can only be invoked directly.

mvn bnd-run:run

An example configuration.

    <plugin>
        <groupId>biz.aQute.bnd</groupId>
        <artifactId>bnd-run-maven-plugin</artifactId>
        <version>${bnd.version}</version>
        <configuration>
            <failOnChanges>false</failOnChanges>
            <includeDependencyManagement>true</includeDependencyManagement>
            <bndrun>mylaunch.bndrun</bndrun>
        </configuration>
    </plugin>

Here's an example setting the bundles used for execution.

    ...
    <configuration>
        ...
        <bundles>
            <bundle>bundles/org.apache.felix.eventadmin-1.4.8.jar</bundle>
            <bundle>bundles/org.apache.felix.framework-5.4.0.jar</bundle>
        </bundles>
    </configuration>
    ...

Multiple bndrun Files per project

The bnd-run-maven-plugin supports multiple bndrun files per project when a unique execution is created for each one allowing each run invocation to be executed by id using the command pattern bnd-run:run@<execution-id>.

Note: It is highly recommended to give every bnd-run-maven-plugin execution a unique id, even if there is only one in the project. See Live Coding.

<plugin>
  <groupId>biz.aQute.bnd</groupId>
  <artifactId>bnd-run-maven-plugin</artifactId>
  <!-- shared configuration -->
  <configuration>
    <includeDependencyManagement>true</includeDependencyManagement>
  </configuration>
  <executions>
    <execution>
      <id>foo</id>
      <configuration>
        <bndrun>foo.bndrun</bndrun>
      </configuration>
    </execution>
    <execution>
      <id>bar</id>
      <configuration>
        <bndrun>bar.bndrun</bndrun>
      </configuration>
    </execution>
  </executions>
</plugin>

For example, executing a run for bar.bndrun as configured above would be:

mvn bnd-run:run@bar

Live Coding

To enable live coding the maven package phase must be called in conjunction with the run invocation. This causes the artifacts discovered for satisfying the bndrun file's -runbundles instruction to be those found in the target directory (as opposed to locally installed artifacts). The run execution must remain active in the foreground during development.

Once the run is executing the bnd launcher takes care to reload modified artifacts. Therefore; any tooling which cause the project target artifacts to be rebuilt automatically can participate in live coding.

Live Coding With Eclipse

When using bndtools M2E Eclipse plugin on a maven project configured to use the bnd-maven-plugin the jar plugin is invoked with each code change, automatically regenerating the target artifact. Therefore; no further configuration is required to use live coding.

Live Coding With Intellij IDEA

Live coding can be enabled with Intellij IDEA using maven goal configurations as described in this blog post.

Multi-module Live Coding

A common maven pattern is having a multi-module structure; referred to as a reactor project. In this model a POM file contains a <modules> element listing a number of child modules (a.k.a. projects) which are built at once, in succession. In order to use this model with the bnd-run-maven-plugin with the goal of having each child module participate in live coding (so that each one is automatically reloaded):

1. the bnd-run-maven-plugin must be configured for every project such that invoking the plugin execution from the reactor does not result in errors (the plugin silently ignores projects not having bndrun files configured)

2. bnd-run-maven-plugin executions must have execution ids that are unique within the whole reactor so that any one can be invoked directly as described in Multiple bndrun Files per project

3. the bnd-run:run invocation must be run from the reactor along with the package phase as described in Live Coding

The resulting invocation from the reactor, where one of the modules is configured with a bnd-run-maven-plugin execution with id bar, should then be:

mvn package bnd-run:run@bar

Bndrun Details Inferred from Maven

The -runee and -runrequires values can be inferred from the maven project as follows:

• -runee, if omitted from the bndrun file, will be inferred from the <target> configuration of maven-compiler-plugin
• -runrequires, if omitted from the bndrun file, will be inferred from the project's artifactId and applied as osgi.identity;filter:='(osgi.identity=<artifactId>)', if the project packaging is jar or war and the project has the bnd-maven-plugin

Implicit Repository

An implicit repository containing the project artifact and project dependencies (as defined through the configuration of bundles, scopes, useMavenDependencies and includeDependencyManagement) is created and added when this plugin is executed.

Configuration Properties

Configuration Property	Description
bndrun	A bndrun file to run. The file is relative to the ${project.basedir} directory. Override with property bnd.run.file.
bundles	A collection of files to include in the implicit repository. Can contain bundle child elements specifying the path to a bundle. These can be absolute paths. You can also specify include and exclude child elements using Ant-style globs to specify bundles. These are relative to the ${project.basedir} directory. Defaults to dependencies in the scopes specified by the scopes property, plus the current artifact (if any and useMavenDependencies is true).
useMavenDependencies	If true, adds the project dependencies subject to scopes to the collection of files to include in the implicit repository. Defaults to true.
scopes	Specify from which scopes to collect dependencies. Defaults to compile, runtime. Override with property bnd.run.scopes.
includeDependencyManagement	Include <dependencyManagement> subject to scopes when collecting files to include in the implicit repository. Defaults to false. Override with property bnd.run.include.dependency.management.
skip	Skip the project. Defaults to false. Override with property bnd.run.skip.