| <title>org.eclipse.ve.releng.builder README</title> | |
| <p><b><font size="+2">**template**<BR><BR>README </font></b></p><p>Last Updated: | |
| Dec 5, 2003</p><p>This document describes how to build <project>components | |
| from the command line using Ant scripts in this project and org.eclipse.releng.basebuilder.</p><p><br> | |
| <b>Table of Contents</b><br> <br> <a href="#description">Description</a><br> <a href="#prereq">Prerequisites</a><br> | |
| <a href="#setup">Setup</a><br> <a href="#components">Run the Build</a><br> <a href="#antbuildproperties">Ant | |
| properties defined build.properties</a><br> <a href="#buildconfigs"><project> | |
| Configurations</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 | |
| contains Ant scripts that invoke script generators in org.eclipse.pde.build to | |
| build all shipped <a href="#components">components of <project>:</a> SDK, | |
| runtime, tests, and examples.<br> <br> </p><p><b><a name="prereq"></a>Prerequisites</b><br> | |
| </p><p>1. <a href="http://www.cvshome.org/">CVS</a> version 1.10 or higher (For | |
| <a href="http://ftp.cvshome.org/release/binary/win32/cvs-1-11-9.zip"> CVS 1.11.9 | |
| WIN32</a>).<br> 2. <a href="http://java.sun.com/j2se/1.4/download.html">1.4 level | |
| JDK</a>.<br> 3. <a href="http://java.sun.com/j2se/1.3/download.html"> A 1.3 level | |
| Windows JRE</a> to compile against.<br> 4. <a href="http://www.info-zip.org/pub/infozip/">Info-Zip | |
| zip and unzip</a><br> 6. org.eclipse.releng.basebuilder and org.eclipse.<project>.releng.builder | |
| from <a href="http://dev.eclipse.org/viewcvs/">dev.eclipse.org</a>.<br> <br> </p><p><b><a name="setup"></a>Setup<br> | |
| <br> </b>1. Add the CVS and Info-Zip executables to your path as required.<br> | |
| 2. Add the 1.4 jre/bin directory of the installed JDK to your path.<b><br> </b>3. | |
| Check out org.eclipse.releng.basebuilder and org.eclipse.<project>.releng.builder | |
| into a directory.<b><br> <br> <br> <a name="run"></a>Run the Build</b></p><p> | |
| cd to org.eclipse.<project>.releng.builder 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 -Dbuilder=<a href="#components">sdk | |
| | runtime| examples | tests</a> [Ant properties to override in a <a href="#antbuildproperties">component's | |
| build.properties</a>] "<br> </p><p><br> <b><a name="components"></a></b>The | |
| component property value sets the name of the directory in org.eclipse.<project>.releng.builder | |
| which contains the Ant scripts that build a given an <project> component | |
| as descibed below: <br> <br> </p><table width="100%" border="1"> <tr> <td width="20%">Component | |
| (directory name in org.eclipse.<project>.releng.builder)</td><td width="80%">Description</td></tr> | |
| <tr> <td width="20%">sdk</td><td width="80%">This directory contains the scripts | |
| used to build the <project> SDK. A <project> SDK is comprised of binaries, | |
| source, and developer documentation.</td></tr> <tr> <td width="20%">runtime</td><td width="80%">This | |
| directory contains the scripts used to build the <project> runtime. The | |
| <project> runtime component contains binaries only.</td></tr> <tr> <td width="20%">examples</td><td width="80%">This | |
| directory contains the scripts used to build the <project> Examples. The | |
| <project> Examples contain binaries and source. </td></tr> <tr> <td width="20%">tests</td><td width="80%">This | |
| directory contains the scripts used to build the <project> Automated testing | |
| environment. This test framework can be used to run JUnit plugin tests on a <project> | |
| SDK from the command line.</td></tr> </table><p><br> <b><a name="antbuildproperties"></a>Ant | |
| Properties Settings in a component's build.properties<br> <br> </b>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.</p><table width="100%" border="1"> | |
| <tr> <td>Name</td><td>Description</td></tr> <tr> <td>baseos,basews,basearch</td><td>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>.</td></tr> | |
| <tr> <td height="26">baseLocation</td><td height="26">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).</td></tr> | |
| <tr> <td>bootclasspath</td><td>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.</td></tr> | |
| <tr> <td height="36">buildDirectory</td><td height="36"> <p>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. </p></td></tr> <tr> | |
| <td>buildId</td><td>The build name. Default set to "build".</td></tr> | |
| <tr> <td>buildLabel</td><td>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.</td></tr> <tr> <td>buildType</td><td> <p>Letters I, N, S, R or M are | |
| used to identify builds as being one of the following:<br> <br> I - Integration<br> | |
| N - Nightly<br> S - Stable<br> R - Release<br> M - Maintenance<br> </p><p> 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. | |
| </p></td></tr> <tr> <td>collPlace</td><td>The directory relative to ${buildLabel} | |
| in which built features and plugins are gathered. Default set to ".".</td></tr> | |
| <tr> <td>collBase</td><td>The directory relative to ${buildLabel} in which to | |
| execute zip of the ${collPlace}directory and configuration specific root files.</td></tr> | |
| <tr> <td>configs</td><td> <p>An ampersand separated list of configurations to | |
| build where a configuration is specified as <os>,<ws>,<arch>.<br> | |
| ie.configs="win32,win32,x86 & linux, motif, x86 & linux, gtk, x86". | |
| The default setting (*,*,*) should be used for platform-independant components.</p></td></tr> | |
| <tr> <td>javacDebugInfo</td><td>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.</td></tr> <tr> | |
| <td>javacFailOnError</td><td>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.</td></tr> <tr> <td>javacSource</td><td>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.</td></tr> | |
| <tr> <td>javacTarget</td><td>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.</td></tr> | |
| <tr> <td>javacVerbose</td><td>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.</td></tr> | |
| <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 | |
| <cvs> task </a>to check out org.eclipse.<project>.releng, the map | |
| file project on dev.eclipse.org used in the build. The default is "HEAD"</p><p>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<build id in About dialog>" | |
| for example "v200307110800" will checkout the map files used to run | |
| the integration at the specified date/time. These scripts work with builds > | |
| ??<br> </p></td></tr> <tr> <td>timestamp</td><td>A timestamp used to fill in value | |
| for buildid in about.mappings files. The timestamp is also used to tag the org.eclipse.<project>.releng | |
| project on dev.eclipse.org only when an appropriate value for mapCvsRoot is provided | |
| and when the tagMaps Ant property is set. </td></tr> <tr> <td>zipargs</td><td>Arguments | |
| to send to the zip executable. ie. zipargs=-y on Linux preserves symbolic links.</td></tr> | |
| </table><p><br> </p><p><font size="+1"><b><a name="buildconfigs"></a><project> | |
| Build Configurations</b></font></p><p><b></b>A configuration refers to the combination | |
| of the operating system, windowing system and processor architecture for which | |
| the component is intended. Currently, all <project> components are platform | |
| independent.<br> <p><br> <br> <b><a name="examples"></a>Examples<br> <br> </b> | |
| <p><a href="#ex1">Build SDK including javadoc on Windows</a><br> <a href="#ex5">Build | |
| Runtime component on Linux</a><br> <a href="#ex5.1">Build test component in a | |
| directory containing a previous SDK buildDirectory</a> <br> <a href="#ex6">Building | |
| examples against a <project> SDK installed in eclipse on Windows</a><br> | |
| </p><p><b><br> <a name="ex1"></a>Build Windows SDK component with javadoc generation | |
| on Windows</b></p><p><b>java -cp ..\org.eclipse.releng.basebuilder\startup.jar | |
| org.eclipse.core.launcher.Main -application org.eclipse.ant.core.antRunner -buildfile | |
| build.xml -Dbuilder=sdk -Dbootclasspath=C:\JRE131\lib\rt.jar -Djavacfailonerror=true | |
| -DjavacVerbose=false -DbuildDirectory=c:\mybuild\eclipse</b> <br> <br> This builds | |
| a <project> SDK in the directory c:\mybuild\eclipse. "-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. <b></b> <br> </p><p><b><a name="ex4"></a>Build | |
| <project> runtime component on Linux</b></p><p><b>java -cp ../org.eclipse.releng.basebuilder/startup.jar | |
| org.eclipse.core.launcher.Main -application org.eclipse.ant.core.antRunner -buildfile | |
| build.xml -Dbuilder=runtime -DbuildDirectory=/builds/runtime/eclipse</b></p><p>This | |
| builds a <project> runtime in the directory "/builds/runtime/eclipse".<br> | |
| <br> <br> <b><a name="ex5.1"></a>Build test component in a directory containing | |
| a source from a previous SDK build on Windows</b></p><p><b>java -cp ..\org.eclipse.releng.basebuilder\startup.jar | |
| org.eclipse.core.launcher.Main -application org.eclipse.ant.core.antRunner -buildfile | |
| build.xml -Dbuilder=tests -Dbootclasspath=C:\JRE131\lib\rt.jar -DbuildDirectory=c:\builds\sdk\eclipse | |
| -Djavacfailonerror=true</b></p><p></p><p>This builds an the <project> test | |
| plugins in the same directory where an SDK was previously built. The build will | |
| fail if there are compile errors.<br> </p><p><br> <b><a name="ex7"></a>Building | |
| examples against a <project> SDK installed in eclipse on Windows</b></p><p><b>java | |
| -cp ..\org.eclipse.releng.basebuilder\startup.jar org.eclipse.core.launcher.Main | |
| -application org.eclipse.ant.core.antRunner -buildfile build.xml -Dbuilder=examples | |
| -Dbootclasspath=C:\JRE131\lib\rt.jar -DbuildDirectory=c:\examples\eclipse -DbaseLocation=c:\eclipse | |
| -Dbaseos=win32 -Dbasews=win32 -Dbasearch=x86 -Djavacfailonerror=true</b></p><p></p><p>This | |
| builds <project> examples in the directory c:\examples against a <project> | |
| SDK installed in eclipse in the directory c:\examples\eclipse. The build will | |
| fail if there are compile errors.<br> </p><p> </p> |