1<title>org.eclipse.ve.releng.builder README</title> 2<p><b><font size="+2">**template**<BR><BR>README </font></b></p><p>Last Updated: 3Dec 5, 2003</p><p>This document describes how to build <project>components 4from the command line using Ant scripts in this project and org.eclipse.releng.basebuilder.</p><p><br> 5<b>Table of Contents</b><br> <br> <a href="#description">Description</a><br> <a href="#prereq">Prerequisites</a><br> 6<a href="#setup">Setup</a><br> <a href="#components">Run the Build</a><br> <a href="#antbuildproperties">Ant 7properties defined build.properties</a><br> <a href="#buildconfigs"><project> 8Configurations</a><br> <a href="#examples">Examples</a><br> <br> </p><p><b><a name="description"></a>Description</b></p><p>org.eclipse.<project>.releng.builder 9contains Ant scripts that invoke script generators in org.eclipse.pde.build to 10build all shipped <a href="#components">components of <project>:</a> SDK, 11runtime, tests, and examples.<br> <br> </p><p><b><a name="prereq"></a>Prerequisites</b><br> 12</p><p>1. <a href="http://www.cvshome.org/">CVS</a> version 1.10 or higher (For 13<a href="http://ftp.cvshome.org/release/binary/win32/cvs-1-11-9.zip"> CVS 1.11.9 14WIN32</a>).<br> 2. <a href="http://java.sun.com/j2se/1.4/download.html">1.4 level 15JDK</a>.<br> 3. <a href="http://java.sun.com/j2se/1.3/download.html"> A 1.3 level 16Windows JRE</a> to compile against.<br> 4. <a href="http://www.info-zip.org/pub/infozip/">Info-Zip 17zip and unzip</a><br> 6. org.eclipse.releng.basebuilder and org.eclipse.<project>.releng.builder 18from <a href="http://dev.eclipse.org/viewcvs/">dev.eclipse.org</a>.<br> <br> </p><p><b><a name="setup"></a>Setup<br> 19<br> </b>1. Add the CVS and Info-Zip executables to your path as required.<br> 202. Add the 1.4 jre/bin directory of the installed JDK to your path.<b><br> </b>3. 21Check out org.eclipse.releng.basebuilder and org.eclipse.<project>.releng.builder 22into a directory.<b><br> <br> <br> <a name="run"></a>Run the Build</b></p><p> 23cd to org.eclipse.<project>.releng.builder directory and execute the following 24command (currently the build.xml script can only be executed in a headless eclipse 25due to <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=35923">bug 35923</a>): 26</p><p>"java -cp ../org.eclipse.releng.basebuilder/startup.jar org.eclipse.core.launcher.Main 27-application org.eclipse.ant.core.antRunner -buildfile build.xml -Dbuilder=<a href="#components">sdk 28| runtime| examples | tests</a> [Ant properties to override in a <a href="#antbuildproperties">component's 29build.properties</a>] "<br> </p><p><br> <b><a name="components"></a></b>The 30component property value sets the name of the directory in org.eclipse.<project>.releng.builder 31which contains the Ant scripts that build a given an <project> component 32as descibed below: <br> <br> </p><table width="100%" border="1"> <tr> <td width="20%">Component 33(directory name in org.eclipse.<project>.releng.builder)</td><td width="80%">Description</td></tr> 34<tr> <td width="20%">sdk</td><td width="80%">This directory contains the scripts 35used to build the <project> SDK. A <project> SDK is comprised of binaries, 36source, and developer documentation.</td></tr> <tr> <td width="20%">runtime</td><td width="80%">This 37directory contains the scripts used to build the <project> runtime. The 38<project> runtime component contains binaries only.</td></tr> <tr> <td width="20%">examples</td><td width="80%">This 39directory contains the scripts used to build the <project> Examples. The 40<project> Examples contain binaries and source. </td></tr> <tr> <td width="20%">tests</td><td width="80%">This 41directory contains the scripts used to build the <project> Automated testing 42environment. This test framework can be used to run JUnit plugin tests on a <project> 43SDK from the command line.</td></tr> </table><p><br> <b><a name="antbuildproperties"></a>Ant 44Properties Settings in a component's build.properties<br> <br> </b>The following 45properties are pre-defined in the build.properties file for the specified component. 46They can be overridden by setting them at the command line at build time or by 47changing them directly in the component's build.properties file.</p><table width="100%" border="1"> 48<tr> <td>Name</td><td>Description</td></tr> <tr> <td>baseos,basews,basearch</td><td>The 49os, ws and arch values of a pre-built eclipse component being compiled against. 50See list of possible values in the table of <a href="#buildconfigs">build configurations</a>.</td></tr> 51<tr> <td height="26">baseLocation</td><td height="26">A directory separate from 52buildDirectory which contains pre-built plugins and features against which to 53compile. The basedirectory must not contain any features, plugins or fragments 54which are already or will be located in the buildDirectory (see below).</td></tr> 55<tr> <td>bootclasspath</td><td>Sets the value for the attribute "bootclasspath" 56in calls to the <a href="http://ant.apache.org/manual/CoreTasks/javac.html">Ant 57<javac> task</a> in a plugins' build.xml. Default set to ${java.home}/lib/rt.jar.</td></tr> 58<tr> <td height="36">buildDirectory</td><td height="36"> <p>The absolute path 59to a working directory where the source for the build will be exported, where 60scripts will be generated and where the end products of the build will be located. 61On Windows systems, the path length should not exceed thirty characters due to 62possible path length limitations when compiling some classes. </p></td></tr> <tr> 63<td>buildId</td><td>The build name. Default set to "build".</td></tr> 64<tr> <td>buildLabel</td><td>Refers to the name of the directory which will contain 65the end result of the build. Default set to ${buildType}.${buildId}, ie."I.build". 66This directory will be created inside the location specified by the ${buildDirectory} 67property.</td></tr> <tr> <td>buildType</td><td> <p>Letters I, N, S, R or M are 68used to identify builds as being one of the following:<br> <br> I - Integration<br> 69N - Nightly<br> S - Stable<br> R - Release<br> M - Maintenance<br> </p><p> If 70set to N, all source will be checked out from the HEAD stream. In all other cases, 71tags as specifed in map files will be used when exporting plugins to the buildDirectory. 72</p></td></tr> <tr> <td>collPlace</td><td>The directory relative to ${buildLabel} 73in which built features and plugins are gathered. Default set to ".".</td></tr> 74<tr> <td>collBase</td><td>The directory relative to ${buildLabel} in which to 75execute zip of the ${collPlace}directory and configuration specific root files.</td></tr> 76<tr> <td>configs</td><td> <p>An ampersand separated list of configurations to 77build where a configuration is specified as <os>,<ws>,<arch>.<br> 78ie.configs="win32,win32,x86 & linux, motif, x86 & linux, gtk, x86". 79The default setting (*,*,*) should be used for platform-independant components.</p></td></tr> 80<tr> <td>javacDebugInfo</td><td>Sets the value for the attribute "debug" 81in calls to the <a href="http://ant.apache.org/manual/CoreTasks/javac.html">Ant 82<javac> task </a>in a plugins' build.xml. Default set to on.</td></tr> <tr> 83<td>javacFailOnError</td><td>Sets the value for the attribute "failonerror" 84in calls to the <a href="http://ant.apache.org/manual/CoreTasks/javac.html">Ant 85<javac> task</a> in a plugins' build.xml. Build will continue even if there 86are compilation errors when this is set to false.</td></tr> <tr> <td>javacSource</td><td>Sets 87the value for the attribute "source" in calls to the <a href="http://ant.apache.org/manual/CoreTasks/javac.html">Ant 88<javac> task</a> in a plugins' build.xml. Default set to 1.3.</td></tr> 89<tr> <td>javacTarget</td><td>Sets the value for the attribute "target" 90in calls to the <a href="http://ant.apache.org/manual/CoreTasks/javac.html">Ant 91<javac> task</a> in a plugins' build.xml. Default set to 1.1.</td></tr> 92<tr> <td>javacVerbose</td><td>Sets the value for the attribute "verbose" 93in calls to the <a href="http://ant.apache.org/manual/CoreTasks/javac.html">Ant 94<javac> task</a> in a plugins' build.xml. Default set to true.</td></tr> 95<tr> <td>mapVersionTag</td><td> <p>Sets the tag attribute in a call to the <a href="http://ant.apache.org/manual/CoreTasks/cvs.html">Ant 96<cvs> task </a>to check out org.eclipse.<project>.releng, the map 97file project on dev.eclipse.org used in the build. The default is "HEAD"</p><p>Can 98be set to a specific tag to download the map files used for a previous integration 99build. Typically, these tags are in the form "v<build id in About dialog>" 100for example "v200307110800" will checkout the map files used to run 101the integration at the specified date/time. These scripts work with builds > 102??<br> </p></td></tr> <tr> <td>timestamp</td><td>A timestamp used to fill in value 103for buildid in about.mappings files. The timestamp is also used to tag the org.eclipse.<project>.releng 104project on dev.eclipse.org only when an appropriate value for mapCvsRoot is provided 105and when the tagMaps Ant property is set. </td></tr> <tr> <td>zipargs</td><td>Arguments 106to send to the zip executable. ie. zipargs=-y on Linux preserves symbolic links.</td></tr> 107</table><p><br> </p><p><font size="+1"><b><a name="buildconfigs"></a><project> 108Build Configurations</b></font></p><p><b></b>A configuration refers to the combination 109of the operating system, windowing system and processor architecture for which 110the component is intended. Currently, all <project> components are platform 111independent.<br> <p><br> <br> <b><a name="examples"></a>Examples<br> <br> </b> 112<p><a href="#ex1">Build SDK including javadoc on Windows</a><br> <a href="#ex5">Build 113Runtime component on Linux</a><br> <a href="#ex5.1">Build test component in a 114directory containing a previous SDK buildDirectory</a> <br> <a href="#ex6">Building 115examples against a <project> SDK installed in eclipse on Windows</a><br> 116</p><p><b><br> <a name="ex1"></a>Build Windows SDK component with javadoc generation 117on Windows</b></p><p><b>java -cp ..\org.eclipse.releng.basebuilder\startup.jar 118org.eclipse.core.launcher.Main -application org.eclipse.ant.core.antRunner -buildfile 119build.xml -Dbuilder=sdk -Dbootclasspath=C:\JRE131\lib\rt.jar -Djavacfailonerror=true 120-DjavacVerbose=false -DbuildDirectory=c:\mybuild\eclipse</b> <br> <br> This builds 121a <project> SDK in the directory c:\mybuild\eclipse. "-DjavaVerbose=false" 122indicates that no compile logs will be generated and "-Djavacfailonerror=true" 123will cause the build to fail if there are any compile errors. <b></b> <br> </p><p><b><a name="ex4"></a>Build 124<project> runtime component on Linux</b></p><p><b>java -cp ../org.eclipse.releng.basebuilder/startup.jar 125org.eclipse.core.launcher.Main -application org.eclipse.ant.core.antRunner -buildfile 126build.xml -Dbuilder=runtime -DbuildDirectory=/builds/runtime/eclipse</b></p><p>This 127builds a <project> runtime in the directory "/builds/runtime/eclipse".<br> 128<br> <br> <b><a name="ex5.1"></a>Build test component in a directory containing 129a source from a previous SDK build on Windows</b></p><p><b>java -cp ..\org.eclipse.releng.basebuilder\startup.jar 130org.eclipse.core.launcher.Main -application org.eclipse.ant.core.antRunner -buildfile 131build.xml -Dbuilder=tests -Dbootclasspath=C:\JRE131\lib\rt.jar -DbuildDirectory=c:\builds\sdk\eclipse 132-Djavacfailonerror=true</b></p><p></p><p>This builds an the <project> test 133plugins in the same directory where an SDK was previously built. The build will 134fail if there are compile errors.<br> </p><p><br> <b><a name="ex7"></a>Building 135examples against a <project> SDK installed in eclipse on Windows</b></p><p><b>java 136-cp ..\org.eclipse.releng.basebuilder\startup.jar org.eclipse.core.launcher.Main 137-application org.eclipse.ant.core.antRunner -buildfile build.xml -Dbuilder=examples 138-Dbootclasspath=C:\JRE131\lib\rt.jar -DbuildDirectory=c:\examples\eclipse -DbaseLocation=c:\eclipse 139-Dbaseos=win32 -Dbasews=win32 -Dbasearch=x86 -Djavacfailonerror=true</b></p><p></p><p>This 140builds <project> examples in the directory c:\examples against a <project> 141SDK installed in eclipse in the directory c:\examples\eclipse. The build will 142fail if there are compile errors.<br> </p><p> </p> 143