View source for Tycho/Migration Howto

This page is intended to give existing projects a jumpstart for setting up a Tycho build.

While each project is different, there are some common steps:

== Scaffolding: Generate pom.xml files ==

Maven needs pom.xml files to drive the build (one pom.xml file per plugin/feature). See [[Tycho/Reference_Card#Generating_POM_files|Generating POM files]] on how to generate an initial skeleton for these files.

=== Manual adjustments ===

In the generated top-level (parent) pom.xml, it's a good idea to globally define the tycho version to use

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

so you can reference it using <tt>${tycho-version}</tt> anywhere in the child pom.xml files e.g. when configuring tycho plugins. See [http://maven.apache.org/guides/introduction/introduction-to-the-pom.html#Project_Inheritance maven project inheritance].

In case you have deeply nested projects and used several generate-poms invocations, add a top-level parent pom.xml and reference it as parent from the intermediate parent poms.
Also, adjust the modules to be built (see [http://maven.apache.org/guides/introduction/introduction-to-the-pom.html#Project_Aggregation maven project aggregation]).

== Adding p2 repositories to resolve external dependencies ==

Almost every project has external dependencies it needs to compile against.
Add all p2 repositories you need for compilation or runtime in the parent pom like in the following snippet:

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

See [[Tycho/Reference_Card#Repository_providing_the_context_of_the_build|Tycho Reference card]]

== Run the build ==

Run <tt>mvn clean install</tt> in the directory of the parent pom.

== Getting tests to run ==

If your test bundle symbolic names end with <tt>.tests</tt>, the pom generator will accordingly define

<pre>
<packaging>eclipse-test-plugin</packaging>
</pre>

This will tell Tycho to scan for test classes and execute them during build. Note that by default, test class scanning is using naming convention

<tt>**/Test*.java **/*Test.java **/*TestCase.java</tt>

to find tests.

For details, see the [http://eclipse.org/tycho/sitedocs/tycho-surefire/tycho-surefire-plugin/test-mojo.html Tycho Surefire docs]

Tips:

* To skip test execution temporarily, use commandline option <tt>-DskipTests</tt>
* To debug tests, use commandline option <tt>-DdebugPort=8000</tt>
* In case you are using SWTBot, see [[SWTBot/Maven#With_Maven_and_Tycho|Running SWTBot tests with Tycho]]
* [http://eclipse.org/tycho/sitedocs/tycho-surefire/tycho-surefire-plugin/test-mojo.html#testSuite How to run a test suite]
* By default, only the transitive dependencies of the test plugin make up the test runtime. See [[Tycho/Packaging_Types#eclipse-test-plugin|How to add implicit dependencies to the test runtime]] if you have implicit (runtime-only) dependencies.

== Generating source bundles and features ==

See the [[Tycho/Reference_Card#Source_Bundles|Tycho Reference Card]] on how to configure source bundles and feature generation in your parent pom.
See also reference documentation for [http://eclipse.org/tycho/sitedocs/tycho-source-plugin/plugin-source-mojo.html source bundles] and [http://eclipse.org/tycho/sitedocs-extras/tycho-source-feature-plugin/source-feature-mojo.html source features].

== Building a p2 repository ==

Once you have a build with plugin and features up and running, you can create a p2 repository for these bundles and features.
For this, create a pom.xml with

<pre>
  <packaging>eclipse-repository</packaging>
</pre>

, add it as a module to the parent pom and place a <tt>category.xml</tt> file in the root. See [[Tycho/Packaging_Types#eclipse-repository| eclipse-repository]] for details.

== What if I'm stuck? ==

Check all the information sources (sample projects, reference docs, mailing list, tutorial) available from the [http://eclipse.org/tycho/documentation.php Tycho documentation]

[[Category:Tycho|Contributor Guide]]