Tycho/How Tos/Dependency on pom-first artifacts

Demo application

• Checkout demo application

git clone http://git.eclipse.org/gitroot/tycho/org.eclipse.tycho-demo.git

Demo application itp02 consist of two parts, build01 and build02.

build01

First part (i.e. build01) is a simple project that uses maven-bundle-plugin to generate OSGi bundle manifest.

pomfirst-bundle is a simple project with packaging=jar that uses maven-bundle-plugin:manifest goal to generate bundle manifest based on sources of the project and their external dependencies, plexus-utils in this particular example.

pomfirst-thirdparty does not have any sources itself, but "wraps" thirdparty library available from maven repository in an OSGi bundle.

You can read more about maven-bundle-plugin here, but important point to note, this is not a tycho project. Artifacts installed into local repository have correct OSGi bundle manifest, but does not have any tycho or p2 specific information.

build02

Second part (i.e. build02) is a multi-module tycho project. tycho.demo.itp02.bundle is eclipse-plugin project which depends on pom-first project via Import-Package: tycho.demo.itp02.pomfirst in bundle manifest. tycho.demo.itp02.bundle.tests is a simple junit4 test project.

Building from command line

• Build pom-first project

cd itp02/build01/pomfirst-bundle
MAVEN_HOME/bin/mvn clean install

This will build and install tycho.demo.itp02:pomfirst-bundle:1.0.0-SNAPSHOT into Maven local repository. The build is expected to succeed.

• Build tycho project

cd ../../build02
MAVEN_HOME/bin/mvn clean install

This will build both build02 modules and the build is expected to succeed.

What happens under the hood

There are two "interesting" elements in build02/pom.xml.

First, there is dependency on the pom-first project Note: The dependencies that the target platform will consider are the ones defined in the pom.xml that specifies the target-platform-configuration. Your bundles should not have any Maven dependencies since OSGi dependencies are specified Manifest-First in MANIFEST.MF as Import-Package (or Require-Bundle).

<dependency>
<groupId>tycho.demo.itp02</groupId>
<artifactId>pomfirst-bundle</artifactId>
<version>1.0.0-SNAPSHOT</version>
</dependency>

Second, there is pomDependencies target platform configuration parameter.

<plugin>
<groupId>org.sonatype.tycho</groupId>
<artifactId>target-platform-configuration</artifactId>
<version>${tycho-version}</version>
<configuration>
<resolver>p2</resolver>
<pomDependencies>consider</pomDependencies>
</configuration>
</plugin>

pomDependencies=consider tells tycho target platform resolver (p2-based in this example) to consider <dependencies/> element. In case of p2-based TP resolver, this is a multistep process

1. p2 metadata is generated for all maven dependencies. Currently this only works for OSGi bundles, all other depenedncies are silently ignored.
2. generated p2 metadata is merged with p2 metadata from configured local and remote repositories
3. p2 resolver is invoked to calculate project build target platform, i.e. transitive set of dependencies
4. finally, equinox resolver is used to resolve actual project dependencies using set of bundles from build target platform

Importing in m2e 0.13.0

Starting with version 0.5.0-SNAPSHOT, m2eclipse-tycho has been extended to provide limited interoperability between Tycho manifest-first and maven-bundle-plugin pom-first projects, including experimental support for "wrapper" bundles that embed thirdparty dependencies using <Embed-Dependency> instructions.

Download Eclipse 3.7 RC1 or newer "Classic" distribution from http://eclipse.org/downloads/. Then install m2e 0.13.0 RC1 or newer from Indigo p2 repository.

Using m2e standard "Existing Maven Project" import wizard, select itp02 directory (i.e. the parent directory of build01 and build02).

M2E is expected to find all pom-first and manifest-first projects and automatically offer installation of m2eclipse-tycho from m2e marketplace

Allow installation of m2eclipse-tycho and confirm workspace restart when prompted.

Upon workspace restart, m2e is expected to automatically complete project configuration and it should be possible to successfully run tycho.demo.itp02.bundle.tests as JUnit Plug-In Test from IDE.

Due to a bug in m2eclipse-tycho or PDE, tycho.demo.itp02.bundle and tycho.demo.itp02.bundle.tests sometimes have compilation errors after import. Although we are not able to reproduce the problem reliably, the following workaround appears to work select all workspace projects, right-click, Maven, Update Project Configuration. clean build all workspace projects

Limitations

It is not possible to mix pom-first and manifest-first projects in the same reactor build.

Dependency resolution happens very early during maven build, before execution of build lifecycle of any project and well before bundle manifests can be generated for pom-first projects. To resolve dependencies of manifest-first projects, however, Tycho needs to to read bundle manifests of all pom-first artifacts.

This limitation cannot be relaxed without fundamental changes to Maven build lifecycle. Currently, the only solution is to build pom-first projects separately, before building manifest-first projects.

Pom-first dependencies of manifest-first projects are not fully transitive

Consider the following related projects, all built separately

• ProjectA, is a pom-first project with regular maven dependencies.
• ProjectB, is a manifest-first project with pom-first dependency on ProjectA
• ProjectC, is a manifest-first project with regular OSGi dependency on ProjectB

Currently, ProjectC build will fail because pom-first are not transitive.

Workaround is to add pom-first dependency on ProjectA to ProjectC. It is likely Nexus/Pro OSGi support will provide more elegant solution to this problem sometime in the future.

Local target platform resolver (i.e. -Dtycho.targetPlatform=...) ignores pomDependencies=consider

No good excuses here and it should be fairly straightforward to implement. (this may have been added in 0.9.0, but the committer unfortunately did not provide integration test(s), so I can't tell for sure)