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/Reference Card"

(→‎Selecting JDK)
(→‎Generating POM files)
(26 intermediate revisions by 12 users not shown)
Line 1: Line 1:
 +
This page provides snippets for using Tycho.  You may also wish to see:
 +
* The [http://eclipse.org/tycho/ Tycho Project page]
 +
* The [http://www.eclipse.org/tycho/sitedocs/ Tycho plugin documents] (generated by Maven)
 +
* The [[Tycho/FAQ | Tycho FAQ]]
 +
 
== Enabling tycho ==
 
== Enabling tycho ==
 
<pre>
 
<pre>
−
   <plugin>
+
   <properties>
−
       <groupId>org.eclipse.tycho</groupId>
+
       <tycho-version>0.16.0</tycho-version>
−
      <artifactId>tycho-maven-plugin</artifactId>
+
  </properties>
−
      <version>${tycho-version}</version>
+
 
−
      <extensions>true</extensions>
+
  <build>
−
  </plugin>
+
      <plugins>
 +
        <plugin>
 +
            <groupId>org.eclipse.tycho</groupId>
 +
            <artifactId>tycho-maven-plugin</artifactId>
 +
            <version>${tycho-version}</version>
 +
            <extensions>true</extensions>
 +
        </plugin>
 +
      </plugins>
 +
  </build>
 
</pre>Note that this is usually defined in the parent POM in under build / plugins
 
</pre>Note that this is usually defined in the parent POM in under build / plugins
  
 
== Repository providing the context of the build ==
 
== Repository providing the context of the build ==
  
−
Specify a repository to get pre-built pieces from. Multiple repository can be specified. See also target platform section.
+
Specify a repository to get pre-built pieces from. Multiple repositories can be specified. See also target file section.
 
<pre>
 
<pre>
 
   <repository>
 
   <repository>
Line 20: Line 33:
 
</pre>
 
</pre>
  
−
== Target platform providing the context of the build ==
+
== Target file providing the context of the build ==
  
 
Use a target platform to get pre-build pieces from. The target platform file can be edited using Eclipse PDE editor.
 
Use a target platform to get pre-build pieces from. The target platform file can be edited using Eclipse PDE editor.
Line 29: Line 42:
 
             <version>${tycho-version}</version>
 
             <version>${tycho-version}</version>
 
             <configuration>
 
             <configuration>
−
              <resolver>p2</resolver>
 
 
               <target>
 
               <target>
 
                 <artifact>
 
                 <artifact>
Line 41: Line 53:
 
           </plugin>
 
           </plugin>
 
</pre>
 
</pre>
 +
 +
== Target runtime environment ==
 +
{{Note|This paragraph is a stub - not verified by a Tycho guru}}
 +
 +
Specify which environments your software should be built for (os/ws/arch). This will determine the set of platform dependent fragments to be included in the project's dependencies. If you omit this the build will say
 +
  No explicit target runtime environment configuration. Build is platform dependent
 +
 +
Target runtime environments are specified like this:
 +
<pre>
 +
      <plugin>
 +
        <groupId>org.eclipse.tycho</groupId>
 +
        <artifactId>target-platform-configuration</artifactId>
 +
        <version>${tycho-version}</version>
 +
        <configuration>
 +
          <environments>
 +
            <environment>
 +
              <os>win32</os>
 +
              <ws>win32</ws>
 +
              <arch>x86</arch>
 +
            </environment>
 +
            <environment>
 +
              <os>linux</os>
 +
              <ws>gtk</ws>
 +
              <arch>x86_64</arch>
 +
            </environment>
 +
            <environment>
 +
              <os>macosx</os>
 +
              <ws>cocoa</ws>
 +
              <arch>x86_64</arch>
 +
            </environment>
 +
          </environments>
 +
        </configuration>
 +
      </plugin>
 +
</pre>
 +
 +
It ''seems'' this specification accepts all os/ws/arch values exactly as they are understood by OSGi.
 +
 +
Source: http://dev.eclipse.org/mhonarc/lists/tycho-user/msg00908.html
  
 
== Bundle, Fragments ==
 
== Bundle, Fragments ==
Line 102: Line 152:
  
 
== Update Site ==
 
== Update Site ==
−
 
+
{{caution | Deprecated [http://software.2206966.n2.nabble.com/Steps-before-deprecating-eclipse-update-site-td6274042.html] | Use [[Tycho/Reference_Card#p2_repositories | eclipse-repository]] instead. To migrate:
 +
# Change packaging to ''eclipse-repository''
 +
# Rename site.xml to ''category.xml''}}
 
<pre>
 
<pre>
 
   <groupId>Some-Group-Id</groupId>
 
   <groupId>Some-Group-Id</groupId>
Line 122: Line 174:
  
 
<pre>
 
<pre>
−
  <plugin>
+
  <plugin>
−
      <groupId>org.eclipse.tycho</groupId>
+
    <groupId>org.eclipse.tycho</groupId>
−
        <artifactId>tycho-surefire-plugin</artifactId>
+
    <artifactId>tycho-surefire-plugin</artifactId>
−
        <version>${tycho-version}</version>
+
    <version>${tycho-version}</version>
−
        <configuration>
+
    <configuration>
−
            <testSuite>Bundle-SymbolicName-of-bundleContaining-Tests</testSuite>
+
      <testSuite>Bundle-SymbolicName-of-bundleContaining-Tests</testSuite>
−
            <testClass>FullyQualifiedNameOfTheTestClass</testClass>
+
      <testClass>FullyQualifiedNameOfTheTestClass</testClass>
−
        </configuration>
+
    </configuration>
−
      </plugin>
+
  </plugin>
 
</pre>
 
</pre>
  
Line 144: Line 196:
 
In the configuration section for the test plug-in
 
In the configuration section for the test plug-in
 
<pre>
 
<pre>
−
           <useUIHarness>true</useUIHarness>
+
           <appArgLine>-nl en</appArgLine>
 
</pre>
 
</pre>
  
Line 218: Line 270:
 
</pre>
 
</pre>
  
−
For convenience, you can do this only once in your parent POM. A source bundle (with ".test" appended to the Bundle-SymbolicName) will be generated for each module inheriting from this parent which has packaging type eclipse-plugin or eclipse-test-plugin.
+
For convenience, you can do this only once in your parent POM. A source bundle (with ".source" appended to the Bundle-SymbolicName) will be generated for each module inheriting from this parent which has packaging type eclipse-plugin or eclipse-test-plugin.
  
−
To assemble source bundles, at this point you need to create source feature(s) which include the source bundles same as for normal bundles.
+
You can then reference source bundles as normal bundles in other MANIFEST.MF or feature.xml by referencing with their Bundle-Name: <bundle.name>.source.
 +
 
 +
== Source Features ==
 +
 
 +
On an existing eclipse-feature, you can create the associated source feature by using the following plugin:
 +
 
 +
<source lang="xml">
 +
<plugin>
 +
<groupId>org.eclipse.tycho.extras</groupId>
 +
<artifactId>tycho-source-feature-plugin</artifactId>
 +
<version>${tychoExtrasVersion}</version>
 +
<executions>
 +
<execution>
 +
<id>source-feature</id>
 +
<phase>package</phase>
 +
<goals>
 +
<goal>source-feature</goal>
 +
</goals>
 +
</execution>
 +
</executions>
 +
</plugin>
 +
</source>
 +
 
 +
Source feature is named <featureId>.source.
  
 
== Generating POM files ==
 
== Generating POM files ==
  
−
mvn org.eclipse.tycho:tycho-pomgenerator-plugin:generate-poms -DgroupId=<MY.PROJECT>
+
If you have an existing build which you want to migrate to tycho, you can generate templates of the required pom.xml files using
 +
 
 +
<tt>mvn org.eclipse.tycho:tycho-pomgenerator-plugin:generate-poms -DgroupId=<MY.GROUPID></tt>
 +
 
 +
This will scan the filesystem starting from the current directory for bundles (i.e. MANIFEST.MF files) and features (feature.xml files) and generate the corresponding pom.xml files. It assumes test bundles have a suffix ".tests". You can change this default by specifying <tt>-DtestSuffix=.mytestBundleSuffix</tt>
 +
 
 +
Note that the generated  pom.xml files are intended to give you a quickstart template only. You will most probably have to refine the generated files e.g. fill in repositories in the generated parent pom from which to resolve depndencies.
 +
 
 +
To address e.g. version 0.15.0-SNAPSHOT of tycho:
  
 +
mvn org.eclipse.tycho:tycho-pomgenerator-plugin:0.15.0-SNAPSHOT:generate-poms -DgroupId=<MY.GROPUID>
  
 
== Putting it all together ==
 
== Putting it all together ==
  
−
=== Examplary parent POM ===
+
=== Exemplary parent POM ===
 
<pre>
 
<pre>
 
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 
<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">
+
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>
 
<modelVersion>4.0.0</modelVersion>
 
<groupId>org.eclipse</groupId>
 
<groupId>org.eclipse</groupId>
Line 240: Line 324:
  
 
<properties>
 
<properties>
−
<tycho-version>0.12.0</tycho-version>
+
<tycho-version>0.16.0</tycho-version>
 
</properties>
 
</properties>
 
<repositories>
 
<repositories>
Line 269: Line 353:
 
<version>${tycho-version}</version>
 
<version>${tycho-version}</version>
 
<configuration>
 
<configuration>
−
<resolver>p2</resolver>
 
 
<environments>
 
<environments>
 
<environment>
 
<environment>
Line 304: Line 387:
 
</pre>
 
</pre>
  
−
=== Examplary bundle/fragment POM ===
+
=== Exemplary bundle/fragment POM ===
  
 
<pre>
 
<pre>
Line 325: Line 408:
 
</pre>
 
</pre>
  
−
=== Examplary Test bundle POM ===
+
=== Exemplary Test bundle POM ===
  
 
<pre>
 
<pre>
Line 348: Line 431:
 
<plugin>
 
<plugin>
 
<groupId>org.eclipse.tycho</groupId>
 
<groupId>org.eclipse.tycho</groupId>
−
<artifactId>maven-osgi-test-plugin</artifactId>
+
<artifactId>tycho-surefire-plugin</artifactId>
 
<configuration>
 
<configuration>
 
<testSuite>org.eclipse.equinox.p2.tests</testSuite>
 
<testSuite>org.eclipse.equinox.p2.tests</testSuite>
 
<testClass>org.eclipse.equinox.p2.tests.AutomatedTests</testClass>
 
<testClass>org.eclipse.equinox.p2.tests.AutomatedTests</testClass>
 
<argLine>-Xmx512m</argLine>
 
<argLine>-Xmx512m</argLine>
 +
<appArgLine>-nl en</appArgLine>
 
<bundleStartLevel>
 
<bundleStartLevel>
 
<bundle>
 
<bundle>

Revision as of 05:12, 8 November 2012

This page provides snippets for using Tycho. You may also wish to see:

Enabling tycho

   <properties>
      <tycho-version>0.16.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>
Note that this is usually defined in the parent POM in under build / plugins

Repository providing the context of the build

Specify a repository to get pre-built pieces from. Multiple repositories can be specified. See also target file section. 

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

Target file providing the context of the build

Use a target platform to get pre-build pieces from. The target platform file can be edited using Eclipse PDE editor. 

          <plugin>
            <groupId>org.eclipse.tycho</groupId>
            <artifactId>target-platform-configuration</artifactId>
            <version>${tycho-version}</version>
            <configuration>
              <target>
                <artifact>
                  <groupId>${project.groupId}</groupId>
                  <artifactId>${project.artifactId}</artifactId>
                  <version>${project.version}</version>
                  <classifier>TargetFileNameWithoutExtension</classifier>
                </artifact>
              </target>
            </configuration>
          </plugin>

Target runtime environment

Note.png
This paragraph is a stub - not verified by a Tycho guru


Specify which environments your software should be built for (os/ws/arch). This will determine the set of platform dependent fragments to be included in the project's dependencies. If you omit this the build will say 

 No explicit target runtime environment configuration. Build is platform dependent

Target runtime environments are specified like this: 

      <plugin>
        <groupId>org.eclipse.tycho</groupId>
        <artifactId>target-platform-configuration</artifactId>
        <version>${tycho-version}</version>
        <configuration>
          <environments>
            <environment>
              <os>win32</os>
              <ws>win32</ws>
              <arch>x86</arch>
            </environment>
            <environment>
              <os>linux</os>
              <ws>gtk</ws>
              <arch>x86_64</arch>
            </environment>
            <environment>
              <os>macosx</os>
              <ws>cocoa</ws>
              <arch>x86_64</arch>
            </environment>
          </environments>
        </configuration>
      </plugin>

It seems this specification accepts all os/ws/arch values exactly as they are understood by OSGi.

Source: http://dev.eclipse.org/mhonarc/lists/tycho-user/msg00908.html

Bundle, Fragments

  <groupId>Some-Group-Id</groupId>
  <artifactId>Bundle-SymbolicName</artifactId>
  <version>Bundle-Version</version>
  <packaging>eclipse-plugin</packaging>

Features

  <groupId>Some-Group-Id</groupId>
  <artifactId>FeatureId</artifactId>
  <version>FeatureVersion</version>
  <packaging>eclipse-feature</packaging>

p2 repositories

  <groupId>Some-Group-Id</groupId>
  <artifactId>RepositoryName</artifactId>
  <version>Version</version>
  <packaging>eclipse-repository</packaging>

Products

  <groupId>Some-Group-Id</groupId>
  <artifactId>RepositoryName</artifactId>
  <version>Version</version>
  <packaging>eclipse-repository</packaging>
  <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>

Update Site

Stop.png
Deprecated [1]
Use eclipse-repository instead. To migrate:
  1. Change packaging to eclipse-repository
  2. Rename site.xml to category.xml
  <groupId>Some-Group-Id</groupId>
  <artifactId>UpdateSiteName</artifactId>
  <version>Version</version>
  <packaging>eclipse-update-site</packaging>

Test bundles

  <groupId>Some-Group-Id</groupId>
  <artifactId>Bundle-SymbolicName</artifactId>
  <version>Bundle-Version</version>
  <packaging>eclipse-test-plugin</packaging>

Setting up the tests to run

  <plugin>
    <groupId>org.eclipse.tycho</groupId>
    <artifactId>tycho-surefire-plugin</artifactId>
    <version>${tycho-version}</version>
    <configuration>
      <testSuite>Bundle-SymbolicName-of-bundleContaining-Tests</testSuite>
      <testClass>FullyQualifiedNameOfTheTestClass</testClass>
    </configuration>
  </plugin>

Setting VM args

In the configuration section for the test plug-in 

           <argLine>-Xmx512m</argLine>

Setting application arguments

In the configuration section for the test plug-in 

           <appArgLine>-nl en</appArgLine>

Running an application or a product

           <application>EclipseApplicationID</application>

           <product>EclipseProductID</product>

Bundle start level

           <bundleStartLevel>
              <bundle>
                 <id>Bundle-SymbolicName</id>
                 <level>1</level>
                 <autoStart>true</autoStart>
              </bundle>
           </bundleStartLevel>

Selecting JDK

Since version 0.13 tycho-surefire-plugin can use Maven Toolchains to run tests with a specific version of JDK independent from the one Maven is running with. 

  <plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-toolchains-plugin</artifactId>
    <version>1.0</version>
    <executions>
      <execution>
        <phase>validate</phase>
        <goals>
          <goal>toolchain</goal>
        </goals>
      </execution>
    </executions>
    <configuration>
      <toolchains>
        <jdk>
          <version>1.5</version>
          <vendor>sun</vendor>
        </jdk>
      </toolchains>
    </configuration>
  </plugin>

Source Bundles

To generate source bundles, you need to execute goal "plugin-source" of plugin tycho-source-plugin: 

  <build>
    <plugins>   
      <plugin>
        <groupId>org.eclipse.tycho</groupId>
        <artifactId>tycho-source-plugin</artifactId>
        <version>${tycho-version}</version>
        <executions>
          <execution>
            <id>plugin-source</id>
            <goals>
              <goal>plugin-source</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>

For convenience, you can do this only once in your parent POM. A source bundle (with ".source" appended to the Bundle-SymbolicName) will be generated for each module inheriting from this parent which has packaging type eclipse-plugin or eclipse-test-plugin.

You can then reference source bundles as normal bundles in other MANIFEST.MF or feature.xml by referencing with their Bundle-Name: <bundle.name>.source.

Source Features

On an existing eclipse-feature, you can create the associated source feature by using the following plugin: 

<plugin>
	<groupId>org.eclipse.tycho.extras</groupId>
	<artifactId>tycho-source-feature-plugin</artifactId>
	<version>${tychoExtrasVersion}</version>
	<executions>
		<execution>
			<id>source-feature</id>
			<phase>package</phase>
			<goals>
				<goal>source-feature</goal>
			</goals>
		</execution>
	</executions>
</plugin>

Source feature is named <featureId>.source.

Generating POM files

If you have an existing build which you want to migrate to tycho, you can generate templates of the required pom.xml files using

mvn org.eclipse.tycho:tycho-pomgenerator-plugin:generate-poms -DgroupId=<MY.GROUPID>

This will scan the filesystem starting from the current directory for bundles (i.e. MANIFEST.MF files) and features (feature.xml files) and generate the corresponding pom.xml files. It assumes test bundles have a suffix ".tests". You can change this default by specifying -DtestSuffix=.mytestBundleSuffix

Note that the generated pom.xml files are intended to give you a quickstart template only. You will most probably have to refine the generated files e.g. fill in repositories in the generated parent pom from which to resolve depndencies.

To address e.g. version 0.15.0-SNAPSHOT of tycho:

mvn org.eclipse.tycho:tycho-pomgenerator-plugin:0.15.0-SNAPSHOT:generate-poms -DgroupId=<MY.GROPUID>

Putting it all together

Exemplary parent POM

<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.eclipse</groupId>
	<artifactId>org.eclipse.equinox.p2-parent</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<packaging>pom</packaging>

	<properties>
		<tycho-version>0.16.0</tycho-version>
	</properties>
	<repositories>
		<repository>
			<id>helios</id>
			<layout>p2</layout>
			<url>http://download.eclipse.org/releases/helios</url>
		</repository>
		<repository>
			<id>galileoTest</id>
			<layout>p2</layout>
			<url>http://download.eclipse.org/eclipse/updates/3.6-JUnit-Tests/</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>
					<environments>
						<environment>
							<os>linux</os>
							<ws>gtk</ws>
							<arch>x86</arch>
						</environment>
						<environment>
							<os>linux</os>
							<ws>gtk</ws>
							<arch>x86_64</arch>
						</environment>
						<environment>
							<os>win32</os>
							<ws>win32</ws>
							<arch>x86</arch>
						</environment>
						<environment>
							<os>win32</os>
							<ws>win32</ws>
							<arch>x86_64</arch>
						</environment>
						<environment>
							<os>macosx</os>
							<ws>cocoa</ws>
							<arch>x86_64</arch>
						</environment>
					</environments>
				</configuration>
			</plugin>
		</plugins>
	</build>
</project>

Exemplary bundle/fragment POM

<?xml version="1.0" encoding="UTF-8"?>
<project
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"
	xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<modelVersion>4.0.0</modelVersion>
	<parent>
		<artifactId>org.eclipse.equinox.p2-parent</artifactId>
		<groupId>org.eclipse</groupId>
		<version>0.0.1-SNAPSHOT</version>
		<relativePath>../org.eclipse.equinox.p2-parent</relativePath>
	</parent>
	<groupId>org.eclipse</groupId>
	<artifactId>org.eclipse.equinox.p2.director</artifactId>
	<version>2.0.0.qualifier</version>
	<packaging>eclipse-plugin</packaging>
</project>

Exemplary Test bundle POM

<?xml version="1.0" encoding="UTF-8"?>
<project
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"
	xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<modelVersion>4.0.0</modelVersion>
	<parent>
		<artifactId>org.eclipse.equinox.p2-parent</artifactId>
		<groupId>org.eclipse</groupId>
		<version>0.0.1-SNAPSHOT</version>
		<relativePath>../org.eclipse.equinox.p2-parent</relativePath>
	</parent>
	<groupId>org.eclipse</groupId>
	<artifactId>org.eclipse.equinox.p2.tests</artifactId>
	<version>1.2.0.qualifier</version>
	<packaging>eclipse-test-plugin</packaging>

	<build>
		<plugins>
			<plugin>
				<groupId>org.eclipse.tycho</groupId>
				<artifactId>tycho-surefire-plugin</artifactId>
				<configuration>
					<testSuite>org.eclipse.equinox.p2.tests</testSuite>
					<testClass>org.eclipse.equinox.p2.tests.AutomatedTests</testClass>
					<argLine>-Xmx512m</argLine>
					<appArgLine>-nl en</appArgLine>
					<bundleStartLevel>
						<bundle>
							<id>org.eclipse.equinox.ds</id>
							<level>1</level>
							<autoStart>true</autoStart>
						</bundle>
					</bundleStartLevel>
				</configuration>
			</plugin>
		</plugins>
	</build>
</project>
Retrieved from "https://wiki.eclipse.org/index.php?title=Tycho/Reference_Card&oldid=321274"

Copyright © Eclipse Foundation, Inc. All Rights Reserved.