Building a cross-platform, feature-based Eclipse RCP Product with Tycho (the umpteenth)

DISCLAIMER: This solution was tested with Eclipse Indigo (3.7.2), Java JDK 1.6.0_37, Tycho 0.16.0, using a Target Definition which contains p2 repositories only, and a Product Definition which is feature-based. A “delta pack” is not needed, as all necessary plug-ins can be pulled from Eclipse release-train p2 repositories.
Other setups may work, but have not been tested.

If you build on a Windows system, you will end up with non-executable products for Mac OS X and Linux. For more information, and how to fix this, please read Building a cross-platform, feature-based Eclipse RCP Product with Tycho II: Mind your OSs.
While the info in this post can easily be found elsewhere, I’m trying to give a beginner-friendly, hopefully at least half-coherent explanation of the topic. Part of the rationale behind this is to make a note to myself, so please forgive any inaccuracies (or better still, comment on them).

When I first set out to build an RCP application, I had to declare dependencies to mavenized OSGi-bundles, which very quickly led me to Tycho, a “set of Maven plugins and extensions for building Eclipse plugins and OSGi bundles with Maven”. And while I managed to get my basic build to work relatively quickly with Tycho 0.13.0 (after a few posts to the immensely helpful tycho-user mailing list, a few questions on stackoverflow.com, and a dozen bundles of pulled out hair), I ran into problems with realizing a working cross-platform build.

When I now had to get back to exactly that with Tycho 0.16.0, which resulted in a number of build errors initially*, I stood back and had a good look at the whole picture again, just to realize how easy building cross-platform Eclipse RCP applications with Tycho really is. Iff the plug-ins in your target platform reside in p2 repositories!

*E.g., the horrific “Problems resolving provisioning plan” error (“Unable to satisfy dependency from org.eclipse.equinox.executable.feature.group”, etc.), the equally horrible “Could not determine SWT implementation fragment bundle” error, and an unlimited number of “[WARNING] No explicit target runtime environment configuration. Build is platform dependent.”

Tycho

Tycho is a great tool, and indeed is included in the Eclipse Foundation’s Common Build Infrastructure strategy. The problem it posed to me was that you (arguably?) need some insight into build mechanisms, PDE, repository technologies, OSGi, Maven, dependency resolution, etc., if you really want to get your head around it. A lot on the plate for any New Code on the Block…

What I found to be a problem when starting to use Tycho is, that documentation seemed sparse and targeted at the advanced developer who in a best-case scenario is also an Eclipse Committer. However, the situation has changed quite a bit. The focal point of Tycho documentation is still the original Tycho demo by Igor Fedorenko (Tycho project lead), to be found at http://git.eclipse.org/c/tycho/org.eclipse.tycho-demo.git/tree/ (note that Tycho has moved from Sonatype to Eclipse). Surely a very learning-by-doing option (isn’t that what it says in my blog title?), so for those after step-by-step introductions, there is Jan Sievers‘ great Tycho tutorial from the EclipseCon 2012, to be found at https://github.com/jsievers/tycho-demo (also see the tutorial homepage for EclipseCon Europe for more information).

Additionally, you will eventually hit an error message in a Tycho build, and you will find out that you share that experience with a lot of people. The problem is that the project setups involved vary, and hence you may find it hard to find a working solution for yourself. In had the experience that while you browse Google page after Google page of mailing list archives (wouldn’t it be time for a Stack Exchange-style site for Eclipse-related questions?), you get the idea that for the apparently error-prone Tycho to work, you will have to give up other amenities, such as the free choice of repository technology. This, however, turned out to be a question of getting used to it, and adopting a number of (sustainable) best practices at the same time. And: there isn’t an alternative if you want to use Maven in an Eclipse plug-in build. Also, you’re sure to gain a lot in the process. And there is always the highly responsive and very helpful tycho-user mailing list!

Target Delta POM Product Parent What?

So, back to the actual build process. What helped me a lot to disentangle the knot of technologies, dependencies, etc. (cf. title) was to take a step back and review the project setup: I am (1) developing Eclipse plug-ins in the Eclipse IDE. These plug-ins (2) declare dependencies in their MANIFEST.MF or plugin.xml, which I (3) get from the target platform via a Target Definition (in Eclipse) to make their APIs available in my code. I also need to (4) include these dependencies in my plug-ins’ feature to make them available to the plug-ins in the first place. The feature in turn is (5) included in my Product Configuration, the actual eclipse-repository type thing I want Tycho to build.

My confusion was here: I didn’t keep in mind that the Target Definition I used, and set the target platform to, is valid inside the scope of my Eclipse IDE instance only, unless I tell Tycho to use it for the build. You don’t, however, have to use the Eclipse IDE, and m2eclipse, and your Eclipse target platform to build the whole thing. Maven can be run from the command-line, assemble the target platform by itself (yes, that’s how powerful it is) and the Eclipse IDE target platform doesn’t necessarily have to “have an effect” on the build (unless… see above).

Tentative definition for this context: A target platform is the set of plug-ins available for consumption by your application.

The confusion mentioned above partly stemmed from the fact that the target platform is what’s being discussed in a lot of related queries on the web. From what I gather, some developers use a customized target platform, build a p2 repository from it, and consume this p2 repository in the Tycho build. Also from what I gather, this target platform must in turn include the org.eclipse.rcp feature, or a delta pack. And from what I keep gathering, this may lead to issues with the org.eclipse.equinox.executable.feature.group, the platform-specific SWT fragments, etc. Please do correct me if any of this is wrong.

The point is: My target platform includes plug-ins exclusively from p2 repositories. One of them is the Indigo release-train repository, the other one a repository I built myself. Therefore I can disregard my Eclipse target platform for the build, as long as I make sure I make the respective p2 repositories known to Maven/Tycho (in the (parent) POM), and allow Tycho to resolve p2 repositories in order to build the application target platform for my application from those repositories.

On topic (finally)

In order to build a cross-platform Eclipse RCP product with Tycho, make sure you tick off the following points before moving on.

  • Your target platform in Eclipse contains only references to p2 repositories.
  • Your product is feature-based. [Not sure if this does have an effect]
  • Make sure you don’t have any platform-specifications in any feature.xml or plug-in manifest (plugin.xml). [From what I've read this may influence the build]

Suppose you have a parent POM, make sure that:

  • It does specify all of the p2 repositories from your target platform.
  • It includes the target-platform-configuration Tycho plugin (TPC).
  • The TPC does NOT include a <target><artifact> section. [You would need to use this were you to use your Eclipse target platform as target platform for the build.]
  • The TPC includes the p2 resolver.
  • The TPC considers POM dependencies, if you have specified any.
  • [optional] You don’t have to include the project including your Target Definition in the build, i.e., you don’t need to add it as a module in the parent POM.

And to make the whole affair ever more visual, this is what your parent POM could (partially) look like.

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>org.newcodeontheblock.project</groupId>
  <artifactId>org.newcodeontheblock.project.parent</artifactId>
  <version>0.0.1-SNAPSHOT</version>
  <packaging>pom</packaging>
  <name>Parent Project</name>
  <modules>
  	<module>../org.newcodeontheblock.project.core</module>
  	<module>../org.newcodeontheblock.project.repository</module>
  	<module>../org.newcodeontheblock.project.feature</module>
  </modules>

  <properties>
    <tycho-version>0.16.0</tycho-version>
  </properties>

  <repositories>
    <repository>
      <id>indigo</id>
      <layout>p2</layout>
      <url>http://download.eclipse.org/releases/indigo/</url>
    </repository>

    <repository>
      <id>thirdparty</id>
      <layout>p2</layout>
      <url>http://example.com/thirdparty/updates/</url>
    </repository>
  </repositories>

   <build>
    <plugins>
      <plugin>
        <groupId>org.eclipse.tycho</groupId>
        <artifactId>tycho-maven-plugin</artifactId>
        <version>${tycho-version}</version>
        <extensions>true</extensions>
      </plugin>

      <plugin>
        <groupId>org.eclipse.tycho</groupId>
        <artifactId>target-platform-configuration</artifactId>
        <version>${tycho-version}</version>
        <configuration>
           <resolver>p2</resolver>
            <environments>
              <environment>
                <os>linux</os>
                <ws>gtk</ws>
                <arch>x86_64</arch>
              </environment>
              <environment>
                <os>win32</os>
                <ws>win32</ws>
                <arch>x86_64</arch>
              </environment>
            </environments>
        </configuration>
      </plugin>
    </plugins>
    </build>

</project>

So, this worked for me. Let me know if it works for you as well!

TwitterFacebookGoogle+EmailLinkedInPinterestDiggRedditStumbleUpon
If you found this post helpful, you may want to consider donating to help cover server costs.
Tagged with: , , , , , , , , , , , , , , , , , , , ,
Posted in Build, Eclipse RCP, Maven, Tycho

Leave a Comment

%d bloggers like this: