View source for Tycho/Packaging Types

This page documents the packaging types available in the latest Tycho release. See [https://wiki.eclipse.org/index.php?title=Tycho/Packaging_Types&action=history History] to discover when new packaging types were added. 

<pre>
<properties>
  <tycho-version>1.2.0</tycho-version>
</properties>

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

== 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

<pre>
<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>
</pre>

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

Since Tycho uses OSGi bundle manifest to determine project dependencies, pom.xml file should NOT contain <tt><dependency></tt> 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 <tt>eclipse-test-plugin</tt> packaging type to represent such projects. Build behavior is like regular Eclipse plugins, but these are treated specially at test-time.

Minimum pom.xml
<pre>
<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>
</pre>

<tt>org.eclipse.tycho:tycho-surefire-plugin:test</tt> mojo executes JUnit plug-in tests and it is bound to the integration-test build phase. Other than than, the tycho-surefire-plugin is similar to the standard maven-surefire-plugin, and it supports most of the parameters of the maven-surefire-plugin (see [https://www.eclipse.org/tycho/sitedocs/tycho-surefire/tycho-surefire-plugin/test-mojo.html site doc] for details). The tycho-surefire-plugin supports both headless and UI-based tests, but use of UI test harness has to be explicitly enabled, as follows:

<pre>
  <build>
    <sourceDirectory>src</sourceDirectory>
    <plugins>
      <plugin>
        <groupId>org.eclipse.tycho</groupId>
        <artifactId>tycho-surefire-plugin</artifactId>
        <version>${tycho-version}</version>
        <configuration>
          <useUIHarness>true</useUIHarness>
        </configuration>
      </plugin>
    </plugins>
  </build>
</pre>

The OSGi runtime for the test execution consists of the test bundle/fragment and its dependencies. If needed, you can add more features ("eclipse-feature"), bundles/fragments ("eclipse-plugin"), or installable units ("p2-installable-unit"), each including their transitive dependencies, to the test runtime. The recommended way to do this is to add an extraRequirements configuration to the target-platform-configuration (!) plugin. Example:

<pre>
<plugin>
   <groupId>org.eclipse.tycho</groupId>
   <artifactId>target-platform-configuration</artifactId>
   <version>${tycho-version}</version>
   <configuration>
      <dependency-resolution>
         <extraRequirements>
            <requirement>
               <type>eclipse-feature</type>
               <id>myproject.app.feature</id>
               <versionRange>1.0.0</versionRange>
            </requirement>
         </extraRequirements>
      </dependency-resolution>
   </configuration>
</plugin>
</pre>

Tips:
* Tests typically fail if implicit dependencies are missing, e.g. if your bundle or a referenced bundle makes use of declarative services, but there is no explicit reference to the bundle org.eclipse.equinox.ds. The same problem can occur when your users install your bundles with p2. Therefore it is a good idea to make the implicit dependencies of your bundles explicit through the feature used to ship your bundles, e.g. by adding a dependency to org.eclipse.equinox.ds in the feature. Configuring this feature in the tycho-surefire-plugin configuration should then also make the test runtime complete.
* In order to add native fragments for several target environments, e.g. the SWT fragments, add a feature that contains all of them, e.g. the feature org.eclipse.rcp.

== eclipse-feature ==

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

<pre>
<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>
</pre>

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

Tycho supports [http://help.eclipse.org/juno/index.jsp?topic=/org.eclipse.pde.doc.user/tasks/pde_rootfiles.htm root properties] in the build.properties file, which can be used to add files to the root of a product installation. (Limitation: <tt>root.folder</tt> properties are currently not supported. Wildcard patterns are supported since Tycho 0.17.0.)

Limitation: The <tt>unpack</tt> attribute in the <tt>feature.xml</tt> is ignored. If you need a bundle to be installed in unpacked form, specify <tt>Eclipse-BundleShape: dir</tt> in the manifest of the bundle.  If this is a third party bundle, it will mean repackaging it to include this Eclipse proprietary value.

== eclipse-repository ==

The packaging type eclipse-repository is used for aggregating content into a p2 repository (aka "update site"). It can also be used for building Eclipse/RCP application distributions. See [[Tycho/eclipse-repository]] for more information.

== eclipse-application ==

{{caution | Deprecated | The packaging type eclipse-application is deprecated. To build Eclipse/RCP application installations, use the packaging type eclipse-repository instead.}}

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

<pre>
<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>
</pre>

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

== eclipse-update-site ==

{{caution | Deprecated | The eclipse-update-site type is deprecated in favour of eclipse-repository.  eclipse-update-site will be removed in a future release.}}

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

<pre>
<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>
</pre>

Complete update site is generated in <tt>$\{project.build.outputDirectory\}/site</tt> directory.

=== Archive Update Site Content ===

To archive the complete content of the generated update site you need to add this configuration:

<pre>
<build>
  <plugins>
    <plugin>
      <groupId>org.eclipse.tycho</groupId>
      <artifactId>tycho-packaging-plugin</artifactId>
      <configuration>
        <archiveSite>true</archiveSite>
      </configuration>
    </plugin>
  </plugins>
</build>
</pre>


== eclipse-target-definition ==

This packaging is used in Tycho to represent a [[PDE/Target Definitions|PDE target definition]]. It is available since version 0.16.0 and requires the following minimum pom.xml

<pre>
<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>target-definition-id</artifactId>
  <version>target-definition-version</version>
  <packaging>eclipse-target-definition</packaging>

</project>
</pre>

It expects exactly one file <tt>&lt;artifactId&gt;.target</tt> in the project's base directory.
To use a target definition in your build, configure the target platform:

<pre>
	<build>
		<plugins>
			<plugin>
				<groupId>org.eclipse.tycho</groupId>
				<artifactId>target-platform-configuration</artifactId>
				<version>${tycho-version}</version>
				<configuration>
					<target>
						<artifact>
							<groupId>some-group-id</groupId>
							<artifactId>target-definition-id</artifactId>
							<version>target-definition-version</version>
						</artifact>
					</target>
				</configuration>
			</plugin>
		</plugins>
	</build>
</pre>

If you get the error '''Unable to locate the equinox launcher feature (aka delta-pack)''' then configure it as follows
<pre>
  <plugin>
    <groupId>org.eclipse.tycho</groupId>
    <artifactId>target-platform-configuration </artifactId>
    <version>${tycho-version}</version>
    <configuration>
      <dependency-resolution>
          <extraRequirements>
            <requirement>
                <type>eclipse-feature</type>
                <!-- see note below -->
                <id>org.eclipse.equinox.executable</id>
                <versionRange>3.6.0</versionRange>
            </requirement>
          </extraRequirements>
      </dependency-resolution>
    </configuration>
  </plugin>
</pre>

'''Note:''' the wiki was previously saying org.eclipse.equinox.executable.feature.group, however it seems that   with version 1.1.0, ".feature.group" is already appended to the id, thus making build fails with a ''You requested to install 'org.eclipse.equinox.executable.feature.group'''.feature.group''' 3.6.0' but it could not be found''.

== p2-installable-unit ==
This packaging type is used in Tycho to directly work with IUs. You would typically use this functionality in replacement of p2.inf to package any file, deliver configuration, or use advanced functionalities of p2. This packaging type is available since version 0.23.0 and requires the following minimum pom.xml. 

<pre>
<?xml version="1.0" encoding="UTF-8"?>
<project>
  <modelVersion>4.0.0</modelVersion>

  <artifactId>myIuId</artifactId>
  <packaging>p2-installable-unit</packaging>
  <version>1.0.0-SNAPSHOT</version>
</project>
</pre>

An [[Tycho/p2iu.xml|p2iu.xml]] file is expected to be found as a sibling of the pom.xml.

[[Category:Tycho|Packaging Types]]