General

What is PDE

How do I test my plug-ins

The Eclipse PDE component provides a great way to test and debug your Eclipse plug-ins in a runtime environment. This is typically called self-hosting. The Eclipse you launch from is your host Eclipse, while the Eclipse instance you start is the runtime workbench.

PDE provides highly customizable launch configurations for self-hosting, but the default options will be enough for many users. There are also actions to run and debug your code in a runtime workbench in the top right corner of the PDE manifest editor, plug-in editor, product editor and more.

To create a new launch configuration, open the launch configuration dialog from the main menu, selecting Run > Run Configurations. From there you must create a new Eclipse Application. Pressing Run will launch the runtime workbench using code from your workspace and target platform.

PDE Build

Target Management

Why do I get an popup dialog saying I have selected a target with a newer version than your current Eclipse installation?

This happens because PDE detects a newer version of the OSGi runtime in your target platform than in your host installation. To resolve this problem, don't point to a target that may contain future versions of Eclipse or just upgrade your current host to a newer version of Eclipse. In the end, this message is trying to convey that PDE is backwards compatible only, not forward compatible.

Products

Why doesn't my JRE get included in a headless build?

At the moment, there is a disparity between PDE UI and Build when it comes to JREs and product definitions. The best way to get your JRE to be included in a headless and UI build is to use root files.

Classpath

How do I find a plug-in (bundle) given a class

If you're interested in finding a class at runtime, please use the PackageAdmin service from OSGi

How do I get access to a plug-in (bundle) in my workspace or target

Use the PluginRegistry API to acquire models from your workspace or target

I have an error that says some package (e.g., com.sun.misc) isn't accessible but it's on my classpath

In most cases, people get this error by accessing the Base64 class from the Sun VM. We generally don't recommend using the Base64 class from the VM because your bundle will be tired to only VMs that have that specific class. However, if this isn't an issue, you can get around the access restriction error by adding an access rule to your system library to make the package accessible. You can do this on the Libraries tab of the Java Build Path project properties. Add an Accessible rule for com/sun/misc/*

Also, in most cases, this package needs to be visible during runtime. To have a package visible during runtime, you will need to add the org.osgi.framework.system.packages.extra system property. For example:

API Tooling

How do I enable API Tooling for my projects

How do I enable API Tooling for headless builds

Build and Deployment Errors

There are a few differences between the environment provided by PDE and the actual deployment environment. PDE's training wheels are a great help when you're developing, but losing them is painful when finally putting together a product!

The first step in diagnosing deployment errors is to examine your workspace/.metadata/.log. The workspace is specified by the osgi.instance.area.default and osgi.instance.area system properties.

My product fails to start

Typical startup problems are:

Missing necessary files (e.g., plugin.xml, Application.e4xmi) in your build.properties. As a result, these files are not being exported. Such errors are typically revealed in your .log.

Unspecified start levels for key bundles like org.eclipse.equinox.ds. Start levels are generally specified in your .product file, though it is possible to provide hints through [p2 metadata] for a bundle.

A typical .product file might include the following configuration stanza:

My bundles aren't loading

See Where Is My Bundle? for an overview of how to use the OSGi console for diagnosing problems.

Why aren't my launcher icons being found?

Different build tools interpret the file paths in a .product differently. See [1] for ome details.

Why aren't my class files being bundled?

Occasionally you will find that a built bundle seems to be missing the generated .class files. This problem generally occurs because the build.properties file is missing a reference to ".". A typical build.properties file looks like:

OSGi uses the Bundle-Classpath entry in a bundle's MANIFEST.MF to decide how to resolve classes within the bundle. This entry is a comma-separated list of directories and jar files from which classfiles are resolved. An absent Bundle-Classpath is interpreted as ".", meaning the root of the bundle.

Earlier versions of PDE did not automatically add a "." when a Bundle-Classpath is first added to a MANIFEST.MF. The workaround is to either explicitly add "." to the MANIFEST.MF, or use the PDE Manifest editor to Runtime > New (in the Classpath section) and add ".". (Note that this advice is specific to the default setup from PDE where classes are directly placed in the bundle rather than in a separate jar file.)

Why am I getting a "package uses conflict"?

"Package uses" are akin to a bundle's require-bundles: they specify a package's dependent packages. Package-uses conflicts are fortunately somewhat rare, but are obscure and difficult-to-diagnose problems. Basically they occur when a bundle's imports causes two different versions of a package to be available within the same bundle — there is no way for the framework to decide which package to allow. The articles linked to earlier in this paragraph provide more detail.

Package uses conflicts often occur with system-level packages from the JVM's execution environment (e.g., javax.transaction) are made available, either via system bundle extensions or the org.osgi.framework.system.packages and org.osgi.framework.system.packages.extra properties (and possibly the Equinox Launcher's compatibility boot-delegation too). For example, many modern JREs now include javax.transaction, javax.annotation, javax.inject, and javax.vecmath, which many apps previously brought in through other bundles. When these packages are exposed through the system bundle, any bundle that re-exports the system bundle (notably org.eclipse.core.runtime) will also expose those classes. Conflicts arise when also including a bundle using a "Dynamic-ImportPackage" as the import set has to be verified against the packages available.

Diagnosing package-uses conflicts can be painful, and Equinox's diagnostics unfortunately omit the offending package names. The Eclipse Virgo project apparently has some enhanced diagnostics. Given a bundle, use the Equinox Console to examine the bundles providing that package using the packages command.
Otherwise set a breakpoint in Equinox's org.eclipse.osgi.internal.module.ResolverImpl#findBestCombination(ResolverBundle[],Dictionary) to examine the local packageConstraints variable.

Misc

How do I add my own template to the New Plug-in Project Wizard

The org.eclipse.pde.ui.pluginContent extension point is what you need. There's a fantastic article on this topic at developerWorks.

How do I know if my project is a plug-in project

In PDE, projects have a specific nature (see the .project file) associated with them if they are a plug-in. The PDE nature is:

When you build bundles using PDE build, you can choose to generate these source bundles.

Please note that it is not possible to attach sources manually for bundles because the classpath is created from the MANIFEST.MF content automatically. Manual changes to the classpath container are not allowed because they would be overwritten.