What is PDE Build?

PDE Build is a plug-in that helps users build their own plug-ins. The term build here is related to deployment and not development. PDE Build takes an Eclipse Plug-in Project, its plugin.xml and build.properties files and generates a build.xml script to be run by Ant. Building plug-ins, fragments or features consists of the 3 stages: fetch, generate scripts and build that are described bellow.

Fetch
Consists of taking the interesting elements from a repository to the build machine. These elements can be plug-ins, fragments or features. "Directory files" or "map files" are responsible for identifying where, how and which plug-ins should go to the build machine. These files are basically Java properties files where the entries have the following format:

        element@element_id=tag,:connection_type:user@host:repository

The current implementation of fetch only works against CVS repositories and there are no plans for supporting different kinds. Skipping or substituting this step should not be hard for users of other VCM systems or other kind of storage.

Examples:

        plugin@org.eclipse.pde.build=v20020717, :pserver:anonymous@dev.eclipse.org:/home/eclipse,
        fragment@org.eclipse.core.resources.win32=v20020627, :pserver:anonymous@dev.eclipse.org:/home/eclipse,
        plugin@org.eclipse.platform=v20020820, :pserver:anonymous@dev.eclipse.org:/home/eclipse,

Generate Ant buildfiles
Once the plug-ins, fragments and features are in place, we need to generate the build.xml scripts. These Ant buildfiles drive the build process. In order to generate them, PDE Build takes as input the plugin.xml, fragment.xml, feature.xml and build.properties files. The complete description of the first three files are elsewhere in the Eclipse documentation. Here we will only fully describe the build.properties file and relevant parts of the others.

Build
This step is basically executed by Ant. One important thing here is to know exactly what targets to call in order to get the desired result.

How do I use PDE Build?

Fetch

This step is done by the eclipse.fetch Ant task provided by PDE Build. Here is an example:
<eclipse.fetch
    scriptName="fetch.xml"
    elements="feature@org.eclipse.platform-feature"
    directory="${basedir}/test.map"
    install="${basedir}/source"
    children="true"
/>
The above task generates an Ant buildfile called fetch.xml. It consists of Ant CVS tasks that retrieve the Eclipse Platform feature and all its plug-ins and fragments.

Generate Scripts

Once features, plug-ins and fragments are downloaded you need to generate their Ant buildfiles. This step is done by the eclipse.buildScripts Ant task provided by PDE Build. Here is an example:

<eclipse.buildScript
    elements="feature@org.eclipse.platform-feature"
    install="${basedir}/source"
    children="true"
/>
The above task will generate Ant buildfiles for the Eclipse Platform feature and all its plug-ins and fragments.

build.properties
The build mechanism is driven by a build specification. The specification for an individual plug-in, fragment, or feature is found in a build.properties file in the corresponding element (feature, plug-in or fragment). It is a simple properties file that describes, for example, where to find the source code for the element.  Other entries describe which files should be included/excluded in/from various forms of distribution (e.g., binary, source). The possible entries are described bellow:

custom = yes
Tells the script generator that no script is necessary for the current element. It is usually used when a custom build.xml script is provided. The build.xml script has to be in the root folder of the element.

bin.includes =
bin.excludes =

source.<jar_name>=<source_locations>
    Indicates, for the specified jar, where to find its source. The source_locations is a comma-separated list of [element-relative?] locations. Plug-ins [elements?] requiring compilation must define this entry.
    Example:
        source.resources.jar = src/

 

jars.compile.order = <comma separated list of JARs>
    Specifies in what order the JARs should be compiled. Should be used to solve build dependencies within the same plug-in/fragment.

    Example:

        jars.compile.order=resources.jar,lib/resources-ant.jar

Build

The generated build.xml scripts from the previous step have many targets. The public ones described bellow. These are the targets that a custom build.xml script must implement.

Feature targets:

all.children
    Calls plugin-template and fragment-template.

all.plugins
    Delegates target calls to all the feature's plug-ins.

all.fragments
    Delegates target calls to all the feature's fragments.

build.jars
    Generates the required jars for the feature and its children.

build.sources
    Creates all the *src.zip files corresponding to this feature's jars and its children. E.g. for startup.jar, it creates startupsrc.zip .

build.update.jar
    Creates a jar file containing a binary build of the feature. Source is not included. The jar is in a format supported by install/update.

gather.bin.parts
    Copies all feature relevant parts (defined by bin.includes and bin.excludes) to ${destination}/install/features/${feature}.

gather.logs
    Copies *.log files to ${destination}/install/features/${feature}.

gather.sources
    Copies files generated by build.sources (*src.zip) to ${destination}/install/features/${feature}.
 

Plug-ins and fragments targets:

build.jars
    Generates the required jars for this plugin/fragment.

build.sources
    Creates all the *src.zip files corresponding to this element's jars. E.g. for resources.jar, it creates resourcessrc.zip .

build.update.jar
    Creates a jar file containing a binary build of the element. Source is not included. The jar is in a format supported by install/update.

clean
    Cleans all temp files and folders plus files created by the script targets (e.g. *.jar, *.zip, ...).

gather.bin.parts
    Copies all plugin relevant parts (defined by bin.includes and bin.excludes) to ${destination}/(plugins | fragments)/(${plugin} | ${fragment}). E.g., ${destination}/plugins/${plugin}.

gather.logs
    Copies *.log files to ${destination}/(plugins | fragments)/(${plugin} | ${fragment}). E.g., ${destination}/plugins/${plugin}.

gather.sources
    Copies files generated by build.sources (*src.zip) to ${destination}/(plugins | fragments)/(${plugin} | ${fragment}). E.g., ${destination}/plugins/${plugin}.

General notes on PDE Build

This section is not organized in any way. It just contains general knowledge on the use and implementation of the PDE Build plug-in. Although it should be up to date there is no guarantee about it. Check with your favorite pde build developer before making any assumptions based on it.