How do I attach the sources for a library bundle in OSGi/Equinox/Eclipse?

Question

I created a library bundle for commons-lang3 and this works well. I can build the bundle, add a dependency and then use all the classes in this bundle in my plugins.

But I don't see the sources in the debugger.

What is the simplest way to create a source bundle for this library bundle?

PS: A library bundle is a plugin which contains the original JAR file; Eclipse doesn't compile the source again, it just adds the existing JAR to the classpath.

Answer 1

If you add the source files to their own jar then create a META-INF/MANIFEST.MF file with an 'Eclipse-SourceBundle' entry which specifies the symbolic name of your library bundle. Below is an example I have from the Felix jar:

Manifest-Version: 1.0
Eclipse-SourceBundle: org.apache.felix.main;version="4.0.1";roots:="."
Bundle-Version: 4.0.1
Bundle-Name: Apache Felix Framework
Bundle-ManifestVersion: 2
Bundle-Vendor: The Apache Software Foundation
Bundle-SymbolicName: org.apache.felix.main.source

To be able to view the source in Eclipse make sure this source jar is in your PDE target (Windows->Preferences->Plugin Development->TargetPlatform). If your using Eclipse itself as the target platform just drop it in to your eclipse plugins folder.

Answer 2

You can include the sources under the OSGI-OPT/src path of the bundle; then they will be seen by the Eclipse debugger (not sure about other IDEs, as I only use Eclipse). I find this a lot simpler than creating a separate source bundle, because one artefact is easier to manage than two, and if you build with Bnd or Bndtools, we create bundles like this by default.

In the rare cases when you need to deploy to a resource-constrained environment, you can simply remove the OSGI-OPT directory from the bundle; this name is a convention for optional data that can be removed without affecting the operation of the bundle.

Incidentally our approach is inspired by UNIX executables, which often contain extra debugging symbols, and the strip command that removes them to create a smaller executable when desired.