What is PDE Core?

    PDE Core is a plug-in that helps users building their own plug-ins. The term building here is related to deployment and not development. Basically, PDE Core takes an Eclipse Plug-in Project, its plugin.xml and build.properties files and generate 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. A file called directory.txt is responsible for identifying where, how and which plug-ins should go to the build machine. Ths file is basically a Java properties file where the entries have the following format: element@element_id=tag,:connection_type:user@host:repository
Examples:

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

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

Build
    This step is basically executed by Ant, although we do need Eclipse defined tasks and types. One important thing here is to know exactly what targets to call in order to get the desired result.
 

How do I use PDE Core?

Fetch

    PDE Core provides the org.eclipse.pde.core.fetch application...
    ...
    explain the ant task as well
    ...

Generate Scripts
    In order to generate build.xml scripts for some element, it is necessary to use the org.eclipse.pde.core.script application extension point provided by PDE Core. The arguments for this application are:


Examples:

(1) java -cp startup.jar org.eclipse.core.launcher.Main
         -application org.eclipse.pde.core.buildScript
         -elements plugin@org.eclipse.core.resources
         -install c:\mybuild\

(2) java -cp startup.jar org.eclipse.core.launcher.Main
         -application org.eclipse.pde.core.buildScript
         -elements plugin@org.eclipse.core.resources,fragment@my.fragment
         -install c:\mybuild\

(3) java -cp startup.jar org.eclipse.core.launcher.Main
         -application org.eclipse.pde.core.buildScript
         -elements feature@org.eclipse.platform.feature -nochildren
         -install c:\mybuild\

    ...
    [explain the ant task as well]
    ...
 

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. It is a simple properties file that describes 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 =
jar.external =

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/

zip.external =
zip.program =
zip.argument =
${zip.file}

jars.compile.order =
 

build variables
    There are currenttly 4 build variables: os, ws, nl and arch. The build.properties file or a custom build.xml script can make use of them in order to create platform specific builds. They can be referenced inside the script as normal Ant properties, whose values are referenced by ${variable_name}.
    In the build.properties file, they can be used as follows:

  ${os/linux}.bin.includes = src/linux
        Indicates that the folder src/linux should be include to the bin target if os=linux .

  ${os/linux,ws/motif}.bin.includes = src/linux
        Indicates that the folder src/linux should be include to the bin target if os=linux and ws=motif .

  ${ws/motif}.bin.includes = src/motif
        Indicates that the folder src/motif should be include to the bin target if ws=motif.
 
 

Build

    The generated build.xml scripts from the previous step have many targets. They public ones described bellow. These are the targets that a custom build.xml script has to 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}.
 
 

To be implemented: