README
Last updated: October 5, 2004
This document describes how to build Eclipse components from the command line using Ant scripts in this project and org.eclipse.releng.basebuilder.
OBSOLETE - contents need to be changed to reflect reorganization in structure of the scripts.
Table
of Contents
Description
Prerequisites
Setup
Run the Build
Ant
properties defined in build.properties
Eclipse
build 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, PDE, RCP, examples, tests and Team Extras.
1. CVS version 1.10 or higher.
2. 1.4 level JDK.
3. Info-Zip zip and unzip
4. (for building Eclipse components for Mac OSX) GNU tar
and gzip.
5. 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=<component name specified in table below> [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.sdk | This directory contains the scripts used to build any or all configurations of the Eclipse Platform SDK. The Eclipse Platform SDK component contains binaries, source, user and developer documentation. |
| platform | This directory contains the scripts used to build any or all configurations of the Eclipse Platform without source and developer documentation. |
| 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.sdk | This directory contains the scripts used to build the platform-independant and/or the Mac OSX configuration of the Eclipse Java Development Tooling SDK. The Eclipse JDT SDK component contains binaries, source, user and developer documentation. |
| jdt | This directory contains the scripts used to build the platform-independant and/or the Mac OSX configuration of the Eclipse Java Development Tooling component without source and developer documentation. |
| pde.sdk | This directory contains the scripts used to build the Eclipse Plug-in Development Environment SDK. The PDE SDK component contains binaries, source, user and developer documentation. |
| pde | This directory contains the scripts used to build the Eclipse Plug-in Development Environment component without source and developer documentation. |
| 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 which contains the test framework plug-ins, JUnit test plug-ins and scripts used to launch the JUnit tests from the command line. |
| test.framework | This directory contains the scripts used to build the Eclipse test framework plug-ins only. |
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, x86_64 | Red Hat Enterprise Linux WS 3 | GTK | AMD 64 |
| linux, gtk, ia64 | Red Hat Enterprise Linux WS 3 | GTK | IA 64 |
| linux, gtk, ppc | Red Hat Enterprise Linux WS 3 | GTK | PowerPC |
| 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 10 | 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, x86_64& \
linux, gtk, x86 & \
linux, motif, x86 & \
solaris,
motif, sparc & \
aix, motif, ppc & \
hpux, motif, PA_RISC & \
macosx, carbon, ppc
So by default, these 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.