Support free tutorials:

vogella training Training Books

Eclipse IDE platform development - tutorial

Contributing to the Eclipse Open Source project

Lars Vogel

Version 6.5


Revision History
Revision 0.1 - 6.5 14.02.2009 - 13.03.2014 Lars
, Hendrik
created bug fixes and enhancements, platform build and JUnit test contributed by Hendrik Still

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
1.3. The Eclipse platform project
1.4. Who is involved?
2. Finding Eclipse source code
3. Official Eclipse SDK releases
3.1. Available Eclipse downloads
3.2. Required Eclipse build for extensions
3.3. Eclipse build for contributions
3.4. Exercise: Download Eclipse SDK build
4. Contributing to the Eclipse project
4.1. Reporting bugs or feature requests
4.2. Fixing code
5. Eclipse setup for Gerrit contributions
5.1. Requirement setup
5.2. Create an Eclipse user
5.3. Sign the Contributor License Agreement (CLA)
5.4. Configure your Eclipse Gerrit user
5.5. Authentication
6. Contributing to an Eclipse project
6.1. Clone the Eclipse platform Git repository
6.2. Gerrit push configuration
6.3. Cloning not from the Gerrit server
7. Pushing reviews and reviewing
7.1. Commit message
7.2. Copyright header update
7.3. Push to the Eclipse Gerrit instance
7.4. Review
8. Eclipse platform Git repositories
8.1. Platform ui
8.2. Java development tools (JDT)
9. Examples for possible contributions
9.1. Eclipse styling
9.2. Simple code fixes
10. Running the Eclipse platform unit tests
10.1. JFace tests
10.2. Repositories for platform tests
10.3. JFace tests
10.4. Running the unit test on a virtual server
10.5. Performance tests
11. Creating a custom Eclipse IDE build
11.1. Requirements
11.2. Setup the build
11.3. Cloning the SDK repository
11.4. Run the build
11.5. The results
12. Additional infos about building the Eclipse platform
12.1. Eclipse platform Hudson builds
12.2. Release builds
12.3. Milestone builds
12.4. Performance improvements
12.5. Changing build id
12.6. Build single parts of the aggregator
12.7. Fedora Eclipse CBI build
13. Eclipse e4 tool
14. Contributing to the e4 tools
14.1. Git repository for the e4 tools
14.2. Infos about the e4 tools
14.3. Adding an editor for a custom model elements
14.4. Building the e4 tools
15. Support this website
15.1. Thank you
15.2. Questions and Discussion
16. Links and Literature
16.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 developer and organizations to fix bugs which affect them and to drive the project into a desired directions.

1.2. Users, Contributors and Committers

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

  • Contributor - Submits patches, but is not actively maintaining a project.

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

1.3. The Eclipse platform project

The Eclipse IDE is an Open Source (OS) project. hosts lots of OS projects which 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.

These components are bundled together as the Eclipse 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 mature project, the platform also has the incubator project called e4 which provides new tools for Eclipse 4 development. It serves as a testing ground for new ideas.

The following table lists the home pages of these projects:

1.4. Who is involved?

Despite the general assumption that the Eclipse SDK components are development by an army of developers, the actual developer team is relatively small. General information about an Eclipse project can be found under, e.g., via the Who's Involved link you can see the project lead and the main committer. For example, the following screenshot shows the contributions to the platform project, which can be reached under the Eclipse project link

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.

As these screenshots demonstrate the majority of the Eclipse platform work is done by a few developers. Therefore, new contributors can create a huge impact on Eclipse with contributions.

2. Finding Eclipse source code

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


This book is not a Git tutorial, i.e., not all aspects of Git are covered. We only cover the necessary bits of Git to contribute back to the Eclipse project. For more information about using Git see the Git online tutorial or the Eclipse Git tutorial online tutorial.

The Git tutorial is also available as book. See Distributed Version Control with Git: Mastering the Git command line .

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 repository.

Eclipse Git repos, Tycho example

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

Eclipse Git repos, e4 tools example

3. Official Eclipse SDK releases

3.1. Available Eclipse downloads

The Eclipse project has a simultaneous release every year at the end of June. In June 2013 Eclipse 4.3 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.

3.2. Required Eclipse build for extensions

If you plan to build upon the Eclipse platform additional functionality, you should download the latest Eclipse release. Official releases stable and a good foundation for building your additional functionality on top of it.

3.3. Eclipse build for contributions

To contribute to the Eclipse Open Source project, you need to download one of the recent integration or milestone builds to compile the platform code.

You find the builds for the next Eclipse release under the following URL: .

3.4. Exercise: Download Eclipse SDK build

Download now the latest M-build or RC-build from the Eclipse download page.


It is good practice to use a recent build for Eclipse platform development. While it is possible to use an older build, you typically end up with cryptic error messages.

The following screenshot shows the download webpage of Eclipse. From the displayed selection you can download the latest M build (or RC once available) or an integration or nightly build. Typically M or RC builds should be good enough, except you want to try out bleeding edge things.

Download development builds

Unzip the download and start Eclipse from it.

4. Contributing to the Eclipse project

4.1. Reporting bugs or feature requests

If you find problems or have an idea on improvements in the Eclipse platform or the e4 tooling, you can open Bug report via the following links: New bug report for the Eclipse platform and New bug report for the e4 tooling project (Eclipse 4 wizards and application model editors)

4.2. Fixing code

Once you cloned a Eclipse platform repository, you can import the related projects and starting working on them.

To test the changes, you can start a runtime Eclipse, see Plug-in development for an introduction.

Once done with the fix, you can commit the change locally and push it to Gerrit. See ??? for the required Gerrit setup.

5. Eclipse setup for Gerrit contributions

5.1. Requirement setup

Most 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 committer.


In theory you can also provide patches via Bugzilla, but in reality these are rarely reviewed, as the process is more time consuming and less streamlined.

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

5.2. Create an Eclipse user

You need to create an user account to contribute to an Eclipse project. First step is to create a user via the following URL: Create a new account.


If you already have a Eclipse Bugzilla user or Eclipse Forum user, you have already done this. These users are the same.

5.3. Sign the Contributor License Agreement (CLA)

You also need to sign a contributor license agreement (CLA). With the CLA you confirm that you have the rights to contribute source code to Eclipse project.

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.


The username registration and CLA signing is not required for cloning the Eclipse repositories and for modifiying the code in your local Git repository. They are only required for contributing a Gerrit review request.

5.4. Configure your Eclipse Gerrit user

You need to upload your SSH key to the Gerrit installation to that you can push changes to Gerrit via SSH. For this open the following URL: Gerrit at Eclipse.

Login with your Eclipse Bugzilla account 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

5.5. Authentication

You can either use SSH or HTTPS to push to Gerrit.

Upload your public SSH key to Gerrit to be able to push to it.

Upload SSH key


Eclipse allows you to create an SSH key via WindowPreferencesGeneralNetwork ConnectionSSH2

6. Contributing to an Eclipse project

6.1. Clone the Eclipse platform Git repository

Once you have your user and CLA, you can clone the repository of your choice. In this example you clone the Eclipse platform.ui repository.

To find the URL to clone a repository with the correct URL for Gerrit, go to the Gerrit Eclipse homepage and select the ProjectsList menu entry. Afterwards search for the project.

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. This is depicted in the following screenshots.

Get URL to clone a Gerrit project


You can also clone anonymously, if you just want to play with the source code locally.

6.2. Gerrit push configuration

You need to configure the push configuration to push to Gerrit. For this select your remote, right-click on it and select Gerrit configuration .

Gerrit Eclipse configuration

6.3. Cloning not from the Gerrit server


Skip this section if you clone via Gerrit as described in Section 6.1, “Clone the Eclipse platform Git repository ”.

Alternatively to Section 6.1, “Clone the Eclipse platform Git repository ” you can also clone the Eclipse Git repositories under the following 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 you have to use a different push URL with an "r" included (For example You need to provide in this case your Gerrit password if you want to push to as depicted in the following screenshot.

Gerrit push configuration

7. Pushing reviews and reviewing

7.1. Commit message

Every Eclipse project handles the required commit message a bit different. For platform commits the following format is recommended.

Bug XXXXXXXX - bug title

Short description of what the fix contains, or the direction of the fix

Change-Id: I0000000000000000000000000000000000000000
Signed-off-by: email-from-the-CLA 

The text in the header must match the title in Bugzilla. For example the following is a valid commit message for the Eclipse platform project, (the detailed description has been skipped in this example, as the header make it clear what it is for).

Bug 434846 - Update the system default Locale if the -nl Locale is invalid

Change-Id: I6099172a5986e9678a830f84d78b2cdb8c161dc6
Signed-off-by: Dirk Fauth <> 


Check with the project's contribution guidelines to see if they have preferences on how your commit message style should be.

7.2. Copyright header update

Every source file contains a copyright header. If you modify the file you should also update the copyright header. If you modify the file, please update the last modified year add yourself to the bug with a reference to the bug. The following listing shows an example.

The file was created in 2008 and last modified in 2014. It was originally created by employees of IBM and also modified by John Doe and he fixed Bug 429728 with it.

/******************************************************************************* * Copyright (c) 2008, 2014 IBM Corporation and others. * All rights reserved. This program and the accompanying materials * are made available under the terms of the Eclipse Public License v1.0 * which accompanies this distribution, and is available at * * * Contributors: * IBM Corporation - initial API and implementation * John Doe <> - Bug 429728 *******************************************************************************/


For new files, use For new files, list "yourself and others" instead of "IBM and others" in the first line.

7.3. Push to the Eclipse Gerrit instance

After you finished the configuration you can push to the Eclipse Gerrit review system. You need to sign off every commit. EGit simplifies that via the sign-of 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


The Change-ID entry is initially set to "Change-Id: I0000000000000000000000000000000000000000". During the commit, this is replaced with ID generated by the Git tooling.


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

The update of the Gerrit review request is the same as described in the general section about the Gerrit usage in this tutorial. Especially follow the guideline to:

  • Deliver a patch as a single commit (you may want to squash your commits first), because each commit generates a separate change.

  • If you want to update a Gerrit review request, 'amend' the existing commit - this creates a new patch set in the previous change

7.4. Review

You find all open Gerrit review under the following URL: Comments from everybody, also non-committers are welcome in Gerrit for review requests.

8. Eclipse platform Git repositories

8.1. Platform ui

The most important Eclipse platform.ui repositories are listed below.

# NOTE better get the Git URL via 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

# Eclipse platform runtime 
# contains the Equinox runtime and the non user interface related services 
# and related tests

8.2. Java development tools (JDT)

The most important JDT repositories are listed below.

# NOTE better get the Git URL via because
# that URL contains also your user. That allows you to contribute back easier

# JDT user interface

# JDT core

9. Examples for possible contributions

9.1. Eclipse styling

The Eclipse styling is defined in the org.eclipse.ui.themes plug-in in the eclipse.platform.ui Git repository.

You can change these CSS files or extend them to configure everything to your need. See Eclipse CSS styling for a guide into CSS development and Importing CSS files for a description how to extend CSS files.

9.2. Simple code fixes

The platform team creates two very simple starter bugs for new contributors, see Remove unnecessary Javadoc and Fix a warning message.

10. Running the Eclipse platform unit tests

10.1. JFace tests

In case you are changing the Eclipse platform code you should ensure that the platform still performs as planned. In this case you should run the existing Eclipse platform tests to validate your changes.

10.2. Repositories for platform tests

Clone the following Git repositories as these contains the existing unit tests.

  • git://

  • git://

  • git://

10.3. JFace tests

Eclipse comes with tests for every component. In this section the unit testing of the JFace component will be described.

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 plattform.ui.

To run this tests import the following plug-ins are needed:

  • 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

It is also required to have a API Baseline configured. You do this by WindowPreferencesPlug-in DevelopmentAPI Baselines. For example you can set the baseline again your current IDE installation.

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

10.4. Running the unit test on a virtual server

The Eclipse platform unit test start 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 (which is not required just for the unit tests) via the following commands.

# 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 set the display which should be used.

Setting the Display variable in Eclipse

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

10.5. 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 from the org.eclipse.core.tests.runtime bundle

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

(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) 

11. Creating a custom Eclipse IDE build

Eclipse provides a Maven based build system for automated build and allows you to build the Eclipse IDE locally. The results of this build are archive files for the different platforms, which include every thing to run as normal Eclipse IDE. The resulting IDE is based on the source code of the current development status, so results and requirement will change from time to time.

11.1. 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, OSX and Linux based distributions. This tutorial is tested with Linux.

On the software-side the following programs are required:

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

11.2. 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 exception.

export MAVEN_OPTS="-Xmx2048m" 

11.3. Cloning the SDK repository

You download the newest version of the source code by cloning the eclipse.platform.releng.aggregator repository and it's submodules via Git.

git clone -b master --recursive git:// 

11.4. Run the build

To assure that the repository is clean and up to date we execute the following git commands.

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

The build requires that for the version numbers of the single Maven artifacts and it's Eclipse plug-ins be in sync. But sometimes developers forget to update this version numbers, so we first have to run a Maven goal to correct, eventually existing inconsistencies.

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

Now we can run the build.

# run the build
mvn clean verify 

11.5. The results

If the build is successful, the resulting packed IDE is placed in


12. Additional infos about building the Eclipse platform

12.1. 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 and

12.2. Release 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 aggregator repository has tags for example every release build. To build e.g. R4_3 you just have to check 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 

The CBI build still depends on external resource 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 to the update site via a parameter to the build:

git checkout tags/R4_3_1
git submodule update
#run the build
mvn clean verify -Dlicense-repo.url= 

12.3. Milestone builds

Currently the Eclipse platform project does not tag the milestone releases. See Bug report. So you have to match the milestone and integration tag manually. You can compare the URL on the Eclipse download page, for example S-4.4M2-201309182000 matches the I20130918-2000 tag.

12.4. Performance improvements

To speedup the build, it is possible to disable the api-generation.

mvn clean verify -P!api-generation 

12.5. 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 

12.6. 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 

12.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.

13. Eclipse e4 tool

You find a recent version of the e4 tools under the following URL:

The following URL lists the official builds for the Eclipse e4 tooling project.

14. Contributing to the e4 tools

14.1. Git repository for the e4 tools

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

# Eclipse e4 tooling
git clone git://

# Some e4 demos, not required, not always working
git clone git:// 

14.2. Infos about the e4 tools

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

14.3. Adding an editor for a custom model elements

The plug-in defines the extension point, which allows to register editors for new model elements.

14.4. 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:// 

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

mvn clean verify 

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


Eclipse also has a Hudson job configured which runs the daily builds. See

15. Support this website

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.

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.

15.1. Thank you

Please consider a contribution if this article helped you.

Flattr this

15.2. Questions and Discussion

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.

16. Links and Literature

16.1. Source Code

Source Code of Examples

Eclipse Wike - How to contribute to platform

Eclipse SDK setup

Eclipse API deprecation policy

Eclipse Platform testing