Dec 4, 2003

This contains template scripts and files that are still being modified and have yet to be tested.

<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 &lt;project&gt;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">&lt;project&gt;
Configurations</a><br> <a href="#examples">Examples</a><br> <br> </p><p><b><a name="description"></a>Description</b></p><p>org.eclipse.&lt;project&gt;.releng.builder
contains Ant scripts that invoke script generators in org.eclipse.pde.build to
build all shipped <a href="#components">components of &lt;project&gt;:</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.&lt;project&gt;.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.&lt;project&gt;.releng.builder
into a directory.<b><br> <br> <br> <a name="run"></a>Run the Build</b></p><p>
cd to org.eclipse.&lt;project&gt;.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>&quot;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>] &quot;<br> </p><p><br> <b><a name="components"></a></b>The
component property value sets the name of the directory in org.eclipse.&lt;project&gt;.releng.builder
which contains the Ant scripts that build a given an &lt;project&gt; component
as descibed below: <br> <br> </p><table width="100%" border="1"> <tr> <td width="20%">Component
(directory name in org.eclipse.&lt;project&gt;.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 &lt;project&gt; SDK. A &lt;project&gt; 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 &lt;project&gt; runtime. The
&lt;project&gt; 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 &lt;project&gt; Examples. The
&lt;project&gt; 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 &lt;project&gt; Automated testing
environment. This test framework can be used to run JUnit plugin tests on a &lt;project&gt;
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 &quot;bootclasspath&quot;
in calls to the <a href="http://ant.apache.org/manual/CoreTasks/javac.html">Ant
&lt;javac&gt; 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 &quot;build&quot;.</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.&quot;I.build&quot;.
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 &quot;.&quot;.</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 &lt;os&gt;,&lt;ws&gt;,&lt;arch&gt;.<br>
ie.configs=&quot;win32,win32,x86 &amp; linux, motif, x86 &amp; linux, gtk, x86&quot;.
The default setting (*,*,*) should be used for platform-independant components.</p></td></tr>
<tr> <td>javacDebugInfo</td><td>Sets the value for the attribute &quot;debug&quot;
in calls to the <a href="http://ant.apache.org/manual/CoreTasks/javac.html">Ant
&lt;javac&gt; task </a>in a plugins' build.xml. Default set to on.</td></tr> <tr>
<td>javacFailOnError</td><td>Sets the value for the attribute &quot;failonerror&quot;
in calls to the <a href="http://ant.apache.org/manual/CoreTasks/javac.html">Ant
&lt;javac&gt; 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 &quot;source&quot; in calls to the <a href="http://ant.apache.org/manual/CoreTasks/javac.html">Ant
&lt;javac&gt; 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 &quot;target&quot;
in calls to the <a href="http://ant.apache.org/manual/CoreTasks/javac.html">Ant
&lt;javac&gt; 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 &quot;verbose&quot;
in calls to the <a href="http://ant.apache.org/manual/CoreTasks/javac.html">Ant
&lt;javac&gt; 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
&lt;cvs&gt; task </a>to check out org.eclipse.&lt;project&gt;.releng, the map
file project on dev.eclipse.org used in the build. The default is &quot;HEAD&quot;</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 &quot;v&lt;build id in About dialog&gt;&quot;
for example &quot;v200307110800&quot; will checkout the map files used to run
the integration at the specified date/time. These scripts work with builds &gt;
??<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.&lt;project&gt;.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>&lt;project&gt;
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 &lt;project&gt; 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 &lt;project&gt; 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 &lt;project&gt; SDK in the directory c:\mybuild\eclipse. &quot;-DjavaVerbose=false&quot;
indicates that no compile logs will be generated and &quot;-Djavacfailonerror=true&quot;
will cause the build to fail if there are any compile errors. <b></b> <br> </p><p><b><a name="ex4"></a>Build
&lt;project&gt; 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 &lt;project&gt; runtime in the directory &quot;/builds/runtime/eclipse&quot;.<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 &lt;project&gt; 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 &lt;project&gt; 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 &lt;project&gt; examples in the directory c:\examples against a &lt;project&gt;
SDK installed in eclipse in the directory c:\examples\eclipse. The build will
fail if there are compile errors.<br> </p><p>&nbsp;</p>