Tycho user docs

Overview

Tycho is a set of Maven plugins and extensions for building Eclipse and OSGI artifacts with Apache Maven. Eclipse and OSGI artifacts have their own metadata for expressing dependencies, source folder locations, etc. that are normally in a Maven POM. Users can choose to generate POM files from the native form ("manifest-first" mode) or generate native files from POM files ("POM-first" mode).

Manifest-first mode is (at present) best developed. To build in this mode is something like:

(1) Run Maven generate-poms

• Specify Eclipse target platform to build against
• Specify directories where source bundles, features, etc. can be found
• Specify "root" project, if you want e.g., to only generate poms for projects required to build a given update site

RESULT: create pom.xml/poma.xml in each project

(2) Run Maven build and/or test

• Specify Eclipse target platform to build against
• Specify test class and bundle to start only a given test suite

RESULT: build target (e.g., update site), run associated tests

MANIFEST-first projects

Overview of MANIFEST-first mode

Tycho introduces maven extensions, packaging types and corresponding lifecycle bindings that allow maven to use OSGi and Eclipse metadata during maven build. OSGi rules are used to resolve project dependencies and package visibility restrictions are honoured by OSGi-aware java compiler.

Target platform

In Eclipse PDE, the "target platform" is roughly speaking the Eclipse installation where the projects being developed will be deployed. When building, the OSGi dependency resolver uses the bundles in the target platform to resolve dependencies not in the source projects.

At present users specify a directory containing the target platform when building (see below).

Supported packaging types

eclipse-plugin

This packaging type corresponds to Eclipse Plug-in and Plug-in Fragment projects. By default, tycho will use compile source roots defined in build.properties file. Minimum required pom.xml

<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/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>some-group-id</groupId>
  <artifactId>Bundle-SymbolicName</artifactId>
  <version>Bundle-Version</version>
  <packaging>eclipse-plugin</packaging>

</project>

Values of artifactId and version elements must match corresponding values from bundle manifest (also see "-SNAPSHOT versions" below).

build/sourceDirectory is needed to tell Maven location of Java sources. As most of project configuration element, it can be inherited from from parent pom.

Since Tycho uses OSGi bundle manifest to determine project dependencies, pom.xml file should NOT contain <dependency/> section, and any dependencies inherited from parent project will be ignored by the build.

eclipse-test-plugin

Maven projects typically have separate test source directories in the same project. The Eclipse convention, however, is to have a separate test bundle (often a fragment of the host/target plugin with the suffix ".tests"). Tycho introduces new eclipse-test-plugin packaging type to represent such projects. Build behavior is like regular Eclipse plugins, but these are treated specially at test-time.

Minimum pom.xml

<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/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>some-group-id</groupId>
  <artifactId>Bundle-SymbolicName</artifactId>
  <version>Bundle-Version</version>
  <packaging>eclipse-test-plugin</packaging>

</project>

org.codehaus.tycho:maven-osgi-test-plugin:test mojo executes plug-in unit tests and it is bound to integration-test build phase. Internally, maven-osgi-test-plugin uses the same Surefire test framework as other maven projects and test mojo supports most of the parameters of standard maven-surefire-plugin but only junit 3.8.x is supported at the moment. maven-surefire-plugin supports both headless and UI-based tests, but use of UI test harness has to be explicitly enabled, as follows:

<build>
    <sourceDirectory>src</sourceDirectory>
    <plugins>
      <plugin>
        <groupId>org.codehaus.tycho</groupId>
        <artifactId>maven-osgi-test-plugin</artifactId>
        <version>0.3.0-SNAPSHOT</version>
        <configuration>
          <useUIHarness>true</useUIHarness>
        </configuration>
      </plugin>
    </plugins>
  </build>

eclipse-feature

This packaging type corresponds to Eclipse Feature project and requires the following minimum pom.xml

<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/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>some-group-id</groupId>
  <artifactId>feature id</artifactId>
  <version>feature version</version>
  <packaging>eclipse-feature</packaging>

</project>

Similar to eclipse-plugin projects, artifactId and version attributes must match id and version attributes of feature.xml file.

eclipse-application

This packaging is used on tycho do represent a Product and doesn't have a correspondent project at Eclipse (Since Product Configurations are only a file at Eclipse, not a project kind)  and requires the following minimum pom.xml

<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/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>some-group-id</groupId>
  <artifactId>product id</artifactId>
  <version>product version</version>
  <packaging>eclipse-application</packaging>

</project>

This packaging can be used to products based on plugins or based on features.

eclipse-update-site

This packaging type corresponds to Eclipse Update Site project and requires the following minimum pom.xml

<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/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>some-group-id</groupId>
  <artifactId>feature id</artifactId>
  <version>feature version</version>
  <packaging>eclipse-update-site</packaging>

</project>

Complete update site is generated in ${project.build.outputDirectory}/site directory.

Most users will use the update site a

Generating pom.xml file for Eclipse PDE projects

Tycho provides a simple maven plugin that creates working pom.xml for Eclipse PDE projects. It can be invoked for a single project or for all projects in the current directory. In the latter case, Tycho will generate parent pom.xml file and corresponding <parent/> element in module pom.xml files.

To generate pom.xml files execute the following command

$TYCHO_HOME/bin/mvn org.codehaus.tycho:maven-tycho-plugin:generate-poms

pom.xml file generator supports the following parameters:

• baseDir directory to look for Eclipse PDE projects. The default value is the current working directory. Augmented with "extraDirs" below.
• groupId groupId to use in generated pom.xml file. It is required for generation of parent pom.xml file.
• version version to use in generated pom.xml files. The default is 0.0.1-SNAPHSHOT. This parameter is ignored for eclipse-plugin and eclipse-feature projects where the version is taken from the manifest.mf or feature.xml.
• aggregator boolean, only applicable for Update Site projects. If true (the default) generated pom.xml file will include aggregator profile that lists all feature and plugin projects referenced by the site.xml.
• extraDirs string, comma separated list of extra directories to look for Eclipse PDE projects (beyond basedir, above).

Downloading sources from Mapfile

Tycho provides a maven plugin capable of processing Mapfiles.  It will open the mapfile and download all described sources.

The general usage is:

$TYCHO_HOME/bin/mvn org.codehaus.tycho:maven-tycho-plugin:import-mapfile -Dmapfile=MY_MAP_FILE.txt

import-mapfile parameters:

• mapfile mapfile containing the sources information.

If your CVS server requires authentication (even anonymous authentication) is necessary to use native CVS implementation. To achieve that use the following parameter:

-Dmaven.scm.provider.cvs.implementation=cvs_native

Note native CVS implementation will use the command line CVS available at your OS. If it is not installed you will need to install it.

Signing jar files

JAR file signing can be enabled with the following configuration properties

• keystore path to keystore (eg, -Dkeystore=/home/igor/.keystore)
• storepass keystore password
• alias keystore entry alias
• keypass keystore entry password

At the moment tycho directly supports jar signing during update site packaging. Use sign mojo from maven-jar-plugin to sign individual plugin jars.

Installing and running Tycho

See tycho demo script for current state of affairs

Sample: Build update site, running associated tests

mvn integration-test \
    -f "updatesite/poma.xml"\
	-Dtycho.targetPlatform=/home/me/tp\
	-DtestSuffix=.tests\
	-DtestSuite=com.company.app.tests\
	-DtestClass=com.company.app.tests.MasterTestSuite

Using local eclipse installation as target platform

In MANIFEST-first mode, Tycho can use local Eclipse 3.2, 3.3 or 3.4 installation as build target platform. Location of the Eclipse installation can be specified using tycho.targetPlatform maven property. For example,

C:\tycho\bin\mvn package -Dtycho.targetPlatform=T:/eclipse-SDK-3.3.2-win32/eclipse

Customizing OSGi resolver

OSGi resolver uses os/ws/arch parameters to determine which platform-specific bundles and bundle fragments to use and Tycho provides default values for these properties based on operating system and hardware configuration of the system it runs on. For cross-platform builds (i.e. building against Linux target platform on Windows XP machine), it is possible to set os/ws/arch paremeters using osgi.os, osgi.ws and osgi.arch maven properties respectively. For example,

<settings>
  <profiles>
    <profile>
      <id>tycho</id>
      <properties>
        <osgi.os>linux</osgi.os>
        <osgi.ws>gtk</osgi.ws>
        <osgi.arch>x86_64</osgi.arch>
      </properties>
    </profile>
  </profiles>
  <activeProfiles>
    <activeProfile>tycho</activeProfile>
  </activeProfiles>
</settings>

Mapping between Maven groupId/artifactId and OSGi

TBD

Tentatively, Tycho uses MavenArtifact-GroupId, MavenArtifact-ArtifactId and MavenArtifact-BaseVersion bundle manifest attributes to define Maven artifact groupId, artifactId and version respectively.

Future work

POM-first projects (TBD, under development)

Tycho introduces new maven packaging type TDB and corresponding lifecycle bindings that generate OSGi bundle manifest as part of process-classes maven build phase.

Generating target platform

Tycho in the future will support building the target platform itself. The target platform can be defined as project dependencies in POMs and Tycho will automatically download all necessary artifacts from remote repositories and assemble target platform during the build (details TBD). It is also possible to use local Eclipse installation as build's target platform. If bundles with the same symbolic name are present both in the build and in the target platform, then bundles from the target platform will be ignored (with a warning).

eclipse-plugin support for maven-specific manifest attributes

TODO: groupId and maven-specific manifest attributes

wrapping existing maven artifacts into OSGi bundles

TBD