Revision as of 09:40, 6 January 2009

Automatic build of JWT Features and Plugins

Helpful resources

• General information about building
• Article from Markus Barchfeld about automatic building
• Sample project

What we did

Pre-requirements

• First, we downloaded CVS support for the command line: [CVS]
• Afterwards, we downloaded PDE Releng:

       cvs -d :pserver:anonymous@dev.eclipse.org:/cvsroot/eclipse export -r HEAD org.eclipse.releng.eclipsebuilder

• We set some system variables, e.g. the ECLIPSE_HOME-variable:

       set ECLIPSE_HOME=C:\Programme\Eclipse //adapt to your Eclipse home directory

• And also configured the Build target directory:

       set BUILD_HOME=C:\Build\New //adapt to your Build directory

Startup the build process

• Generate a build.xml from the feature using right-click, PDE Build -> Generate Ant Script (this creates a build.xml in the feature directory)

• Go to the directory of the feature: cd ...\jwt-we-feature

• Execute:

      java -cp %ECLIPSE_HOME%\plugins\org.eclipse.equinox.launcher_1.0.101.R34x_v20080819.jar 
         org.eclipse.core.launcher.Main -application org.eclipse.ant.core.antRunner 
        -buildfile build.xml -Dcomponent=sdk.examples 
        -Dconfigs="*,*,*" 
        -Dbaseos=win32 
        -Dbasews=win32 -Dbasearch=x86 -Djavacfailonerror=true 
        -Dpde.build.scripts=%ECLIPSE_HOME%/plugins/org.eclipse.pde.build_3.4.1.R34x_v20080805/scripts 
        -DbaseLocation=%ECLIPSE_HOME% 
        -DbuildDirectory=&BUILD_HOME%

• This generates the JAR-file of the feature.

What we have

JWT build minimal Eclipse base

In order for the build and automated testing to be working as fast as possible, it is necessary to maintain a build base (in /shared/technology/jwt/base on build.eclipse.org), that contains only the projects that are necessary to build and test JWT, and to ensure that these project are built for for the build server you are using.

Creating the base

To create a build base, you'll need to expand the following projects in the directory you want to use ase the eclipse base:

• Eclipse platform linux/ppc/gtk => ~/downloads/eclipse/downloads/[buildId]/eclipse-platform-[version]-linux-gtk-ppc.tar.gz
• Eclipse PDE => ~/downloads/eclipse/downloads/[buildId]/eclipse-PDE-[version].zip
• Eclipse JDT => ~/downloads/eclipse/downloads/[buildId]/eclipse-JDT-[version].zip
• EMF Runtime => ~/downloads/modeling/emf/emf/downloads/drops/[version]/[buildId]/emf-runtime-[buildId].zip
• GEF Runtime => ~/downloads/tools/gef/downloads/drops/[version]/[buildId]/GEF-runtime-[buildId].zip

Choosing the version of each project:

• Currently, JWT build on Eclipse server uses the latest version that contains a Maintenance or Release build (ie buildId starting with R or M)
• However, we could discuss about trying to build usng stable or milestone builds, to ensure the compatibility with the latest versions of projects. But this would require much more work until we succeed to automate the creation of the base with the latest drops...

Check an existing base

There are 2 ways to check that an eclipse installation matches your machine platform:

• Try to run the eclipse launcher program (./eclipse). If eclipse starts, it is OK
• From the eclipse directory, try command ls plugins/ | grep org.eclipse.swt, then you should get a list of plugins, and one of them specifies a os/ws/arch 3-uplet in its name. It must be match your server platform.

If you don't have the same eclipse target and server platforms, then you might be able to build, but testing will be impossible for you.

How to use it

Update sites organisation

First, as it is the case in most of "one feature" projects (such as GEF), JWT now has 3 update sites:

• http://download.eclipse.org/technology/jwt/update-site is the update-site that contains the current release of JWT
• http://download.eclipse.org/technology/jwt/integration-update-site is the update-site the could contain any development or nightly build of JWT. Contents of this update-site should only be used by JWT contributors for testing.
• http://download.eclipse.org/technology/jwt/stable-update-site is the update-site for stable development build, and also for Galileo milestones

Building on build.eclipse.org

Requirements

Since testing requires the ability to start the eclipse UI, you'll need to have a X-server started on your machine to enable testing. See EMF advices about X configuration for more details. If you already have a X server on your machine, you won't have to change anything, but you'll need to connect to the eclipse build server using ssh -X [login]@build.eclipse.org.

If you there is a problem with X server, you'll have an error telling you that there is a problem with gtk_init...

Start a build

Anyone who has access to build.eclipse.org can now start a build of cvs HEAD by typing from JWT home folder ./build.sh [buildType] where build type is I (default), S or R, respectively for integration, stable or release build.

This script will start the whole build process and update the update-site for the specified build type.

Start a build on your local machine

If you want to build locally JWT, simply checkout the org.eclipse.jwt/releng CVS module and write a script that starts the build with your local configuration (please do not modify build.sh or build.properties, that are build.eclipse.org files). See build.mistria.openwide.sh for example.

Continuous integration

TODO Note that the PDE build process supports unit testing. I've read about several Eclipse projects that used a continuous integration tool (such as cruise, continuum or hudson) to monitor their builds and test results. I'll try to choose if one of these solutions is fine for JWT.

Releasing Policy

When releasing JWT, here are the steps to follow:

1. Tag the feature and all plugins included into the release with tag R{releaseVersion} (for example R0.5.0)
2. Build on build.eclipse.org the feature to release (./build.sh R). The update site is automatically updated.
3. Increment the feature version number (See Version Numbering)
4. Increment all plugins versions that will be modified in next release)
5. Create a buzz about this release!

Adding new plugins to the JWT release

This section describes the steps to follow to add a new plugin to JWT release and get the build working with this add-ons. We'll use an example to facilitate the explanations.

Assume that jwt-we (plugin) now depends on a new plugin (jwt.we.conf.model) that was not part of the automated build before. In such case, some things needs to be updated to build the jwt-we automatically, else you'll get a "missing bundle" error telling you that the build cannot find the jwt.we.conf.model.

• Ensure that jwt.we.conf.model version ends with .qualifier (see Version Numbering)
• Add those plugins to the top-level feature (currently jwt-we-feature) with version 0.0.0 (automatically chosen at build time)
• Add those plugins CVS path to the builder map file (currently releng/maps/jwt.map)
• Add the test plugins as dependencies to the top-level test plugin (currently jwt-we-tests)
  • Add them as dependencies to the plugin.xml
  • Add them into the AllTests testSuite of the plugin
  • Add them to the top-level test feature (so that they will be fetched from CVS at build time)
  • Add those plugins CVS path to the builder map file (currently releng/maps/jwt.map)