Overview

This system was derived from the system used by WTP and STP (and probably others). The system performs the following tasks:

Component builds

builds plugins and features

generates install ZIP

generates update site JARs

Component testing

executes unit tests

generates results files

Update site generation

[TBD]

Download site generation

generates html for download site

incorporates build settings

incorporates build results (e.g. warnings/errors)

incorporates test results

Uploading build information

publishes generated files to DTP web site

Design

The build system is designed to organized as follows:

distribution

a group of one or more components

component

synonymous with feature; the input to the builder/assembler/packager

The system is comprised of custom Ant scripts which are used to initialize build properties, download dependencies, invoke the PDE builder for individual components, generate site files.

The head-less PDE builder is used to generate plugin JARs and ZIPs. The PDE builder executes a build using information in the feature and plugin manifests. This helps ensure the plugin build environment is similar to its execution environment.

org.eclipse.datatools.releng.builder

This project contains the scripts used to execute the build. It is divided into the following sections (by folder):

components

cruise

distribution

scripts

At the root is the build.xml file that drives the build for a particular distribution (i.e. the distribution must be specified when this file is invoked; e.g. dtp).

components folder

The components folder contains a folder for each component that will be built. These folders may be used directly with PDE builder as the buildLocation for the build.

A component is synonymous with a feature. The feature specified by the component is used to drive the build. See the PDE builder documentation for more information.

This system deviates from the general PDE build integration by the following:

allElements.xml is incorporated directly within customTargets.xml

The allElements and assemble.element.id[.config.spec] targets are defined directly within customTargets.xml.

most of the targets for customTargets.xml are imported from scripts/build/defaultCustomTargets.xml

scripts/build/defaultCustomTargets.xml contains targets that are common to all component builds (e.g. fetching dependencies). (Note, individual components may override any targets imported from defaultCustomTargets.xml.)

dependency.xml

This file is used to specify the dependencies required by the component. The dependencies.properties file in org.eclipse.datatools.releng must contain an entry for each of the group IDs specified in this file.

generates the download site files for the build. (verify: does this also generate the update site)

api

TODO: document this

tests

invokes tests and consolidates results

upload

uploads generated build zips and site files to the web site

whatisfixed

TODO: document this

The following distributions and targets are defined for DTP:

dtp

the main DTP distribution

build

builds component zips

site

builds download site files (TODO: should update the html template files to fit in with the new-look Eclipse web site)

tests

TODO: needs to be updated for DTP

upload

TODO: needs to be updated for DTP

scripts folder

Contains common scripts available for use from distribution and component build scripts. For example, scripts/dependency contains scripts for downloading dependencies required by a particular component; scripts/build/build.xml contains targets for executing the PDE builder for a particular component.

Executing a Build

Building a Distribution

A distribution build may be exectuted through either of the following build files: (note, these may be invoked using a normal Ant install; i.e. no special tasks or additional libraries are required)

org.eclipse.datatools.releng.builder/cruise/build.xml

This is the build file used with CruiseControl. Executing the build through this file will fetch the org.eclipse.datatools.releng and org.eclipse.datatools.releng.builder projects, the former will be fetched using the tag specified by the mapVersionTag property, while the latter will be fetched using the tag specified by the dtpBuilderVersion property located in the fetched org.eclipse.datatools.releng/maps/build.cfg file. The build is then executed through the fetched org.eclipse.datatools.releng.builder/build.xml file.

org.eclipse.datatools.releng.builder/build.xml

This is the main build file for the DTP, containing targets for building a distribution's build, site, api, tests, upload and whatisfixed targets. There is no default target for this build file, so you must specify one or more on the command line.

The following properties must be defined when invoking either of the above targets:

basearch

The architecture (e.g. x86)

baseos

The operating system (e.g. win32)

basews

The windowing system (e.g. win32)

build.home

The working directory for the build (e.g. c:\tmp\dtp\build)

env.J2SE14

The build classpath for plugins built against J2SE-1.4 execution environment. Currently, this must include rt.jar, jsse.jar and jce.jar (e.g. c:\j2sdk1.4.2\jre\lib\rt.jar;c:\j2sdk1.4.2\jre\lib\jsse.jar;c:\j2sdk1.4.2\jre\lib\jce.jar)

env.J2SE15

Similar to J2SE15, but applies to J2SE-1.5 execution environment.

lpgJavaRuntimeJarFileLocation

Location of lpgjavaruntime.jar file. This is required for building SQL tools. This file is copied into org.eclipse.datatools.lpg/lib prior to building and deleted prior to packaging.

build.trial

Set to true when testing the build system.

build.clean

Set to true to remove any existing build directory (only for cruise/build.xml)