Copyright © 2009, 2010, 2011, 2012, 2013, 2014, 2015 vogella GmbH
Table of Contents
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 description focuses on the process of contributing code to an Eclipse project.
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
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 eclipse.org.
This tutorial assumes that you have already Eclipse plug-in development experience. See the Eclipse Plug-in development tutorial for details.
Eclipse projects use the Git version control system. Eclipse lists all Eclipse Git repositories under their project page: Eclipse projects page under the Developer Resources link.
To find all repositories of this project, go to Eclipse project page and search for it. 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.
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".
Click on the Learn more link and select the Developer resources tab.
You can download the latest integration build for the next Eclipse release under the following URL: Eclipse developer 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.
To contribute to an Eclipse project you need to have a valid user. 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 Eclipse.org user account .
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.
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.
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 typical easier to configure to get started. If you use HTTPS you will have to enter you password for operations with Gerrit. If your company is using a proxy it also may be easier to use 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).
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.
This is an alternative to HTTPS access as described in the previous section. If you want to use HTTPS with a password, please skip this section. 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.
For more information on SSH see Section 16, “Authentication via SSH”.
Ensure you are logged into the Gerrit server webpage. This will enable you to use SSH or the HTTPS for cloning the repository.
Go to the Gerrit Eclipse homepage and select the → menu entry. Afterwards search for the platform.ui project.
select the correct project repository. This opens a new webpage. This page contains links for cloning the Git repository. The selection for HTTPS is depicted in the following screenshot.
Now select→ → → → .
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.
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 15, “Appendix: Cloning from the Git server and adjusting the push URL” for a description how to do that.
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→ → → .
Several Eclipse projects needs to ensure that it does 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.
To use the API baseline you have to have a officially released Eclipse version installed. This defines your baseline for the API. You can define in the preference there this installation can be found. For this select the→ → → menu entry. . Here you can define the Eclipse release to use as baseline, this allows you to use a recent Eclipse developer build for developing but still get an API breakage reported.
For example if you develop for the next Eclipse 4.x+1 release (for example 4.5), you should select the official Eclipse 4.x release (for example Eclipse 4.4.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 based on the Eclipse 4.4.1 release. This assumes that the 4.4.1 is the latest official release. In the preference press the Add Baseline... button.
Enter a name for this baseline, select the folder which contains the latest official Eclipse release and press thebutton to use this installation as baseline.
Sometimes a plug-ins continues to give you error message, which you can't solve. For example if the plug-in is specific to MacOS or the Windows Operating System and you are using Linux, you will get compiler errors which you cannot solve.
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.
Find a very simple change for your first contribution. For example fix a typo or a compiler warning.
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.
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.
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).
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.
The following table lists the home pages of these projects:
Table 1. Eclipse projects
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/
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/
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.
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.
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.
If you are running a Maven / Tycho build from the command line, you can export the display variable.
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
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.
In case you want to contribute Gerrit patches to these projects, you should clone them via the Gerrit system as described in Section 6, “Exercise: Clone the Eclipse platform.ui repository”. But you can always adjust the push URL later, as described in Section 15, “Appendix: Cloning from the Git server and adjusting the push URL”.
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:
To test the full JFace TestSuite, you only need to run the
run configuration from the
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)
The Eclipse project has a simultaneous release every year at the end of June. In June 2015 the Eclipse 4.5 (Mars) 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.
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.
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.
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.
As the build continuously changes, the results and requirement of the build might be slightly changed at the time you read this. See Section 13.1, “Reporting issues or asking questions about the build” for finding additional information.
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:
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
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://git.eclipse.org/gitroot/platform/eclipse.platform.releng.aggregator.git
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:
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
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.
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.
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 -Dlicense-repo.url=http://download.eclipse.org/cbi/updates/license/
To check which properties can be overridden check the properties fields in the eclipse-platform-parent/pom.xml file.
A normal CBI Build shows, "Build id: @build@" in the "About Eclipse
SDK" window. To define a custom build id use the
parameter and the
mvn clean verify -DbuildId=foobar -Pupdate-branding-plugins
It is also possible to build just single parts of the aggregator
repository, by passing the
The following example shows how to build just the
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.
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
natives by passing the -Dnative pointing to the build.
case of Linux. List of options available at
The Fedora project has removed some non Eclipse IDE related plug-ins to speed up the build process. See the Fedora build script.
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.
The e4 tools are also available 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
Most e4 tools project contain a
file which describes their usage and important classes.
plug-in defines the
extension point, which allows registering editors for new model
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.
Eclipse also has a Hudson job configured which runs the daily builds. See https://hudson.eclipse.org/platform/job/deploy-eclipse-e4-parent/
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, “Exercise: Clone the Eclipse platform.ui 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.
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://email@example.com/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.
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
The icon for repository configured to be used for Gerrit uses a green icon. Also Gerrit
specific commands are added to
context menu, e.g.,
Push to Gerrit...
Fetch from Gerrit...). In addition, the repository
configured to always add a Change-ID
to the commit message.
the repositories configured for
repository in this screenshot is not configured for Gerrit.
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.
If you select the origin entry, right mouse click on it and select Gerrit Configuration... the entry should look like the following screenshot.
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.
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.
To create an SSH key under Linux (or Windows / Mac with OpenSSH
installed) switch to the command line and
The generated SSH
key is by default
located in the
directory of the user home directory. Ensure that you backup existing
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 "firstname.lastname@example.org" # 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→ → → → .
It is good practice to use a
passphrase to protect your
private key. It
is also good practice to
operating system level permission settings
to ensure that only
owning user can access the
folder and its content.
In the above
command the -C parameter is a comment. Using your email is good
practice so that
someone looking at your public key can contact you
case they have
questions. Including the email enables system
to contact the person in case of questions.
The result will be two files,
which is your private key and
which is your public key.
You can specify alternative key names with the
parameter on the
This is helpful if you have multiple
repositories and you
want to have a different key for each
example, you can name
your SSH keys in domain
as well as
additional configuration in the
will be picked up by
default. The following code shows an
Host *.eclipse.org IdentityFile ~/.ssh/eclipse.org Host *.github.com IdentityFile ~/.ssh/github.com