1 <HTML> 2 <HEAD> 3 <TITLE>Automating Product Builds with PDE BUILD</TITLE> <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1"> 4 </HEAD> 5 6 <BODY BGCOLOR="#FFFFFF" TEXT="#000000"> 7 <P><FONT SIZE="+3"> Automating Builds with PDE BUILD</FONT><BR></P><P>Last Updated: 8 June16, 2005</P><P><FONT SIZE="+1"><A HREF="#intro">Introduction</A></FONT></P><P><FONT SIZE="+1"><A HREF="#preparation">Preparing 9 the infrastrucure</A></FONT></P><UL><LI><A HREF="#commit">Commit feature and plug-in 10 projects to CVS repository</A></LI><LI><A HREF="#createmap">Create map file project</A></LI><LI><A HREF="#gensource">Set 11 up auto-generation of source features and plug-ins</A></LI></UL><P><FONT SIZE="+1"><A HREF="#buildconfigfiles">Preparing 12 Build Configuration Files</A> </FONT></P><UL> <LI><A HREF="#build.properties">Write 13 build.properties</A></LI><LI><A HREF="#customTargets.xml">Write customTargets.xml</A></LI></UL><P><FONT SIZE="+1"><A HREF="#buildexec"> 14 Build Execution</A></FONT></P><UL> <LI><A HREF="#buildmachinesetup">Set up build 15 machine</A></LI><LI><A HREF="#runbuild">Running the build</A></LI></UL><P> </P><HR><P><FONT SIZE="+2"><B><A NAME="intro"></A>Introduction</B></FONT></P><P>This 16 document describes how to automate the building of Eclipse-based features and 17 their plug-ins using script generators in the org.eclipse.pde.build plug-in in 18 Eclipse 3.2 stream SDK.<BR> </P><P>Either an existing Eclipse 3.2 stream SDK or 19 the org.eclipse.releng.basebuilder project on dev.eclipse.org:/home/eclipse can 20 be used in this automated build process. The org.eclipse.releng.basebuilder project 21 contains the minimal set of plug-ins extracted from the latest stable Eclipse 22 3.2 stream SDK build (a milestone or release) needed to run applications and custom 23 Ant tasks in org.eclipse.ant.core, org.eclipse.pde.build, org.eclipse.pde, and 24 org.eclipse.help.base. This project is used by the Eclipse release engineering 25 team to build Eclipse itself. <P>It is assumed the reader is starting with a set 26 of pre-existing features and plug-ins, their build.properties, and has a working 27 knowledge of Apache Ant. In this document, features, plug-ins and fragments are 28 also referred to as "elements". The word "distribution" is 29 used to describe the end result of building a feature, a functional unit comprised 30 of one or more groupings of plug-ins. The result of building a feature results 31 in a zip or tar.gz file which contains the binary version of the feature and it's 32 plug-ins. If the feature contains nested features (i.e. <includes> elements), 33 the nested features will be built recursively and included in the distribution.<br> 34 <br> For example, the Eclipse SDK distributions are built from the <a href="http://dev.eclipse.org/viewcvs/index.cgi/%7Echeckout%7E/org.eclipse.sdk-feature/feature.xml?rev=1.7" target="extra">org.eclipse.sdk 35 feature</a> which is comprised of features org.eclipse.rcp, org.eclipse.rcp.source, 36 org.eclipse.platform, org.eclipse.platform.source, org.eclipse.jdt, org.eclipse.jdt.source, 37 org.eclipse.pde, org.eclipse.pde.source and the org.eclipse.sdk plug-in. The distribution 38 built from the org.eclipse.sdk feature will therefore contain the binary version 39 of the org.eclipse.sdk feature and its one plug-in plus the binary versions of 40 its eight nested features and all their plug-ins.<br> <br> <HR><P><FONT SIZE="+2"><B><A NAME="preparation"></A>Preparing 41 the infrastructure</B></FONT></P><P><B><FONT SIZE="+1" COLOR="#000000"><A NAME="commit"></A>Commit 42 feature and plug-in projects to CVS repository</FONT></B></P><P>Since Eclipse 43 3.0, PDE Build allows a very flexible organization of feature, plug-in and fragment 44 projects in a CVS repository where:</P><UL> <LI> the directory containing the 45 source for an element can exist as a root level CVS module or in any subdirectory 46 in the repository.</LI><LI>the directory name containing the element's source 47 does not have to match the id attribute in it's manifest (feature.xml, plugin.xml, 48 fragment.xml).</LI></UL><P>This flexibility was not present for the Eclipse process 49 prior to version 3.0 which is one reason for the very flat organization of projects 50 in the dev.eclipse.org:/home/eclipse repository. It is recommended that this flat 51 structure <B>not</B> be used as an example. Rather, using a structure similar 52 to the one used for the <A HREF="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.equinox/?cvsroot=Technology_Project" target="extra">Equinox</A> 53 or <A HREF="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.stellation/?cvsroot=Technology_Project" target="extra" >Stellation</A> 54 project should be considered where all files and directories for a given product 55 are stored under a single directory or module at the cvs root level:<BR><BR><cvs 56 root><BR><BR> /org.eclipse.equinox<BR><BR> /plugins<BR><BR> /all 57 plug-ins at this level<BR> </P><P>Once 58 the source for all elements is committed to a repository, the next step consists 59 of recording the location and access method for each feature, plug-in and fragment 60 in one or more <A HREF="#createmap">map files</A>.</P><P> </P><P><B><FONT SIZE="+1"><A NAME="createmap"></A>Create 61 map file project</FONT></B></P><P>A .map file is a java property file which contains 62 mappings of elements to their CVS locations and access methods. Map files are 63 used by PDE Build early in the build process to generate Ant scripts which use 64 the Ant <cvs> task to export source to a directory. This is described further 65 <A HREF="#getmaps">below</A>.<BR> <BR>Map file entries use the following format:<BR><BR> 66 <B>feature|fragment|plugin (a] element.Id=<cvs tag>,<access method>:<cvs 67 user>@<cvs repository>,<cvs password>[,<repository path> 68 (no starting slash) ]</B><BR> </P><P>The <repository path> is only required 69 when the module (or directory) containing the source for the element does not 70 match the element.Id or if the directory is not at the root of the repository.<BR> 71 <BR>A map file entry must exist for each feature being built, it's <plugin> 72 elements and it's <includes> elements (ie. nested features and their plug-ins). 73 Adding a plug-in or fragment to a feature therefore requires updating the map 74 files with the new element.<BR><BR><BR><B>Map File Entry Examples</B></P><UL><LI>The 75 org.eclipse.platform plug-in source is located at the root of the <A HREF="http://dev.eclipse.org/viewcvs/" target="extra">dev.eclipse.org:/home/eclipse</A> 76 repository. It is contained in a directory with the name "org.eclipse.platform". 77 The resulting map file entry for this plug-in is:<BR><BR>plugin (a] org.eclipse.platform=v20031121,:pserver:anonymous (a] dev.eclipse.org:/home/eclipse,<BR><BR></LI><LI>The 78 org.eclipse.platform feature source is located at the root of the <A HREF="http://dev.eclipse.org/viewcvs/" target="extra">dev.eclipse.org:/home/eclipse</A> 79 repository in a directory with the name "org.eclipse.platform-feature". 80 The resulting map file entry for this feature is:<BR><BR>feature (a] org.eclipse.platform=v20031128,:pserver:anonymous (a] dev.eclipse.org:/home/eclipse,,org.eclipse.platform-feature<BR><BR></LI><LI>The 81 org.eclipse.gef.sdk feature source is located in directory in the <A HREF="http://dev.eclipse.org/viewcvs/?cvsroot=Tools_Project" target="extra">dev.eclipse.org:/home/tools</A> 82 repository in a subdirectory called "org.eclipse.gef.sdk" of "org.eclipse-gef 83 feature". The resulting map file entry for this feature is:<BR><BR>feature (a] org.eclipse.gef.sdk=I_20031117, 84 :pserver:anonymous (a] dev.eclipse.org:/home/tools,,org.eclipse.gef-feature/org.eclipse.gef.sdk<BR></LI></UL><P>One 85 or more map files can be used to list the elements. The map files can be kept 86 under version control. Some examples of map file projects include <A target="extra" HREF="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.releng/">org.eclipse.releng</A>, 87 <A target="extra" HREF="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.gef.releng/?cvsroot=Tools_Project">org.eclipse.gef.releng</A>, 88 <A target="extra" HREF="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.ve.releng/?cvsroot=Tools_Project">org.eclipse.ve.releng</A>.<BR> 89 <BR></P><P><B><FONT SIZE="+1"><A NAME="gensource"></A>Generating source features 90 and plug-ins at build time</FONT></B></P><P>Source features and plug-ins can be 91 generated at build time by PDE Build. Source features and associated source plug-ins 92 are typically generated for a development kit distributions (i.e. SDK). It is 93 also possible to generate a source plug-in only. This is typically the case for 94 example features or JUnit testing features.<BR> <BR>To generate a <B>source feature 95 and associated source plug-in</B> at build time, you will need to do the following:</P><OL> 96 <LI> Add an entry to the build.properties file in the feature project for which 97 you wish to include the source feature and plug-in. The generated source feature 98 should also be listed in the feature.xml as an <includes> element.<BR> <BR> 99 The build.properties entry should use the following format:<BR> <BR> generate.feature@<source.feature.id 100 to generate>=<feature.id from which to which to collect source>, plugin@<plugin.id><BR> 101 <BR> Example taken from <A target="extra" HREF="http://dev.eclipse.org/viewcvs/index.cgi/%7Echeckout%7E/org.eclipse.sdk-feature/build.properties?rev=1.4">org.eclipse.sdk-feature/build.properties</A>: 102 <BR> generate.feature (a] org.eclipse.jdt.source=org.eclipse.jdt, 103 plugin (a] org.eclipse.jdt.doc.isv<BR> <BR> In this example, a source feature and 104 a plug-in, both with id "org.eclipse.jdt.source" will be generated and 105 will contain source from plug-ins listed in the org.eclipse.jdt feature and will 106 also include the plug-in org.eclipse.jdt.doc.isv. The generated org.eclipse.jdt.source 107 plug-in will be automatically listed in the org.eclipse.jdt.source feature.xml. 108 <BR> <BR> <BR> </LI><LI>In the feature project from which the source feature will 109 be generated, a directory called "<B>sourceTemplateFeature</B>" and 110 a directory called "<B>sourceTemplatePlugin</B>" will be required. These 111 directories should contain the files that are included in the root of the generated 112 source feature and plug-in. The feature.xml and plugin.xml files are not required 113 since these are generated. A build.properties is required in the sourceTemplatePlugin 114 directory. This should contain a "bin.includes" setting as well as the 115 entry "sourcePlugin = true". The plugin.xml file and src/ directory 116 should be listed in the bin.includes.<BR> <BR> See <A target="extra" HREF="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.jdt-feature/">org.eclipse.jdt-feature</A> 117 and <A target="extra" HREF="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.platform-feature/">org.eclipse.platform-feature</A> 118 for examples.<BR> <BR> </LI></OL><P>To generate a <B>source plug-in only</B> at 119 build time, you will need to do the following:</P><OL> <LI> Add an entry to the 120 build.properties file in the feature project for which you wish to include the 121 source plug-in. The generated source plug-in should also be listed in the feature.xml 122 as a <plugin> element.. <BR> <BR> The build.properties entry should use 123 the following format:<BR> <BR> generate.plugin@<source.plugin.id to generate>=<feature.id 124 from which to which to collect source>, plugin@<plugin.id><BR> <BR> Example 125 taken from <A target="extra" HREF="http://dev.eclipse.org/viewcvs/index.cgi/%7Echeckout%7E/org.eclipse.ve.tests-feature/build.properties?rev=1.2&cvsroot=Tools_Project">org.eclipse.ve.tests-feature/build.properties</A>: 126 <BR> generate.plugin (a] org.eclipse.ve.tests.source=org.eclipse.ve.tests<BR> 127 <BR> <BR> </LI><LI>In the runtime feature project from which the source plug-in 128 will be generated, create a directory called "sourceTemplatePlugin" 129 which must contain a build.properties with a "bin.includes" setting 130 and "sourcePlugin=true". The plugin.xml file and src/ directory should 131 be listed in the bin.includes.<BR> <BR> See <A target="extra" HREF="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.ve.examples-feature/sourceTemplatePlugin/?cvsroot=Tools_Project">org.eclipse.ve.examples-feature/sourceTemplatePlugin</A> 132 for an example.<BR> </LI></OL><HR><P><FONT SIZE="+2"><A NAME="buildconfigfiles"></A><B>Preparing 133 Build Configuration Files</B></FONT></P><P>The distilled build process consists 134 of the following four steps:</P><OL><LI>build environment setup</LI><LI>check 135 out source from one or more CVS repositories</LI><LI>compilation</LI><LI> assembly 136 of distribution<BR></LI></OL><P>The script which controls the build sequence is 137 the build.xml Ant script in org.eclipse.pde.build. However this script requires 138 two user-implemented build configuration files,<A target="extra" HREF="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.pde.build/templates/build.properties?rev=HEAD&content-type=text/vnd.viewcvs-markup">build.properties</A> 139 and <A target="extra" HREF="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.pde.build/templates/customTargets.xml?rev=HEAD&content-type=text/vnd.viewcvs-markup">customTargets.xml</A>. 140 These two files provide the information on the "where and how" to build 141 specific elements. </P><P>Templates of these files are provided in the <A target="extra" HREF="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.pde.build/templates/">org.eclipse.pde.build/templates</A> 142 directory and examples are available in <A target="extra" HREF="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.releng.eclipsebuilder/">org.eclipse.releng.eclipsebuilder</A>, 143 <A target="extra" HREF="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.releng.gefbuilder/?cvsroot=Tools_Project">org.eclipse.releng.gefbuilder</A> 144 and <A target="extra" HREF="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.ve.releng.builder/?cvsroot=Tools_Project">org.eclipse.ve.releng.builder</A> 145 for building Eclipse, GEF and VE runtimes, respectively.</P><P><B><FONT SIZE="+1"><A NAME="build.properties"></A>build.properties</FONT></B></P><P>The 146 build.properties file defines a number of properties that are used as Ant properties 147 at build time and as arguments to script generators in org.eclipse.pde.build to 148 describe how and where to execute the build. The values for properties listed 149 in this file override any values set in the generated build.xml files. See "Generating 150 Ant scripts from the command line" in the PDE Guide in Eclipse 3.2 stream 151 Help for a description of required and optional properties.</P><P><B><FONT SIZE="+1"><A NAME="customTargets.xml"></A>customTargets.xml</FONT></B></P><P>customTargets.xml 152 is an Ant script containing targets called by PDE Build scripts to provide the 153 following information:</P><OL><LI>the list of elements for which to generate scripts</LI><LI>instruction 154 on retrieval of map file projects</LI><LI>steps to execute before and after the 155 following: retrieving map files, checking out source, generating build.xml scripts, 156 executing build.xml scripts, and assembling the binary distributions.</LI><LI>instruction 157 on things to do after the build is done.</LI></OL><P>The table below lists the 158 targets that are used to provide this information.<BR><BR></P><TABLE WIDTH="100%" BORDER="1"><TR><TD WIDTH="24%">Target</TD><TD WIDTH="76%">Description</TD></TR><TR><TD WIDTH="24%">allElements</TD><TD WIDTH="76%"><P>This 159 target lists all features that will be packaged into a binary distribution where 160 each listing comes in the form of an <ant> call to org.eclipse.pde.build/scripts/genericTargets.xml:<BR><BR><B><ant 161 antfile="${genericTargets}" target="${target}" ><BR> <property 162 name="type" value="feature" /><BR> <property 163 name="id" value="<element.id>" /><BR> </ant><BR></B><BR> 164 The user is only required to specify a value for properties "type" and 165 id (the value for the id attribute in the feature.xml) for each listing. At this 166 time, only the type "feature" is supported.<BR></P><P>Example from <A target="extra" HREF="http://dev.eclipse.org/viewcvs/index.cgi/%7Echeckout%7E/org.eclipse.releng.eclipsebuilder/jdt/customTargets.xml?rev=HEAD&content-type=text/xml">org.eclipse.releng.eclipsebuilder/jdt/customTargets.xml</A>:</P><P><B><target 167 name="allElements"><BR> <ant antfile="${genericTargets}" 168 target="${target}" ><BR> <property 169 name="type" value="feature" /><BR> <property 170 name="id" value="org.eclipse.jdt" /><BR> </ant><BR></target></B></P><P>The 171 <A target="extra" HREF="http://dev.eclipse.org/viewcvs/index.cgi/%7Echeckout%7E/org.eclipse.pde.build/scripts/genericTargets.xml?rev=HEAD&content-type=text/xml">genericTargets.xml 172 </A>script is an Ant script in the org.eclipse.pde.build plug-in containing targets 173 which call PDE Build custom Ant tasks to generate scripts for the specified elements 174 at various stages of the build. This script also executes the generated scripts 175 at various build stages. The target property is set by it's calling script, org.eclipse.pde.build/scripts/build.xml.<BR><BR>For 176 example, the fetch target in the build.xml calls allElements and sets the target 177 to property to "fetchElement":<BR><BR> <ant antfile="${customTargets}" 178 target="allElements"><BR> <property 179 name="target" value="fetchElement" /><BR> </ant><BR><BR>The 180 result of this is that the fetchElement target in genericTargets.xml is executed 181 using arguments type and id set in allElements.<BR></P></TD></TR><TR><TD WIDTH="24%">assemble.<element.id>[.config.spec]</TD><TD WIDTH="76%"><P>For 182 every configuration specified in the build.properties for the distribution (see 183 <A HREF="#configs">configs</A> above), a target named "assemble.<element.id>.<config.spec>" 184 is required. If the distribution is not platform-specific, the ".<config.spec>" 185 section of the target name is not required. </P><P>Providing the target name should 186 be all that is required unless you wish to give the produced binary distributable 187 file a name different from the default "<elment-id>-<buildid>-<config.spec>.zip". 188 In this case, an explicit value for the property "archiveName" should 189 be specified at the beginning of the target.<BR><BR>Example from <A target="extra" HREF="http://dev.eclipse.org/viewcvs/index.cgi/%7Echeckout%7E/org.eclipse.releng.eclipsebuilder/jdt/customTargets.xml?rev=HEAD&content-type=text/xml">org.eclipse.releng.eclipsebuilder/jdt/customTargets.xml</A>:<BR><BR> 190 Since two configurations for building the org.eclipse.jdt distribution are specified 191 in it's build.properties "configs=*,*,* & macosx,carbon,ppc", the 192 following two targets are provided in the customTargets.xml script.</P><P><FONT COLOR="#000000"><B><target 193 name="assemble.org.eclipse.jdt"><BR> <property 194 name="archiveName" value="eclipse-JDT-${buildId}.zip"/><BR> 195 <ant antfile="${assembleScriptName}"/><BR></target></B></FONT></P><P><B><FONT COLOR="#000000"><target 196 name="assemble.org.eclipse.jdt.macosx.carbon.ppc"><BR> <property 197 name="archiveName" value="eclipse-JDT-${buildId}-macosx-carbon.tar.gz"/><BR> 198 <ant antfile="${assembleScriptName}"/><BR></target></FONT></B><BR></P></TD></TR><TR><TD WIDTH="24%"><A NAME="getmaps"></A>getMapFiles</TD><TD WIDTH="76%"><P>The 199 result of executing this target should be to place *.map files in any directory 200 or subdirectory under ${buildDirectory}/maps. All .map files found here are concatenated 201 into a single file ${buildDirectory}/directory.txt. Map file projects are typically 202 kept under version control in a CVS repository. <BR><BR>In the following example 203 from <A target="extra" HREF="http://dev.eclipse.org/viewcvs/index.cgi/%7Echeckout%7E/org.eclipse.releng.eclipsebuilder/sdk/customTargets.xml?rev=HEAD&content-type=text/xml">org.eclipse.releng.eclipsebuilder/sdk/customTargets.xml</A>, 204 the implementation of this target and it's helper targets are provided to illustrate 205 how map files for Eclipse builds are checked out from a CVS repository and then 206 tagged with the build timestamp to capture the versions of all projects used in 207 the build.<BR><BR><B><target name="getMapFiles" depends="checkLocal" 208 unless="mapsLocal"><BR> <property 209 name="mapCvsRoot" value=":pserver:anonymous (a] dev.eclipse.org:/home/eclipse" 210 /><BR> <property name="mapVersionTag" 211 value="HEAD" /><BR> <cvs cvsRoot="${mapCvsRoot}"<BR> 212 package="org.eclipse.releng"<BR> 213 dest="${buildDirectory}/maps"<BR> 214 tag="${mapVersionTag}"<BR> 215 /><BR> <antcall target="tagMapFiles" 216 /><BR></target></B></P><P><B><FONT COLOR="#008000"><!--helper targets---></FONT><BR></B><B><BR><target 217 name="checkLocal"><BR> <available 218 property="mapsLocal" file="${buildDirectory}/maps/org.eclipse.releng" 219 /><BR></target><BR></B></P><P><B><target name="tagMapFiles" 220 if="tagMaps"><BR> <cvs dest="${buildDirectory}/maps/org.eclipse.releng" 221 command="tag v${timestamp}" /><BR></target></B><BR><BR></P></TD></TR><TR><TD WIDTH="24%" HEIGHT="24">preSetup 222 and postSetup</TD><TD WIDTH="76%" HEIGHT="24"><P>Used to run operations before 223 and after retrieving the map files.<BR><BR>Example from <A target="extra" HREF="http://dev.eclipse.org/viewcvs/index.cgi/%7Echeckout%7E/org.eclipse.releng.gefbuilder/sdk/customTargets.xml?rev=HEAD&content-type=text/xml&cvsroot=Tools_Project">org.eclipse.releng.gefbuilder/sdk</A>. 224 This example demonstrates how the postSetup target (and a helper target) is used 225 to download and install an Eclipse SDK to compile against.</P><P><B><target 226 name="postSetup"><BR> <available 227 file="${buildDirectory}/../eclipse-SDK.zip" property="baseExists" 228 /> <BR> <antcall target="getBaseEclipse" 229 /> <BR> </target><BR></B></P><P><B><target name="getBaseEclipse" 230 unless="baseExists"></B></P><P><B><FONT COLOR="#008000"> <!--this 231 task definition is available in org.eclipse.releng.basebuilder/plugins/org.eclipse.build.tools. 232 It removes the _ <version> 233 from all directories specified as a value for the directory attribute. </FONT></B><FONT COLOR="#008000"><B>Not 234 really necessary, but helpful in this 235 case to avoid having/needing hard-coded versions in GEF javadoc scripts.--></B></FONT><B></B><B><BR></B><B> <taskdef 236 name="stripVersions" classname="org.eclipse.releng.VersionNumberStripper" 237 /> <BR> <BR><FONT COLOR="#008000"> <!--this 238 property file contains the values for ${eclipseURL} and ${eclipseBuildID}--></FONT><BR> <property 239 file="${buildDirectory}/maps/org.eclipse.gef.releng/maps/build.cfg" 240 /> <BR> <get src="${eclipseURL}/eclipse-SDK-${eclipseBuildID}-win32.zip" 241 dest="${buildDirectory}/../eclipse-SDK.zip" /> <BR> <exec 242 dir="${buildDirectory}/.." executable="unzip"><BR> <arg 243 line="-o -qq eclipse-SDK.zip" /> <BR> </exec><BR> 244 <BR> <stripVersions 245 directory="${buildDirectory}/plugins" /> <BR><BR><FONT COLOR="#008000"> <!-- 246 Extract doc.zip so we can create links in GEF java doc --> </FONT><BR> <exec 247 dir="${buildDirectory}/plugins/org.eclipse.platform.doc.isv" executable="unzip"><BR> 248 <arg line="-o 249 -qq doc.zip" /> <BR> </exec><BR> </target></B><BR><BR></P></TD></TR><TR><TD WIDTH="24%">preFetch 250 and postFetch </TD><TD WIDTH="76%"><P>Used to run operations before and after 251 fetching source for the build.<BR></P><P>Example from <A target="extra" HREF="http://dev.eclipse.org/viewcvs/index.cgi/%7Echeckout%7E/org.eclipse.releng.gefbuilder/sdk/customTargets.xml?rev=HEAD&content-type=text/xml&cvsroot=Tools_Project">org.eclipse.releng.gefbuilder/sdk</A>. 252 This example demonstrates how the postFetch target can be used to set the build 253 timestamp as a value for "0" in about.mappings files.<BR><BR><B><target 254 name="postFetch"><BR> <replace dir="${buildDirectory}/plugins" 255 value="${timestamp}" token="@buildid@"><BR> <include 256 name="**/about.mappings" /> <BR> </replace><BR> 257 </target></B></P></TD></TR><TR><TD WIDTH="24%">preGenerate and postGenerate</TD><TD WIDTH="76%"><P>Used 258 to run operations before and after generating build.xml files for features, plug-ins 259 and fragments.<BR><BR>Example from <A target="extra" HREF="http://dev.eclipse.org/viewcvs/index.cgi/%7Echeckout%7E/org.eclipse.releng.gefbuilder/sdk/customTargets.xml?rev=HEAD&content-type=text/xml&cvsroot=Tools_Project">org.eclipse.releng.gefbuilder/sdk</A>. 260 This example demonstrates how the postGenerate target (and a helper target) is 261 used to run the build.xml scripts to clean the source of any stale, pre-compiled 262 jars that might exist in the source directories. jars are not recompiled if they 263 already exist in plug-in or fragment directories.<BR></P><P> <B><target name="postGenerate"><BR> 264 <antcall target="clean" /> <BR> 265 </target></B></P><P><B><target name="clean" unless="noclean"><BR> <antcall 266 target="allElements"><BR> <param 267 name="target" value="cleanElement" /> <BR> </antcall><BR> 268 </target><BR></B></P></TD></TR><TR><TD WIDTH="24%">preProcess and postProcess</TD><TD WIDTH="76%"> 269 Used to run operations before and after compiling the source.</TD></TR><TR><TD WIDTH="24%">preAssemble 270 and postAssemble</TD><TD WIDTH="76%">Used to run operations before and after assembling 271 the binary distributables.</TD></TR><TR><TD WIDTH="24%">postBuild</TD><TD WIDTH="76%"><P>Used 272 to run operations at the end of the build.<BR></P><P>Example from <A target="extra" HREF="http://dev.eclipse.org/viewcvs/index.cgi/%7Echeckout%7E/org.eclipse.releng.gefbuilder/sdk/customTargets.xml?rev=HEAD&content-type=text/xml&cvsroot=Tools_Project">org.eclipse.releng.gefbuilder/sdk</A>. 273 This example demonstrates how the postBuild target (and a helper target) is used 274 to gather and place the compile logs in the ${buildLabel} directory. These files 275 are used in the publishing of the GEF build (see below under Publishing the Build 276 section).<BR></P><P><B><target name="postBuild"><BR> <antcall 277 target="gatherLogs" /> <BR> </target><BR><BR><target name="gatherLogs"><BR> 278 <mkdir dir="${buildDirectory}/${buildLabel}/compilelogs" 279 /> <BR> <antcall 280 target="allElements"><BR> <param 281 name="target" value="gatherLogs" /> <BR> </antcall><BR> <unzip 282 dest="${buildDirectory}/${buildLabel}/compilelogs" overwrite="true"><BR> <fileset 283 dir="${buildDirectory}/features/org.eclipse.gef.sdk"><BR> <include 284 name="*.log.zip" /> <BR> </fileset><BR> 285 </unzip><BR> </target></B><BR><BR></P></TD></TR></TABLE><P> </P><HR><P><BR><FONT SIZE="+2"><B><A NAME="buildexec"></A>Build 286 Execution </B></FONT></P><P><FONT SIZE="+1"><A NAME="buildmachinesetup"></A><B>Build 287 machine setup</B></FONT><BR><BR>This build process can be executed on any of the 288 <A target="extra" HREF="http://www.eclipse.org/eclipse/development/eclipse_project_plan_3_2.html#TargetOperatingEnvironments">Eclipse 289 3.2 Reference Platforms</A> plus the following:</P><UL><LI><A target="extra" HREF="http://www.cvshome.org/">CVS</A> 290 client version 1.10 or higher on system path. </LI><LI><A target="extra" HREF="http://www.info-zip.org/pub/infozip/">Info-Zip</A> 291 zip and unzip executables on system path.</LI><LI><A target="extra" HREF="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.releng.basebuilder/">org.eclipse.releng.basebuilder</A> 292 from dev.eclipse.org or any Eclipse 3.2 stream SDK install. Please note that the 293 Mailer java class in this project require a j2ee.jar on the classpath to compile 294 and run. This class is not used in the mechanism described in this document.</LI></UL><P>The 295 cvs, zip and unzip executables should be placed on the system path.</P><P> On 296 Windows systems, the HOME environement variable should be set to "c:" 297 (no slash) for CVS operations.</P><P>The org.eclipse.releng.basebuilder project 298 can be placed in any directory.</P><P><BR><B><FONT SIZE="+1"><A NAME="runbuild"></A>Running 299 the Build</FONT></B></P><P>To run the build, execute the following command from 300 ../plugins/org.eclipse.pde.build/scripts to <B>build a single distribution</B>:<BR><BR><B>java 301 -jar <path>/startup.jar -application org.eclipse.ant.core.antRunner [-buildfile 302 build.xml] -Dbuilder=<path to directory containing build.properties and customTargets.xml> 303 [Ant property settings to override those in <A HREF="#build.properties" TARGET="_blank">build.properties</A>]</B><B><BR></B></P><P> </P> 304 </BODY> 305 </HTML> 306
