Attaching sources to android dependencies in eclipse

The problem

Up until recently is has been impossible to attach source code to any of the jar files contained in the ‘android dependencies’ portion of an android project in eclipse. If you are trying to debug into a third party library or understand how something works then this is very annoying. Fortunately in version 20 of the android development tools, Google have provided a work around of sorts. Its all detailed in the following bug reports:

https://android-review.googlesource.com/#/c/35702/
http://code.google.com/p/android/issues/detail?id=28658

How to attach source

You need to create a properties file with the same name as your .jar file and place it in the same directory as the jar (this is usually ‘libs’). Inside the properties file you can specify the location of the source code and documentation for a jar. So for example if my project contains

libs/abc.jar

I would create a file named:

libs/abc.jar.properties

Which contains details on the path to the source code of abc.jar .  This could be to a jar file containing the source or to a directory where the source lives.  The path could be relative or absolute.

src=/Users/lukesleeman/Documents/Android dev/abc-src.jar

Now when you attempt to view any of the class files contained inside ABC.jar eclipse will automatically display the source.  You can also place a ‘doc’ element in the properties file if you have the javadocs but not the source code.

Some gotchas

  • I found that when I first created the .properties file I needed to restart eclipse before it would pick up the source.
  • if you are a windows user don’t forget that windows uses \ as a path separator. So your ABC.properties should look like SRC=c:\\asdf\\asdf\\abc-src.jar .  This comment has some more information.