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