Difference between revisions of "Tycho/Reference Card"

From Eclipsepedia

Jump to: navigation, search
(the user should understand, that the execution must occur in the feature project. Otherwise, nothing happens)
(8 intermediate revisions by 3 users not shown)
Line 2: Line 2:
 
* The [http://eclipse.org/tycho/ Tycho Project page]
 
* The [http://eclipse.org/tycho/ Tycho Project page]
 
* The [http://www.eclipse.org/tycho/sitedocs/ Tycho plugin documents] (generated by Maven)
 
* The [http://www.eclipse.org/tycho/sitedocs/ Tycho plugin documents] (generated by Maven)
* The [[Tycho/FAQ | Tycho FAQ]]
+
* [http://stackoverflow.com/questions/tagged/tycho?sort=frequent&pagesize=15 Frequently asked Tycho questions on stackoverflow.com]
 +
* The old page with [[Tycho/FAQ|FAQs]]
  
 
== Enabling tycho ==
 
== Enabling tycho ==
 
<pre>
 
<pre>
 
   <properties>
 
   <properties>
       <tycho-version>0.17.0</tycho-version>
+
       <tycho-version>0.18.1</tycho-version>
 
   </properties>
 
   </properties>
  
Line 55: Line 56:
  
 
== Target runtime environment ==
 
== 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
 
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
Line 276: Line 276:
 
== Source Features ==
 
== Source Features ==
  
If you have configured source bundle generation (see above), you can also generate source features by using the following configuration snippet:
+
If you have configured source bundle generation (see above), you can also generate source features by using the following configuration snippet within the feature lifecycle (as part of the feature project configuration or inheriting from parents):
  
 
<source lang="xml">
 
<source lang="xml">
<plugin>
+
<build>
<groupId>org.eclipse.tycho.extras</groupId>
+
  <plugins>
<artifactId>tycho-source-feature-plugin</artifactId>
+
    <plugin>
<version>${tychoExtrasVersion}</version>
+
      <groupId>org.eclipse.tycho.extras</groupId>
<executions>
+
      <artifactId>tycho-source-feature-plugin</artifactId>
<execution>
+
      <version>${tychoExtrasVersion}</version>
<id>source-feature</id>
+
      <executions>
<phase>package</phase>
+
        <execution>
<goals>
+
          <id>source-feature</id>
<goal>source-feature</goal>
+
          <phase>package</phase>
</goals>
+
          <goals>
</execution>
+
            <goal>source-feature</goal>
</executions>
+
          </goals>
</plugin>
+
        </execution>
<plugin>
+
      </executions>
<groupId>org.eclipse.tycho</groupId>
+
    </plugin>
<artifactId>tycho-p2-plugin</artifactId>
+
    <plugin>
<version>${tycho-version}</version>
+
      <groupId>org.eclipse.tycho</groupId>
<executions>
+
      <artifactId>tycho-p2-plugin</artifactId>
<execution>
+
      <version>${tycho-version}</version>
<id>attach-p2-metadata</id>
+
      <executions>
<phase>package</phase>
+
        <execution>
<goals>
+
          <id>attach-p2-metadata</id>
<goal>p2-metadata</goal>
+
          <phase>package</phase>
</goals>
+
          <goals>
</execution>
+
            <goal>p2-metadata</goal>
</executions>
+
          </goals>
</plugin>
+
        </execution>
 +
      </executions>
 +
    </plugin>
 +
  </plugins>
 +
</build>
 
</source>
 
</source>
  
Line 324: Line 328:
 
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.
 
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:
+
Due to [https://bugs.eclipse.org/bugs/show_bug.cgi?id=409871 bug 409871] the filesystem scan depth is limited one level currently. If you have deeply nested plugin or feature projects, you may have to run the generator separately in each of the direct parent directories.
 
+
mvn org.eclipse.tycho:tycho-pomgenerator-plugin:0.15.0-SNAPSHOT:generate-poms -DgroupId=<MY.GROPUID>
+
  
 
== Putting it all together ==
 
== Putting it all together ==
Line 341: Line 343:
  
 
<properties>
 
<properties>
<tycho-version>0.17.0</tycho-version>
+
<tycho-version>0.18.1</tycho-version>
 
</properties>
 
</properties>
 
<repositories>
 
<repositories>

Revision as of 09:19, 10 September 2013

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

Contents

Enabling tycho

   <properties>
      <tycho-version>0.18.1</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

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

If you have configured source bundle generation (see above), you can also generate source features by using the following configuration snippet within the feature lifecycle (as part of the feature project configuration or inheriting from parents):

<build>
  <plugins>
    <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>
    <plugin>
      <groupId>org.eclipse.tycho</groupId>
      <artifactId>tycho-p2-plugin</artifactId>
      <version>${tycho-version}</version>
      <executions>
        <execution>
          <id>attach-p2-metadata</id>
          <phase>package</phase>
          <goals>
            <goal>p2-metadata</goal>
          </goals>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

The generated source feature will have the feature id <featureId>.source. Feature label (with a configurable suffix), description, branding plugin and other attributes are taken over from the original feature by default. If required, you can override individual source feature values by adding a sourceTemplateFeature/feature.properties file. See bug 398250 on why the p2-metadata goal is required for now.

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.

Due to bug 409871 the filesystem scan depth is limited one level currently. If you have deeply nested plugin or feature projects, you may have to run the generator separately in each of the direct parent directories.

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