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 <project>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"><project> 8 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 9 contains Ant scripts that invoke script generators in org.eclipse.pde.build to 10 build all shipped <a href="#components">components of <project>:</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.<project>.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.<project>.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.<project>.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>"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>] "<br> </p><p><br> <b><a name="components"></a></b>The 30 component property value sets the name of the directory in org.eclipse.<project>.releng.builder 31 which contains the Ant scripts that build a given an <project> component 32 as 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 35 used to build the <project> SDK. A <project> 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 <project> runtime. The 38 <project> 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 <project> Examples. The 40 <project> 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 <project> Automated testing 42 environment. This test framework can be used to run JUnit plugin tests on a <project> 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 "bootclasspath" 56 in 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 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 "build".</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."I.build". 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 ".".</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 <os>,<ws>,<arch>.<br> 78 ie.configs="win32,win32,x86 & linux, motif, x86 & linux, gtk, x86". 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 "debug" 81 in 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" 84 in 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 86 are compilation errors when this is set to false.</td></tr> <tr> <td>javacSource</td><td>Sets 87 the 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" 90 in 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" 93 in 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 97 file project on dev.eclipse.org used in the build. The default is "HEAD"</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 "v<build id in About dialog>" 100 for example "v200307110800" will checkout the map files used to run 101 the 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 103 for buildid in about.mappings files. The timestamp is also used to tag the org.eclipse.<project>.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><project> 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 <project> 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 <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 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 <project> SDK in the directory c:\mybuild\eclipse. "-DjavaVerbose=false" 122 indicates that no compile logs will be generated and "-Djavacfailonerror=true" 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 <project> 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 <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 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 <project> 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 <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 140 builds <project> examples in the directory c:\examples against a <project> 141 SDK installed in eclipse in the directory c:\examples\eclipse. The build will 142 fail if there are compile errors.<br> </p><p> </p> 143
