Jump to: navigation, search

Difference between revisions of "Developing Tycho"

m (Inline "Tips" Heading)
m (add description for local integration tests)
(30 intermediate revisions by 7 users not shown)
Line 1: Line 1:
 
== Importing the Tycho sources ==
 
== Importing the Tycho sources ==
  
For importing the Tycho sources into Eclipse, you need to have m2eclipse 1.0.0 or later (available from the Indigo software site) installed.
+
To import the Tycho sources into Eclipse, you need to have a recent version of the [http://www.eclipse.org/m2e/ Maven integration for Eclipse (m2eclipse)] installed. m2eclipse is included in various Eclipse packages, e.g. the "Eclipse for RCP and RAP Developers" package. (Note: m2eclipse is '''not''' included in an the Eclipse Standard package.) If you need to add m2eclipse to your Eclipse installation, you can get it from the Eclipse Marketplace.
  
Here is the step by step approach assuming you use a Windows OS:
+
Step by step instructions:
# Get an Indigo version of [http://www.eclipse.org/downloads/index-developer.php Eclipse]
+
# Get an "Eclipse for RCP and RAP Developers" or "Eclipse IDE for Java EE Developers" package for your platform from the [http://www.eclipse.org/downloads/ Eclipse Downloads] page
 
<ol start="2">
 
<ol start="2">
<li> Install the following additional software into Eclipse:
 
* [http://www.eclipse.org/m2e/download/ Maven Integration for Eclipse (m2e)], version 1.0.0 or later
 
* [http://www.eclipse.org/egit/download/ EGit Team Provider] (optional)
 
 
<li> Install [http://maven.apache.org/download.html Maven] version 3.0 or later
 
<li> Install [http://maven.apache.org/download.html Maven] version 3.0 or later
<li> '''Window > Preferences > Maven > Installations > Add...''' and add your Maven 3 installation; activate it
+
<li> If your internet connection uses a proxy, make sure that you have the proxy configured in your [http://maven.apache.org/settings.html Maven settings.xml]
<li> Get the sources from [https://github.com/sonatype/sonatype-tycho Github]; there are different ways to do this:
+
<li> Get the [http://git.eclipse.org/c/tycho/org.eclipse.tycho.git/ Tycho sources] from eclipse.org; there are different ways to do this:
* In EGit, open the '''Git Repositories''' view, select '''Clone a Git Repository''' and clone from the location https://github.com/sonatype/sonatype-tycho.git
+
* In EGit, open the '''Git Repositories''' view, select '''Clone a Git Repository''' and clone from the location https://git.eclipse.org/r/tycho/org.eclipse.tycho.git
* In a shell (e.g. from [http://code.google.com/p/msysgit/ msysgit] or [http://cygwin.com/ Cygwin]), execute <tt>git clone git://github.com/sonatype/sonatype-tycho.git</tt>
+
* In a shell, execute <tt>git clone https:</tt><tt>//git.eclipse.org/r/tycho/org.eclipse.tycho.git</tt>
<li> In Eclipse, use '''File > Import > Existing Maven Projects''' and the <tt>sonatype-tycho/tycho-p2-resolver</tt> and <tt>sonatype-tycho/</tt> directories. (The two imports are necessary because there is no POM that aggregates all Tycho modules.) Install the proposed project configurators and restart Eclipse after the second import.
+
<li> In Eclipse, use '''File > Import > Existing Maven Projects''', select the root directory of the sources, and import all projects. Install the proposed project configurators and restart Eclipse.
<li> Optional: Select all projects, right click and choose '''Team > Share Project > Git'''
+
<li> Configure the target platform: Open the file <tt>tycho-bundles-target/tycho-bundles-target.target</tt> and click on '''Set as Target Platform''' in the upper right corner of the target definition editor.
 
<li> The result should be an eclipse workspace without build errors. m2eclipse may take some time to download required libraries from Maven central.
 
<li> The result should be an eclipse workspace without build errors. m2eclipse may take some time to download required libraries from Maven central.
 
</ol>
 
</ol>
  
If there are build errors after import, you can try the following steps to work around caching issues in the PDE:
+
If you get an "Error Updating Maven Configuration" for the projects org.eclipse.tycho.surefire.junit, org.eclipse.tycho.surefire.junit4, and org.eclipse.tycho.surefire.osgibooter, select just these three projects, select '''Maven > Update project...''' from the context menu and confirm the dialog.
# Refresh all projects. A <tt>jars</tt> folder should show up in both org.eclipse.tycho.surefire.junit and org.eclipse.tycho.surefire.osgibooter.
+
# For the projects starting with "org.eclipse.tycho.surefire", select '''Maven > Update Project Configuration''' from the context menu. This should add a Referenced Libraries classpath container referencing the libraries in projects' <tt>jars</tt> folders (where available).
+
# Remove the Plug-in Dependencies classpath containers on the projects starting with "org.eclipse.tycho", and re-create them via the context menu '''PDE Tools > Update Classpath...'''. After this step, the Plug-in Dependencies classpath containers should also contain projects from the workspace.
+
  
 
== Building Tycho ==
 
== Building Tycho ==
  
In order to build Tycho from the command line, you should use the scripts in the root of the sources:
+
Tycho can be built from source by executing <tt>mvn clean install</tt> in the root directory.
# Edit <tt>bootstrap.cmd</tt> in the <tt>sonatype-tycho/</tt> root directory and adapt the variables <tt>TYCHO_TEST_TARGET_PLATFORM</tt> -> point to Eclipse SDK 3.7.0 plus delta pack, <tt>TYCHO_M2_HOME</tt> -> point to maven 3 home directory
+
 
# If you want to skip long-running integration tests, comment out line <tt>mvn -f tycho-its\pom.xml clean test</tt>
+
In order to execute the Tycho integration tests, you can use the scripts in the root of the sources:
 +
# Edit <tt>bootstrap.cmd</tt> in the root directory and adapt the variables <tt>TYCHO_TEST_TARGET_PLATFORM</tt> -> point to Eclipse SDK 3.7.0 plus delta pack, <tt>TYCHO_M2_HOME</tt> -> point to maven 3 home directory
 
# Execute <tt>.\bootstrap.cmd</tt>
 
# Execute <tt>.\bootstrap.cmd</tt>
 +
 +
== Continuous Integration Build Jobs ==
 +
 +
CI and gerrit voter as well as integration test build jobs at eclipse can be found on [http://hudson.eclipse.org/tycho hudson.eclipse.org/tycho]
 +
 +
== Debugging Tycho ==
 +
 +
In order to debug Tycho plugins inside Eclipse:
 +
# Get Tycho sources in Eclipse
 +
# create/get a project that highlight the bug
 +
# Run the project with '''mvnDebug clean install'''
 +
# Go into your Eclipse, use Debug > Remote Java Application, select port 8000
  
 
== Advanced Topics ==
 
== Advanced Topics ==
Line 35: Line 42:
 
=== Executing integration tests in Eclipse ===
 
=== Executing integration tests in Eclipse ===
  
It is possible to start the integration tests directly from Eclipse. Note however that you will still need to build Tycho through a <tt>mvn install</tt> whenever you have made changes to the Tycho code, e.g. using the <tt>bootstrap.cmd</tt> as described above. (Background: The integration tests trigger builds of test projects -- and these builds take Tycho from it's normal location, i.e. the local Maven repository.)
+
It is possible to start most integration tests directly from Eclipse. Note however that you will still need to build Tycho through a <tt>mvn install</tt> first whenever you have made changes to the Tycho code, e.g. using the <tt>bootstrap.cmd</tt> as described above. (Background: The integration tests trigger builds of test projects -- and these builds take Tycho from it's normal location, i.e. the local Maven repository.)
  
 
'''Tips:'''
 
'''Tips:'''
 
* The integration test builds use the settings stored in <tt>tycho-its/settings.xml</tt> (they don't use the default Maven settings.xml). If you have special requirements, e.g. for proxy settings, you can edit this file. Alternatively, you can point to a different settings.xml with the system property <tt>tycho.testSettings</tt>.
 
* The integration test builds use the settings stored in <tt>tycho-its/settings.xml</tt> (they don't use the default Maven settings.xml). If you have special requirements, e.g. for proxy settings, you can edit this file. Alternatively, you can point to a different settings.xml with the system property <tt>tycho.testSettings</tt>.
 +
 +
=== Writing integration tests ===
 +
 +
The hardest part for writing Tycho integration tests is the naming. While names are mostly important for readability, there were also cases where the ID "feature" was used multiple times and hence a test used the build result of a different integration test.
 +
 +
Therefore, here are a few tips for writing good integration tests:
 +
* Test project name: Although many existing test have a bug number in the name, this is '''not''' the recommended naming scheme. Since integration test can take some time to execute, it may be a good idea to test related things in one test. <br>So name the test projects in a way that they can be found, and that related tests are sorted next to each other, e.g. in the form <tt>&lt;feature&gt;.&lt;aspect&gt;</tt>.
 +
* Package: Should be <tt>org.eclipse.tycho.test.&lt;feature&gt;</tt> (without the aspect so that we don't get an excessive number of packages)
 +
* Test project groupIds: Should be <tt>tycho-its-project.&lt;feature&gt;.&lt;aspect&gt;</tt> plus a segment for the reactor in case of multi-reactor tests. The groupId is particularly important if the test project is installed to the local Maven repository. (Avoid install; use verify if possible.)
 +
* Test project artifactIds: Should be the same as the ID of the feature/bundle; need to start with something unique, e.g. the first letters of each segment of the project name.
 +
 +
If you have integration tests under your local sub-module (like tycho-eclipserun-plugin from tycho-extras) then you need to:
 +
* Build tycho using "bootstrap.sh"
 +
* Build tycho-extras using "mvn install -Dmaven.repo.local=/tmp/tycho-bootstrap.localrepo"
 +
* Run you integration test "mvn integration-test -Pits -Dtycho-snapshots-url=file:/tmp/tycho-bootstrap.localrepo"
  
 
=== Building Tycho against a locally built version of p2 ===
 
=== Building Tycho against a locally built version of p2 ===
Line 46: Line 68:
 
# Get the p2 sources (see [[Equinox p2 Getting Started for Developers]])
 
# Get the p2 sources (see [[Equinox p2 Getting Started for Developers]])
 
# Make changes in the p2 sources
 
# Make changes in the p2 sources
# (Temporarily) increase the versions of the changed p2 bundles, and require these versions in the tycho-p2-runtime.product
+
# (Temporarily) increase the versions of the changed p2 bundles, and require these versions in the tycho-bundles-external.product
 
# Build the changed p2 bundles individually with <tt>mvn clean install</tt> (a full p2 build with Tycho may not work; see [https://bugs.eclipse.org/bugs/show_bug.cgi?id=304594 bug 304594])
 
# Build the changed p2 bundles individually with <tt>mvn clean install</tt> (a full p2 build with Tycho may not work; see [https://bugs.eclipse.org/bugs/show_bug.cgi?id=304594 bug 304594])
# Build at least the Tycho module tycho-p2-runtime with <tt>mvn clean install</tt>
+
# Build at least the Tycho module tycho-bundles-external with <tt>mvn clean install</tt>
 
Then the locally built Tycho SNAPSHOT includes the patched p2 version.
 
Then the locally built Tycho SNAPSHOT includes the patched p2 version.
  

Revision as of 10:08, 27 March 2014

Importing the Tycho sources

To import the Tycho sources into Eclipse, you need to have a recent version of the Maven integration for Eclipse (m2eclipse) installed. m2eclipse is included in various Eclipse packages, e.g. the "Eclipse for RCP and RAP Developers" package. (Note: m2eclipse is not included in an the Eclipse Standard package.) If you need to add m2eclipse to your Eclipse installation, you can get it from the Eclipse Marketplace.

Step by step instructions:

  1. Get an "Eclipse for RCP and RAP Developers" or "Eclipse IDE for Java EE Developers" package for your platform from the Eclipse Downloads page
  1. Install Maven version 3.0 or later
  2. If your internet connection uses a proxy, make sure that you have the proxy configured in your Maven settings.xml
  3. Get the Tycho sources from eclipse.org; there are different ways to do this:
  4. In Eclipse, use File > Import > Existing Maven Projects, select the root directory of the sources, and import all projects. Install the proposed project configurators and restart Eclipse.
  5. Configure the target platform: Open the file tycho-bundles-target/tycho-bundles-target.target and click on Set as Target Platform in the upper right corner of the target definition editor.
  6. The result should be an eclipse workspace without build errors. m2eclipse may take some time to download required libraries from Maven central.

If you get an "Error Updating Maven Configuration" for the projects org.eclipse.tycho.surefire.junit, org.eclipse.tycho.surefire.junit4, and org.eclipse.tycho.surefire.osgibooter, select just these three projects, select Maven > Update project... from the context menu and confirm the dialog.

Building Tycho

Tycho can be built from source by executing mvn clean install in the root directory.

In order to execute the Tycho integration tests, you can use the scripts in the root of the sources:

  1. Edit bootstrap.cmd in the root directory and adapt the variables TYCHO_TEST_TARGET_PLATFORM -> point to Eclipse SDK 3.7.0 plus delta pack, TYCHO_M2_HOME -> point to maven 3 home directory
  2. Execute .\bootstrap.cmd

Continuous Integration Build Jobs

CI and gerrit voter as well as integration test build jobs at eclipse can be found on hudson.eclipse.org/tycho

Debugging Tycho

In order to debug Tycho plugins inside Eclipse:

  1. Get Tycho sources in Eclipse
  2. create/get a project that highlight the bug
  3. Run the project with mvnDebug clean install
  4. Go into your Eclipse, use Debug > Remote Java Application, select port 8000

Advanced Topics

Executing integration tests in Eclipse

It is possible to start most integration tests directly from Eclipse. Note however that you will still need to build Tycho through a mvn install first whenever you have made changes to the Tycho code, e.g. using the bootstrap.cmd as described above. (Background: The integration tests trigger builds of test projects -- and these builds take Tycho from it's normal location, i.e. the local Maven repository.)

Tips:

  • The integration test builds use the settings stored in tycho-its/settings.xml (they don't use the default Maven settings.xml). If you have special requirements, e.g. for proxy settings, you can edit this file. Alternatively, you can point to a different settings.xml with the system property tycho.testSettings.

Writing integration tests

The hardest part for writing Tycho integration tests is the naming. While names are mostly important for readability, there were also cases where the ID "feature" was used multiple times and hence a test used the build result of a different integration test.

Therefore, here are a few tips for writing good integration tests:

  • Test project name: Although many existing test have a bug number in the name, this is not the recommended naming scheme. Since integration test can take some time to execute, it may be a good idea to test related things in one test.
    So name the test projects in a way that they can be found, and that related tests are sorted next to each other, e.g. in the form <feature>.<aspect>.
  • Package: Should be org.eclipse.tycho.test.<feature> (without the aspect so that we don't get an excessive number of packages)
  • Test project groupIds: Should be tycho-its-project.<feature>.<aspect> plus a segment for the reactor in case of multi-reactor tests. The groupId is particularly important if the test project is installed to the local Maven repository. (Avoid install; use verify if possible.)
  • Test project artifactIds: Should be the same as the ID of the feature/bundle; need to start with something unique, e.g. the first letters of each segment of the project name.

If you have integration tests under your local sub-module (like tycho-eclipserun-plugin from tycho-extras) then you need to:

  • Build tycho using "bootstrap.sh"
  • Build tycho-extras using "mvn install -Dmaven.repo.local=/tmp/tycho-bootstrap.localrepo"
  • Run you integration test "mvn integration-test -Pits -Dtycho-snapshots-url=file:/tmp/tycho-bootstrap.localrepo"

Building Tycho against a locally built version of p2

Tycho makes heavy use of p2 functionality. Therefore it may be useful to try out patches in p2 before the next version of p2 has been released. With the following steps it is possible to build Tycho against a locally built version of p2.

  1. Get the p2 sources (see Equinox p2 Getting Started for Developers)
  2. Make changes in the p2 sources
  3. (Temporarily) increase the versions of the changed p2 bundles, and require these versions in the tycho-bundles-external.product
  4. Build the changed p2 bundles individually with mvn clean install (a full p2 build with Tycho may not work; see bug 304594)
  5. Build at least the Tycho module tycho-bundles-external with mvn clean install

Then the locally built Tycho SNAPSHOT includes the patched p2 version.

Note: Tycho always allows references to previously built artifacts, even if they are not part of the target platform. Therefore you may want to clear the list of locally built artifacts (in the local Maven repository in .meta/p2-local-metadata.properties) after local changes a described above.