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 "Developing Tycho"

(Debugging)
(14 intermediate revisions by 7 users not shown)
Line 1: Line 1:
== Importing the Tycho sources ==
+
== Setup your environment ==
  
 +
=== Using the Eclipse Installer (Oomph) ===
 
Step by step instructions:
 
Step by step instructions:
# Get an Eclipse IDE with a recent version of the [http://www.eclipse.org/m2e/ 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 [https://wiki.eclipse.org/Simultaneous_Release release train p2 repository] or from the [https://www.eclipse.org/m2e/download/ m2eclipse download site].
+
# Download the [https://wiki.eclipse.org/Eclipse_Installer Eclipse Installer].
 +
# Start the installer using the ''eclipse-inst'' executable.
 +
# On the first page (product selection), click the preference button in the top-right corner and select the ''Advanced Mode''.
 +
# If you are behind a proxy, at this point you might want to double check your network settings by clicking in the "Network Proxy Settings" at the bottom.
 +
# Select ''Eclipse IDE for Eclipse Committers''. Click ''Next''.
 +
# Under ''Eclipse.org'', double-click on ''Tycho'' (single click is not enough!). Make sure that ''Tycho'' is shown in the table on the bottom. Click ''Next''.
 +
# You can edit the ''Installation Folder'', but you do not have to select the ''Target Platform'' here, this will be set later automatically. By choosing ''Show all variables'' at the bottom of the page, you are able to change other values as well but you do not have to. Click ''Next''.
 +
# Press ''Finished'' on the ''Confirmation'' page will start the installation process.
 +
# The installer will download the selected Eclipse version, starts Eclipse and will perform all the additional steps (cloning the git repos, etc...). When the downloaded Eclispe started, the progress bar in the status bar shows the progress of the overall setup.
 +
# Once the ''Executing startup tasks'' job is finished you should have all the Tycho and Tycho Extras projects imported into 2 working sets called ''Tycho'' and ''Tycho Extras''.
 +
# Some Projects might sill have errors. Select them (or all) and choose ''Maven''->''Update Project..'' from the context menu. De-select ''Clean projects'' in the shown dialog and press ''OK'' to update the projects. After that, no more error should be there. 
 +
 
 +
=== Manually setup ===
 +
Prefered and easier way is to follow the instructions above, but you could also setup your environment manually:
 +
# Get an [https://www.eclipse.org/downloads/ Eclipse IDE] with a recent version of the [http://www.eclipse.org/m2e/ Maven integration for Eclipse (m2eclipse)] and Eclipse PDE installed. m2eclipse is included in various Eclipse packages, e.g. the "Eclipse IDE for Eclipse Committers" package. To add m2eclipse to your existing Eclipse installation, install it from the [https://wiki.eclipse.org/Simultaneous_Release release train p2 repository] or from the [http://download.eclipse.org/technology/m2e/releases m2eclipse update site].
 
# Install [http://maven.apache.org/download.html Maven] version 3.0 or later
 
# Install [http://maven.apache.org/download.html Maven] version 3.0 or later
 
# 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]
 
# 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]
 
# Get the [https://projects.eclipse.org/projects/technology.tycho/developer Tycho sources] from eclipse.org; there are different ways to do this:
 
# Get the [https://projects.eclipse.org/projects/technology.tycho/developer 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 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 for Tycho.
#* In a shell, execute <tt>git clone https:</tt><tt>//git.eclipse.org/r/tycho/org.eclipse.tycho </tt>
+
#* In a shell, execute <tt>git clone https:</tt><tt>//git.eclipse.org/r/tycho/org.eclipse.tycho </tt> for Tycho.
 
# 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.
 
# 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.
# 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.
+
# For Tycho only: 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.
  
 
The result should be an Eclipse workspace without build errors. m2eclipse may take some time to download required libraries from Maven central.
 
The result should be an Eclipse workspace without build errors. m2eclipse may take some time to download required libraries from Maven central.
Line 15: Line 30:
 
* If there are compile errors in the project <tt>tycho-p2-director-plugin</tt>, 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 <tt>tycho-p2-director-plugin/.settings/org.eclipse.jdt.core.prefs</tt>. (Background: The project optionally uses classes from the Java 7 library, so it needs to compile with a Java 7 JDK.)
 
* If there are compile errors in the project <tt>tycho-p2-director-plugin</tt>, 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 <tt>tycho-p2-director-plugin/.settings/org.eclipse.jdt.core.prefs</tt>. (Background: The project optionally uses classes from the Java 7 library, so it needs to compile with a Java 7 JDK.)
  
== Building Tycho ==
+
== Building and Testing ==
  
Tycho can be built from source by executing '''<tt>mvn clean install</tt>''' in the source root.
+
To build Tycho/Tycho Extras from source, executed '''<tt>mvn clean install</tt>''' in the source root. This also runs the unit tests.
  
Then, you can execute the Tycho integration tests with <tt>mvn clean install -f tycho-its/pom.xml</tt>
+
=== Tycho integration tests ===
  
== Continuous Integration Build Jobs ==
+
The Tycho integration tests are located in the project <tt>tycho-its</tt>. To run all Tycho integration tests, execute <tt>mvn clean install -f tycho-its/pom.xml</tt>. To run a single integration test, select the test class in Eclipse and run it as ''JUnit Test''.
  
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]
+
'''Background information on the Tycho integration tests'''
  
== Debugging Tycho ==
+
The integration tests trigger sample builds that use Tycho. These builds expect that Tycho has been installed to the local Maven repository. This is why you need to build Tycho through a <tt>mvn install</tt> before you can run the integration tests.
 +
 
 +
Alternatively, e.g. if you are only interested in modifying an integration test and do not want to patch Tycho itself, you can configure the integration tests to download the current Tycho snapshot produced by the [http://hudson.eclipse.org/tycho/view/CI Tycho CI builds]. To do this, you need to edit the Maven settings stored in <tt>tycho-its/settings.xml</tt> and add the tycho-snapshots repository as described in [[Getting Tycho]]. (Advanced note: The integration tests can also be pointed to a different settings.xml with the system property <tt>tycho.testSettings</tt>.)
 +
 
 +
=== Tycho Extras integration tests ===
 +
 
 +
Each Tycho Extras project does have its own integration tests located in the subdirectory <tt>it</tt> within the project (e.g. <tt>tycho-eclipserun-plugin/src/it</tt>).
 +
To run the tests use the maven profile <tt>its</tt>, run <tt>mvn integration-test -Pits</tt> either within the Tycho Extras source folder to run all Tycho Extras integration tests or within a Tycho Extras plugin directory to run only the integration tests of that project.
 +
 
 +
'''Background information on the Tycho Extras integration tests'''
 +
 
 +
Tycho Extras and Tycho are developed and released in parallel and will use the snapshot version of Tycho from the repository <tt>https://repo.eclipse.org/content/repositories/tycho-snapshots/</tt>.
 +
If you want to run the tests with a specific version of Tycho use the <tt>tycho-version</tt> system property, e.g. <tt>mvn integration-test -Pits -Dtycho-version=0.22.0</tt>.
 +
To use a different Tycho snapshot repository use the system property <tt>tycho-snapshots-url</tt>, e.g. <tt>mvn integration-test -Pits -Dtycho-snapshots-url=file:/path/to/repo</tt>
 +
 
 +
== Debugging ==
  
 
In order to debug Tycho plugins inside Eclipse:
 
In order to debug Tycho plugins inside Eclipse:
# Get Tycho sources in Eclipse
+
# Get the Tycho sources in Eclipse
 
# Create/get a project that highlights the bug
 
# Create/get a project that highlights the bug
 
# Run the project with <tt>mvnDebug clean install</tt>
 
# Run the project with <tt>mvnDebug clean install</tt>
Line 35: Line 65:
 
== Advanced Topics ==
 
== Advanced Topics ==
  
=== Executing integration tests in Eclipse ===
+
=== Writing Tycho integration tests ===
 
+
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. (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 <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.
 
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:
 
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>.
+
* 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;component&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)
+
* Package: Should be <tt>org.eclipse.tycho.test.&lt;component&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 groupIds: Should be <tt>tycho-its-project.&lt;component&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.
+
* Test project artifactIds: Have to 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 ===
  
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.
+
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.
  
# Get the p2 sources (see [[Equinox p2 Getting Started for Developers]])
+
# Get the p2 sources (see [http://projects.eclipse.org/projects/rt.equinox.p2/developer p2 project information])
 
# 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-bundles-external.product
+
# Build the changed p2 bundles individually with <tt>mvn clean install -Pbuild-individual-bundles</tt> (see [[Equinox/p2/Build]] for more information)
# 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-bundles-external with <tt>mvn clean install</tt> - you should see a warning that the locally built p2 bundles have been used.
# 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.
  
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.
+
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.
 +
 
 +
=== Updating the Equinox and JDT dependencies of Tycho ===
 +
 
 +
Tycho has Maven dependencies to Equinox and JDT, so these artifact are used from  Maven  Central repository.  
  
 
[[Category:Tycho]]
 
[[Category:Tycho]]

Revision as of 03:18, 28 May 2020

Setup your environment

Using the Eclipse Installer (Oomph)

Step by step instructions:

  1. Download the Eclipse Installer.
  2. Start the installer using the eclipse-inst executable.
  3. On the first page (product selection), click the preference button in the top-right corner and select the Advanced Mode.
  4. If you are behind a proxy, at this point you might want to double check your network settings by clicking in the "Network Proxy Settings" at the bottom.
  5. Select Eclipse IDE for Eclipse Committers. Click Next.
  6. Under Eclipse.org, double-click on Tycho (single click is not enough!). Make sure that Tycho is shown in the table on the bottom. Click Next.
  7. You can edit the Installation Folder, but you do not have to select the Target Platform here, this will be set later automatically. By choosing Show all variables at the bottom of the page, you are able to change other values as well but you do not have to. Click Next.
  8. Press Finished on the Confirmation page will start the installation process.
  9. The installer will download the selected Eclipse version, starts Eclipse and will perform all the additional steps (cloning the git repos, etc...). When the downloaded Eclispe started, the progress bar in the status bar shows the progress of the overall setup.
  10. Once the Executing startup tasks job is finished you should have all the Tycho and Tycho Extras projects imported into 2 working sets called Tycho and Tycho Extras.
  11. Some Projects might sill have errors. Select them (or all) and choose Maven->Update Project.. from the context menu. De-select Clean projects in the shown dialog and press OK to update the projects. After that, no more error should be there.

Manually setup

Prefered and easier way is to follow the instructions above, but you could also setup your environment manually:

  1. Get an Eclipse IDE with a recent version of the Maven integration for Eclipse (m2eclipse) and Eclipse PDE installed. m2eclipse is included in various Eclipse packages, e.g. the "Eclipse IDE for Eclipse Committers" package. 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 for Tycho.
    • In a shell, execute git clone https://git.eclipse.org/r/tycho/org.eclipse.tycho for 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. For Tycho only: 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 and Testing

To build Tycho/Tycho Extras from source, executed mvn clean install in the source root. This also runs the unit tests.

Tycho integration tests

The Tycho integration tests are located in the project tycho-its. To run all Tycho integration tests, execute mvn clean install -f tycho-its/pom.xml. To run a single integration test, select the test class in Eclipse and run it as JUnit Test.

Background information on the Tycho integration tests

The integration tests trigger sample builds that use Tycho. These builds expect that Tycho has been installed to the local Maven repository. This is why you need to build Tycho through a mvn install before you can run the integration tests.

Alternatively, e.g. if you are only interested in modifying an integration test and do not want to patch Tycho itself, you can configure the integration tests to download the current Tycho snapshot produced by the Tycho CI builds. To do this, you need to edit the Maven settings stored in tycho-its/settings.xml and add the tycho-snapshots repository as described in Getting Tycho. (Advanced note: The integration tests can also be pointed to a different settings.xml with the system property tycho.testSettings.)

Tycho Extras integration tests

Each Tycho Extras project does have its own integration tests located in the subdirectory it within the project (e.g. tycho-eclipserun-plugin/src/it). To run the tests use the maven profile its, run mvn integration-test -Pits either within the Tycho Extras source folder to run all Tycho Extras integration tests or within a Tycho Extras plugin directory to run only the integration tests of that project.

Background information on the Tycho Extras integration tests

Tycho Extras and Tycho are developed and released in parallel and will use the snapshot version of Tycho from the repository https://repo.eclipse.org/content/repositories/tycho-snapshots/. If you want to run the tests with a specific version of Tycho use the tycho-version system property, e.g. mvn integration-test -Pits -Dtycho-version=0.22.0. To use a different Tycho snapshot repository use the system property tycho-snapshots-url, e.g. mvn integration-test -Pits -Dtycho-snapshots-url=file:/path/to/repo

Debugging

In order to debug Tycho plugins inside Eclipse:

  1. Get the 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

Writing Tycho 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 <component>.<aspect>.
  • Package: Should be org.eclipse.tycho.test.<component> (without the aspect so that we don't get an excessive number of packages)
  • Test project groupIds: Should be tycho-its-project.<component>.<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: Have to 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.

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.

Updating the Equinox and JDT dependencies of Tycho

Tycho has Maven dependencies to Equinox and JDT, so these artifact are used from Maven Central repository.

Back to the top