Jump to: navigation, search

Platform-releng-sample-project

Revision as of 10:33, 14 February 2006 by Kmoir (Talk | contribs)

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

<p>org.eclipse.releng.eclipsebuilder contains Ant scripts that invoke script generators in org.eclipse.pde.build to build all shipped <a href="#components">components of Eclipse:</a> SDK, Platform

JDT, PDE, RCP, examples, tests and Team Extras.

Prerequisites

1. CVS version 1.10 or higher
2. <a href="http://java.sun.com/j2se/1.4/download.html">1.4 level JDK</a>.
3. <a href="http://www.info-zip.org/pub/infozip/">Info-Zip zip and unzip</a>
4. (for building Eclipse components for Mac OSX) GNU <a href="http://www.gnu.org/software/tar/">tar</a> and <a href="http://www.gnu.org/software/gzip/gzip.html">gzip</a>.
5. org.eclipse.releng.basebuilder and org.eclipse.releng.eclipsebuilder from <a href="http://dev.eclipse.org/viewcvs/">dev.eclipse.org</a>.

</p><p><b><a name="setup"></a>

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.<b>
3. Check out org.eclipse.releng.basebuilder and org.eclipse.releng.eclipsebuilder into a directory.


Run the Build

<p> 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 <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=35923">bug 35923</a>): </p><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:

</p>

Component (directory name in org.eclipse.releng.eclipsebuilder)Description
sdkThis 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.sdkThis 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.
platformThis directory contains the

scripts used to build any or all configurations of the Eclipse Platform without

source and developer documentation.
sdk.rcpThis

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.
rcpThis directory contains the scripts used to build any or all configuration of the Eclipse RCP plug-ins.
jdt.sdkThis 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.
jdtThis

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

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.
pdeThis directory contains the scripts used

to build the Eclipse Plug-in Development Environment component without source

and developer documentation.
sdk.examplesThis

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

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

directory contains the scripts used to build the Eclipse test framework plug-ins

only.
<p>
<b><a name="antbuildproperties"></a>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.

NameDescription
baseos,basews,basearchThe

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>.
baseLocationA 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).
bootclasspathSets 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.
buildDirectoryThe 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.
buildIdThe build name. Default set to "build".
buildLabelRefers

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.

archivePrefixThe name of the top level directory which should exist in the produced zip file. Typically set to "eclipse".
collectingFolderThe 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.

javacDebugInfoSets 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.
javacFailOnErrorSets 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.
javacSourceSets

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.
javacTargetSets 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.
javacVerboseSets 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.

timestampA 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.
zipargsArguments to send to the zip executable. ie. zipargs=-y on Linux preserves symbolic links.



Eclipse Build Configurations

<p><b>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, x86Red Hat Enterprise Linux WS 3MotifIntel x86
linux, gtk, x86_64Red Hat Enterprise Linux WS 3GTKAMD 64
linux, gtk, ia64Red Hat Enterprise Linux WS 3GTKIA 64
linux, gtk, ppcRed Hat Enterprise Linux WS 3GTKPowerPC
linux, gtk, x86Red Hat Enterprise Linux WS 3GTKIntel x86
aix, motif, ppcIBM AIX 5L Version 5.2MotifPowerPC
solaris, motif, sparcSun Solaris 8MotifSPARC
hpux, motif, PA_RISCHP HP-UX 11iMotifhp9000 PA-RISC
macosx, carbon, ppcApple Mac OS X 10.3CarbonPowerPC
win32,win32, x86Microsoft Windows XPWin32Intel 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><a href="#ex1">Build Windows

SDK Windows</a>
<a href="#ex2">Build Linux GTK and Motif SDK on Linux</a>
<a href="#ex3">Build Windows SDK component on Linux</a>
<a href="#ex4">Build Linux Motif platform component on Linux</a>
<a href="#ex5">Build JDT component against a pre-built Windows Platform component on Windows</a>
<a href="#ex5.1">Build JDT component in a directory containing a previous Windows Platform buildDirectory</a>
<a href="#ex6">Building Eclipse FTP-WebDAV against an installed Eclipse SDK on Linux </a>
<a href="#ex7">Building Eclipse JUnit Plugin tests against an installed Eclipse SDK on Windows </a>
</p><p>
<a name="ex1"></a>Build Windows SDK component on Windows
</p><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" -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.

<a name="ex2"></a>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><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.

</p><p><a name="ex4"></a>Build Linux Motif platform component on Linux</p><p>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</p><p>This builds an eclipse platform runtime for the linux motif configuration. The buildDirectory will be set "/builds/platform".

</p><p><a name="ex5"></a>Build JDT component against a pre-built Windows Platform component on Windows</p><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><p></p><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.

</p><p><a name="ex5.1"></a>Build JDT component in a directory containing a previous Windows Platform buildDirectory</p><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\platform -Dbaseos=win32 -Dbasews=win32 -Dbasearch=x86 -Djavacfailonerror=true</p><p></p><p>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.


<a name="ex6"></a>Building Eclipse FTP-WebDAV against an installed Eclipse SDK on Linux
</p><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><p></p><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.</p><p>
<a name="ex7"></a>Building Eclipse JUnit Plugin tests against an installed Eclipse SDK on Windows</p><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</p><p></p><p>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.
</p><p> </p>