README

Last Updated: September 12, 2005

This document describes how to build GEF 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
GEF Configurations
Examples

Description

org.eclipse.releng.gefbuilder contains Ant scripts that invoke script generators in org.eclipse.pde.build to build all shipped components of GEF: SDK, runtime, and examples.

Prerequisites

1. CVS version 1.10 or higher.
2. 1.3.1 level JDK.
3. (optional) 1.4 level JDK for generating javadoc when building Eclipse SDK component only.
4. A 1.3 level Windows JRE
5. Info-Zip zip and unzip
6. org.eclipse.releng.basebuilder and org.eclipse.releng.gefbuilder from dev.eclipse.org.

Setup

1. Add the zip, unzip 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.gefbuilder into a directory.


Run the Build

cd to org.eclipse.releng.gefbuilder 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 | runtime| examples | 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.gefbuilder which contains the Ant scripts that build a given an GEF component as descibed below:

Component (directory name in org.eclipse.releng.gefbuilder) Description
sdk This directory contains the scripts used to build the GEF SDK. A GEF SDK is comprised of binaries, source, and developer documentation.
runtime This directory contains the scripts used to build the GEF runtime. The GEF runtime component contains binaries only.
examples This directory contains the scripts used to build the GEF Examples. The GEF Examples contain binaries and source.
tests This directory contains the scripts used to build the GEF Automated testing environment. This test framework can be used to run JUnit plugin tests on a GEF 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 possible path length limitations when compiling some classes. For GEF builds, the directory name must be called "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 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.

collPlace The directory relative to ${buildLabel} in which built features and plugins are gathered. Default set to ".".
collBase The directory relative to ${buildLabel} in which to execute zip of the ${collPlace}directory and configuration specific root files.
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". The default setting (*,*,*) should be used for all GEF components.

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.
JAVADOC14_HOME The JAVADOC14_HOME property is used in the *.doc.isv/buildDoc.xml scripts and must be set to the bin directory of a JDK containing the javadoc tool in order to generate javadoc in both org.eclipse.draw2d.doc.isv and org.eclipse.gef.doc.isv. This only needs to be set when building the GEF SDK component. A 1.4 level JDK is recommended to generate javadoc with the correct separator character '/' in links to external classes (see http://developer.java.sun.com/developer/bugParade/bugs/4359874.html).
mapVersionTag

Sets the tag attribute in a call to the Ant <cvs> task to check out org.eclipse.gef.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 "I<build-date>", for example "I20050912".

timestamp A timestamp used to fill in value for buildid in about.mappings files. The timestamp is also used to tag the org.eclipse.gef.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.


GEF Build Configurations

A configuration refers to the combination of the operating system, windowing system and processor architecture for which the component is intended. Currently, all GEF components are platform independent.



Examples

Build SDK including javadoc on Windows
Build Runtime component on Linux
Build test component in a directory containing a previous SDK buildDirectory
Building examples against a GEF SDK installed in eclipse on Windows


Build Windows SDK component with javadoc generation 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 -Djavacfailonerror=true -DjavacVerbose=false -DbuildDirectory=c:\mybuild -DJAVADOC14_HOME=c:\jdk141\bin

This builds a GEF SDK 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. By setting the value of "-DJAVA14_HOME", javadoc will be generated in plugins org.eclipse.draw2d.doc.isv and org.eclipse.gef.doc.isv.

Build GEF runtime 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=runtime -DbuildDirectory=/builds/runtime

This builds a GEF runtime in the directory "/builds/runtime".


Build test component in a directory containing a source from a previous SDK build 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=tests -DbuildDirectory=c:\builds\sdk -Djavacfailonerror=true

This builds an the GEF test plugins in the same directory where a SDK was previously built. The build will fail if there are compile errors.


Building examples against a GEF SDK installed in eclipse 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=examples -DbuildDirectory=c:\examples -DbaseLocation=c:\eclipse -Dbaseos=win32 -Dbasews=win32 -Dbasearch=x86 -Djavacfailonerror=true

This builds GEF examples in the directory c:\examples against a GEF SDK installed in eclipse in the directory c:\eclipse. The build will fail if there are compile errors.