| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN"> |
| <html> |
| <head> |
| <meta name="copyright" |
| content="Copyright (c) IBM Corporation and others 2006. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page."> |
| <meta http-equiv="Content-Type" |
| content="text/html; charset=ISO-8859-1"> |
| <meta http-equiv="Content-Style-Type" content="text/css"> |
| <link rel="STYLESHEET" href="../book.css" charset="ISO-8859-1" |
| type="text/css"> |
| <title>Building features</title> |
| </head> |
| <body style="background-color: rgb(255, 255, 255);"> |
| <h1>Building features</h1> |
| PDE Build comes with infrastructure to automate the build of features. |
| Most of the setup necessary |
| for such a build can be done through a few modifications to the |
| template build.properties provided |
| in PDE build. The following section focuses on setting up a simple |
| build assuming that all plug-ins |
| and features (both to-build and pre-built) referenced from the feature |
| being built are already |
| locally available on disk. |
| <h2>Basic Setup</h2> |
| <p>The first step in setting up a build is to create the directory in |
| which the build will take |
| place. This directory will be referred to as the <i>build directory</i> |
| and will contain the |
| plug-ins and features to build as well as all the generated artifacts. |
| Next, copy your plug-ins and |
| features respectively into "plugins" and "features" subdirectories. |
| The feature folder is expected to contain the feature being built.</p> |
| The second step in setting up a build is to copy the template |
| build.properties file from |
| org.eclipse.pde.build/templates/headless-build to a new directory which |
| will be the build |
| configuration directory (also referred to as the <i>configuration |
| directory</i>). Edit the copied build.properties file and set the |
| following properties: |
| <br> |
| <ul> |
| <li><span style="font-weight: bold;"></span><span |
| style="font-weight: bold;">baseLocation</span>: the location of an |
| eclipse install containing all the pre-built features and plug-ins in |
| <tt>features/</tt> and <tt>plugins/</tt> subdirectories.</li> |
| <li><span style="font-weight: bold;"></span><span |
| style="font-weight: bold;">baseos</span>: indicate the os of the |
| eclipse specified by baseLocation.</li> |
| <li><span style="font-weight: bold;"></span><span |
| style="font-weight: bold;">basews</span>: indicate the ws of the |
| eclipse specified by baseLocation. </li> |
| <li><span style="font-weight: bold;"></span><span |
| style="font-weight: bold;">basearch</span>: indicate the arch of the |
| eclipse specified by baseLocation. </li> |
| <li><span style="font-weight: bold;">buildDirectory</span>: |
| the directory the build will take place in. Set this to the full |
| path of the build directory created previously.</li> |
| <li><span style="font-weight: bold;">configs</span>: list the |
| configurations for which you want your feature to be built. You can |
| uncomment the configuration(s) provided (be careful of the line |
| continuations). If the feature you are building is platform |
| independent, this property does not need to be set or can be set |
| to <tt>*,*,*</tt>.</li> |
| <li><span style="font-weight: bold;">archivePrefix</span>: |
| the name of the directory in which your feature will be unzipped on disk.</li> |
| </ul> |
| <h2>Controlling what will be built: allElements.xml</h2> |
| Copy the allElements.xml file from |
| org.eclipse.pde.build/templates/headless-build to your configuration |
| directory. This is the file that tells PDE which feature |
| you are building. This |
| file contains two kinds of targets: the <tt>allElementsDelegator</tt> |
| which specifies the feature being built, and |
| the assemble targets which are called to assemble individual |
| configurations. The |
| <tt>allElementsDelegator</tt> for a feature named <code>org.foo.Feature</code> |
| is: |
| <br> |
| <div style="text-align: left; margin-left: 40px;"> |
| <pre> <target name="allElementsDelegator"><br> <ant antfile="${genericTargets}" target="${target}"><br> <property name="type" value="feature" /><br> <property name="id" value="<span |
| style="font-weight: bold;">org.foo.Feature</span>" /><br> </ant><br> </target><br></pre> |
| </div> |
| The assemble targets allow you to control the name of the final archive |
| on a per configuration |
| basis. You should have one target for each configuration you are |
| building. For example, |
| when building |
| <code>org.foo.Feature</code> |
| for windows (when <tt>configs</tt> is set to win32, win32, x86) you should have the following target: |
| <br> |
| <pre style="margin-left: 80px;"><!--Target for assembling os=win32, ws=win32, arch=x86 --><br><target name="assemble.<span style="font-weight: bold;">org.foo.Feature</span>.win32.win32.x86"><br> <ant antfile="${assembleScriptName}" dir="${buildDirectory}/"><br></target> <br></pre> |
| When building a platform independent configuration (when <tt>configs</tt> is not set or is set to <tt>*,*,*</tt>), you should a target like the following: |
| <pre style="margin-left: 80px;"><!--The platform independent assemble target--><br><target name="assemble.<span style="font-weight: bold;">org.foo.Feature</span>"><br> <ant antfile="${assembleScriptName}" dir="${buildDirectory}"/><br></target><br> <br></pre> |
| <h2>Running the build</h2> |
| To run the build you will use the org.elipse.ant.core.antRunner |
| application. When invoking eclipse |
| with this application to perform a build you need to set two arguments |
| on the command line: |
| <br> |
| <ul> |
| <li><code>-buildfile=</path/to/build.xml></code>: This is |
| the path to the build.xml provided by pde build. It is located in |
| the org.eclipse.pde.build/scripts directory. This is the build |
| file that drives the whole build process.</li> |
| <li><code>-Dbuilder=</path/to/configuration folder></code>: |
| This is the path to the build configuration folder.</li> |
| </ul> |
| Run the antRunner application using the following command: |
| <br> |
| <div style="text-align: center;"> |
| <div style="text-align: left;"> |
| <div style="margin-left: 40px;"><code>java -jar |
| <eclipseInstall>/startup.jar |
| -application org.eclipse.ant.core.antRunner -buildfile |
| <<eclipseInstall>/plugins/org.eclipse.pde.build_<version>/scripts/build.xml> |
| -Dbuilder=<path to the build configuration folder></code><br> |
| </div> |
| </div> |
| </div> |
| Once the build is complete, you can get the result in the build |
| directory in the folder named I.TestBuild (this name can be configured |
| by setting the buildLabel property). |
| <h2>Advanced scenarios</h2> |
| <p>If you require more customization of the build, ie |
| fetching from a repository, see the <a |
| href="pde_build_advanced_topics.htm">Advanced |
| PDE Build topics</a> for |
| more information.<br> |
| </p> |
| </body> |
| </html> |
