Generating Source Features and Plug-ins
PDE Build can generate a source feature or plug-in. Consider the
following SDK feature:
features/
org.foo.sdk/
feature.xml: <includes id="org.foo.rcp" />
<includes id="org.foo.rcp.source" />
build.properties: [email protected] = 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 plugin 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>
plugin.
-
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: [email protected] = org.foo.nested
feature.xml: <includes id="org.foo.rcp" />
<includes id="org.foo.rcp.source" />
build.properties: [email protected] = org.foo.rcp, [email protected]
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>
Example:
features/
org.foo.sdk/
feature.xml: <plugin id="org.foo.rcp" />
<plugin id="org.foo.sdk.source" />
build.properties: [email protected] = org.foo.sdk