Zed Builds and Bugs Manager makes it easy to automate your eclipse builds today, but often the question comes up around just exactly what steps are required to accomplish this. There is a tutorial that we have included in the documentation for Zed that walks you through automating eclipse builds with Zed.

In general the tutorial shows you how to take an eclipse feature project along with the associated plugin projects that are included in the feature and use the eclipse built-in mechanisms to get the feature compiled, packaged, and ready for deployment as either a zipped package or a set of jars ready to deploy to an eclipse update site.

There are a number of different websitesfrom eclipse that will walk you through the details at a very low level for how to take advantage of the eclipse PDE build system and show you how to automate your builds within the eclipse and Ant framework. The issue with many of these guides is that they are either out of date, or they make the process too complicated.

With Zed Builds And Bugs Manager the process is actually very straightforward.

Prerequisites

In order to most easily fit into this process, it's beneficial to follow a few guidelines about creating plugins for eclipse:

• Create a Feature for your plugins. This is the best way to organize and give yourself a single starting point for your build.
• Manage your plugin dependencies properly. Use the eclipse plugin dependencies instead of hard-coding classpath settings, so that the eclipse build system will be able to auto-resolve your plugin build requirements.

Eclipse Tools & Variables

In this guide, we'll be using and making reference to the eclipse Ant Runner application that is provided with the base eclipse PDE installation. This is the key to running a "headless" eclipse that still knows how to manage plugins, analyze dependencies, and produce correct builds for your application.

The eclipse Ant Runner application is provided by the org.eclipse.equinox.launcher jar file, which will have a specific version depending on your eclipse installation. We recommend creating the following two build environment variables to help abstract the specifics of your eclipse version:

• EclipseHome Set this to the full path of your eclipse installation. e.g. c:\eclipse34
• EclipseLauncher Set this to the full path of your equinox launcher jar file. e.g. c:\eclipse34\plugins\org.eclipse.quinox.launcher_1.0.100.v20080509-1800.jar

We also recommend setting a variable to point to your java executable:

• JavaBinary Set this to the full path of your java executable: e.g. c:\jdk1.6.0_04\bin\java

Eclipse Ant commands for Features and Plugins

A careful read of the eclipse help on ant tasks will help you to understand the full power of the Ant Tasks that eclipse has contributed and are available when you use the AntRunner application from the equinox.launcher plugin. We're going to make use of these in order to get eclipse to help make our build process easier.

We'll be using the eclipse.buildScript target specifically to auto-generate all of the Ant build files that will be involved.

Example

A full example of the steps documented here can be found in the Hericus Online Demo Application. Reference the instructions on accessing the demo system for logon and link information. The demo system uses the eclipse Graphical Editor Framework to provide a simple example of all of the steps involved from source to packaged binaries.

Build Steps

• The first build step you will want to create will be one to check out your feature and all of the related plugins from your source control system. Refer to the Build Management How To guide for specifics on working with your version control system. Ensure that your feature and all of its plugins are checked out. You may use a flat structure (like your workspace layout), or the traditional features/, plugins/ directory structure if you like.
• The next step to create will be your standard Update Version Number In Source step. Search and replace through all of the plugin.xml and build.xml files in your project to ensure your build version number is correctly applied.
• Create a step that will create a simple ant build file that will be used to create all of the ant build.xml files for each of the features and plugins involved in your project. The ant build file should look like this:

<?xml version="1.0" encoding="UTF-8"?>
<project name="buildBuildFiles" default="all" basedir=".">
        <target name="all">
                <eclipse.buildScript elements="feature@org.eclipse.gef"
                        buildDirectory="${WORKDIR}"
                        baseLocation="${EclipseHome}"
                />
        </target>
</project>

• Create a step that will run the newly created Ant build file with a command that should look like this:

 
java -cp ${EclipseLauncher} org.eclipse.core.launcher.Main -application org.eclipse.ant.core.antRunner -v -file ${WORKDIR}/genbuildxml.xml

• By default, eclipse will generate the build.xml files with some settings that you may want to change. Use the Zed Search & Replace feature to update any settings in the newly created build.xml files that you would like to change. We recommend setting the javacFailOnError setting to "true" instead of "false" so that you will know about errors in the build immediately.
• At this point, you are ready to run the actual build of your feature. Create a step that will run the clean and build.jars ant targets:

 
java -cp ${EclipseLauncher} org.eclipse.core.launcher.Main -application org.eclipse.ant.core.antRunner -v -file ${WORKDIR}/features/org.eclipse.gef-feature/build.xml clean build.jars

• The final build step will be to assemble your distribution zip file by using the zip.distribution ant target:

 
java -cp ${EclipseLauncher} org.eclipse.core.launcher.Main -application org.eclipse.ant.core.antRunner -v -file ${WORKDIR}/features/org.eclipse.gef-feature/build.xml zip.distribution

• At this point you may do anything else that your build requires. In our sample that you can find on the zed demo server we simply copy the zipped distribution file into the Status directory to make it available for download.

Comments

The eclipse ant build framework does include tasks that allow you to use the built in eclipse support for CVS to allow you to download your source code from a CVS repository. The disadvantage of this is that it won't support all types of source control management systems, like Perforce, ClearCase, etc. We recommend splitting this step out, even if you are using CVS, because it gives you better visibility into the steps that are performed by your build, and it gives you more flexibility over the underlying source control systems that you can incorporate.