Support free tutorials



vogella training Training Books

Eclipse IDE platform development - tutorial

Contributing to the Eclipse open source project

Lars Vogel

Version 6.5

13.03.2014

Eclipse platform development

This tutorial explains how to contribute to the Eclipse Open Source project for the Eclipse IDE.


Table of Contents

1. Contributing to the Eclipse open source project
1.1. Extending via contributing
1.2. Users, Contributors and Committers
2. Accessing the source code of an Eclipse project
2.1. Which version control system is used?
2.2. How to get a copy of the Eclipse source code
3. Eclipse projects responsible for the Java IDE
3.1. The Eclipse project
3.2. The Eclipse platform projects home pages
4. The platform development team
4.1. Who is involved?
4.2. Example: platform.ui
5. Official Eclipse SDK releases
5.1. Available Eclipse downloads
5.2. Download latest M or RC build
5.3. Download the latest integration build
6. Install additional development tools
6.1. Required plug-ins
6.2. Exercise: Install Eclipse e4 tool
6.3. Exercise: Install additional plug-ins via install file
7. Contributing to the Eclipse project
7.1. What can you contribute
7.2. Answering questions in the Eclipse forums or Stack Overflow
7.3. Writing or updating documentation
7.4. Reporting bugs or feature requests
7.5. Helping with bug triage
7.6. Fixing existing code
8. Exercise: Review Eclipse bug reports
8.1. Target
8.2. Run Bugzilla query
8.3. Review Bugs
8.4. Optional: Request the right to close bugs
9. Eclipse setup for Gerrit contributions
9.1. Required setup
9.2. Create an Eclipse user account
9.3. Sign the Contributor License Agreement (CLA)
10. Eclipse Gerrit configuration
10.1. Configure your Eclipse Gerrit user
10.2. Authentication via HTTPS
10.3. Authentication via SSH
10.4. Authentication via SSH
10.5. Eclipse support for SSH based authentication
11. Clone a selected Eclipse Git repository
12. Gerrit push configuration
12.1. Gerrit push URL
12.2. Exercise: Configure Gerrit push refspec
12.3. Validate: Gerrit push configuration
13. Make a change and push a review
13.1. Make a code change
13.2. Push to the Gerrit review system
13.3. Updating the Gerrit review
14. Eclipse platform Git repositories
14.1. Platform UI
14.2. Java development tools (JDT)
15. Eclipse and tests
15.1. Eclipse projects and their test suite
15.2. Version of JUnit
15.3. Tips: running the unit tests on a virtual server
16. Running the Eclipse platform unit tests
16.1. Repositories for platform tests
16.2. Example: JFace tests
16.3. Performance tests
17. Creating a custom Eclipse IDE build
17.1. Eclipse IDE builds and the Common Build Infrastructure (CBI)
17.2. Requirements
17.3. Setup the build
17.4. Cloning the SDK repository
17.5. Run the build
17.6. The results
17.7. Cleanup before the next build
18. Additional infos about building the Eclipse platform
18.1. Reporting issues or asking questions about the build
18.2. Eclipse platform Hudson builds
18.3. Release and milestone builds
18.4. Changing build ID
18.5. Build single parts of the aggregator
18.6. Building natives (SWT binary files)
18.7. Fedora Eclipse CBI build
19. Information about the e4 tools
19.1. e4 tools and committer
19.2. Git repository for the e4 tools
19.3. Infos about the e4 tools
19.4. Adding an editor for a custom model elements
19.5. Building the e4 tools
20. Cloning from the Git server and adjusting the push URL
20.1. Why adjusting the push URL?
20.2. Cloning from the Git server and adjusting the push URL
21. About this website
21.1. Donate to support free tutorials
21.2. Questions and discussion
21.3. License for this tutorial and its code
22. Links and Literature
22.1. Source Code

Get the book Eclipse Contribution book

1. Contributing to the Eclipse open source project

1.1. Extending via contributing

As the Eclipse project is an open source project, it is possible to get the source code, modify it and provide the change back to the project. Eclipse projects typically use a review process based on the Gerrit code review system to review the changes and, if the change fits into the project goal, apply it once it has been polished.

Contributing to an Eclipse project has the benefit of getting feedback directly from the core developers. It also allows developers and organizations to fix bugs which affect them and to drive the project into a desired direction.

1.2. Users, Contributors and Committers

The development of the individual Eclipse projects is done by the Eclipse developers - companies and individuals alike - which develop the code.

The Eclipse project distinguishes between the following group of people:

  • Eclipse User - Using at least one product, e.g., a JAR file, of the Eclipse project. Eclipse users consume the software created by the Eclipse developers but do not help with the Eclipse project.

  • Contributor - Submits code corrections, write documentation or file bug reports. A contributor does not have access right to submit code directly to an Eclipse project.

  • Committer - Has been trusted with reviewing patches and the privilege to make changes without going through code review.

Everyone has read access to the code repositories hosted at eclipse.org.

2. Accessing the source code of an Eclipse project

2.1. Which version control system is used?

Eclipse projects use the Git version control system. Eclipse lists all Eclipse Git repositories under the following URL: Eclipse source code repository.

2.2. How to get a copy of the Eclipse source code

To find the URL for cloning the Git repository of a project, you can search in this webpage. For example, if you want to clone the e4 tools Git repository, you can search for e4 and click on the e4.tools repository.

Eclipse Git repos, Tycho example

If you click on the project, you see the details of this project, e.g., the commits. At the bottom of the page you also see the URL to clone the repository.

Eclipse Git repos, e4 tools example

Note

The URL listed in this part is not optimized for Gerrit contributions. See Section 11, “Clone a selected Eclipse Git repository” for a better way to clone in case you want to contribute via Gerrit.

3. Eclipse projects responsible for the Java IDE

3.1. The Eclipse project

The Eclipse IDE is an open source (OS) project. Eclipse.org hosts lots of OS projects with different purposes, but the foundation of the whole Eclipse IDE is delivered by the Eclipse platform, the Java development tools (JDT) and the Plug-in Development Environment (PDE) project.

All these projects belong to the project called "Eclipse project". The name is a bit strange since nowadays there are many Eclipse projects. But it originates from the fact that these projects are at the beginning the only available Eclipse projects.

These components are bundled together as the Eclipse Standard Development Kit (SDK) release. This is also known as the Eclipse standard distribution. The Eclipse SDK contains all tools to develop Eclipse plug-ins.

In addition to these projects, the platform also has an incubator project called e4 which provides new tools for Eclipse 4 developments. It also serves as a testing ground for new ideas.

3.2. The Eclipse platform projects home pages

The following table lists the home pages of these projects:

Table 1. Eclipse projects

Project Home page
Platform Eclipse platform project
Java development tools (JDT) JDT project
Plug-in Development Environment (PDE) PDE project
e4 e4 project


4. The platform development team

4.1. Who is involved?

Despite the general assumption that the Eclipse SDK components are developed by an army of developers, the actual core developer team is relatively small.

General information about an Eclipse project can be found under http://projects.eclipse.org/. For example via the Members link you can see the project lead and the most active committers. For example, the information for the platform project can be found under the Eclipse project link.

Note

Since the core team is relatively small, contributors can really make a difference.

Tip

To find out how many people contribute to a given Eclipse Git repo you can use the following command on a Linux like system. For example running this command shows 27 on July, 07, 2014 result in 27 people contributing to the platform.ui repository.

git log --since='last 3 month' --raw | grep "^Author: " | sort | uniq -c | wc -l 

4.2. Example: platform.ui

It is possible to see the contributions by individual Git repository, for example, as depicted in the following screenshot for the platform.ui project, which can be reached via Eclipse platform.ui project page.

An alternative view gives the new dashboard. For example the following screeenshot shows the Platform.ui dashboard link.

Platform.ui dashboard

5. Official Eclipse SDK releases

5.1. Available Eclipse downloads

The Eclipse project has a simultaneous release every year at the end of June. In June 2014 the Eclipse 4.4 (Luna) version was released.

The Eclipse project creates regular builds of the next releases. You find Stable Builds which are tested by the community. These milestone (ending with M and a number) and release candidate (RC) builds are created based on a predefined time schedule.

Integration (I) and Nightly (N) builds are test builds which are automatically created. They are not manually tested.

In general, milestone and RC builds are relative stable compared to integration builds, but may not contain the latest features and patches.

5.2. Download latest M or RC build

To contribute to the Eclipse open source project, you need to download one of the recent integration or milestone builds. The official Eclipse release typical don't compile the latest code, because too many dependencies have changed.

You find one of latest M or RC builds under the Eclipse project download page link.

Note

Directly after a new Eclipse release, you will not find M or RC builds. The first milestone build is typically created 6 weeks after the official release.

Typically M or RC builds should be good enough, except when you want to try out bleeding edge things.

5.3. Download the latest integration build

You can download the latest integration build for the next Eclipse release under the following URL: Eclipse developer builds .

Download development builds

This is sometimes necessary to test the latest features or to test a build which is later promoted to M or RC build by the Eclipse platform team.

6. Install additional development tools

6.1. Required plug-ins

The Eclipse SDK development requires that certain plug-ins are installed in your IDE. These plug-ins include for example the Mockito test library. The latest Eclipse SDK does also not include the Git tooling which needs to get installed separately.

6.2. Exercise: Install Eclipse e4 tool

You should also install the e4 tools as they provide tools for developing Eclipse 4 components.

You find a recent version of the e4 tools under the following update site: http://download.vogella.com/luna/e4tools. For newer versions check the http://download.vogella.com website.

Note

The above URL has been created by the vogella GmbH company to provide a stable update site. You find the official update sites for the Eclipse e4 tooling project under the following URL: http://download.eclipse.org/e4/downloads/

6.3. Exercise: Install additional plug-ins via install file

The Eclipse platform team provides a file from which these plug-ins can be installed. Download the following file: http://git.eclipse.org/c/platform/eclipse.platform.ui.git/plain/releng/org.eclipse.ui.releng/platformUiTools.p2f

You can install the plug-ins described by this file by using FileImport...InstallInstall Software Items from File.

7. Contributing to the Eclipse project

7.1. What can you contribute

Like in every successful open source project you have different possibilities to contribute to the Eclipse open source project. This chapter gives an overview of the possible options.

Non of these options are exclusive. Active Eclipse committers and contributors typically do all of them, e.g., answers questions in the forum, open bugs, update the wiki pages, etc.

7.2. Answering questions in the Eclipse forums or Stack Overflow

Currently, the best places to find, ask and answer questions are the Eclipse forums and Stack Overflow. Try to stay polite with your postings, as the Eclipse community values polite behaviour.

The Eclipse forums offer several topic-specific forums in which you can post and answer questions. To post or to answer questions in the Eclipse forums, you need a valid user account in the Eclipse bug tracker.

Stack Overflow also requires a user account and its community is also very active. Stack Overflow does not have separate forum sections for specific questions. At Stack Overflow you tag your questions with the relevant keyword, e.g., Eclipse and people search for them or subscribe to them.

7.3. Writing or updating documentation

Another way of contributing to the Eclipse open source project is to update the Eclipse Wiki and to write about Eclipse tips and tricks you find useful.

Another way to contribute to Eclipse is to write articles or blog posts about it. PlanetEclipse is a blog aggregator which collects new posts about Eclipse. If you blog about Eclipse you can ask to get aggregated at PlanetEclipse. Just click on the highlighted link to get started.

PlanetEclipse Aggregation

7.4. Reporting bugs or feature requests

If you find problems or have an idea on improvements in an Eclipse project you can open a new bug report at the Eclipse bugtracker.

As example you can report bugs for the Eclipse platform via the following link: Bug report for the Eclipse platform .

7.5. Helping with bug triage

If you are interested to help with bug solving, most Eclipse projects have a huge backlog of existing bug reports. It is often not possible for the committer to re-test all old bug reports. A contributor can re-test bug reports and report if they are already solved.

People which are interested in this activity should contact the email distribution list after re-testing a few bugs. Committer can nominate them to get the right to close bug reports form from others. See Eclipse bug triage for the nomination process.

This is also a valuable preparation step to contribute code fixes to the Eclipse project.

7.6. Fixing existing code

Once you have cloned a Git repository from Eclipse, you can import the related projects and start working on them.

After you finished a code contribution, you can commit the change locally and push it to Gerrit so that the Eclipse developers can review your change.

Note

This book focus on the contribution of code to the Eclipse project. The Eclipse platform project is used for the exercises and examples but the process should be applicable for almost all Eclipse projects.

8. Exercise: Review Eclipse bug reports

8.1. Target

In this exercise you use the Bugzilla system to review some of the Eclipse platform bugs. No action is excepted from you, but if you find an updated bug, you should update the bug report and describe that the problem is solved.

This exercise uses the Eclipse platform as example but you can use any Eclipse project of your choice.

8.2. Run Bugzilla query

Open to Eclipse Bugzilla and select the Search button. Select the Advanced Search tab and search for EclipsePlatformUI for all bugs in status NEW, ASSIGNED and REOPENED.

8.3. Review Bugs

Review at least 10 bugs from the result list. Try to reproduce the issue, if the bug reports a software error. If you are unable to reproduce the bug, add a comment in the bug that you cannot reproduce it.

8.4. Optional: Request the right to close bugs

After you commented on the outdated bugs, wait for a few days (or weeks) for the reaction of the existing Eclipse committer.

If your analysis of the bug was correct and you found several outdated bugs, you have proven that your analysis tends to be correct. In this case you could also request the right to close bugs directly. This is typically done via the https://dev.eclipse.org/mailman/listinfo/ Eclipse project mailing list, e.g., Platform UI mailing list for this example. Send a short email to the list, describing that you would like to help with the bug reports and lists the bugs you contributed to.

9. Eclipse setup for Gerrit contributions

9.1. Required setup

Most Eclipse.org projects and all Eclipse platform projects use the Gerrit code review system for contributions. Gerrit makes the process of contributing relatively simple (after the initial setup). It makes also reviewing these contributions very easy for the Eclipse committers.

Note

In theory you can also provide patches via Bugzilla, but experience has shown that patches are not that actively reviewed compared to Gerrit changes. Gerrit changes are easier to review and to update for both sides, hence committers are more likely to review Gerrit changes. Some projects, like Nebula, and JGit, EGit have stopped accepting patches through Bugzilla completely.

To contribute, you need to configure your Bugzilla and Gerrit user, this process is described in this chapter.

9.2. Create an Eclipse user account

You need to create an Eclipse.org user account to contribute to an Eclipse project via the following URL: Create Eclipse.org user account .

Tip

If you already have an Eclipse Bugzilla or Eclipse Forum account, you have already done this step. These systems use the same account.

9.3. Sign the Contributor License Agreement (CLA)

You also need to sign a contributor license agreement (CLA) via a web interface.

With the CLA you confirm that you have the rights to contribute source code to the Eclipse open source project.

Warning

In case you contribute to the Eclipse open source project during your work time, ensure that your employer agrees that the code can be contributed.

The Eclipse CLA FAQ describes the process and purpose of the CLA. At the end this document contains a link for signing the CLA. You find it under the following URL: Eclipse CLA FAQ.

After signing the CLA you are allowed to contribute code to the Eclipse platform project via Gerrit.

Note

The CLA signatures are cached on the Eclipse servers. It can take up to 10 minutes for your CLA signature to be refreshed, i.e., if you sign the CLA and try to push immediately you may receive an error message, that you did not sign the CLA.

Tip

The user name registration and CLA signing is not required for cloning the Eclipse repositories and for modifying the code in your local Git repository. They are only required for contributing a Gerrit change.

10. Eclipse Gerrit configuration

10.1. Configure your Eclipse Gerrit user

You have two options to authenticate with the Eclipse Gerrit server. You can either use SSH or HTTPS.

To configure these access methods open the following URL: Gerrit at Eclipse.

Login with your Eclipse account (registered email address) and password.

Afterwards select Settings as highlighted in the following screenshot.

Gerrit settings for Eclipse

Select Profile and note down your user. This user is later required for the push configuration.

Gerrit settings for Eclipse, user

Warning

The Gerrit user is NOT the same as your Eclipse user. Also, the Gerrit HTTPS password is NOT the same as your Eclipse user password.

You can either use SSH or HTTPS to push to Gerrit. See Section 10.2, “Authentication via HTTPS” for the configuration of HTTPS and Section 10.3, “Authentication via SSH” for the configuration of the SSH access.

Tip

If you are not familiar with SSH, the HTTPS authentication is typical easier to configure to get started. If you use HTTPS you will have to enter you password for operations with Gerrit, this can be avoided with SSH. If your company is using a proxy it may be difficult or impossible to use ssh.

10.2. Authentication via HTTPS

The Gerrit review system enables you to generate an HTTP password. Select the HTTP password in the Gerrit user settings and generate a password. This setting is depicted in the following screenshot (the password is obfuscated).

Eclipse Gerrit HTTPS access

Note down this password; as you need it to push your changes to the Eclipse Gerrit system. You can visit this page later if you forgot the password.

Warning

If you are not planning to use HTTPs authentication it is recommended to clear the password or never to generate it so that this login method is effectively disabled.

10.3. Authentication via SSH

Tip

This is an alternative to Section 10.2, “Authentication via HTTPS”. If you want to use HTTPS with a password, please skip this and the next section.

You need to upload your SSH key to the Gerrit installation so that you can push changes to Gerrit via SSH. If you are not familiar with SSH please see Section 10.4, “Authentication via SSH”.

Once you have created a SSH key pair, upload your public SSH key to Gerrit to be able to push to it.

Upload SSH key

10.4. Authentication via SSH

10.4.1. The concept of SSH

Most Git (and Gerrit) servers support SSH based authentication. This requires a SSH key pair for automatic authentication.

An SSH key par consists of a public and private key. The public key is uploaded to the application you want to authenticate with. The application has no access to the private key. If you interact with the hosting provider via the ssh protocol, the public key is used to identify a user who encrypted the data during communication with the corresponding private key.

10.4.2. SSH key pair generation

To create an SSH key under Linux (or Windows / Mac with OpenSSH installed) switch to the command line and execute the following commands. The generated SSH key is by default located in the .ssh directory of the user home directory. Ensure that you backup existing keys in this directory before running the following commands.

# Switch to your .ssh directory
cd ~/.ssh

# If the directory
# does not exist, create it via:
# mkdir .ssh 

# Manually backup all existing content of this dir!!!

# Afterwards generate the ssh key
ssh-keygen -t rsa -C "your_email@youremail.com"

# Press enter to select the default directory
# You will be prompted for an optional passphrase 
# A passphrase protects your private key 
# but you  have to enter it manually during ssh operations 

The Eclipse IDE allows you to create an SSH key pair via WindowPreferencesGeneralNetwork ConnectionSSH2.

Generating a SSH key via the Eclipse IDE

It is good practice to use a passphrase to protect your private key. It is also good practice to use operating system level permission settings to ensure that only the owning user can access the ~/.ssh folder and its content.

Note

In the above ssh-keygen command the -C parameter is a comment. Using your email is good practice so that someone looking at your public key can contact you in case they have questions. Including the email enables system administrators to contact the person in case of questions.

The result will be two files, id_rsa which is your private key and id_rsa.pub which is your public key.

You find more details for the generation of an SSH key on the following webpages: GitHub Help: description of SSH key creation or OpenSSH manual.

Tip

You can specify alternative key names with the -f parameter on the command line. This is helpful if you have multiple different repositories and you want to have a different key for each one. For example, you can name your SSH keys in domain name format, e.g., eclipse.org and eclipse.org.pub as well as github.com and github.com.pub.

You need additional configuration in the .ssh/config file, because only the id_rsa will be picked up by default. The following code shows an example.

Host *.eclipse.org
  IdentityFile ~/.ssh/eclipse.org

Host *.github.com
  IdentityFile ~/.ssh/github.com 

10.5. Eclipse support for SSH based authentication

The Eclipse IDE allows you to create an SSH key pair for SSH based communication via WindowPreferencesGeneralNetwork ConnectionSSH2.

Generating a SSH key via the Eclipse IDE

11. Clone a selected Eclipse Git repository

To find the correct URL to clone a repository from Gerrit, go to the Gerrit Eclipse homepage and select the ProjectsList menu entry. Afterwards search for the project. In the depicted screenshot, the search is done for the Eclipse platform.ui repository.

Get URL to clone a Gerrit project

Once you found a project you can click on it and select SSH or the HTTP tab to see how you can clone that. The selection for SSH is depicted in the following screenshot.

Get URL to clone a Gerrit project

The selection for HTTPS is depicted in the following screenshot.

Get URL to clone a Gerrit project

Note that the URL automatically includes your user name. This makes it easier to push later a commit to the Eclipse Gerrit review system.

Tip

In case you cloned a Git repository without using the Gerrit URL as described in this section you have to adjust the push URL. See Section 20, “Cloning from the Git server and adjusting the push URL” for a description how to do that.

You can also clone anonymously, if you just want to play with the source code locally and do not intend to contribute changes.

12. Gerrit push configuration

12.1. Gerrit push URL

The Gerrit server requires that you push using a predefined refspec, called HEAD:refs/for/master. A refspec allows you to configure which remote branch should be used for remote operations.

The Eclipse tooling allows you to set this up more or less automatically.

12.2. Exercise: Configure Gerrit push refspec

Select your remote repository in the Git Repositories view, right-click on it and select Gerrit configuration.

Gerrit Eclipse configuration

If you select the origin entry, right mouse click on it and select Gerrit Configuration... the entry should look like the following screenshot.

Gerrit Eclipse configuration

Note

For HTTPS access the URL is different.

12.3. Validate: Gerrit push configuration

You can validate the Push Specification if you select the highlighted node in the following screenshot and check the Remote Push Specification entry in the Properties view.

Gerrit Eclipse configuration

Also the icon for the repository changes to a green one and Gerrit specific commands are added to the repository's context menu, e.g., Push to Gerrit... and Fetch from Gerrit...). In addition, the repository is configured to always add a Change-ID to the commit message.

In the following screenshot the repositories configured for Gerrit are highlighted. The eclipse.jdt repository in this screenshot is not configured for Gerrit.

Gerrit Eclipse configuration

13. Make a change and push a review

13.1. Make a code change

Make a code change (fix) which you want to upload to Gerrit.

Tip

Find a very simple change for your first contribution. For example fix a typo or a compiler warning.

13.2. Push to the Gerrit review system

Assuming you did a code change and performed the Gerrit configuration, you can now push to the Gerrit review system.

The easiest way is to use the Git Staging view. In this view you see all the changes you did and you can drag and drop files to the Staged Changes part.

You need to sign off every commit. The Git functionality in Eclipse simplifies that via the sign-off push button. The Add Change-Id push button allows you to include a Change-Id entry to the commit message. Both buttons are highlighted in the following screenshot.

Eclipse Signed-off-by

Note

The Change-ID entry is initially set to "Change-Id: I0000000000000000000000000000000000000000". During the commit, this is replaced with an ID generated by the Git tooling. Like other Git IDs it is a SHA1 over the content it captures and the letter 'I' is added a prefix to make it obvious that it is a Gerrit Change-Id and not a Git commit ID.

Warning

To get picked up by Gerrit, the Change-Id must be in the last paragraph together with the other footers. To avoid problems do not separate it from the Signed-off-by message with a new-line character.

13.3. Updating the Gerrit review

If you want to react to review comments and improve the initial commit you pushed for review use commit amend to create an improved commit and push it again to Gerrit.

Since the amended commit contains the same Change-Id as the initial commit, Gerrit knows that you want to update this change with the new commit. Also in your local Git repository commit amend replaces the previous commit in your local history (and keep the same parent commit).

14. Eclipse platform Git repositories

14.1. Platform UI

The most important Eclipse platform repositories are listed below.

# the links below are web links intended to be opened by a browser
# the pages contain URL for cloning the repositories 
# at the bottom of the page

# NOTE better get the Git URL via http://git.eclipse.org/r because
# that URL contains also your user. That allows you to contribute back easier

# Eclipse platform UI repository
# contains JFace, Eclipse user interface, example projects
# and related tests
http://git.eclipse.org/c/platform/eclipse.platform.ui.git/

# Eclipse platform runtime 
# contains the Equinox runtime, the dependency injection engine,
# the non user interface related services and related tests
http://git.eclipse.org/c/platform/eclipse.platform.runtime.git/ 

14.2. Java development tools (JDT)

The most important JDT repositories are listed below.

# the links below are web links intended to be opened by a browser
# the pages contain URL for cloning the repositories 
# at the bottom of the page

# NOTE better get the Git URL via http://git.eclipse.org/r because
# that URL contains also your user. That allows you to contribute back easier

# JDT user interface
http://git.eclipse.org/c/jdt/eclipse.jdt.ui.git/

# JDT core
# hosts the Eclipse java compiler
http://git.eclipse.org/c/jdt/eclipse.jdt.core.git/

# JDT debug
http://git.eclipse.org/c/jdt/eclipse.jdt.debug.git/ 

15. Eclipse and tests

15.1. Eclipse projects and their test suite

Most Eclipse projects provide a test suite which can be used to validate that everything still works as planned.

For example, in case you are changing the Eclipse platform code you should ensure that the platform tests still perform as planned. If changes in the tests are required, you should adjust the tests with the same Gerrit change.

15.2. Version of JUnit

At the time of this writing, lots of unit tests of the Eclipse projects are still based on JUnit 3.x. JUnit 3.x uses the test prefix of method names to identify test methods.

It is planned to migrate the Eclipse platform tests to JUnit 4 in the future, see the Convert Eclipse platform.ui test suite to JUnit 4 bug report for the discussion.

15.3. Tips: running the unit tests on a virtual server

On Unix based system you can also run the user interface tests with a virtual display. This makes the execution of the tests faster and allows to developer to continue to work on the same machine.

Tip

This step is optional. You can of course run the tests without a virtual server.

The Eclipse platform unit tests starts an Eclipse IDE and visually interacts with it. This screen flickering can be annoying. You can use a virtual server and execute the tests on this virtual device.

On Ubuntu you can install the virtual server and the client via the following commands. The client is not required to run the unit tests but useful in case you want to view the test execution on the virtual server.

# install the server 
sudo apt-get install vnc4server

# optionally install the client
sudo apt-get install xtightvncviewer 

You start the server with the following parameters.

# start the server on display #1
vncserver :1 -name testing -depth 24 -geometry 1280x1024 

In the Eclipse launch configuration you can define the display which is used for the test execution.

Setting the Display variable in Eclipse

If you are running a Maven / Tycho build from the command line, you can export the display variable.

export DISPLAY=:1 

If you want to watch the unit tests, you can also connect to the virtual server via the vncclient.

# connect to the server, IP will be asked
vncviewer 

16. Running the Eclipse platform unit tests

16.1. Repositories for platform tests

Clone the following Git repositories as these contain the existing unit tests. The clone URLs (these are not URLs for the browser!) are listed below.

  • git://git.eclipse.org/gitroot/platform/eclipse.platform.releng.git

  • git://git.eclipse.org/gitroot/platform/eclipse.platform.ui.git

  • git://git.eclipse.org/gitroot/platform/eclipse.platform.runtime.git

Tip

In case you want to contribute Gerrit patches to these projects, you should clone them via the Gerrit system as described in Section 11, “Clone a selected Eclipse Git repository”. But you can always adjust the push URL later, as described in Section 20, “Cloning from the Git server and adjusting the push URL”.

16.2. Example: JFace tests

In this section the procedure to run the unit tests of the JFace components is described as an example for running tests from an Eclipse project.

The unit tests for the JFace Bundle are placed in the org.eclipse.ui.tests plug-in. This plug-in includes also several other tests for the Eclipse platform.ui component.

To run theses tests, import the following required plug-ins:

  • org.eclipse.core.tests.harness from the eclipse.platform.runtime repository
  • org.eclipse.core.tests.runtime from the eclipse.platform.runtime repository
  • org.eclipse.test.performance from the eclipse.platform.releng repository
  • org.eclipse.ui.tests from the eclipse.platform.ui repository
  • org.eclipse.ui.tests.harness from the eclipse.platform.ui repository

To test the full JFace TestSuite, you only need to run the JFace-All Tests.launch run configuration from the org.eclipse.ui.tests plug-in.

Screenshot of the JFace JUnit run

16.3. Performance tests

The performance tests allow you to analyze the performance of various actions, e.g. UIStartup, of the eclipse platform.

To run the tests you have to choose the perfAllTests.java file from the org.eclipse.core.tests.runtime bundle

As a result you get detail performance information like the following from the console:

Scenario 
'org.eclipse.core.tests.runtime.perf.UIStartupTest.testUIApplicationStartup' 
(average over 1 samples):
  System Time:          16.037,55d (no confidence)
  Used Java Heap:           91,25M (no confidence)
  Working Set:             446M (no confidence)
  Elapsed Process:          11,93s (no confidence)
  Kernel time:             750ms (no confidence)
  CPU Time:                 27,7s (no confidence)
  Hard Page Faults:         22 (no confidence)
  Soft Page Faults:        172,24K (no confidence)
  Text Size:                 4K (no confidence)
  Data Size:                 0 (no confidence)
  Library Size:              3,79G (no confidence) 

17. Creating a custom Eclipse IDE build

17.1. Eclipse IDE builds and the Common Build Infrastructure (CBI)

Eclipse provides a Maven based build system for automated build using the Maven Tycho plug-in. This effort is called the Common Build Infrastructure (CBI) and intents to provide tools to simplify and standardize the Eclipse build system.

This build system allows you to create your custom version of the Eclipse IDE. The results of this build are archive files for the different platforms, which include everything to run an Eclipse IDE. The resulting IDE is based on the source code of the current development status.

Note

As the build continuously changes, the results and requirement of the build might be slightly changed at the time you read this. See Section 18.1, “Reporting issues or asking questions about the build” for finding additional information.

17.2. Requirements

The build itself takes around 2 hours on a Core i5 machine with SSD, so of course time is required for this. Also, approximately 25 Gigs of free space and 4 Gigs of RAM are required on the hardware-side. Building of an Eclipse IDE is possible on Windows, OS X and Linux based distributions. This tutorial is tested with Linux.

On the software-side the following software is required:

  • Git
  • Maven Version 3.0.4
  • Oracle 1.6 JDK or higher

17.3. Setup the build

Check if your JVM runs in Server mode, by checking the version.

java -version
java version "1.7.0_09"
Java(TM) SE Runtime Environment (build 1.7.0_09-b05)
Java HotSpot(TM) 64-Bit Server VM (build 23.5-b02, mixed mode) 

You also have to assure that Maven has enough memory, to avoid a java.lang.OutOfMemoryError error.

export MAVEN_OPTS="-Xmx2048m" 

17.4. Cloning the SDK repository

You download the newest version of the source code by cloning the folllowing repository and it's submodules via Git.

git clone -b master 
   --recursive git://git.eclipse.org/gitroot/platform/eclipse.platform.releng.aggregator.git 

17.5. Run the build

You start the build with the following command.

mvn clean verify 

17.6. The results

If the build is successful, the Eclipse SDK is packaged as archive files for all supported platforms. These packages can be found in the Git repository in the following folder:

eclipse.platform.releng.tychoeclipsebuilder/sdk/target/products/* 

17.7. Cleanup before the next build

To ensure that the repository is clean and up to date we execute the following Git commands.

git submodule foreach git clean -f -d -x
git submodule foreach git reset --hard HEAD
git clean -f -d -x
git reset --hard HEAD 

Tip

The build requires that the version numbers of each single Maven artifacts and it's Eclipse plug-ins are in sync. But sometimes (this is rare these days) developers forget to update the Maven version numbers. In this case the build complains about a version mismatch. Run the following command to correct existing inconsistencies.

mvn -Dtycho.mode=maven org.eclipse.tycho:tycho-versions-plugin:update-pom 

18. Additional infos about building the Eclipse platform

18.1. Reporting issues or asking questions about the build

A good place to post questions about the CBI build is the CBI mailing list. The webinterface for this mailing list can be found under the following URL CBI mailing list.

18.2. Eclipse platform Hudson builds

The Eclipse platform has a Hudson build instance which can be found under the following URL: Eclipse platform Hudson. This build instance is currently not used for the main build, only to validate Gerrit contributions.

See Bug report for migrating the platform build to Hudson .

18.3. Release and milestone builds

To have a reproducible and stable build, it is possible to switch to a specific version instead of using the newest source code. For this the platform aggregator repository has tags for every release build.

To build for example the R4_3 release, you have to checkout this specific tag out and start the build like the following:

git checkout tags/R4_3
git submodule update
#run the build
mvn clean verify 

Warning

The CBI build still depends on external resources like p2 update sites. From time to time this resources change or will become unavailable. The R4_3_1 tag for example depends on a removed update site, so you have to add the new URL via a parameter to the build:

git checkout tags/R4_3_1
git submodule update

# run the build
# command must be issued in one line
mvn clean verify 
 -Dlicense-repo.url=http://download.eclipse.org/cbi/updates/license/ 

Tip

To check which properties can be overridden check the properties fields in the eclipse-platform-parent/pom.xml file.

18.4. Changing build ID

A normal CBI Build shows, "Build id: @build@" in the "About Eclipse SDK" window. To define a custom build id use the buildId parameter and the update-branding-plugins profile.

mvn clean verify -DbuildId=foobar -Pupdate-branding-plugins 

18.5. Build single parts of the aggregator

It is also possible to build just single parts of the aggregator repository, by passing the build-individual-bundles profile. The following example shows how to build just the rt.equinox.framework.

cd rt.equinox.framework \
mvn -Pbuild-individual-bundles clean verify 

Note

Unfortunately while there are numerous bundles for which the build succeed with this method, there are a couple bundles / features that cannot be built using this method.

18.6. Building natives (SWT binary files)

The CBI build does not build natives by default (SWT binary files). Instead, the CBI build simply copies pre-built native files from the swt.binaries repository.

For Windows/Mac/Linux it is possible to force the CBI build to build these natives by passing the -Dnative pointing to the build. For example the -Dnative=gtk.linux.x86_64 parameter in the case of Linux. List of options available at Building natives.

18.7. Fedora Eclipse CBI build

The Fedora project has removed some non Eclipse IDE related plug-ins to speed up the build process. See the Fedora build script.

19. Information about the e4 tools

19.1. e4 tools and committer

The e4 tools project provides tools for developing Eclipse 4 based applications. The following follows more or less the same guidelines as the Eclipse platform team.

19.2. Git repository for the e4 tools

The e4 tools are also available as via their Git repository.

# Eclipse e4 tooling
git clone git://git.eclipse.org/gitroot/e4/org.eclipse.e4.tools.git

# Some e4 demos, not required, not always working
git clone git://git.eclipse.org/gitroot/e4/org.eclipse.e4.ui.git 

19.3. Infos about the e4 tools

Most e4 tools project contain a README.md file which describes their usage and important classes.

19.4. Adding an editor for a custom model elements

The org.eclipse.e4.tools.emf.ui plug-in defines the org.eclipse.e4.tools.emf.ui.editors extension point, which allows registering editors for new model elements.

19.5. Building the e4 tools

You can build the e4 tools locally via Maven Tycho. If you have Maven installed on your machine, the build process is trivial.

Clone the e4 tools project with the following command.

# clone e4 tooling
git clone git://git.eclipse.org/gitroot/e4/org.eclipse.e4.tools.git 

Afterwards, you can build the e4 tools via Maven on the command line.

cd org.eclipse.e4.tools
mvn clean verify 

After the build finishes successfully, you find a p2 update site in the following folder.

org.eclipse.e4.tools.build/org.eclipse.e4.core.tools.update/target/repository/ 

Note

Eclipse also has a Hudson job configured which runs the daily builds. See https://hudson.eclipse.org/platform/job/deploy-eclipse-e4-parent/

20. Cloning from the Git server and adjusting the push URL

20.1. Why adjusting the push URL?

If you cloned an Eclipse Git repository directly from the Eclipse Git server (without using the Gerrit server) you have to adjust the push URL to create Gerrit changes. For example, you may have found the clone URL on: Eclipse Git web interface.

It is far easier to clone from the Gerrit server as this does not require you to change the push URL. See Section 11, “Clone a selected Eclipse Git repository” for the description how to clone. In case you can use the Gerrit server, this section is not relevant for you.

20.2. Cloning from the Git server and adjusting the push URL

The push configuration in the following dialog depends a bit if you want to use SSH or HTTPS. If you want to use SSH ensure to use the 29418 port and remove the "gitroot" string from the push-url.

The following screenshot demonstrates that for the Eclipse platform UI Git repository.

Gerrit push configuration

If you want to use HTTPS to push to the Gerrit server, you have to use a push URL with an "r" included (For example https://userid@git.eclipse.org/r/platform/eclipse.platform.ui.git). You need to provide in this case your Gerrit password if you want to push to an Eclipse Git repository as depicted in the following screenshot.

Gerrit push configuration

21. About this website

21.1. Donate to support free tutorials

Please consider a contribution Support free tutorials if this article helped you. It will help to maintain our content and our Open Source activities.

21.2. Questions and discussion

Writing and updating these tutorials is a lot of work. If this free community service was helpful, you can support the cause by giving a tip as well as reporting typos and factual errors.

If you find errors in this tutorial, please notify me (see the top of the page). Please note that due to the high volume of feedback I receive, I cannot answer questions to your implementation. Ensure you have read the vogella FAQ as I don't respond to questions already answered there.

21.3. License for this tutorial and its code

This tutorial is Open Content under the CC BY-NC-SA 3.0 DE license. Source code in this tutorial is distributed under the Eclipse Public License. See the vogella License page for details on the terms of reuse.

22. Links and Literature

22.1. Source Code

Source Code of Examples

Eclipse Wike - How to contribute to platform

Eclipse SDK setup

Eclipse API deprecation policy

Eclipse Platform testing