README
Last Updated: May 31, 2004
This document describes how to build Eclipse components from the command line using Ant scripts in this project and org.eclipse.releng.basebuilder.
Table
of Contents
Description
Prerequisites
Setup
Run the Build
Ant
properties defined build.properties
Eclipse Configurations
Examples
org.eclipse.releng.eclipsebuilder
contains Ant scripts that invoke script generators in org.eclipse.pde.build to
build all shipped components of Eclipse: SDK, Platform
JDT, examples, tests and Team Extras.
1. CVS version 1.10 or higher.
2. 1.4 level JDK.
3. (When building Windows SDK, Platform or examples on non Windows systems only)
a 1.4 level Windows JRE or JDK
4. Info-Zip
zip and unzip
5. (for building Eclipse components for Mac OSX) GNU tar
and gzip.
6. org.eclipse.releng.basebuilder
and org.eclipse.releng.eclipsebuilder from dev.eclipse.org.
Setup
1. Add the zip, unzip, tar,
gzip and cvs executables to your path as required.
2. Add the jre/bin directory
of the installed JDK to your path.
3. Check out org.eclipse.releng.basebuilder
and org.eclipse.releng.eclipsebuilder into a directory.
Run
the Build
cd to org.eclipse.releng.eclipsebuilder directory and execute the following command (currently the build.xml script can only be executed in a headless eclipse due to bug 35923):
"java -cp ../org.eclipse.releng.basebuilder/startup.jar
org.eclipse.core.launcher.Main -application org.eclipse.ant.core.antRunner -buildfile
build.xml -Dcomponent=sdk | platform | jdt | sdk.examples
| sdk.tests [Ant properties to override in a component's
build.properties] "
The component
property value sets the name of the directory in org.eclipse.releng.eclipsebuilder
which contains the Ant scripts that build a given an Eclipse component as descibed
below:
| Component (directory name in org.eclipse.releng.eclipsebuilder) | Description |
| sdk | This directory contains the scripts used to build any or all configurations of the Eclipse SDK. An Eclipse SDK is comprised of binaries, source, user and developer documentation for the Eclipse Platform, Java Development Tooling and Plug-in Development components. |
| platform | This directory contains the scripts used to build any or all configurations of the Eclipse Platform runtime. The Eclipse Platform component contains binaries and user documentation only. |
| sdk.rcp | This directory contains the scripts used to build the RCP SDK. The RCP SDK is comprised of the base RCP plug-ins and the org.eclipse.platform.source plug-in. This build can only be executed in a buildDirectory where the Eclipse SDK was previously built. |
| rcp | This directory contains the scripts used to build any or all configuration of the Eclipse RCP plug-ins. |
| jdt | This directory contains the scripts used to build the platform-independant and/or the Mac OSX configuration of the Eclipse Java Development Tooling runtime. The Eclipse JDT component contains binaries and user documentation only. |
| sdk.examples | This directory contains the scripts used to build the platform-independant and/or the Windows configuration of the Eclipse Examples. The Eclipse Examples contain binaries and source. |
| sdk.tests | This directory contains the scripts used to build the Eclipse Automated testing environment. This test framework can be used to run JUnit plugin tests on an Eclipse SDK from the command line. |
Ant
Properties Settings in a component's build.properties
The following
properties are pre-defined in the build.properties file for the specified component.
They can be overridden by setting them at the command line at build time or by
changing them directly in the component's build.properties file.
| Name | Description |
| baseos,basews,basearch | The os, ws and arch values of a pre-built eclipse component being compiled against. See list of possible values in the table of build configurations. |
| baseLocation | A directory separate from buildDirectory which contains pre-built plugins and features against which to compile. The basedirectory must not contain any features, plugins or fragments which are already or will be located in the buildDirectory (see below). |
| bootclasspath | Sets the value for the attribute "bootclasspath" in calls to the Ant <javac> task in a plugins' build.xml. Default set to ${java.home}/lib/rt.jar. |
| buildDirectory | The absolute path to a working directory where the source for the build will be exported, where scripts will be generated and where the end products of the build will be located. On Windows systems, the path length should not exceed thirty characters due to path length limitations when compiling some classes in eclipse. |
| buildId | The build name. Default set to "build". |
| buildLabel | Refers to the name of the directory which will contain the end result of the build. Default set to ${buildType}.${buildId}, ie."I.build". This directory will be created inside the location specified by the ${buildDirectory} property. |
| buildType |
Letters I, N, S, R or M are used in Eclipse builds to identify builds
as being one of the following: If set to N, all source will be checked out from the HEAD stream. In all other cases, tags as specifed in map files will be used when exporting plugins to the buildDirectory. |
| archivePrefix | The name of the top level directory which should exist in the produced zip file. Typically set to "eclipse". |
| collectingFolder | The name of the top level directory where the built features and plugins will be gathered. This is typically set to "eclipse". |
| configs |
An ampersand separated list of configurations to build where a configuration
is specified as <os>,<ws>,<arch>. |
| javacDebugInfo | Sets the value for the attribute "debug" in calls to the Ant <javac> task in a plugins' build.xml. Default set to on. |
| javacFailOnError | Sets the value for the attribute "failonerror" in calls to the Ant <javac> task in a plugins' build.xml. Build will continue even if there are compilation errors when this is set to false. |
| javacSource | Sets the value for the attribute "source" in calls to the Ant <javac> task in a plugins' build.xml. Default set to 1.3. |
| javacTarget | Sets the value for the attribute "target" in calls to the Ant <javac> task in a plugins' build.xml. Default set to 1.1. |
| javacVerbose | Sets the value for the attribute "verbose" in calls to the Ant <javac> task in a plugins' build.xml. Default set to true. |
| mapVersionTag |
Sets the tag attribute in a call to the Ant <cvs> task to check out org.eclipse.releng, the map file project on dev.eclipse.org used in the build. Can be set to a specific tag to download the map files used for a previous
integration build. Typically, these tags are in the form "v<date/timestamp>"
for example "v200307110800" will checkout the map files used
to run the integration at the specified date/time. These scripts work
with 3.0 stream builds > 20030701. |
| timestamp | A timestamp used to fill in value for buildid in about.mappings files. The timestamp is also used to tag the org.eclipse.releng project on dev.eclipse.org only when an appropriate value for mapCvsRoot is provided and when the tagMaps Ant property is set. |
| zipargs | Arguments to send to the zip executable. ie. zipargs=-y on Linux preserves symbolic links. |
A configuration refers to the combination
of the operating system, windowing system and processor architecture for which
the component is intended. This table lists available configurations:
| Build Configuration (os, ws, arch) | Operating System (os) | Window System (ws) | Processor Architecture (arch) |
| linux, motif, x86 | Red Hat Enterprise Linux WS 3 | Motif | Intel x86 |
| linux, gtk, amd64 | Red Hat Enterprise Linux WS 3 | GTK | AMD 64 |
| linux, gtk, x86 | Red Hat Enterprise Linux WS 3 | GTK | Intel x86 |
| aix, motif, ppc | IBM AIX 5L Version 5.2 | Motif | PowerPC |
| solaris, motif, sparc | Sun Solaris 8 | Motif | SPARC |
| hpux, motif, PA_RISC | HP HP-UX 11i | Motif | hp9000 PA-RISC |
| macosx, carbon, ppc | Apple Mac OS X 10.3 | Carbon | PowerPC |
| win32,win32, x86 | Microsoft Windows XP | Win32 | Intel x86 |
The component's build.properties lists the configurations
that apply to the component. If no configurations are specified, all configurations
listed in the build.properties for the component will be built.
For
example, the build.properties for the Platform component contains the following:
configs= \
win32, win32, x86 &\
linux, gtk, amd64& \
linux, gtk, x86 & \
linux, motif, x86 & \
solaris, motif, sparc & \
aix, motif, ppc & \
hpux, motif, PA_RISC & \
qnx, photon, x86 & \
macosx, carbon, ppc
So by default, all nine configurations of the Eclipse Platform will be built
if the "configs" property is not overwritten at the command line.
Although it is possible to build for all configurations on one machine, building
Unix flavours of Eclipse on Windows will result in missing execute permissions
and missing symbolic links. In these cases you would have to write an install
or post install script to set permissions properly. (UNIX builds built on UNIX
systems will set sufficient permissions and make the appropriate links).
Build
Windows SDK Windows
Build Linux GTK and Motif SDK on Linux
Build Windows SDK component on Linux
Build
Linux Motif platform component on Linux
Build JDT
component against a pre-built Windows Platform component on Windows
Build
JDT component in a directory containing a previous Windows Platform buildDirectory
Building Eclipse FTP-WebDAV against an installed Eclipse SDK
on Linux
Building Eclipse JUnit Plugin tests against an
installed Eclipse SDK on Windows
Build
Windows SDK component on Windows
java -cp ..\org.eclipse.releng.basebuilder\startup.jar
org.eclipse.core.launcher.Main -application org.eclipse.ant.core.antRunner -buildfile
build.xml -Dcomponent=sdk -Dconfigs="win32,win32,x86" -Djavacfailonerror=true
-DjavacVerbose=false -DbuildDirectory=c:\mybuild
This builds an eclipse
SDK for the windows configuration only in the directory c:\mybuild. "-DjavaVerbose=false"
indicates that no compile logs will be generated and "-Djavacfailonerror=true"
will cause the build to fail if there are any compile errors.
Build Linux GTK and Motif SDK components on Linux
java -cp ../org.eclipse.releng.basebuilder/startup.jar org.eclipse.core.launcher.Main
-application org.eclipse.ant.core.antRunner -buildfile build.xml -Dcomponent=sdk
-Dconfigs="linux,gtk,x86 & linux,motif,x86" -Dzipargs=-y
This builds an eclipse SDK for the linux gtk and linux motif configurations.
By default the buildDirectory will be set "src" in eclipse.releng.eclipsebuilder.
"-Dzipargs=-y" is used here to preserve the symbolic links libXm.so
and libXm.so.2 in the Linux Motif root directory of eclipse. The symbolic links
will only be created at build time if the build is run on a Linux operating system.
Build Windows SDK component on Linux
java
-cp ../org.eclipse.releng.basebuilder/startup.jar org.eclipse.core.launcher.Main
-application org.eclipse.ant.core.antRunner -buildfile build.xml -Dcomponent=sdk
-Dconfigs="win32,win32,x86" -Dbootclasspath=/builds/windows/jre/lib/rt.jar
This is a command that can be used to build an eclipse SDK for the windows
configuration on a *nix system. A bootclasspath pointing to a Windows rt.jar is
explicitly specified so that bootstrap classes not available in the *nux virtual
machine are available to compile windows specific classes in Eclipse. By default
the buildDirectory will be set "src" in eclipse.releng.eclipsebuilder.
Build Linux Motif platform component on Linux
java -cp ../org.eclipse.releng.basebuilder/startup.jar org.eclipse.core.launcher.Main -application org.eclipse.ant.core.antRunner -buildfile build.xml -Dcomponent=platform -Dconfigs="linux,motif,x86" -DbuildDirectory=/builds/platform
This
builds an eclipse platform runtime for the linux motif configuration. The buildDirectory
will be set "/builds/platform".
Build JDT component against a pre-built Windows Platform component on Windows
java -cp ..\org.eclipse.releng.basebuilder\startup.jar org.eclipse.core.launcher.Main -application org.eclipse.ant.core.antRunner -buildfile build.xml -Dcomponent=jdt -Dconfigs="*,*,*" -DbuildDirectory=c:\builds\jdt -DbaseLocation=c:\builds\platform -Dbaseos=win32 -Dbasews=win32 -Dbasearch=x86 -Djavacfailonerror=true
This
builds an Eclipse JDT component against a pre-built eclipse platform plugins.
The build will fail if there are compile errors. The value specified for baseLocation
must not contain any JDT features or plugins or the build will fail. "baseos",
"basews" and "basearch" should be specified in order to find
the correct location of platform specific jars (i.e. swt.jar) on the classpath.
Build JDT component in a directory containing a previous Windows Platform buildDirectory
java -cp ..\org.eclipse.releng.basebuilder\startup.jar org.eclipse.core.launcher.Main -application org.eclipse.ant.core.antRunner -buildfile build.xml -Dcomponent=jdt -Dconfigs="*,*,*" -DbuildDirectory=c:\builds\platform -Dbaseos=win32 -Dbasews=win32 -Dbasearch=x86 -Djavacfailonerror=true
This
builds an Eclipse JDT component in the same directory where a Windows platform
configuration was previously built. The build will fail if there are compile errors.
"baseos", "basews" and "basearch" should be specified
in order to find the correct location of platform specific jars (i.e. swt.jar)
on the classpath.
Building Eclipse FTP-WebDAV
against an installed Eclipse SDK on Linux
java -cp ../org.eclipse.releng.basebuilder/startup.jar org.eclipse.core.launcher.Main -application org.eclipse.ant.core.antRunner -buildfile build.xml -Dcomponent=team.extras -DbuildDirectory=/builds/team.extras -DbaseLocation=/home/user/fred/eclipse -Dbaseos=linux -Dbasews=motif -Dbasearch=x86 -Djavacfailonerror=true
This builds an Eclipse FTP-WebDAV component against an eclipse SDK installed in directory /home/user/fred/eclipse. The build will fail if there are compile errors. The build output will be located in /builds/team.extras.
Building
Eclipse JUnit Plugin tests against an installed Eclipse SDK on Windows
java -cp ..\org.eclipse.releng.basebuilder\startup.jar org.eclipse.core.launcher.Main -application org.eclipse.ant.core.antRunner -buildfile build.xml -Dcomponent=sdk.tests -DbuildDirectory=c:\tests -DbaseLocation=c:\eclipse -Dbaseos=win32 -Dbasews=win32 -Dbasearch=x86 -Djavacfailonerror=true
This builds an Eclipse
SDK tests component in the directory c:\tests against an eclipse installed in
the directory c:\. The build will fail if there are compile errors.