PDE/Build/FAQ

How do I run the PDE/Build JUnit tests

The PDE/Build JUnit tests are in the Git repository eclipse.pde.build under org.eclipse.pde.build.tests.

The tests require a special target platform configuration: Create a target definition with one location of type "Directory" pointing to an Eclipse SDK, e.g. in /dev/eclipse/, and set it as target platform. Place the delta pack in a folder next to the Eclipse installation. Example:

  /dev/eclipse/            (the directory pointed to in the target definition)
  /dev/deltapack/eclipse/  (unzipped deltapack)

The delta pack can be downloaded from each build (3.6.1 is here). The version of the deltapack being used must match the version of eclipse in your target platform.

Tests can be run by selecting individual test methods or test classes and doing Run As -> JUnit Plugin Test. The main test suite is PDEBuildTestSuite. Because of firewall issues on the test machines, the FetchTests are not part of the suite by default and a system property "pde.build.includeFetch=true" must be set to include them in the suite.

The tests will automatically create a junit-workspace/pde.build folder. Under this folder, each test will create a subfolder to use as a working area. The tests will automatically clean up these working folders unless the test fails, in which case the test folder is left so that the results can be inspected.

How do I add 'Eclipse-SourceReferences' Headers

Out of the box, PDE build does not generate Eclipse-SourceReferences headers when building bundles. The following property must be specified:

    generateSourceReferences = true

For more infomration see Source Reference Headers

How do I enable API tooling in a headless build

PDE Build can automatically call the API tooling ant task to generate API descriptions for your bundles. Just specify the following property in your build configuration build.properties file:

     generateAPIDescription = true 

Java source level problems during Export

• I set my compliance levels, why doesn't it work?
• How do I Compile against arbitrary JDKs?
• java.lang.UnsupportedClassVersionError

PDE/UI performs the export by using PDE/Build to generate build scripts. PDE/Build does not know anything about the Java Builder settings in your workspace or on your project. Your plug-in's manifest.mf and build.properties files are the input to PDE/Build. See this page for specifics on controlling the compilation environment for your plug-in.

The properties specifying the locations of the JDKs to compile against are automatically set during export by PDE/UI based on your installed JREs: Preferences->Java->Installed JREs->Execution Environment.

So, to set your compilation environment:

1. Setup your installed JREs in your preferences.
2. Set your Bundle-RequiredExecutionEnvironment in your manifest.
3. or set jre.compilation.profile in your build.properties
4. or set javacSource, javacTarget in your build.properties

Including files in the root of my build

Files can be included in the root of your build by using a Feature. See this page for the root properties to set in your feature's build.properties file.

If you are doing a product build using productBuild.xml and a .product file instead of a normal feature driven build, then you must somehow include your feature containing the root files. There are two possibilities for doing this:

1. Have your .product file based on features, and include your root feature. If your root feature does not containg the bin.includes property, then it will not be included in the final build results, but the root files will be.
2. If your .product file is based on plug-ins, you need to get your feature to be included in the generated container feature that is driving the product build. The feature generator allows you to specify a list of additional features and plug-ins to be included. Use the featureList property to add your root feature. Note that in 3.2, the productBuild.xml script did not pass this property to the feature generator (bug 158761). You will need to add it to the productBuild.xml:

<target name="generateFeature">
   <eclipse.generateFeature
      featureId="org.eclipse.pde.build.container.feature"
      buildDirectory="${buildDirectory}"
      baseLocation="${baseLocation}"
      productFile="${product}"
      verify="${verify}"
      pluginPath="${pluginPath}"
      configInfo="${configs}"
      pluginList="${pluginList}"
      featureList="${featureList}"
   />
</target>

Fetching the .product file in a product build

When using the productBuild.xml and a .product file to build your product, the feature or plug-in that contains the .product file must exist on disk before the fetch phase of the build. This is because we need to generate the container feature first so that we know what we need to fetch.

You can fetch the feature/plug-in containing the .product file using a custom step earlier on in the build. Use customTargets.xml, in the postSetup target, call ${genericTargets}/fetchElement. Something like:

 <ant antfile="${genericTargets}" target="fetchElement">
    <property name="type" value="feature"/>
    <property name="id" value="org.feature.containing.product.file" />
 </ant>

See bug 159128.

Problems parsing feature file in a product build

Error is something like:

org.eclipse.pde.build_3.2.0.v20060601\scripts\productBuild\productBuild.xml:45: 
Problems parsing the feature file:/build/features/org.eclipse.pde.build.container.feature/feature.xml.

or:

[eclipse.generateFeature] Could not read:
file:/tmp/builder/build/tempbuild/features/org.eclipse.pde.build.container.feature/feature.xml

This is bug 152577. The workaround is to modify the productBuild.xml to delete the feature before its regeneration in the generateFeature target:

 <target name="generateFeature">
    <delete dir="${buildDirectory}/features/org.eclipse.pde.build.container.feature"/>
    <eclipse.generateFeature
       featureId="org.eclipse.pde.build.container.feature"
       buildDirectory="${buildDirectory}"
       baseLocation="${baseLocation}"
       productFile="${product}"
       verify="${verify}"
       pluginPath="${pluginPath}"
       configInfo="${configs}"
    />
 </target>

How do I build from SVN

Out of the box, PDE Build does not have the ability to fetch code from a subversion repository. Some discussion have started to make Subversive Fetch task part of the BaseBuilder. Subversive provides an SVN fetch task. The corresponding plugin can be downloaded from Subversive's website and some documentation can be found on dedicated wiki page.

Before that, Chris Vines from the community created a plug-in adding this support. It can be found at [1]. Any specific problem with this plug-in must be reported there too.

Setting up a workspace to test builds

• Start a runtime workbench
• File -> New -> Project
• Name it "Builder"
• Finish
• File -> New -> Folder -> Builder/features
• File -> New -> Folder -> Builder/plugins
• Put your feature inside the Builder/features directory
• From the PDE/Build plug-in in your install, copy allElements.xml, build.properties and customTargets.xml to the Builder project.
• Edit Builder/build.properties
  • Set buildDirectory to be the file-system path of your workspace project. (e.g. d:/temp/workspace/Builder)
  • Set baseLocation to the file-system path of the target that you are building against (e.g. d:/R32/eclipse)
• In your dev, create a new Eclipse Application
  • Set the application to be org.eclipse.ant.core.antRunner
  • Set the arguments to be -buildfile ${resource_loc:/org.eclipse.pde.build/scripts/build.xml} -Dbuilder=d:/temp/workspace/Builder -nosplash
• Run the launch config.

Platform Specific fragments in Multi-Platform Product or Feature Export

When exporting a feature, or a product based on features you get an error like:

Unable to find plugin: org.eclipse.filesystem.win32.x86_1.1.0

or

Bundle org.eclipse.swt.gtk.linux.x86_0.0.0 failed to resolve.

This is caused by a missing ws/os/arch filter on the fragment's inclusion in the feature.xml. This can easily be set in the Plug-ins Tab of the feature editor by selecting the fragment on the left and specifying the Operating System, Window System and Architecture on the right. Or it can be set directly in the feature.xml :

   
<plugin id="org.eclipse.swt.gtk.linux.x86" os="linux" ws="gtk" arch="x86"
         version="0.0.0" fragment="true" unpack="false"/>

The feature lists everything that needs to be present for the export to succeed. Platform specific fragments will not resolve, and hence not be available, on platforms that do not match their Eclipse-PlatformFilter. In order to let export know that it is ok that this fragment is not available on this platform, a similar platform filter is needed in the feature.xml.