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]*]*

<source feature id>: This is the id of the source feature and plug-in to be generated. Normally it is something like <feature id>.source
<feature id>: The feature on which to base the source feature, the source for all contained plug-ins will be collected into the <source feature id> plug-in.
feature@<feature id>: This will include the named feature in the generated source feature.
plugin@<plug-in id>: This will include the named plug-in in the generated source feature. If the plug-in is JARed specify unpack="false". If multiple versions of the plug-in are available, specify the requested version using version=<pluginVersion> followed by qualifier.
attribute=value : Both feature@ and plugin@ entries can be qualified with additional attributes that should be added in the generated source feature.
Possible attributes (with example values) for feaure@ entries are:
- version = 1.0.0 : specify the version of the feature to include
- optional = true : set the included feature as optional
- ws=gtk : set the window system for the included feature
- os=linux : set the operating system for the included feature
- arch=x86 : set the architecture for the included feature
Possible attributes for plugin@ entries are:
- version = 1.0.0 : specify the version of the plug-in to include
- unpack = true : set the included plug-in to be unpacked (ie the plug-in should be installed as a folder).
- ws=gtk : set the window system for the included plug-in
- os=linux : set the operating system for the included plug-in
- arch=x86 : set the architecture for the included plug-in

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