This page provides instructions for building the Eclipse Platform using preferred technologies identified as part of the CBI initiative.
- 1 Prerequisites
- 2 Build environment setup
- 3 Building
- 3.1 cloning platform source tree
- 3.2 Check for Necessary pom.xml updates
- 3.3 Running the build
- 3.4 Running the build without tests
- 3.5 Build result
- 3.6 Cleaning the build repo
- 3.7 Using BREE Libs
- 3.8 Pack200 & Signing
- 3.9 Building natives
- 3.10 Building Selected Projects
- 4 running the tests
- 5 Troubleshooting
- 6 Submitting for aggregator builds
Free HDD space
- ~25GB is recommended.
Oracle Java 1.8
- Oracle 1.8 JDK needs to be on PATH as the VM that "runs the build". (OpenJDK also works and is becoming officially supported on Red Hat Enterprise Linux for Kepler. See plan).
- Verify correct version of java is used
- Set JAVA_HOME to point to your JDK
- Ensure your java is set to run in Server mode
- For some uses, lower VM levels might work, but it's recommended to use Java 8, to avoid issues in some areas, such as JavaDoc generation, or reading pack.gz files.
- Some of the inner build callouts, like the SWT fragment build, depend on having an Oracle JVM.
- Not sure is this is still required, if using Java 8 to run the build, but highly recommended (if not required) to have all JDKs, from CDC-1.0/Foundation-1.0 to Java 8, in a configured toolchains.xml file. See Bug report and Mailing List) and see the Section below titled 'Using BREE Libs'.
Java Server Mode
A parameter used by the build "-XX:-UseLoopPredicate" is not recognized by java when running in Client mode. To check which mode you are running in by default run:
$ java -version java version "1.8.0_60" Java(TM) SE Runtime Environment (build 1.8.0_60-b27) Java HotSpot(TM) 64-Bit Server VM (build 25.60-b23, mixed mode)
If the last line says "Client VM" instead of "Server VM" then you are running in client mode. In which case you will need to modify the file /jdk1.8.0/jre/lib/amd64/jvm.cfg and ensure that the line -server KNOWN is the first line in the file.
- Download from http://maven.apache.org/download.html or use your Linux distribution provided version (whether it works depends on the distribution).
- make sure mvn is available in your PATH
- You can install Git using your distro's package manager.
Using Maven on Ubuntu
The Maven included in Ubuntu sometimes has issues. See Bug report. If you face such issues, install Maven from the Maven Homepage.
Using Maven on Fedora
Maven package included in Fedora is working without a problem and is used to build the Eclipse Platform package shipped with Fedora.
- Download from http://code.google.com/p/git-osx-installer/
- Install using the downloaded DMG file
- Download Git for Windows from http://msysgit.github.com/
- Install using the downloaded exe file
- We recommend using the "Git Bash" application provided by Git for Windows as your commandline shell throughout the build
Important: Per Bug 376400 we discovered that msysgit has a max character limit somewhere around 256 which causes cloning files with a path longer than that to fail
Workaround: Put your repo in the root of a drive and give it a short name. For example: C:\z
cd c: git clone -b master --recursive \ git://git.eclipse.org/gitroot/platform/eclipse.platform.releng.aggregator.git \ z
Note: The final "z" parameter at the end of the command is important as tells git to checkout the repository and rename it to "z". This reduces the path length of the repository to be short enough to workaround Bug 376400.
Build environment setup
Note: Unless otherwise stated, these instructions apply to Linux, MacOSX, and Windows platforms
review maven settings.xml
To avoid getting hit by bug 365727 and to make sure your local environment configuration does not interfere with CBI build, make sure build user account does not have maven settings.xml
igor@desktop:~$ ls -l ~/.m2/settings.xml ls: cannot access /home/igor/.m2/settings.xml: No such file or directory
On Windows XP this is located in:
C:\Documents and Settings\your_user\.m2\settings.xml File should not exist, if it does delete it.
On Windows 7 this is located in:
C:\Users\your_user\.m2\settings.xml File should not exist, if it does delete it.
give maven JVM more ram
export MAVEN_OPTS=-Xmx2048m 
If you are using Windows:
disable checking mirrors for dependencies
Along with making more memory available to Maven, you also might want to disable checking mirrors for dependencies, especially if you start seeing build errors like the following:
Caused by: java.lang.RuntimeException: "Messages while reading artifacts from child repositories": ["Problems while reading artifacts from http://download.eclipse.org/<...>": ["Retry another mirror": ["Artifact not found: <...>/org.eclipse.emf.ecore.xmi_2.9.0.v20130528-0742.jar.pack.gz."], "Retry another mirror": ["Artifact not found: <...>/org.eclipse.emf.common_2.9.0.v20130528-0742.jar.pack.gz."]]]
To turn off mirror checking do the following (assuming you want to add it at the same time as adding more memory):
export MAVEN_OPTS="-Xmx2048m -Declipse.p2.mirrors=false"
If you are using Windows:
SET MAVEN_OPTS="-Xmx2048m -Declipse.p2.mirrors=false"
Note: Unless otherwise stated, these instructions apply to Linux, MacOSX, and Windows platforms
We're currently working on the master branch (for Luna) and are backporting patches to R4_3_maintenance (for Kepler SRs).
A script that captures the steps is available in 
cloning platform source tree
Replace master with the branch you'd like to checkout.
Clone the repository and checkout the branch:
git clone -b master --recursive \ git://git.eclipse.org/gitroot/platform/eclipse.platform.releng.aggregator.git
To update this clone and all submodules:
cd eclipse.platform.releng.aggregator git pull --recurse-submodules git submodule update
If you want to switch from another branch to this one, replace git merge origin/master with:
git checkout -b master origin/master
Check for Necessary pom.xml updates
From time to time committers will forget to update the bundle version contained in a pom.xml when a bundle version change is made in a bundle project manifest. If building from master you should likely check the latest I-Build from the eclipse project downloads page for a link called POM updates made to see if there are any outstanding patches that you should apply before allowing a successful local build.
Running the build
From the aggregator root, run:
mvn clean verify
- NOTE: If you build multiple streams on the same system, you'll want to add -Dmaven.repo.local=/some/directory/somewhere to the end of the 3 mvn commands to avoid collisions (Using a different local repo for each stream). Most casual developers won't be affected.
- On Windows use -Dmaven.repo.local=C:\path\to\somewhere
Running the build on R4_3_1 tag
- NOTE for building from R4_3_1 tag: Due to some mis-timing of removing a temporary repository (bug 418627) if you want to re-build Eclipse 4.3.1 from its tag, you will need to add following '-D' option for the current license repository. This is not required if building from master branch or current R4_3_maintenance branch.
mvn clean verify -Dlicense-repo.url=http://download.eclipse.org/cbi/updates/license/
Running the build on master (or R4_4_maintenance) using 1.7 JRE
If you use Java 8 to "run the build", you can disregard this section. If you use Java 7, there is a system variable that has to be specified, to correctly generate JavaDoc for the org.eclipse.jdt.doc.isv bundle. The reason is that there is one bundle (with API) that depends on Java 8, namely org.eclipse.jdt.annotation, version 2.x.x. To correctly generate that JavaDoc, you just provide a system variable called "eclipse.javadoc" that points to the 'javadoc' executable from a Java 8 installation. For example:
If specified, the ant tasked used to build the Java Doc will use that executable. Otherwise, it will use the Java Doc tool that is associated with the currently running Java.
Running the build without tests
From the aggregator root, run:
mvn clean verify -DskipTests=true
- NOTE "-Dmaven.test.skip=true" cannot be used in CBI, see bug 456510
Once the build finishes, the following artifacts are created.
Packaged SDK zip files are located in your eclipse.platform.releng.aggregator directory under
Packaged JUnit Plugin Tests and Automated Testing Framework
Cleaning the build repo
To completely clean a build repo (before a new build or before updating the aggregator and submodules):
git submodule foreach git clean -f -d git submodule foreach git reset --hard HEAD git clean -f -d git reset --hard HEAD
To get a pristine build repository, after a build, you will have to specify the -x option for git clean.
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 reason is that /targets is specified in the .gitignore file, so git ... ignores them. They are included in .gitignore so they are not accidentally committed and don't clutter visual displays of "changes". Normally Maven will clean those up before a build, but in case you want to be positive you do not get an "old" copy, of one of the target artifacts, use -x.
Using BREE Libs
BREE libs can be used to build using the same BREE as what is used on build.eclipse.org. You will first need to download and install the ee.zip attached to Bug 386649 (https://bugs.eclipse.org/bugs/show_bug.cgi?id=386649) and follow the instructions in the description of the bug.
Here's an example of toolchains.xml. It currently only works with Oracle JREs (see bug 389856). Someone running the platform build would need their own version of toolchains.xml in their build ids home directory's .m2 directory (~/.m2/toolchains.xml) which points to the location on their file system of the tools required (BREE libs and JDKs).
Once setup you can inform the build to use it by passing -Pbree-libs on the mvn build command.
Pack200 & Signing
Pack200 & Signing is supported when built using build.eclipse.org and is disabled by default.
- Simply Run the build with -Peclipse-sign parameter.
If you'd like to build your own version of the eclipse-jarsigner-plugin you can use the instructions below.
Eclipse Jarsigner can be built from: http://git.eclipse.org/c/cbi/org.eclipse.cbi.maven.plugins.git
git clone -n git://git.eclipse.org/gitroot/cbi/org.eclipse.cbi.maven.plugins.git cd org.eclipse.cbi.maven.plugins git checkout master mvn -f eclipse-jarsigner-plugin/pom.xml \ clean install
Optionally, you can pass -Dnative= parameter with one of the following options to compile the natives for the specified native.
- cocoa.macosx.x86 - cocoa.macosx.x86_64 - gtk.linux.x86 - gtk.linux.x86_64 - win32.win32.x86 - win32.win32.x86_64 - win32.wce_ppc.arm
mvn clean verify \ -DskipTests=true -Dnative=gtk.linux.x86_64
Building Selected ProjectsInstead of a full build, selected projects can be built by going to the desired root directory of the project(s) and specifying the
(from the eclipse.platform.releng.aggregator repository root) \ cd rt.equinox.framework \ mvn -Pbuild-individual-bundles clean verify
This would build all projects under rt.equinox.framework.
(from the eclipse.platform.releng.aggregator repository root) \ cd rt.equinox.framework/bundles/org.eclipse.osgi \ mvn -Pbuild-individual-bundles clean verify
This would build only the org.eclipse.osgi project.
running the tests
Copy the junit tests and the CBI SDK (pick the one for your platform) that was built to a testing directory. Also unzip the junit tests and enter them.
mkdir -p /var/tmp/lts/R3_platform-tests cp eclipse.platform.releng.tychoeclipsebuilder/sdk/target/products/org.eclipse.sdk.ide-linux.gtk.x86_64.tar.gz /var/tmp/lts/R3_platform-tests cp eclipse.platform.releng.tychoeclipsebuilder/eclipse-junit-tests/target/eclipse-junit-tests-bundle.zip /var/tmp/lts/R3_platform-tests cd /var/tmp/lts/R3_platform-tests unzip eclipse-junit-tests-bundle.zip cd eclipse-testing
Modify the file equinoxp2tests.properties to point to the CBI built repository. (This example uses /home/user/R3_platform-aggregator as the CBI platform root)
Note down the org.eclipse.equinox.p2.reconciler.tests.platform.archive.linux-x86_64= file name for your architecture. (In this example linux x86_64)
Rename your org.eclipse.sdk.ide-linux.gtk.x86_64.tar.gz you copied earlier to match the name you jotted down.
mv ../org.eclipse.sdk.ide-linux.gtk.x86_64.tar.gz eclipse-platform-201204121421-linux-gtk-x86_64.tar.gz
Copy your eclipse-platform to eclipse SDK
cp eclipse-platform-201204121421-linux-gtk-x86_64.tar.gz eclipse-SDK-201204121421-linux-gtk-x86_64.tar.gz
Download a copy of the latest released Eclipse Classic (Eclipse IDE for Java Developers) from http://www.eclipse.org/downloads/.
Copy the Eclipse Classic SDK to eclipse-platform
cp eclipse-SDK-3.7.2-linux-gtk-x86_64.tar.gz eclipse-platform-3.7.2-linux-gtk-x86_64.tar.gz
You should now have 4 copies of the platform, 2 from the latest released and 2 from the CBI build.
eclipse-SDK-3.7.2-linux-gtk-x86_64.tar.gz eclipse-platform-3.7.2-linux-gtk-x86_64.tar.gz eclipse-platform-201204121421-linux-gtk-x86_64.tar.gz eclipse-SDK-201204121421-linux-gtk-x86_64.tar.gz
Unzip the CBI platform
tar zxvf eclipse-platform-201204121421-linux-gtk-x86_64.tar.gz
Run the tests
./runtests -os linux -ws gtk -arch x86_64
In case you get "testing.properties: No such file or directory", rename or symlink test.properties
ln -s test.properties testing.properties
and re-run the tests.
The build fails
With the (standart) master branch, you will use the current development version of the source code. So check the aggregator build on Hudson if it might also have a problem with the build.
Bug 384482 - Apple JVM renamed rt.jar to classes.jar causing CBI Platform build issues
Apple JVM renamed rt.jar to classes.jar causing the CBI Platform build to fail when building on macosx. Running the build a 2nd time after the failure however produces a working build. It isn't ideal to have the user run the build twice though.
A workaround for this issue is to create a symbolic link for classes.jar to rt.jar.
cd /System/Library/Frameworks/JavaVM.framework/Versions/1.6.0/Home/lib sudo ln -s ../../Classes/classes.jar rt.jar
Submitting for aggregator builds
[Note: see Platform-releng/Automated Platform Build#Contributing_to_a_build for the "how to" using the automatic processing done by the Platform-releng/Automated Platform Build. But, this "manual" approach is still important to know how to do, especially as "good citizens" if the aggregator build is broken, a "fix" can often be made before the next automated build.]
In PDE build the features specify what plugins to build and the map files specify where to get the plugin projects and which version to check out.
In the CBI build the pom.xml files and the directory structure specify what plugins to build and the aggregator git repo specifies which checkout is the build input by capturing the commit for each component repo as a submodule entry.
The manual process for submitting Platform UI for a build involves updating the submodule in the aggregator:
# starting in eclipse.platform.releng.aggregator cd eclipse.platform.ui git checkout R4_2_maintenance git pull cd .. git status
The status should look something like:
# On branch R4_2_maintenance # Changed but not updated: # (use "git add <file>..." to update what will be committed) # (use "git checkout -- <file>..." to discard changes in working directory) # (commit or discard the untracked or modified content in submodules) # # modified: eclipse.platform.ui (new commits) #
To pull in the new commits, just add the repo:
git add eclipse.platform.ui git commit git push origin HEAD
These steps are be driven by a file named repositories.txt used by Platform-releng/Automated Platform Build at the beginning of an automated build.
- In some cases, even more. Such as for Luna (4.4) Eclipse builds, we have found we needed 2560m for signed builds. See bug 413691.