Generating Source Features and Plug-ins

Starting in 3.4, Eclipse has shipped with individual source bundles which allow for more flexible delivery of source. See the "Individual Source Bundles" page for details. Traditional folder-shaped source plug-ins can still be built as outlined below.

Consider the following SDK feature:


features/
org.foo.sdk/
feature.xml: <includes id="org.foo.rcp" />
<includes id="org.foo.rcp.source" />
build.properties: generate.feature@org.foo.rcp.source = org.foo.rcp
org.foo.rcp/
feature.xml: <plugin id="org.foo.BundleA" />
<plugin id="org.foo.BundleB" />
<plugin id="org.foo.BundleB.win32" fragment="true" os="win32" />

The idea of the SDK is that it includes a feature as well as the source for that feature.  Notice the generate.feature property in the feature's build.properties file.  This property tells PDE Build to generate a feature named "org.foo.rcp.source" based on the contents of the feature "org.foo.rcp".  PDE build will generate an org.foo.rcp.source feature, a plug-in that will contain the source code, and fragments containing the source of any platform specific bundles that were included in the feature:


features/
org.foo.rcp.source/
feature.xml: <plugin id="org.foo.rcp.source"/>
<plugin id="org.foo.rcp.source.win32" fragment="true" os="win32" />
plugins/
org.foo.rcp.source/src/
org.foo.BundleA/src.zip
org.foo.BundleB/src.zip
org.foo.rcp.source.win32/src/
org.foo.BundleB.win32/src.zip

Customizing the Generated Source Feature

The generate.feature property has the following form:

generate.feature@<source feature id> = <feature id> [, feature@<feature id>[;attribute=value]*]* [, plugin@<plugin id>[;attribute=value]*]*

Use plugin@ to add additional plug-ins that weren't part of the original feature to the generated source feature.  This is useful for documentation plug-ins.  The feature@ together with a source template can be used to nest source features (see below).

Source Templates

The feature from which the source feature is being generated can provide template files to be included in the generated source feature:


features/
org.foo.rcp/
sourceTemplateFeature/<files to be included in generated source feature>
sourceTemplatePlugin/<files to be included in generated source plugin>
sourceTemplateFragment/<files to be included in generated platform specific fragments>

Any files located in these sourceTemplate folder will be included in the appropriate generated feature/plug-in/fragment.  Specifically, files from these directories will replace files generated by PDE build.  This can be used to provide a custom feature.xml if there are requirements for your source feature that PDE build does not support.

Nesting Generated Source Features

You can nest source features by providing a sourceTemplateFeature/build.properties file for your generated source feature that contains a generate.feature property for the nested source feature.  You will also need to ensure that your top source feature.xml includes the nested source feature, do this either by using feature@ or by providing a template feature.xml:

features/
org.foo.sdk/
sourceTemplateFeature/
build.properties: generate.feature@org.foo.nested.source = org.foo.nested

feature.xml: <includes id="org.foo.rcp" />
<includes id="org.foo.rcp.source" />

build.properties: generate.feature@org.foo.rcp.source = org.foo.rcp, feature@org.foo.nested.source

org.foo.rcp/...
org.foo.nested/...
In the above example, org.foo.sdk contains a generated source feature named org.foo.rcp.source.  This generated source feature will get the template sourceTemplateFeature/build.properties file.  It will also include org.foo.nested.source in its feature.xml.  So when PDE build is processing the generated org.foo.rcp.source, it sees the inclusion of the org.foo.nested.source feature and the generate.feature property and then generates the org.foo.nested.source.

Generating a Source Plug-in

It is also possible to generate a single source plug-in based on a feature instead of generating an entire source feature.  The property to do this is:

generate.plugin@<source plug-in id>=<feature-in id>

Be aware that these old-style source plug-ins (one plug-in containing the source for all plug-ins of the feature) must be installed in folder form. Therefore you have to set the unpack="true" attribute in the file feature.xml.

Example:
features/
org.foo.sdk/
feature.xml: <plugin id="org.foo.rcp" />
<plugin id="org.foo.sdk.source" unpack="true" />

build.properties: generate.plugin@org.foo.sdk.source = org.foo.sdk