Individual Source Bundles

The traditional format of source bundles in Eclipse was a folder containing src.zip's for all the plug-ins included in a given feature. Starting in 3.4, Eclipse now ships with individual source bundles. For each bundle there is a corresponding source bundle which is a jar containing the source for that bundle. This allows for more flexible delivery of source, and it also alleviates some path length issues that may be experienced on some platforms.

Eclipse-SourceBundle

A source bundle is identified by the presence of the Eclipse-SourceBundle header in its manifest. The format of this header is:

Eclipse-SourceBundle: <bundle-id>;version=<version>;roots:="root1, root2"

The bundle-id and version indicate the bundle that the included source code corresponds to. The roots directive indicates the folders within the source bundle that actually contain source code. If no roots directive is specified, then a value of "." is assumed.

Class file libraries are mapped to source locations in a predictable manner. The root of the plug-in maps to the root of the source bundle. This is the main case for most jarred plug-ins. If the plug-in contains additional libraries "foo/lib.jar", the source is expected to be in corresponding "foo/libsrc/" folders in the source bundles.

Example 1 : The org.eclipse.pde.core bundle has class files in the root of the jar, plus a nested jar "ant_tasks/pde-ant.jar". Therefore, the source bundle should have java files in the root and java files in a "ant_tasks/pde-antsrc" folder. The roots directive lists both the root of the source bundle "." and the "ant_tasks/pde-antsrc" folder.
```
org.eclipse.pde.core.jar		org.eclipse.pde.core.source.jar
  - org/**/*.class			  - org/**/*.java
  - ant_tasks/pde-ant.jar		  - ant_tasks/pde-antsrc/org/**/*.java


Eclipse-SourceBundle: org.eclipse.pde.core;version="3.4.0.N20071128-0010";roots:="ant_tasks/pde-antsrc,."
```

Example 2 : The org.eclipse.pde.build bundle is a folder on disk. It contains a pdebuild.jar and a lib/pdebuild-ant.jar. The source bundle will be a jar that contains a "pdebuildsrc" folder and a "lib/pdebuild-antsrc" folder.

org.eclipse.pde.build/			org.eclipse.pde.build.source.jar
  - pdebuild.jar			  - pdebuildsrc/org/**/*.java
  - lib/pdebuild-ant.jar		  - lib/pdebuild-antsrc/org/**/*.java


Eclipse-SourceBundle: org.eclipse.pde.build;version="3.4.0.N20071128-0010";roots:="pdebuildsrc,lib/pdebuild-antsrc"

Generating Individual Source Bundles

PDE/Build can automatically generate individual source bundles, but only in a headless build. Individual soure bundle geneation can be turned on by specifying:

individualSourceBundles=true

This must be specified in the build configuration's top level build.properties file and it controls all source generation for that build. See Generating Source Features and Plug-ins for details on generating traditional source plug-ins and features, the remainder of this page assumes familiarity with traditional source generation.

generate.feature

In a feature's build.properties file, the generate.feature property tells pde.build to generate a source feature.

generate.feature@<source feature id> = <feature id> [, feature@<feature id>]* [, plugin@<plugin id>]* [, exclude@<plugin id>]*

When generating individual source bundles, this property remains as before and supports the same attributes (eg version, unpack, optional, etc), the difference will be noticed in the resulting source feature. Before, the source feature would have included 1 source plug-in + a source fragment for each platform being built. In the new format, the source feature will include a source bundle for each plug-in/fragment listed in the original feature.

Plug-ins that were included in the source feature via the plugin@ syntax will not get corresponding source bundles. This is useful for adding doc plug-ins to the source feature.

The exclude@ entry is new for individual source generation. Some plug-ins that were included in the originating feature (ie doc plug-ins or fragments that contain only native code) may not have source and should be excluded from the generated source feature. The exclude@ entry supports a version attribute.

Example:

generate.feature@org.eclipse.jdt.source=org.eclipse.jdt, plugin@org.eclipse.jdt.doc.isv;unpack="false",exclude@org.eclipse.jdt.doc.user

generate.plugin

In the old format, the generate.plugin property generates a source plug-in based on the contents of a given feature. When generating individual source bundles, this changes to be based on a given plug-in:

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

The generate.plugin property was used by features to include source without having a source feature (even though behind the scenes an entire source feature was generated). When generating individual source bundle, features will need to include a *.source bundle for each plug-in along with a corresponding generate.plugin property for each one.

Example: The sdk.examples feature used to look like this:

   	<feature id="org.eclipse.sdk.examples"  ... > 
		....
		<plugin id="org.eclipse.sdk.examples.source"  version="0.0.0"/>
		<plugin id="org.eclipse.sdk.examples.source.win32.win32.x86" version="0.0.0"/>
	</feature>

	generate.plugin@org.eclipse.sdk.examples.source=org.eclipse.sdk.examples

This changes to:

	<feature id="org.eclipse.sdk.examples" ...>
		...
		<plugin id="org.eclipse.compare.examples.source"  version="0.0.0"/>
		<plugin id="org.eclipse.debug.examples.core.source" version="0.0.0"/>
		<plugin id="org.eclipse.swt.examples.source" version="0.0.0"/>
	</feature>


	generate.plugin@org.eclipse.compare.examples.source=org.eclipse.compare.examples
	generate.plugin@org.eclipse.debug.examples.core.source=org.eclipse.debug.examples.core
	generate.plugin@org.eclipse.swt.examples.source=org.eclipse.swt.examples

generateSourceBundle

Specific plug-ins may not require source bundles because they don't actually contain source. This may occur with platform specific fragments that only contain a native library. In this case, the bundles may be excluded by the feature as outlined above in generate.feature.

Or, bundles can explicitly specify in their own build.properties file that no source bundle should be generated for them:

generateSourceBundle=false

Custom Content

Custom content can always be added to generated source bundles using the post.gather.source custom callback in the originating bundle. (See Feature and Plug-in custom build steps).

When doing this, set the property "src.additionalRoots" in the plugin's build.properties file so that the generate source bundle has the correct roots directive on the Eclipse-SourceBundle header.

Example:

org.junit4 :
   build.properties
      src.includes = about.html,junitsrc.zip
      src.additionalRoots=junitsrc
      customBuildCallbacks=customBuildCallbacks.xml

   customBuildCallbacks.xml
    	<target name="post.gather.sources" >
		<mkdir dir="${target.folder}/junitsrc"/>
		<unzip src="${target.folder}/junitsrc.zip" dest="${target.folder}/junitsrc" overwrite="false"/>
		<delete file="${destination.temp.folder}/junitsrc.zip" />		
	</target>

Branding the Source Feature

Previously, the generated source plug-in served as a branding plug-in for the generated source feature. Branding files (about.properties, eclipse32.gif, etc) were provided using the sourceTemplatePlugin directory in the original feature.

When generating individual source bundles, the branding plug-in for the source feature will be the source bundle corresponding to the original branding plug-in. This means that branding files for the source feature's branding plug-in can be contributed using the src.includes property in the original branding plug-in.

The sourceTemplatePlugin folder of the feature for which we are generating source also contributes files to the branding plug-in.

sourceTemplatePlugin vs sourceTemplateBundle

Previously, the contents of the sourceTemplatePlugin directory of the original feature was copied into the source plug-in. When generating individual source bundles, this remains true only for the branding source bundle (see above).

For all the other source bundles, the contents of a sourceTemplateBundle directory will be copied over.