2.4. Building a Product

Building a commercial product involves packaging up only those elements to be delivered in a form that the customer can install into his or her environment. You can build the product in several different ways, including manually or by using a Windows batch script, a UNIX shell script, or an Apache Ant script. You can deliver the end product as a single compressed file or as a stand-alone executable. For our purposes, the Favorites plug-in will be delivered with source code as a single compressed zip file.

2.4.1. Building manually

Building a product manually involves launching an Eclipse Export wizard, filling out a few fields, and clicking the Finish button. Select the File > Export command to launch the desired export wizard. On the first wizard page (see Figure 2-14), select Deployable plug-ins and fragments and then click the Next button.

Figure 2-14. Export wizard page 1choosing the type of export.

The Eclipse 3.1 version is shown on the left and the Eclipse 3.2 version is shown on the right. The Eclipse 3.2 version adds a filter field and categorized export types.

[View full size image]

On the second page of the Export wizard (see Figure 2-15), select the plug-ins to be exported, enter the name of the zip file to contain the result, and select the options shown. In addition, specify that this export operation be saved as an Ant script in a file named build-favorites.xml in the com.qualityeclipse.favorites project, then click Finish.

Figure 2-15. Export wizard page 2specifying the zip file's contents.

[View full size image]

The created zip file contains a single plug-in JAR file (a plug-in can be deployed as a single JAR file as of Eclipse 3.1):

plugins/com.qualityeclipse.favorites_1.0.0.jar

And that plug-in JAR file contains the plug-in and its source code as specified in the Export wizard:

favorites.jar
favoritessrc.zip
plugin.xml
icons/sample.gif
META-INF/MANIFEST.MF

Unfortunately, this process is manual, and therefore prone to errors. Manually building a product is fine once or twice, but what if a different person in the company needs to build the product? What happens as the product grows and encompasses more plug-ins? A commercial product needs a repeatable and reliable method for building it.

2.4.2. Building with Apache Ant

An Apache Ant script provides a reliable, flexible, and repeatable process for building a commercial plug-in project. There is a little more up-front work to set up an Ant script, but it is much less error-prone over time than building a product manually. For more information about Ant and constructing more complex build scripts, see Chapter 19.

Eclipse can generate simple Ant scripts. The prior section specified that the Export wizard generates an Ant script file named build-favorites.xml in the com.qualityeclipse.favorites project:

<?xml version="1.0" encoding="UTF-8"?>
<project default="plugin_export" name="build">
   <target name="plugin_export">
      <pde.exportPlugins
         destination="\Build\QualityEclipse"
         exportSource="true"
         exportType="zip"
         filename="FavoritesPlugin.zip"
         plugins="com.qualityeclipse.favorites"
         source="1.3"
         target="1.2"
         useJARFormat="true" />
 </target>
</project>

The preceding simple script works well from the Eclipse UI; however, unfortunately, the pde.exportPlugins and other pde.export* tasks are asynchronous and cannot be used in a headless environment (see Bugzilla entry 58413 at bugs.eclipse.org/bugs/show_bug.cgi?id=58413) making it difficult to build more than simple scripts.

If you want your build script to do more than just export plug-ins (see Section 3.2.1, Link files, on page 105), then you'll need a more complex Ant script similar to the following. For more on Ant and build scripts, see Chapter 19, Building a Product.

<?xml version="1.0" encoding="UTF-8"?>
<project default="plugin_export" name="build">
   <target name="plugin_export">

      <!-- Define build directories -->
      <property name="build.root"
         location="/Build/QualityEclipse" />
      <property name="build.temp"
         location="${build.root}/temp" />
      <property name="build.out"
         location="${build.root}/product" />

      <!-- Create build directories -->
      <delete dir="${build.temp}" />
      <mkdir dir="${build.temp}" />
      <mkdir dir="${build.out}" />

      <!-- Read the MANIFEST.MF -->
      <copy file="META-INF/MANIFEST.MF" todir="${build.temp}" />
      <replace file="${build.temp}/MANIFEST.MF">
         <replacefilter token=":=" value="=" />
         <replacefilter token=":" value="=" />
         <replacetoken>;</replacetoken>
         <replacevalue>
         </replacevalue>
      </replace>
      <property file="${build.temp}/MANIFEST.MF"/>

      <!-- Plugin locations -->
      <property name="plugin.dir" value=
         "com.qualityeclipse.favorites_${Bundle-Version}" />
      <property name="plugin.files" location=
         "${build.temp}/files/${plugin.dir}" />
      <property name="plugin.jar" location=
         "${build.temp}/jars/plugins/${plugin.dir}.jar" />
      <property name="product.zip" value=
         "${build.out}/Favorites_v${Bundle-Version}.zip" />

      <!-- Assemble the files -->
      <mkdir dir="${plugin.files}" />
      <jar destfile="${plugin.files}/favorites.jar">
         <fileset dir="bin" />
      </jar>
      <jar destfile="${plugin.files}/favoritessrc.zip">
         <fileset dir="src" />
      </jar>
      <copy todir="${plugin.files}">
         <fileset dir="." includes="META-INF/MANIFEST.MF" />
         <fileset dir="." includes="plugin.xml" />
         <fileset dir="." includes="icons/*.gif" />
      </copy>
       <!-- Assemble plug-in jar -->
      <mkdir dir="${build.temp}/jars/plugins" />
      <zip destfile="${plugin.jar}">
         <zipfileset dir="${plugin.files}">
            <include name="**/*.*" />
         </zipfileset>
       </zip>

       <!-- Assemble the product zip -->
       <zip destfile="${product.zip}">
         <fileset dir="${build.temp}/jars" />
       </zip>

    </target>
</project>

To execute this Ant script, right-click on the build-favorites.xml file and select Run Ant... (see Figure 2-16). When the Ant wizard appears, click on the JRE tab and select the Run in the same JRE as the workspace option (see Figure 2-17). Click the Run button to build the product.

Figure 2-17. The Ant wizard.

[View full size image]