Support free tutorials

Quick links

Eclipse IDE platform development - tutorial

Contributing to the Eclipse open source project

Lars Vogel

Version 6.7


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. Code contributing
1.2. User interface guidelines
1.3. Users, Contributors and Committers
2. Prerequisites
3. Finding information about an Eclipse project
3.1. The Eclipse project page
3.2. Finding the Git repositories for an Eclipse project
3.3. Example: Finding the Git repositories for the Eclipse Platform UI project
3.4. The Eclipse dashboard
4. Installation description
4.1. Download the latest integration build
4.2. Install the Git tooling into the Eclipse IDE
5. Exericse: Eclipse user creation and Gerrit server configuration
5.1. Create an Eclipse user account
5.2. Sign the Contributor License Agreement (CLA)
5.3. Configure your Eclipse Gerrit user
5.4. Authentication via HTTPS
5.5. Authentication via SSH
6. Clone the selected Eclipse Git repository
6.1. Finding the correct Git repository
6.2. Clone the repository via the Eclipse IDE
7. Exercise: Install required plug-ins and configure your workspace
7.1. Exercise: Install additional plug-ins via install file
7.2. Configure API baseline
7.3. Closing projects
7.4. Setup for other Eclipse projects
8. Exercise: make a change and push a review
8.1. Make a code change
8.2. Push to the Gerrit review system
8.3. Updating the Gerrit review
9. Eclipse projects responsible for the Java IDE
9.1. The Eclipse project
9.2. The Eclipse platform projects home pages and Git repositories
10. Eclipse and tests
10.1. Eclipse projects and their test suite
10.2. Version of JUnit
10.3. Tips: running the unit tests on a virtual server
11. Running the Eclipse platform unit tests
11.1. Repositories for platform tests
11.2. Example: JFace tests
12. Reporting Eclipse bugs and asking questions
12.1. Asking (and answering) questions
12.2. Eclipse bug reports and feature requests
12.3. Using Eclipse Bugzilla
13. Creating a custom Eclipse IDE build
13.1. Building the Eclipse IDE
13.2. Requirements
13.3. Cloning the SDK repository
13.4. Building the Eclipse IDE
13.5. Cleanup before the next build
14. Additional infos about building the Eclipse platform
14.1. Reporting issues or asking questions about the build
14.2. Eclipse platform Hudson builds
14.3. Release and milestone builds
14.4. Changing build ID
14.5. Build single parts of the aggregator
14.6. Building natives (SWT binary files)
14.7. Fedora Eclipse CBI build
15. Updating the copyright header of a source file
15.1. Why updating the copyright header of a changed file?
15.2. Using the Eclipse releng tooling for updating the copyright header
16. Appendix: Cloning from the Git server and adjusting the push URL
16.1. Overview
16.2. Gerrit push configuration
17. Using the Eclipse installer for code contributions
18. Authentication via SSH
18.1. Authentication via SSH
18.2. Eclipse support for SSH based authentication
19. About this website
20. Links and Literature

Get the book Eclipse Contribution book

1. Contributing to the Eclipse open source project

1.1. Code 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. Most Eclipse projects use a code review process based on the Gerrit code review system. Some Eclipse projects also use Github for code contributions.

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.

While there are other ways of contributing to an Eclipse project, e.g., via updating the project documentation, this book focuses on the process of contributing code to an Eclipse project.

1.2. User interface guidelines

Eclipse has a description for its user interface guidelines. These can be found under the following url: Wiki about UI guidelines.

It is not expected that you read this guide completely, but in case you want to check what the Eclipse way of doing things is, you can have a look at this (old but still valid) description.

1.3. 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. Users also report bugs and issue feature requests in Eclipse projects they are using.

  • Contributors are individuals who contribute code, fixes, tests, documentation, or other work that is part of the project.

  • Committers have write access to the project's resources (source code repository, bug tracking system, website, build server, downloads, etc.) and are expected to influence the project's development.

Everyone has read access to the code repositories hosted at

2. Prerequisites

This tutorial assumes that you have already Eclipse plug-in development experience. See the Eclipse Plug-in development tutorial for details.

3. Finding information about an Eclipse project

3.1. The Eclipse project page

Additional information about a project can be found under its Eclipse project page. This includes information about future developments plans, documentation, wiki pages, developer mailing lists and the project charter.

The following screenshot depicts the website for the JDT UI project. This project page can be found under JDT UI project page.

Eclipse top-level project homepage

3.2. Finding the Git repositories for an Eclipse project

Eclipse lists all project repositories under their project page. This page can be found via the main Eclipse projects page.

Use this page to search for an Eclipse project. If you click on the Learn more in one of the search results you are taken to the project homepage. Click on the Developer resources tab to see all Git repositories of the project.

3.3. Example: Finding the Git repositories for the Eclipse Platform UI project

The Eclipse platform UI project is responsible for the user interface, runtime and user assistant components of the Eclipse platform. In this example search for "Platform UI".

Eclipse Platform UI search result

Click on the Learn more link and select the Developer resources tab.

Eclipse Platform UI developer resources`

3.4. The Eclipse dashboard

At the time of this writing the Eclipse foundation is setting up a new dashboard.

For example gives an overview of Eclipse contributions. The dashboard allows you to drill down as depicted in the following screenshot.


The URL and appearance may still change. See Bug 405792 for details.

Project members dash

You can select in the top the sub-project to see. For example the reporting for the Eclipse project is depicted in the following screenshot.

Eclipse project dashboard

4. Installation description

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


For several Eclipse projects you can also use the Eclipse installer. See Section 17, “Using the Eclipse installer for code contributions” for a small description. At the time of this writing the installer does not work well for platform contributions hence is not the preferred way for contributing to it.

4.2. Install the Git tooling into the Eclipse IDE

After you downloaded a recent build for the Eclipse IDE, you need to install a few more plug-ins, most notable the Eclipse Git tooling.

5. Exericse: Eclipse user creation and Gerrit server configuration

5.1. Create an Eclipse user account

To contribute to an Eclipse project you need to have valid user credentials. If you already have an Eclipse Bugzilla or Eclipse Forum account, you have already done this step. These systems use the same account. You can create a new user via the following: Create user account .

5.2. Sign the Contributor License Agreement (CLA)

You also need to confirm to the Eclipse foundation that you have the right to contribute your code to the Eclipse open source project. This requires that you sign a contributor license agreement (CLA) via a web interface. Signing is really simple and only takes a few minutes.

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.


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.

5.3. Configure your Eclipse Gerrit user

You need to configure Gerrit if you want to use SSH or HTTPS to upload your contributions. 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.

To configure your access method open the following URL: Gerrit at Eclipse and login with your Eclipse account (registered email address) and password via the top right corner of your browser.

Afterwards select Settings as highlighted in the following screenshot.

Gerrit settings for Eclipse

You can either use SSH or HTTPS to push to Gerrit. See Section 5.4, “Authentication via HTTPS” for the configuration of HTTPS and Section 5.5, “Authentication via SSH” for the configuration of the SSH access. If you are not familiar with SSH, the HTTPS authentication is most likely easier to configure for you. If your company is using a proxy, you may have to use HTTPS as some proxies block SSH.

5.4. Authentication via HTTPS

The web page of 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

Take note or copy the password, as it will be needed to push your changes to the Eclipse Gerrit system. In contrast to SSH, when using HTTPS you will have to enter your password for each operation with Gerrit. You can visit this page later if you forgot the password.

5.5. Authentication via SSH

You need to upload your SSH key to the Gerrit installation so that you can push changes to Gerrit 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

See Section 18, “Authentication via SSH” more information on SSH Section 18.2, “Eclipse support for SSH based authentication” for instructions how to create your SSH key via the Eclipse IDE.

6. Clone the selected Eclipse Git repository

6.1. Finding the correct Git repository

Ensure you are logged into the Gerrit server webpage. This will enable you to use SSH or HTTPS for cloning the repository.

Go to the Gerrit Eclipse homepage and select the ProjectsList menu entry. This opens the Project search page. Afterwards search for the project you want to contribute to. In our example we want to contribute to the platform.ui project.

Get URL to clone a Gerrit project

Select the correct project. This opens a new webpage. This page contains links for cloning the Git repository. The selection for HTTPS is depicted in the following screenshot. Please note that the URL for you is different, as it contains your user name.

Get URL to clone a Gerrit project

6.2. Clone the repository via the Eclipse IDE

To clone, select FileImport...GitProjects from GitClone URI.

Get URL to clone a Gerrit project

Get URL to clone a Gerrit project

Enter the URL from the Gerrit webpage in the first line of the wizard. The Eclipse Git tooling removes "git clone" from the clone URI automatically.

Note that the URL automatically includes your user name. This makes it easier to push a change to the Eclipse Gerrit review system. If you clone the repository using the Eclipse Git functionality, your local repository is already configured to push changes to Gerrit, no additional setup step is required. You can also clone anonymously via Anonymous HTTP, if you just want to play with the source code locally and do not intend to contribute changes. The following screenshot shows this selection, please the depicted user name with yours.

Get URL to clone a Gerrit project

On the next wizard page you can choose to clone all branches or only the master branch. Finish this wizard by selecting the Next button until you the option Finish option becomes available. You end up with the projects from the repository imported into your workspace.


In case you cloned a Git repository without using the Gerrit URL or not via Eclipse Git you have to adjust the push URL. See Section 16, “Appendix: Cloning from the Git server and adjusting the push URL” for a description how to do that.

7. Exercise: Install required plug-ins and configure your workspace

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

The Eclipse Platform UI team provides a file describing all the plugins typically needed for platform development. You can download from the following link this file, stored under version control:

To install all the development plug-ins import the p2f file via the FileImport...InstallInstall Software Items from File menu path.

7.2. Configure API baseline

Eclipse projects frequently needs to ensure that they do not break API, compared to the previous release. For this the API tooling is used, and a missing API baseline is reported as error.


Handling baseline issues and API is something which the core committers can help with. New contributors can set this error message to warning to have an easy start. This setting is highlighted in the following screenshot.

Setting the API baseline to ignore

To define and use an API baseline, you need to download and install an official released version of Eclipse. This installation defines your baseline for the API, and you can specify its location in the Eclipse preferences. For this select the WindowPreferencesPlug-in DevelopmentAPI Baselines menu entry. Here you can define the Eclipse release to use as baseline. With this system, Eclipse can report API breakage by comparing the code in your workspace with the last released code.

For example if you develop for the next Eclipse 4.x+1 release (for example 4.6), you should select the official Eclipse release (for example Eclipse 4.5.1) as API baseline. This way the Eclipse API baseline tooling can check if you break existing API and can add error or warning markers to your code. The tooling can also propose quickfixes for such violations.

The following screenshots demonstrates how to configure a API baseline. This assumes that the 4.5 is the latest official release. In the preference press the Add Baseline... button.

Setting up the API baseline

Enter a name for this baseline, select the folder which contains the latest official Eclipse release and press the Reset button to use this installation as baseline.

Setting up the API baseline

For detailed information about the usage of the API baseline, see Eclipse Version Numbering Wiki and API Tools.

7.3. Closing projects

Sometimes a plug-in give you error messages, which you can't solve. For example, if the plug-in is specific to the Windows operating system API and you are using Linux, you get compiler errors for it.

In this case, right-click on the project and select Close Project from the context menu. This will make the Eclipse IDE ignore this plug-in in your workspace.

7.4. Setup for other Eclipse projects

If you planning to contribute to another Eclipse project, please have a look at their contribution guide. This guide is typically available via the project website, which can be found via the search functionality of the Eclipse project side.

8. Exercise: make a change and push a review

8.1. Make a code change

Find a very simple change for your first contribution. For example fix a typo or a compiler warning. Eclipse projects frequently tag bugs with the keyword bugday or helpwanted, these are candidates for initial contributions.

8.2. Push to the Gerrit review system

Use the Git Staging view to commit your change and to push it to the Gerrit review server.

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


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.


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.

8.3. Updating the Gerrit review

You may get review comments asking to improve the Gerrit change. Or you find a better way of doing the change. You can update an existing Gerrit review by using the same Change-Id for another commit. The easiest way of doing this is to amend the last commit and push this commit 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).

9. Eclipse projects responsible for the Java IDE

9.1. The Eclipse project

The Eclipse IDE is an open source (OS) project. 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 were 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.

9.2. The Eclipse platform projects home pages and Git repositories

The following table lists the home pages of these projects along with the developer pages, which list the Git (and Gerrit) repositories.

Table 1. Eclipse projects

Project Home page Developer pages with Git repositories
Platform Eclipse platform project Not relevant, as platform is only the top project
Platform UI Eclipse platform UI project Platform UI developer page
Java development tools (JDT) JDT project JDT UI developer page and JDT core developer page
Plug-in Development Environment (PDE) PDE project PDE developer page
e4 e4 project e4 developer page

10. Eclipse and tests

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

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

Several projects are currently migrating their test to JUnit 4, so this will hopefully change in the future.

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


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

11. Running the Eclipse platform unit tests

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

  • git://

In case you want to contribute Gerrit patches to these projects, you should clone them via the Gerrit system as described in Section 6.1, “Finding the correct Git repository”. But you can always adjust the push URL later, as described in Section 16, “Appendix: Cloning from the Git server and adjusting the push URL”.

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

12. Reporting Eclipse bugs and asking questions

12.1. Asking (and answering) questions

Due to the complexity and extensibility of Eclipse, you will need additional resources to help you solve your specific problems. Fortunately, the web contains several resources which can help you with your Eclipse problems.

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

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. The advantage of the Eclipse forums is that, depending on the topic, developers of Eclipse projects (Eclipse committers) are also active there and might directly answer your question.

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. Stack Overflow allows to tag questions with the relevant keyword, e.g., Eclipse and people search for them or subscribe to these theses.


Ensure that you search the forums and mailing lists for solutions for your problem since often somebody else has asked the same question earlier and the answer is already available.

12.2. Eclipse bug reports and feature requests

12.2.1. Reporting bugs and feature requests

If you encounter a problem with the Eclipse IDE or think about a potential improvement for it, you should report this to the Eclipse project. The Eclipse bug and feature tracker is using the open source Bugzilla project from Mozilla. In this system, you enter Eclipse error reports. You can also request new features or improvements of existing features.


Most Eclipse projects receive lots of bug and feature requests. So if you want something fixed or enhanced you may have to provide a Gerrit review for it. If the Eclipse developer sees that you try to fix the problem yourself, you typically receive more support from them.

12.2.2. Using the Eclipse bugzilla system

This bug tracker can be found under Eclipse Bugzilla. Here you can search for existing bugs and review them.

To participate actively in the Eclipse bug tracker, you need to create a new account. This can be done by clicking the Create a New Account link.

Opening an account at Eclipse bugzilla

Once you have a user account, you can login to the Eclipse bug tracker. This allows you to comment on existing bugs and report new ones. The user data for the all Eclipse sites are the same, i.e, the forum, marketplace, bug tracker, etc. Only for the Gerrit access, different user data is used.

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

12.2.3. Eclipse bug priorities

The Eclipse Bugzilla system allows you and the Eclipse committer to enter the bug priority. But overall, it is up to each project do decide how they handle bugs so some variation from project to project will occur. The following rules can be used as guideline.

Table 2. Bug priorities

Priority Description
blocker The bug blocks development or testing of the build and no workaround is known.
critical Implies "loss of data" or frequent crashes or a severe memory leak.
major Implies a "major loss of function".
normal This is the default value for new bug reports. Implies some loss of functionality under specific circumstances, typically the correct setting unless one of the other levels fit.
minor Something is wrong, but doesn't affect function significantly or other problem where easy workaround is present.
trivial This describes a cosmetic problem like misspelled words or misaligned text, but doesn't affect function.
enhancement Represents a request for enhancement (also for "major" features that would be really nice to have).

12.3. Using Eclipse Bugzilla

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

12.3.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, UNCONFIRMED and REOPENED.

Search for bugs

In most cases Eclipse project have tons of unsolved bugs. If you are looking for existing software bugs, it is recommended to look at the latest bugs, e.g., the bugs which have been recently updated.

13. Creating a custom Eclipse IDE build

13.1. Building the Eclipse IDE

Eclipse uses a Maven based build system for automated build using the Maven Tycho plug-in. Using this build system you can create your custom build of the Eclipse IDE. If you building the Eclipse IDE from the current master branch you get an IDE based on the latest developments of the Eclipse development team.

This effort is part of the Common Build Infrastructure (CBI) project which provide tools to simplify and standardize the Eclipse build process.

The results of this build are archive files for the different platforms, which include everything to run an Eclipse IDE.

13.2. Requirements

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

Depending on your network connection and your machine power the build of the Eclipse IDE 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.3.1
  • Oracle 1.8 JDK or higher

13.3. Cloning the SDK repository

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

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

13.4. Building the Eclipse IDE

You start the build with the following command.

mvn clean verify 

If you receive java.lang.OutOfMemoryError error during the Maven build, you should increase the memory which is available for the build.

export MAVEN_OPTS="-Xmx2048m" 

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:


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

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 

14. Additional infos about building the Eclipse platform

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

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

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


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 


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

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

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


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.

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

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

15. Updating the copyright header of a source file

15.1. Why updating the copyright header of a changed file?

Most Eclipse projects insists that you update the last changed date in the copyright header if you change the file. You can do this manually but the Eclipse releng project also provides tooling for that.

15.2. Using the Eclipse releng tooling for updating the copyright header

You need to install the copyright header tool from the following update site:

Adjust the number "4.5" to the number matching your eclipse version.

Installing the copyright header tool

After the installation you can select the entry from the context menu of a project or source folder.

Using the fix copyright header tool

16. Appendix: Cloning from the Git server and adjusting the push URL

16.1. Overview

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 6.1, “Finding the correct Git repository” for the description how to clone. In case you can use the Gerrit server, this section is not relevant for you.

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

16.2. Gerrit push configuration

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.

If you clone a Git repository managed by a Gerrit server, this push url is already correctly configured in most cases. The icon for repository configured to be used for Gerrit uses a green icon. Also 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

If you have to configure the push URL manually, 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


For HTTPS access the URL is different.

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

17. Using the Eclipse installer for code contributions

You can also use the Eclipse installer (which is provided by the Eclipse Oomph project) to automated some of the steps of code contributions. Please note that the Eclipse installer is currently still under heavy development and the user interface might change significantly.


Currently the main Eclipse platform projects do not actively configure Oomph, hence the contribution setup via the Eclipse installer may not result in a correct setup.

Download for this, the Eclipse installer from Eclipse installer. Depending your operating system you have to extract it, or you can just run the executable.

Download Eclipse installer

Start it and select the Advanced Mode.

Download Eclipse installer

Select Eclipse IDE for Java Developers.

Afterwards you can select the project you want to contribute to. If this project maintains a correct Oomph configuration will clone the corresponding repository and configure your workspace. The following screenshots are from JDT UI, for which the Eclipse installer configuration is valid as the time of this writing.

JDT contributions via Ooomph 1

JDT contributions via Oomph 1

JDT contributions via Oomph 3

JDT contributions via Oomph 4

You end up with a workspace with the existing Git repositories. After this initial setup you should consult the contribution guide of the project to ensure you know their contribution guidelines.

JDT contributions via Oomph 5

18. Authentication via SSH

18.1. Authentication via SSH

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

18.1.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 ""

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


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


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., and as well as and

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 *
  IdentityFile ~/.ssh/

Host *
  IdentityFile ~/.ssh/ 

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

19. About this website

20. Links and Literature

Tutorial about Eclipse plug-in development

Eclipse Wike - How to contribute to platform

Eclipse SDK setup

Eclipse API deprecation policy

Eclipse Platform testing