readme.html
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
README.txt
1Dec 4, 2003
2
3This contains template scripts and files that are still being modified and have yet to be tested.
4