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