tycho: How to create a new OSGi bundle

About

User documentation

How to create a new OSGi bundle
Target platform management

Development

Introduction

This tutorial describes how to create a new OSGi bundle in Eclipse and build it with Tycho.

Prerequisites

This tutorial assumes that you have installed a Java SDK, Eclipse and Tycho. For better understanding it would be helpful if you had a basic understanding of Java, OSGi, Eclipse and Maven. See ’Further Reading’ below.

Prepare Target Platform

In Eclipse PDE, the ’target platform’ is roughly speaking the Eclipse installation where the projects being developed will be deployed. This can e.g. be a complete Eclipse installation or a minimal OSGi runtime. The target platform is not only used for the execution environment during runtime, but also in the build for resolving artifacts.

To keep things simple we are using minimal OSGi target platform containing only the OSGi framework component. For convenience reasons we have already prepared it as a P2 repository. Download and extract it to c:p2equinox.

For using the target platform in Eclipse go to Window -> Preferences -> Plug-In Development -> Target Platform and add a new one based on an empty definition. In the next screen add the c:p2equinox directory. Give the definition a useful name like "Standalone Equinox 3.5.1". The resulting definition should look like:

equinox-tp.png

After having finished the definition select the configuration to make it active.

Create a new OSGi bundle in Eclipse

Now we’re ready to create a new OSGi bundle. In Eclipse, bundles are developed with the PDE (the Eclipse Plug-in development tooling). So, to start developing a new bundle, create a new Plug-In project. Give it a meaningful name like "com.sap.demo.helloworldplugin". Select a ’standard’ OSGi environment as target platform and proceed to the next screen. You can keep the defaults here. On the next screen, select the "Hello OSGi Bundle" as template for our new project and press ’Finish’.

Running the OSGi bundle in Eclipse

You should immediately be able to run the newly created project by right clicking and choosing Run As -> OSGi Framework. On the console the bundle should report with ’Hello World!’ that it has been activated. You can terminate the running application by entering ’exit’.

Building the OSGi bundle with Tycho

Tycho follows the Manifest-first approach, that means that it directly reads out information from the OSGi manifest file and the Eclipse build.properties file for the Maven build. Additionaly (at least for now) it needs a Maven pom.xml file with some minimal information about the project. Although Tycho is able to generate a pom.xml for existing projects, we will specify our own because Tycho isn’t able to create parent and module relationships properly.

Firstly, we need to create another project in Eclipse which will serve as the parent project for Maven where some general settings are made:

Create a ’general project’ and name it ’com.sap.demo.helloworldparent’
Create a pom.xml file with the following content

<?xml version="1.0" encoding="UTF-8"?>
<project
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"
	xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<modelVersion>4.0.0</modelVersion>
	<groupId>com.sap.demo</groupId>
	<artifactId>com.sap.demo.helloworld_parent</artifactId>
	<version>1.0.0-SNAPSHOT</version>
	<packaging>pom</packaging>
	<build>
		<plugins>
			<plugin>
				<groupId>org.codehaus.tycho</groupId>
				<artifactId>target-platform-configuration</artifactId>
				<configuration>
					<resolver>p2</resolver>
				</configuration>
			</plugin>
		</plugins>
	</build>
	<modules>
		<module>../com.sap.demo.helloworld_plugin</module>
		<module>../com.sap.demo.helloworld_feature</module>
		<module>../com.sap.demo.helloworld_updatesite</module>
	</modules>
	<repositories>
		<repository>
			<id>equinox</id>
			<url>file:c:/p2/equinox</url>
			<layout>p2</layout>
		</repository>
	</repositories>
</project>

Notes:

The build plugin configuration for org.codehaus.tycho.target-platform-configuration activates the P2 resolver which allows us to consume P2 repositories in the Maven build
The modules configuration is optional. It’s just for convenience. Once all projects are setup up you can build all projects at once by executing ’mvn clean package’ in the parent project directory
The repository configuration activates the local equinox P2 repository as target platform for the Maven build

Now create another pom.xml file for the ’com.sap.demo.helloworldplugin’ project:

<?xml version="1.0" encoding="UTF-8"?>
<project
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"
	xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<modelVersion>4.0.0</modelVersion>
	<artifactId>com.sap.demo.helloworld_plugin</artifactId>
	<packaging>eclipse-plugin</packaging>
	<version>1.0.0-SNAPSHOT</version>
	<parent>
		<artifactId>com.sap.demo.helloworld_parent</artifactId>
		<groupId>com.sap.demo</groupId>
		<version>1.0.0-SNAPSHOT</version>
		<relativePath>../com.sap.demo.helloworld_parent/pom.xml</relativePath>
	</parent>
</project>

Notes:

By specifying a parent project the plugin project inherits all configuration, in our case especially the P2 resolver and target platform configuration
.qualifier in OSGi manifest is replaced by eclipse with a timestamp when exporting a build of the project. -SNAPSHOT does similar things in the Maven world. The usage of .qualifier and -SNAPSHOT must match.
Bundle-SymbolicName and artifactId must match
groupId has no matching counterpart in the OSGi manifest
eclipse-plugin, eclipse-feature, eclipse-update-site and others are special Maven packaging types brought by Tycho

Now the bundle can be built with Tycho: Open a command line window and change to the directory where you created the bundle project ’com.sap.demo.helloworldplugin’. Then call mvn clean install.

As a result you will get a bundle jar in the target directory.

Running the OSGi bundle from the command line

You can now already run the OSGi bundle from the command line in the Equinox framework. Execute on the command line from the bundle project directory:

java -jar c:p2equinoxpluginsorg.eclipse.osgi_3.5.1.R35x_v20090827.jar -console

Install the newly created bundle in the OSGi framework:

install file:targetcom.sap.demo.helloworld-1.0.0-SNAPSHOT.jar

The ’install’ command reports the bundle id of the newly installed bundle. Now you can start it:

start <bundleid>

As previously in Eclipse this should print ’Hello World!’ on the standard output. If you leave Equinox with ’exit’ the current state (regarding installed and started bundles) is saved and restored on next startup.

Creating an Update Site / P2 repository

To publish our helloworldplugin bundle into a P2 repository where it can be consumed, we have to create another two projects: A feature project which groups plugins together and an update site project which finally is able to publish the features:

Create the feature project and name it ’com.sap.demo.helloworldfeature’. On the next screen select ’com.sap.demo.helloworld (1.0.0.qualifier)’ in the ’initialize from the plug-ins list’ selection to reference the helloworldplugin in the feature. Next, we have again to create a pom.xml file in the project root to be able to build it with Maven:

<?xml version="1.0" encoding="UTF-8"?>
<project
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"
	xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<modelVersion>4.0.0</modelVersion>
	<artifactId>com.sap.demo.helloworld_feature</artifactId>
	<packaging>eclipse-feature</packaging>
	<version>1.0.0-SNAPSHOT</version>
	<parent>
		<artifactId>com.sap.demo.helloworld_parent</artifactId>
		<groupId>com.sap.demo</groupId>
		<version>1.0.0-SNAPSHOT</version>
		<relativePath>../com.sap.demo.helloworld_parent/pom.xml</relativePath>
	</parent>
</project>

Note that the only differences to the plugin project are the project’s artifactId and the packaging type. All necessary configuration is again inherited from the parent POM. On the command line change to the project’s directory and execute mvn clean install to build the feature project.

Finally, we have to create the ’Update Site Project’ in Eclipse. Name it ’com.sap.demo.helloworldupdatesite’ and press finish. Afterwards, open the site.xml file and add the ’com.sap.demo.helloworldfeature’ feature. To always reference the latest version, open the XML view and change all occurences of ’1.0.0.qualifier’ to the ’magic’ version ’0.0.0’. To get the Maven build going put the following pom.xml at the project root:

<?xml version="1.0" encoding="UTF-8"?>
<project
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"
	xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<modelVersion>4.0.0</modelVersion>
	<artifactId>com.sap.demo.helloworld_updatesite</artifactId>
	<packaging>eclipse-update-site</packaging>
	<version>1.0.0-SNAPSHOT</version>
	<parent>
		<artifactId>com.sap.demo.helloworld_parent</artifactId>
		<groupId>com.sap.demo</groupId>
		<version>1.0.0-SNAPSHOT</version>
		<relativePath>../com.sap.demo.helloworld_parent/pom.xml</relativePath>
	</parent>
</project>

You can now change to the project’s directory and execute mvn clean install to produce the update site in ’target/site’. This is a P2 repository which could now be consumed e.g. by Eclipse or other Maven/Tycho builds as target platform.