Jump to: navigation, search

Difference between revisions of "Tycho/Packaging Types"

(eclipse-target-definition)
(p2-installable-unit)
 
(19 intermediate revisions by 4 users not shown)
Line 3: Line 3:
 
<pre>
 
<pre>
 
<properties>
 
<properties>
   <tycho-version>0.16.0</tycho-version>
+
   <tycho-version>0.22.0</tycho-version>
 
</properties>
 
</properties>
  
Line 59: Line 59:
 
</pre>
 
</pre>
  
<tt>org.eclipse.tycho:tycho-surefire-plugin:test</tt> 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:
+
<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>
 
<pre>
Line 77: Line 77:
 
</pre>
 
</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. Versions are interpreted as version ranges, so for example "1.3.0" stands for version 1.3.0 or later. Example:
+
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>
 
<pre>
  <build>
+
<plugin>
    <plugins>
+
  <groupId>org.eclipse.tycho</groupId>
      <plugin>
+
  <artifactId>target-platform-configuration</artifactId>
        <groupId>org.eclipse.tycho</groupId>
+
  <version>${tycho-version}</version>
        <artifactId>tycho-surefire-plugin</artifactId>
+
  <configuration>
        <version>${tycho-version}</version>
+
      <dependency-resolution>
        <configuration>
+
        <extraRequirements>
          <dependencies>
+
             <requirement>
             <dependency>
+
              <type>eclipse-feature</type>
              <type>eclipse-feature</type>
+
              <id>myproject.app.feature</id>
              <artifactId>com.example.my-component.feature</artifactId>
+
              <versionRange>1.0.0</versionRange>
              <version>0.0.0</version>
+
             </requirement>
             </dependency>
+
        </extraRequirements>
          </dependencies>
+
       </dependency-resolution>
        </configuration>
+
  </configuration>
       </plugin>
+
</plugin>
    </plugins>
+
  </build>
+
 
</pre>
 
</pre>
  
Line 124: Line 122:
 
Similar to eclipse-plugin projects, <tt>artifactId</tt> and <tt>version</tt> attributes must match id and version attributes of feature.xml file.
 
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: wildcard patterns and <tt>root.folder</tt> properties are currently not supported.)
+
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.
 
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.
Line 130: Line 128:
 
== eclipse-repository ==
 
== 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.
+
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.
 
+
This is the minimum pom.xml to create a p2 repository:
+
 
+
<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>repository-name</artifactId>
+
  <version>repository version</version>
+
  <packaging>eclipse-repository</packaging>
+
</project>
+
</pre>
+
 
+
The packaging type eclipse-repository can be configured using the following tycho-p2-repository-plugin configuration parameters:
+
 
+
* <tt>includeAllDependencies</tt>
+
: true: Assemble all transitively referenced artifacts into the generated p2 repository
+
: false (default): Assemble only bundles and features that are (transitively) included in the specified features and product definitionsfacts.)
+
* <tt>createArtifactRepository</tt>
+
: false: Only create a p2 metadata repository
+
: true (default): Create a zip file containing both metadata and artifact repositories
+
* <tt>compress</tt>
+
: Create compressed metadata files (e.g. content.jar vs content.xml)
+
 
+
Notes:
+
* "included" means listed as inclusion in the metadata files, i.e. in a <tt>feature.xml</tt> these are the <tt>&lt;plugin&gt;</tt> and <tt>&lt;includes&gt;</tt> elements; in product files, these are the <tt>&lt;plugins&gt;</tt> and <tt>&lt;features&gt;</tt> elements. Note that product installations (see [[#Creating Product Zip Files|below]]) contain both included and referenced artifacts, so if you want the same result as for the product installation, you should use <tt>includeAllDependencies=true</tt>.
+
* Only optional, greedy dependencies are assembled with <tt>includeAllDependencies=true</tt>. (Optional, greedy dependencies are marked with <tt>greedy='true'</tt> in the p2 metadata.) Optional, non-greedy dependencies are ignored for assembly.
+
 
+
Example:
+
<pre>
+
  <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>
+
</pre>
+
 
+
Note: Due to [https://bugs.eclipse.org/bugs/show_bug.cgi?id=359090 bug 359090], either of the following warnings actually break the build:
+
* "The product specifies bundles although useFeatures is true. These bundles are ignored."
+
* "The product specifies features although useFeatures is false. These features are ignored."
+
The workaround is to remove leftover plugins/features which are ignored due to the useFeatures attribute (see bug report for details).
+
 
+
=== 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:
+
<pre>
+
<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>
+
</pre>
+
 
+
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 <tt>attachId</tt> (which becomes a part of the classifier) to make the classifiers unique. Similarly, you can specify the root folder in the product zip files.
+
 
+
<div style="color:red">Warning:</div>If you are using Tycho version 0.11.0, 0.11.1, or 0.12.0, do not specify more than one product per eclipse-repository module. These releases contain the critical [https://bugs.eclipse.org/bugs/show_bug.cgi?id=346532 bug 346532] which leads to in-deterministic and broken results 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.
+
 
+
<pre>
+
<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>
+
            <attachId>other</attachId>
+
 
+
            <!-- optional parameters (with default values) -->
+
            <rootFolder></rootFolder>
+
          </product>
+
        </products>
+
        <!-- global optional parameters (with default values) -->
+
        <installFeatures>true</installFeatures>
+
        <profile>DefaultProfile</profile>
+
      </configuration>
+
    </plugin>
+
  </plugins>
+
</build>
+
</pre>
+
 
+
The product installation can be configured through the following parameters:
+
 
+
* <tt>rootFolder</tt>
+
: The path where the installed product shall be stored in the archive, e.g. <tt>eclipse</tt>. By default, the product is stored in the archive root.
+
* <tt>installFeatures</tt>
+
: true (default): Include the feature JARs in installation. (Technically, this sets the p2 profile property <tt>org.eclipse.update.install.features</tt> to true.)
+
: false: Omit the features folder in the installation.
+
* <tt>profile</tt>
+
: The name of the p2 profile to be used for the installation
+
 
+
'''Note:''' See [[#eclipse-feature]] for details on unpack limitations.
+
  
 
== eclipse-application ==
 
== eclipse-application ==
  
This packaging type will soon be deprecated and we recommend using packaging type eclipse-repository instead. See [https://bugs.eclipse.org/bugs/show_bug.cgi?id=348586 bug 348586] for details.
+
{{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
 
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
Line 379: Line 235:
 
</pre>
 
</pre>
  
 +
== 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]]
 
[[Category:Tycho|Packaging Types]]

Latest revision as of 22:38, 25 February 2015

This page documents the packaging types available in the latest Tycho release.

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

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

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

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:

<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: root.folder properties are currently not supported. Wildcard patterns are supported since Tycho 0.17.0.)

Limitation: The unpack attribute in the feature.xml is ignored. If you need a bundle to be installed in unpacked form, specify Eclipse-BundleShape: dir 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

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

<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

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

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


eclipse-target-definition

This packaging is used in Tycho to represent a PDE target definition. It is available since version 0.16.0 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>target-definition-id</artifactId>
  <version>target-definition-version</version>
  <packaging>eclipse-target-definition</packaging>

</project>

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

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

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.

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

An p2iu.xml file is expected to be found as a sibling of the pom.xml.