Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Tycho/Packaging Types"

(348184: copy content from https://docs.sonatype.org/display/TYCHO/PackagingTypes; migrated to Tycho 0.12)
 
m (add to Tycho category)
Line 305: Line 305:
 
</build>
 
</build>
 
</pre>
 
</pre>
 +
 +
[[Category:Tycho]]

Revision as of 08:09, 3 June 2011

This page documents the packaging types available in Tycho 0.12.0.

<properties>
  <tycho-version>0.12.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>

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).

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.eclipse.tycho:tycho-surefire-plugin:test mojo executes plug-in unit tests and it is bound to integration-test build phase. Internally, tycho-surefire-plugin uses the same Surefire test framework as other maven projects and test mojo supports most of the parameters of standard maven-surefire-plugin. 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.eclipse.tycho</groupId>
        <artifactId>tycho-surefire-plugin</artifactId>
        <version>${tycho-version}</version>
        <configuration>
          <useUIHarness>true</useUIHarness>
        </configuration>
      </plugin>
    </plugins>
  </build>

The OSGi runtime for the test execution consists of the test bundle/fragment and its dependencies. If needed, you can include additional bundles or fragments (and their dependencies) in the test runtime. Tip: In order to add native fragments for several target environments, add the feature that contains them. Versions are interpreted as version ranges, so for example "1.3.0" stands for version 1.3.0 or later. Example:

  <build>
    <plugins>
      <plugin>
        <groupId>org.eclipse.tycho</groupId>
        <artifactId>tycho-surefire-plugin</artifactId>
        <version>${tycho-version}</version>
        <configuration>
          <dependencies>
            <dependency>
              <type>eclipse-plugin</type>
              <artifactId>org.example.bundle</artifactId>
              <version>1.3.0</version>
            </dependency>
            <dependency>
              <type>p2-installable-unit</type>
              <artifactId>org.example.feature.feature.group</artifactId>
              <version>[2.1.0,3.0.0)</version>
            </dependency>
          </dependencies>
        </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.

Tycho supports root properties in the build.properties file, which can be used to add files to the root of a product installation. (Limitation: wildcard patterns and root.folder properties are currently not supported.)

eclipse-repository

This packaging type creates a p2 repository (the "update site" replacement of p2) which can contain features, bundles, categories, and product definitions. To include features, list them in a category.xml file in the project root. The same file allows to define categories. To include a product definition, place a *.product file into the project root. (Note: The p2.inf file for a product definition example.product needs to be called example.p2.inf). ?By default, all bundles and features that are contained in a product definition or included feature are also included in the p2 repository. Through a configuration parameter (see below for details) the p2 repository can be extended to also contain all features and bundles that are required by included features and bundles.

This is the minimum pom.xml to create a p2 repository:

<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>repository-name</artifactId>
  <version>repository version</version>
  <packaging>eclipse-repository</packaging>
</project>

The packaging type eclipse-repository can be configured using the following tycho-p2-repository-plugin configuration parameters:

  • includeAllDependencies
true: Include all transitive dependencies into the generated p2 repository
false (default): Include only bundles and features that are (transitively) included in the specified products and features.
  • createArtifactRepository
false: Only create a p2 metadata repository
true (default): Create a zip file containing both metadata and artifact repositories
  • compress
Create compressed metadata files (e.g. content.jar vs content.xml)

Example:

  <build>
    <plugins>
      <plugin>
        <groupId>org.eclipse.tycho</groupId>
        <artifactId>tycho-p2-repository-plugin</artifactId>
        <version>${tycho-version}</version>
        <configuration>
          <includeAllDependencies>true</includeAllDependencies>
        </configuration>
      </plugin>
    </plugins>
  </build>

Creating Product Zip Files

The packaging type eclipse-repository creates a p2 repository, which may contain product definitions. By configuring additional goals, these products can be installed (with the p2 director) and zipped to create ready-to-use product installations.

To accomplish this, add the following build plug-in configuration:

<build>
  <plugins>
    <plugin>
      <groupId>org.eclipse.tycho</groupId>
      <artifactId>tycho-p2-director-plugin</artifactId>
      <version>${tycho-version}</version>
      <executions>
        <execution>
          <id>materialize-products</id>
          <goals>
            <goal>materialize-products</goal>
          </goals>
        </execution>
        <execution>
          <id>archive-products</id>
          <goals>
            <goal>archive-products</goal>
          </goals>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

If the p2 repository contains more than one product definition, you need to choose which ones shall be materialized. And if you choose to materialize (and archive) more than one product, you need to specify the attachId (which becomes a part of the classifier) to make the classifiers unique. Similarly, you can specify the root folder in the product zip files.

Warning: Do not specify more than one product per eclipse-repository module!

Due to a critical bug in all Tycho releases since 0.11.0, the build results are in-deterministic and broken if more than one product is defined in one eclipse-repository module. The issue does not occur if products are defined in a separate eclipse-repository module each, so this the the recommended workaround.


<build>
  <plugins>
    <plugin>
      <groupId>org.eclipse.tycho</groupId>
      <artifactId>tycho-p2-director-plugin</artifactId>
      <version>${tycho-version}</version>
      <executions>
        <execution>
          <id>materialize-products</id>
          <goals>
            <goal>materialize-products</goal>
          </goals>
        </execution>
        <execution>
          <id>archive-products</id>
            <goals>
              <goal>archive-products</goal>
            </goals>
        </execution>
      </executions>
      <configuration>
        <products>
          <product>
            <id>some.product.id</id>
          </product>
          <product>
            <id>other.product.id</id>
            <rootFolder>eclipse</rootFolder>
            <attachId>other</attachId>
          </product>
        </products>
      </configuration>
    </plugin>
  </plugins>
</build>

eclipse-application

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

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

Archive Update Site Content

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

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

Copyright © Eclipse Foundation, Inc. All Rights Reserved.