Platform-releng-eclipsebuilder-readme

Using the releng templates to run your build

This small example project shows how to set up the infrastructure to build eclipse in a similar manner to the eclipse platform team. Last Updated: Feb 14, 2006. Draft document - in progress.

This document describes how to build Eclipse components from the command line using Ant scripts in this project and org.eclipse.releng.basebuilder.

Description

org.eclipse.releng.eclipsebuilder contains Ant scripts that invoke script generators in org.eclipse.pde.build to build all shipped Platform-releng-sample-project#Components components of Eclipse: SDK, Platform JDT, PDE, RCP, SWT, Equinox, examples, tests and Team Extras.

Prerequisites

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

<p>"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 defined in build.properties

[Ant properties to override in a <a href="#antbuildproperties">component's build.properties</a>] "

Components

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

<p> 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 <a href="#buildconfigs">build configurations</a>.
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 <a href="http://ant.apache.org/manual/CoreTasks/javac.html">Ant <javac> task</a> 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: I - Integration N - Nightly S - Stable R - Release M - Maintenance 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>. ie.configs="win32,win32,x86 & linux, motif, x86 & linux, gtk, x86". See list of <a href="#buildconfigs">build configurations</a> below.
javacDebugInfo	Sets the value for the attribute "debug" in calls to the <a href="http://ant.apache.org/manual/CoreTasks/javac.html">Ant <javac> task </a>in a plugins' build.xml. Default set to on.
javacFailOnError	Sets the value for the attribute "failonerror" in calls to the <a href="http://ant.apache.org/manual/CoreTasks/javac.html">Ant <javac> task</a> 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 <a href="http://ant.apache.org/manual/CoreTasks/javac.html">Ant <javac> task</a> in a plugins' build.xml. Default set to 1.3.
javacTarget	Sets the value for the attribute "target" in calls to the <a href="http://ant.apache.org/manual/CoreTasks/javac.html">Ant <javac> task</a> in a plugins' build.xml. Default set to 1.1.
javacVerbose	Sets the value for the attribute "verbose" in calls to the <a href="http://ant.apache.org/manual/CoreTasks/javac.html">Ant <javac> task</a> in a plugins' build.xml. Default set to true.
mapVersionTag	Sets the tag attribute in a call to the <a href="http://ant.apache.org/manual/CoreTasks/cvs.html">Ant <cvs> task </a>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.

Eclipse Build Configurations

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

<p>
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: <p>configs= \
     win32, win32, x86 &\
     linux, gtk, x86_64& \
     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, 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). <p>

Examples

<p>

Build Windows SDK component on Windows

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

<a name="ex3"></a>Build Windows SDK component on Linux

<p>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</b>

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

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

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

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

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