Difference between revisions of "Developing Tycho"

Revision as of 14:27, 11 February 2015

Importing the Tycho sources

Step by step instructions:

1. Get an Eclipse IDE with a recent version of the Maven integration for Eclipse (m2eclipse) and PDE installed. m2eclipse is included in various Eclipse packages, e.g. the "Eclipse for Java Developers" package. (Note: m2eclipse is not included in an the "Eclipse for Committers" package which includes PDE.) To add m2eclipse to your existing Eclipse installation, install it from the release train p2 repository or from the m2eclipse update site.
2. Install Maven version 3.0 or later
3. If your Internet connection uses a proxy, make sure that you have the proxy configured in your Maven settings.xml
4. Get the 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://git.eclipse.org/r/tycho/org.eclipse.tycho
   • In a shell, execute git clone https://git.eclipse.org/r/tycho/org.eclipse.tycho
5. In Eclipse, use File > Import > Existing Maven Projects, select the root directory of the sources, and import all projects. If prompted by m2eclipse, install the proposed project configurators and restart Eclipse.
6. 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.

The result should be an Eclipse workspace without build errors. m2eclipse may take some time to download required libraries from Maven central.

• If there are compile errors in the projects org.eclipse.tycho.surefire.junit, org.eclipse.tycho.surefire.junit4, org.eclipse.tycho.surefire.junit47, or org.eclipse.tycho.surefire.osgibooter, just select these projects and manually trigger an update via Maven > Update project... from the context menu.
• If there are compile errors in the project tycho-p2-director-plugin, right-click on the project and go to Build Path > Configure Build Path... and change the JRE System Library to JavaSE-1.7. Then revert the changes that the PDE does to the file tycho-p2-director-plugin/.settings/org.eclipse.jdt.core.prefs. (Background: The project optionally uses classes from the Java 7 library, so it needs to compile with a Java 7 JDK.)

Building Tycho

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

Then, you can execute the Tycho integration tests with mvn clean install -f tycho-its/pom.xml

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 highlights 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. (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 to p2 without waiting for a new p2 release, or even just the next nightly build. With the following steps it is possible to build Tycho against a locally built version of p2.

1. Get the p2 sources (see p2 project information)
2. Make changes in the p2 sources
3. Build the changed p2 bundles individually with mvn clean install -Pbuild-individual-bundles (see Equinox/p2/Build for more information)
4. Build at least the Tycho module tycho-bundles-external with mvn clean install - you should see a warning that the locally built p2 bundles have been used.

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

Note: Tycho always allows references to locally 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 you have finished your trials with the patched p2 version.