| <!doctype html public "-//w3c//dtd html 4.0 transitional//en"> |
| <html> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> |
| <link rel="stylesheet" href="http://dev.eclipse.org/default_style.css" type="text/css"> |
| <title>Download</title> |
| <style type="text/css"> |
| <!-- |
| .style1 { |
| font-size: 12px; |
| font-weight: bold; |
| } |
| --> |
| </style> |
| </head> |
| |
| <body> |
| <table BORDER=0 CELLSPACING=5 CELLPADDING=2 WIDTH="100%" ><tr><td ALIGN=LEFT width="80%"> |
| <p><b><font face="Verdana" size="+3">WTP Builds</font></b><br> |
| Last Updated: October 20, 2004</p> |
| <p>This document describes the build policy and how to build WTP components from |
| the command line using Ant scripts.</p> |
| <p><b>Table |
| of Contents</b><br> |
| <br> |
| <a href="#policy">Build Policy</a><br> |
| <a href="#tools">Tools</a><br> |
| <a href="#setup">Setup</a><br> |
| <a href="#build">Run the Build</a><br> |
| <a href="#antbuildproperties">Ant |
| properties defined build.properties</a><br> |
| <a href="#infra">Build Infrastructure</a><br> |
| <a href="#cvs">CVS Structure</a><br> |
| <a href="#mapfile">Map File</a><br> |
| <A href="gensource">Generating source features and plug-ins at build time</a><br> |
| <a href="#team">Release Team</a><br> |
| <br> |
| </p></td></tr> |
| </table> |
| |
| |
| <table border=0 cellspacing=5 cellpadding=2 width="100%" ><tr> |
| <td align=LEFT valign=TOP colspan="3" bgcolor="#0080C0"> <b><font face="Arial,Helvetica" color="#FFFFFF"><a name="policy"></a>Build |
| Policy</font></b></td> |
| </tr> |
| <TR><TD align="LEFT" valign="TOP" colspan="3"> |
| |
| <P>The process described here is modeled after other eclipse build processes, |
| and borrows general principles from other sources, some of which are described |
| in detail by the document http://www.martinfowler.com/articles/continuousIntegration.html.</P> |
| <strong>General principles:</strong><ol><li><strong>Automatic and continuos: </strong>A build must be a fully automated and reproducible, |
| must include quality assurance (i.e. testing), and must be able to run as often |
| as possible. Automatic build processes are more reliable and higher quality |
| than manually and ensure that most obvious errors during a build. It is less |
| risky, it is independent of a human builder, it is repeatable and communicable. |
| It is typically faster than a manual build. Finally it allows for built-in |
| QA process by integration tests and post-processing such as potentially running |
| metrics on the code. A build must be a fully automated and reproducible, must |
| include quality assurance (i.e. testing), and must be able to run as often |
| as possible.that runs many times a day. |
| |
| This imposes some constraints: |
| Storage - CVS Provides a common place where all code lives and anyone can obtain |
| the current sources from. |
| Scripting: Use a single command to build the system from the sources. An automated |
| build process and scripting suitable for eclipse projects is described in http://dev.eclipse.org/viewcvs/index.cgi/~checkout~/org.eclipse.releng.basebuilder/readme.html?rev=1.21&content-type=text/plain. |
| We should follow similar principles as they have already build the tools and |
| the scripts to automate eclipse builds. Testing: Automate the testing so that |
| you can run a good suite of tests on the system at any time with a single command. |
| |
| |
| A frequency of minimum one build a day seems often enough for geographically |
| and logistically challenging projects such as WTP. It is also important to |
| describe what will happen when a build fails. Typically, it is assumed that |
| sending an email will suffice as an action. This is not so. A build must succeed!</li> |
| <li><strong>A build must succeed, it should not be an attempt.</strong> A build |
| is a success if: |
| <ul> |
| <li>All the sources are checked out of the configuration management system |
| as described by the .map (not necessarily the latest) files. Every file |
| is compiled |
| from |
| scratch |
| The resulting object files (Java classes in our case) and linked and |
| deployed for execution (put into jars). </li> |
| <li>The system is started and suite |
| of tests |
| (JUnit and PDE JUnits Tests) is run against the system. |
| If all of these steps execute without error or human intervention and |
| every test passes, then we have a successful build</li> |
| <li>It is expected that |
| all "smooth" builds can be managed this way. The |
| problem is when things go wrong. WTP release engineering team intervenes |
| with the process for managing build errors! </li> |
| </ul> |
| </li> |
| <li><strong>Build Management:</strong> An automated build provides the most |
| return when it can produce a master build with as little human intervention |
| as possible. Although |
| there are arguments that there should be a human in the loop for a build, it |
| should not be the act of producing a build. Build automation makes a lot of |
| sense |
| for individual developers, they can test a build before it is "checked in" to |
| CVS. But the most critical activity of human intervention is to facilitate |
| a procedure to bring the team together in resolving integration and build problems. |
| WTP is a geographically and logistically challenging so (put the team together |
| to fix problems). Build manager is responsible for the builds/infrastructure |
| (scripts and environment) so a build can run. S/he facilitates to bring the |
| teams/people together to fix build |
| errors |
| (sending |
| automated emails from scripts is not sufficient). |
| Make sure that when there are problems, there is a process describing |
| every stage to fix it, work out what went wrong when the process fails. |
| Make sure |
| the mind |
| of the process captured in automated script code, rather than people's |
| head so that it can be dealt with minimal interaction the next time. Manage |
| major |
| builds |
| and release process (For major integration builds (milestones), release |
| candidates and releases.</li> |
| <li><strong>Keeping in sync: </strong>With an automated build we should integrate regularly |
| (once a week perhaps - with an integration build). For an integration build |
| to be meaningful, there must be a critical mass of code checked-in. Being able to run the master |
| build locally will also give developers a chance to minimize build errors and |
| they will have to do less at integration time. |
| </td></tr></table> |
| |
| <table border=0 cellspacing=5 cellpadding=2 width="100%" ><tr> |
| <td align=LEFT valign=TOP colspan="3" bgcolor="#999999"> |
| <b><font face="Arial,Helvetica" color="#FFFFFF"> |
| <a name="tools"></a>Tools used to manage the build process</font></b></td> |
| </tr> |
| |
| <TR><TD align="LEFT" valign="TOP" colspan="3"> |
| <p>1. <a href="http://www.cvshome.org/">CVS</a> version 1.10 or higher.<br> |
| 2. <a href="http://java.sun.com/j2se/1.4/download.html">1.4 level JDK</a>.<br> |
| 3. <a href="http://www.info-zip.org/pub/infozip/">Info-Zip |
| zip and unzip</a><br> |
| 4. org.eclipse.releng.basebuilder |
| and org.eclipse.releng.eclipsebuilder from <a href="http://dev.eclipse.org/viewcvs/">dev.eclipse.org</a>.<br> |
| 5. Ant optional tasks (ftp) This task depends on external libraries not included |
| in the Ant distribution. See ant <a href="http://ant.apache.org/manual/install.html#commons-net">library |
| dependencies</a> for ftp, rexec and telnet tasks<br> |
| for |
| more information.</p> |
| <p>For more information on eclipse release engineering tool, refer to the <a href="http://dev.eclipse.org/viewcvs/index.cgi/~checkout~/org.eclipse.pde.build/notes/usingPDEBuild.html">plugin</a> |
| itself.</p> |
| <p>For examples, refer to the <a href="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.releng.eclipsebuilder/">org.eclips.releng.eclipsebuilder</a> |
| itself. <a href="https://dev.eclipse.org/viewcvs/index.cgi/~checkout~/org.eclipse.releng.eclipsebuilder/readme.html">Readme</a></p></TD> |
| </TR></table> |
| |
| <table border=0 cellspacing=5 cellpadding=2 width="100%" ><tr> |
| <td align=LEFT valign=TOP colspan="3" bgcolor="#999999"> |
| <b><font face="Arial,Helvetica" color="#FFFFFF"> |
| <a name="setup"></a>Setup</font></b></td> |
| </tr> |
| |
| <TR><TD align="LEFT" valign="TOP" colspan="3"> |
| <p> |
| <ol><li>Add the zip, unzip, and cvs executables to your PATH environment variable.</li> |
| |
| <li>Add the jre/bin directory of the installed JDK to your PATH environment variable.</li> |
| |
| <li>Add the ant/bin directory of the installed Ant to your PATH environment variable.</li> |
| |
| <li>Create a directory for the build, e.g. |
| <ul><li><code><pre>mkdir /tmp/wtpbuild</pre></code></li></ul> |
| </li> |
| |
| <li>Install the eclipse builder (this installation will be used to run the build tools, |
| it is not itself a WebTools installation): Check out <b>org.eclipse.releng.basebuilder</b> and |
| <b>org.eclipse.releng.basebuilder</b> from the CVS repository <b>/home/eclipse</b> (note: |
| <b>not</b> /home/webtools) into the build directory, e.g. |
| <ul><li><code><pre>cd /tmp/wtpbuild |
| cvs -d :pserver:anonymous@dev.eclipse.org:/home/eclipse co org.eclipse.releng.basebuilder |
| cvs -d :pserver:anonymous@dev.eclipse.org:/home/eclipse co org.eclipse.releng.eclipsebuilder |
| </pre></code></li></ul> |
| </li> |
| |
| <li>Checkout org.eclipse.wtp.releng into the build directory. |
| <ul><li><code><pre>cvs -d :pserver:anonymous@dev.eclipse.org:/home/webtools co org.eclipse.wtp.releng</pre></code></li></ul> |
| </li></p> |
| |
| <li>You have also to adjust some build properties in the org.eclipse.wtp.releng/buildAll.properties (see below).</li> |
| </TD> |
| </TR></table> |
| |
| |
| <table border=0 cellspacing=5 cellpadding=2 width="100%" ><tr> |
| <td align=LEFT valign=TOP colspan="3" bgcolor="#999999"> |
| <b><font face="Arial,Helvetica" color="#FFFFFF"> |
| <a name="build"></a>Run the Build</font></b></td> |
| </tr> |
| |
| <TR><TD align="LEFT" valign="TOP" colspan="3"> |
| <p> |
| <b>Run |
| the Build</b></p> |
| <p> cd to org.eclipse.wtp.releng directory and execute the following |
| command. Alternatively, you can checkout the module org.eclipse.wtp.releng |
| in an eclipse workspace and use the ant run tools.</p> |
| <p>"ant -f cruise.xml" </p> |
| <p>There are three ant targets in cruise.xml (an ant build file): build, publish</p> |
| <p> </p> |
| <table width="75%" border="1"> |
| <tr> |
| <td width="20%">Ant Target</td> |
| <td width="80%">Description</td> |
| </tr> |
| <tr> |
| <td width="20%">all</td> |
| <td width="80%">Default. Builds WTP from scratch (all plugins and features), |
| runs tests, and publishes to a ftp site. For ftp push two propserties |
| ftpUser and ftpPassowrd must be defined. </td> |
| </tr> |
| <tr> |
| <td width="20%">build</td> |
| <td width="80%">Builds WTP from scratch (all plugins and features), does |
| not run tests, and does not publish to a ftp site.</td> |
| </tr> |
| <tr> |
| <td width="20%">publish</td> |
| <td width="80%">Must have run all, or build with no "clean" option prior |
| to running this task. It creates drop files and uploads them to an ftp |
| site. For ftp push two propserties |
| ftpUser and ftpPassowrd must be defined. </td> |
| </tr> |
| </table> |
| <p></p> |
| <p>[Ant properties to override |
| in <a href="#antbuildproperties">buildAll.properties</a>] ". |
| To override a property you must use a syntax like "ant -f cruise.xml |
| -Dclean=true"</p> |
| <p><b><br> |
| </b></p></TD> |
| </TR></table> |
| |
| |
| <table border=0 cellspacing=5 cellpadding=2 width="100%" ><tr> |
| <td align=LEFT valign=TOP colspan="3" bgcolor="#999999"> |
| <b><font face="Arial,Helvetica" color="#FFFFFF"> |
| <a name="antbuildproperties"></a>Ant Properties Settings in buildAll.properties</font></b></td> |
| </tr> |
| |
| <TR><TD align="LEFT" valign="TOP" colspan="3"> |
| <p>The following properties are pre-defined in the <a href="http://dev.eclipse.org/viewcvs/indexwebtools.cgi/~checkout~/org.eclipse.wtp.releng/buildAll.properties">buildAll.properties</a> file |
| for the build. They can be overridden by setting them at the |
| command line at build time or by changing them directly in the component's |
| build.properties file.</p> |
| <table width="100%" border="1"> |
| <tr> |
| <td>Name</td> |
| <td>Description</td> |
| </tr> |
| <tr> |
| <td height="26">baseLocation</td> |
| <td height="26"><p>A directory separate from buildDirectory which contains |
| pre-built plugins and features against which to compile. The basedirectory |
| must not contain any features, plugins or fragments which are already |
| or will be located in the buildDirectory (see below).</p> |
| <p>Build script unzips previosly downloaded eclipse, plugisn and features |
| to use for the build. This configuration is maintained in <a href="http://dev.eclipse.org/viewcvs/indexwebtools.cgi/~checkout~/org.eclipse.wtp.releng/maps/build.cfg">build.cfg</a>.</p></td> |
| </tr> |
| <tr> |
| <td >baseLocationRoot</td> |
| <td >A directory that hosts the current built. baseLocation |
| be created under this folder. |
| </td> |
| </tr> |
| <tr> |
| <td>localDownloads</td> |
| <td>A directory that contains pre-downloaded zip files |
| defined in the <a href="http://dev.eclipse.org/viewcvs/indexwebtools.cgi/~checkout~/org.eclipse.wtp.releng/maps/build.cfg">build configuration</a>. </td> |
| </tr> |
| <tr> |
| <td>bootclasspath</td> |
| <td>Sets the value for the attribute "bootclasspath" in calls |
| to the <a href="http://ant.apache.org/manual/CoreTasks/javac.html">Ant <javac> task</a> in |
| a plugins' build.xml. Default set to ${java.home}/lib/rt.jar.</td> |
| </tr> |
| <tr> |
| <td height="36">buildDirectory</td> |
| <td height="36">The absolute path to a working directory where the source |
| for the build will be exported, where scripts will be generated and where |
| the end products of the build will be located. On Windows systems, the |
| path length should not exceed thirty characters due to path length limitations |
| when compiling some classes in eclipse.</td> |
| </tr> |
| <tr> |
| <td>buildId</td> |
| <td>The build name. Default set to "build".</td> |
| </tr> |
| <tr> |
| <td>buildLabel</td> |
| <td>Refers to the name of the directory which will contain the end result |
| of the build. Default set to ${buildType}.${buildId}, ie."I.build". |
| This directory will be created inside the location specified by the ${buildDirectory} |
| property.</td> |
| </tr> |
| <tr> |
| <td>buildType</td> |
| <td> |
| <p>Letters I, N, S, R or M are used in Eclipse builds to identify builds |
| as being one of the following:<br> |
| <br> |
| I - Integration<br> |
| N - Nightly<br> |
| S - Stable<br> |
| R - Release<br> |
| M - Maintenance<br> |
| </p> |
| <p> If set to N, all source will be checked out from the HEAD stream. |
| In all other cases, tags as specifed in map files will be used when |
| exporting plugins to the buildDirectory. </p> |
| </td> |
| </tr> |
| <tr> |
| <td>archivePrefix</td> |
| <td>The name of the top level directory which should exist in the produced |
| zip file. Typically set to "eclipse".</td> |
| </tr> |
| <tr> |
| <td> collectingFolder</td> |
| <td>The name of the top level directory where the built features and plugins |
| will be gathered. This is typically set to "eclipse".</td> |
| </tr> |
| <tr> |
| <td>configs</td> |
| <td> |
| <p>An ampersand separated list of configurations to build where a configuration |
| is specified as <os>,<ws>,<arch>.<br> |
| ie.configs="win32,win32,x86 & linux, motif, x86 & linux, |
| gtk, x86". See list of <a href="#buildconfigs">build configurations</a> below.</p> |
| </td> |
| </tr> |
| <tr> |
| <td>javacDebugInfo</td> |
| <td>Sets the value for the attribute "debug" in calls to the <a href="http://ant.apache.org/manual/CoreTasks/javac.html">Ant <javac> task </a>in |
| a plugins' build.xml. Default set to on.</td> |
| </tr> |
| <tr> |
| <td>javacFailOnError</td> |
| <td>Sets the value for the attribute "failonerror" in calls to |
| the <a href="http://ant.apache.org/manual/CoreTasks/javac.html">Ant <javac> task</a> in |
| a plugins' build.xml. Build will continue even if there are compilation |
| errors when this is set to false.</td> |
| </tr> |
| <tr> |
| <td>javacSource</td> |
| <td>Sets the value for the attribute "source" in calls to the <a href="http://ant.apache.org/manual/CoreTasks/javac.html">Ant <javac> task</a> in |
| a plugins' build.xml. Default set to 1.3.</td> |
| </tr> |
| <tr> |
| <td>javacTarget</td> |
| <td>Sets the value for the attribute "target" in calls to the <a href="http://ant.apache.org/manual/CoreTasks/javac.html">Ant <javac> task</a> in |
| a plugins' build.xml. Default set to 1.1.</td> |
| </tr> |
| <tr> |
| <td>javacVerbose</td> |
| <td>Sets the value for the attribute "verbose" in calls to the <a href="http://ant.apache.org/manual/CoreTasks/javac.html">Ant <javac> task</a> in |
| a plugins' build.xml. Default set to true.</td> |
| </tr> |
| <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 <cvs> task </a>to |
| check out org.eclipse.releng, the map file project on dev.eclipse.org |
| used in the build.</p> |
| <p>Can be set to a specific tag to download the map files used for a |
| previous integration build. Typically, these tags are in the form "v<date/timestamp>" for |
| example "v200307110800" will checkout the map files used |
| to run the integration at the specified date/time. These scripts work |
| with 3.0 stream builds > 20030701.<br> |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td>timestamp</td> |
| <td>A timestamp used to fill in value for buildid in about.mappings files. |
| The timestamp is also used to tag the org.eclipse.releng project on dev.eclipse.org |
| only when an appropriate value for mapCvsRoot is provided and when the |
| tagMaps Ant property is set. </td> |
| </tr> |
| <tr> |
| <td>eclipseBuilderDirectory</td> |
| <td>A directory separate from buildDirectory and baseLocation, which contains |
| eclipse releng base builder, plugins and features that is used to run |
| the PDE build tools and locate the template scripts.</td> |
| </tr> |
| <tr> |
| <td>cvsRoot</td> |
| <td>CVS root (i.e. /home/webtools)</td> |
| </tr> |
| <tr> |
| <td>cvsServer</td> |
| <td>Address of the CVS server (i.e. dev.eclipse.org)</td> |
| </tr> |
| <tr> |
| <td>cvsProtocol</td> |
| <td>CVS protocol (i.e. pserver, local)</td> |
| </tr> |
| <tr> |
| <td>cvsUser</td> |
| <td>User id used for CVS authentication. You will need to run cvs -d <cvs-root> |
| login prior to build so that authentication information is cached.</td> |
| </tr> |
| <tr> |
| <td>ftpUser</td> |
| <td>ftp user id</td> |
| </tr> <tr> |
| <td>ftpPassword</td> |
| <td>ftp password</td> |
| </tr> <tr> |
| <td>ftpServer</td> |
| <td>Address of the ftp server (i.e. download.eclipse.org)</td> |
| </tr> |
| <tr> |
| <td>ftpRemoteDirectory</td> |
| <td>Directory that will be used to upload the build folder.</td> |
| </tr> |
| <tr> |
| <td>publishDirectory</td> |
| <td>A local directory that is used to keep a copy of the final build artifacts |
| .</td> |
| </tr> |
| <tr> |
| <td>clean</td> |
| <td>Existence of this property causes the build script to delete all working folders after completion. It's value is not used.</td> |
| </tr> |
| <tr> |
| <td>zipargs</td> |
| <td>Arguments to send to the zip executable. ie. zipargs=-y on Linux preserves |
| symbolic links.</td> |
| </tr> |
| </table> |
| <p></p></TD> |
| </TR> |
| <TR> |
| <TD>The following properties are pre-defined in the <a href="http://dev.eclipse.org/viewcvs/indexwebtools.cgi/org.eclipse.wtp.releng/maps/build.cfg?rev=1.1&content-type=text/vnd.viewcvs-markup">build.cfg</a> file |
| for the build.</TD> |
| </TR> |
| <TR><td height="167"><table width="100%" border="1"> |
| <tr> |
| <td>Name</td> |
| <td>Description</td> |
| </tr> |
| <tr> |
| <td>baseos,basews,basearch</td> |
| <td>The os, ws and arch values of a pre-built eclipse component being compiled against. See list of possible values in the table of <a href="#buildconfigs">build configurations</a>.</td> |
| </tr> |
| <tr> |
| <td><pre>eclipseURL</pre></td> |
| <td>Eclipse download URL. If you haven't got any eclipse-*.SDK.zip in your download build-home/downloads dir. Download it from this url.</td> |
| </tr> |
| <tr> |
| <td>eclipseFile</td> |
| <td>Eclipse zip file which will be used for building project</td> |
| </tr> |
| <tr> |
| <td>emfURL</td> |
| <td>EMF download URL. If you haven't got any emf*.zip in your download build-home/downloads dir. Download it from this url.</td> |
| </tr> |
| <tr> |
| <td>emfFile</td> |
| <td>EMF zip file which will be used for building project</td> |
| </tr> |
| </table> |
| </td></tr> |
| </table> |
| |
| <table border=0 cellspacing=5 cellpadding=2 width="100%" ><tr> |
| <td align=LEFT valign=TOP colspan="3" bgcolor="#999999"> |
| <b><font face="Arial,Helvetica" color="#FFFFFF"> |
| <a name="infra"></a>Build Infrastructure</font></b></td> |
| </tr> |
| |
| <TR> |
| <TD align="LEFT" valign="TOP" colspan="3"> |
| The automated build process currently runs on a Redhat Linux based build machine |
| hosted at eteration a.s. Build |
| process is run and monitored by <a href="cruisecontrol.sf.net">cruise control</a></TD> |
| </TR></table> |
| |
| |
| <table border=0 cellspacing=5 cellpadding=2 width="100%" ><tr> |
| <td align=LEFT valign=TOP colspan="3" bgcolor="#999999"> |
| <b><font face="Arial,Helvetica" color="#FFFFFF"> |
| <a name="cvs"></a>CVS Structure</font></b></td> |
| </tr> |
| |
| <TR> |
| <TD align="LEFT" valign="TOP" colspan="3">The CVS structure uses a granular |
| approach to to break up the WTP project into its subprojects and each subproject |
| into its its main components to achieve the following benefits: |
| <p>1.Organize the large number of contributions and teams into manageable pieces. <br> |
| 2.Organize the code into smaller collections so they are easier to understand. <br> |
| 3. Make it more extensible for future projects and components.</p> |
| <p>Each component group in a subproject implies ownership |
| of a chunk of functionality by a group of committers (i.e. server, sse).</p> |
| <table width="100%" border="0" > |
| <tr> |
| <td colspan="6"><strong>/home/webtools</strong></td> |
| <td width="62%">CVS ROOT</td> |
| </tr> |
| <tr > |
| <td width="2%"> </td> |
| <td colspan="5" bordercolor="0"><strong>/wst</strong></td> |
| <td>J2EE Standard Tools Subproject </td> |
| </tr> |
| <tr> |
| <td> </td> |
| <td width="3%" bordercolor="0"> </td> |
| <td colspan="4"><strong>/components</strong></td> |
| <td>Each component group in a subproject implies ownership of a chunk |
| of functionality by a group of committers</td> |
| </tr> |
| <tr bordercolor="#CCFFFF"> |
| <td> </td> |
| <td> </td> |
| <td width="3%"> </td> |
| <td colspan="3"><strong>/sse</strong></td> |
| <td>Structured Source Editor framework </td> |
| </tr> |
| <tr> |
| <td> </td> |
| <td bordercolor="0"> </td> |
| <td> </td> |
| <td width="3%"> </td> |
| <td width="6%"><strong>/plugins</strong></td> |
| <td width="21%"> </td> |
| <td> </td> |
| </tr> |
| <tr> |
| <td> </td> |
| <td bordercolor="0"> </td> |
| <td> </td> |
| <td> </td> |
| <td> </td> |
| <td>org.eclipse.wst.sse.core</td> |
| <td>The sse plugin(s)</td> |
| </tr> |
| <tr> |
| <td> </td> |
| <td bordercolor="0"> </td> |
| <td> </td> |
| <td> </td> |
| <td><strong>/features</strong></td> |
| <td> </td> |
| <td> </td> |
| </tr> |
| <tr> |
| <td> </td> |
| <td bordercolor="0"> </td> |
| <td> </td> |
| <td> </td> |
| <td> </td> |
| <td>org.eclipse.wst.sse-feature</td> |
| <td>The sse feature(s)</td> |
| </tr> |
| <tr> |
| <td> </td> |
| <td bordercolor="0"> </td> |
| <td> </td> |
| <td> </td> |
| <td><strong>/tests</strong></td> |
| <td> </td> |
| <td> </td> |
| </tr> |
| <tr> |
| <td> </td> |
| <td bordercolor="0"> </td> |
| <td> </td> |
| <td> </td> |
| <td> </td> |
| <td>org.eclipse.wst.sse-tests</td> |
| <td>sse test plugin(s)</td> |
| </tr> |
| <tr> |
| <td> </td> |
| <td colspan="5" bordercolor="0"><strong>/jst</strong></td> |
| <td> </td> |
| </tr> |
| </table> |
| </TD> |
| </TR></table> |
| <table width="100%" border="0"> |
| <tr> |
| <td bgcolor="#999999"><b><font face="Arial,Helvetica" color="#FFFFFF"> |
| <a name="mapfile"></a>How to Create Map File </FONT></b></td> |
| </tr> |
| <tr> |
| <td>A .map file is a java property file which contains mappings of elements to their CVS locations and access methods. Map files are used by PDE Build early in the build process to generate Ant scripts which use the Ant <cvs> task to export source to a directory. This is described further <A HREF="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.releng.basebuilder/readme.html?rev=HEAD#getmaps">below</A>.</td> |
| </tr> |
| <tr> |
| <td>Map file entries use the following format:</td> |
| </tr> |
| <tr> |
| <td><span class="style1">feature|fragment|plugin@element.Id=<cvs tag>,<access method>:<cvs user>@<cvs repository>,<cvs password>[,<repository path> (no starting slash) ]</span></td> |
| </tr> |
| <tr> |
| <td height="50"><br>The <repository path> is only required when the module (or directory) containing the source for the element does not match the element.Id or if the directory is not at the root of the repository.</td> |
| </tr> |
| <tr> |
| <td><br> |
| A map file entry must exist for each feature being built, it's <plugin> elements and it's <includes> elements (ie. nested features and their plug-ins). Adding a plug-in or fragment to a feature therefore requires updating the map files with the new element.</td> |
| </tr> |
| <tr> |
| <td><B><br>Map File Entry Examples</B> </td> |
| </tr> |
| <tr> |
| <td height="365"><UL> |
| <LI><P>The 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> |
| repository. It is contained in a directory with the name |
| "org.eclipse.platform". The resulting map file entry |
| for this plug-in |
| is:<BR><BR>plugin@org.eclipse.platform=v20031121,:pserver:anonymous@dev.eclipse.org:/home/eclipse,</P> |
| <LI><P>The 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> |
| repository in a directory with the name |
| "org.eclipse.platform-feature". The 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</P> |
| <LI><P>The 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> |
| repository in a subdirectory called "org.eclipse.gef.sdk" |
| of "org.eclipse-gef feature". The resulting map file |
| entry for this feature |
| is:<BR><BR>feature@org.eclipse.gef.sdk=I_20031117, |
| :pserver:anonymous@dev.eclipse.org:/home/tools,,org.eclipse.gef-feature/org.eclipse.gef.sdk</P> |
| </UL> |
| <p>One or more map files can be used to list the elements. The map files can be kept under version control. Some examples of map file projects include <A HREF="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.releng/" TARGET="extra">org.eclipse.releng</A>, <A HREF="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.gef.releng/?cvsroot=Tools_Project" TARGET="extra">org.eclipse.gef.releng</A>, <A HREF="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.ve.releng/?cvsroot=Tools_Project" TARGET="extra">org.eclipse.ve.releng</A>.</p> |
| </td> |
| </tr> |
| <tr> |
| <td><A NAME="gensource"></A><FONT SIZE=4><B>Generating source features and plug-ins at build time</B></FONT> |
| <P>Source features and plug-ins can be generated at build time by PDE Build. Source features and associated source plug-ins are typically generated for a development kit distributions (i.e. SDK). It is also possible to generate a source plug-in only. This is typically the case for example features or JUnit testing features.<BR> |
| <BR> |
| To generate a <B>source feature and associated source plug-in</B> at build time, you will need to do the following:</P> |
| <OL> |
| <LI> |
| <P>Add an entry to the build.properties file in the feature project for which you wish to include the source feature and plug-in. The generated source feature should also be listed in the feature.xml as an <includes> element.<BR> |
| <BR> |
| The build.properties entry should use the following format:<BR> |
| <BR> |
| generate.feature@<source.feature.id to generate>=<feature.id from which to which to collect source>, plugin@<plugin.id><BR> |
| <BR> |
| Example taken from <A HREF="http://dev.eclipse.org/viewcvs/index.cgi/~checkout~/org.eclipse.sdk-feature/build.properties?rev=1.4" TARGET="extra">org.eclipse.sdk-feature/build.properties</A>: <BR> |
| generate.feature@org.eclipse.jdt.source=org.eclipse.jdt, plugin@org.eclipse.jdt.doc.isv<BR> |
| <BR> |
| In this example, a source feature and a plug-in, both with id "org.eclipse.jdt.source" will be generated and will contain source from plug-ins listed in the org.eclipse.jdt feature and will also include the plug-in org.eclipse.jdt.doc.isv. The generated org.eclipse.jdt.source plug-in will be automatically listed in the org.eclipse.jdt.source feature.xml. |
| </P> |
| <LI> |
| <P>In the feature project from which the source feature will be generated, a directory called "<B>sourceTemplateFeature</B>" and a directory called "<B>sourceTemplatePlugin</B>" will be required. These directories should contain the files that are included in the root of the generated source feature and plug-in. The feature.xml and plugin.xml files are not required since these are generated. A build.properties is required in the sourceTemplatePlugin directory. This should contain a "bin.includes" setting as well as the entry "sourcePlugin = true". The plugin.xml file and src/ directory should be listed in the bin.includes.<BR> |
| <BR> |
| See <A HREF="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.jdt-feature/" TARGET="extra">org.eclipse.jdt-feature</A> and <A HREF="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.platform-feature/" TARGET="extra">org.eclipse.platform-feature</A> for examples.</P> |
| </OL> |
| <P>To generate a <B>source plug-in only</B> at build time, you will need to do the following:</P> |
| <OL> |
| <LI> |
| <P>Add an entry to the build.properties file in the feature project for which you wish to include the source plug-in. The generated source plug-in should also be listed in the feature.xml as a <plugin> element.. <BR> |
| <BR> |
| The build.properties entry should use the following format:<BR> |
| <BR> |
| generate.plugin@<source.plugin.id to generate>=<feature.id from which to which to collect source>, plugin@<plugin.id><BR> |
| <BR> |
| Example taken from <A HREF="http://dev.eclipse.org/viewcvs/index.cgi/~checkout~/org.eclipse.ve.tests-feature/build.properties?rev=1.2&cvsroot=Tools_Project" TARGET="extra">org.eclipse.ve.tests-feature/build.properties</A>: <BR> |
| generate.plugin@org.eclipse.ve.tests.source=org.eclipse.ve.tests |
| </P> |
| <LI> |
| <P>In the runtime feature project from which the source plug-in will be generated, create a directory called "sourceTemplatePlugin" which must contain a build.properties with a "bin.includes" setting and "sourcePlugin=true". The plugin.xml file and src/ directory should be listed in the bin.includes.<BR> |
| <BR> |
| See <A HREF="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.ve.examples-feature/sourceTemplatePlugin/?cvsroot=Tools_Project" TARGET="extra">org.eclipse.ve.examples-feature/sourceTemplatePlugin</A> for an example.</P> |
| </OL> |
| </td> |
| </tr> |
| </table> |
| <p></p> |
| <table border=0 cellspacing=5 cellpadding=2 width="100%" > |
| <tr> |
| <td align=LEFT valign=TOP colspan="3" bgcolor="#999999"> |
| <b><font face="Arial,Helvetica" color="#FFFFFF"> |
| <a name="team"></a>WTP Release Engineering Team</font></b></td> |
| </tr> |
| |
| <TR> |
| <TD height="23" colspan="3" align="LEFT" valign="TOP"> |
| Ozgur Tumer (ozgur.tumer_at_eteration.com)<br> |
| Dominique Devito (dominique.devito_at_objectweb.org)</TD> |
| </TR></table> |
| |
| |
| </html> |