Attaching Android platform source in Eclipse

Are you tired of seeing this when you look at your platform JAR in Eclipse?

Dude, where's my source?

Or how about this when you’re debugging?

How am I supposed to debug this?

Android is open source, right? So how do we see the source?

Some background

  • Tip: If you’re just here to get it working and don’t care where it came from, you can skip on a bit.

This article summarizes and augments three other posts that spelled out how to get the source and use it. It is surprisingly difficult to get your hands on the correct version of the source you need for this purpose, so in addition to describing that process I’m providing the end result for your convenience.

My sources

My three source posts are:

Both the posts and the comments were very helpful, but somewhat out of date now. How to put it all together?

Getting the right code

The source is all available, but it’s spread out among several projects which put together constitute the Android Open Source Project. Thus I needed to install the repo tool (as described on the “Get source” page) in order to pull down all of the relevant git repositories. The articles describe getting the latest code – the trick is getting the code specific to the platform version you’re working on; at the time everyone was working with 1.0!

When you sync the Android repos, you’ll see output describing the available branches and tags something like this:

 * [new branch]      cupcake    -> korg/cupcake
 * [new branch]      cupcake-release -> korg/cupcake-release
 * [new branch]      donut      -> korg/donut
 * [new branch]      donut-release -> korg/donut-release
 * [new branch]      eclair     -> korg/eclair
 * [new branch]      master     -> korg/master
 * [new branch]      release-1.0 -> korg/release-1.0
 * [new tag]         android-1.0 -> android-1.0
 * [new tag]         android-1.5 -> android-1.5
 * [new tag]         android-1.5r2 -> android-1.5r2
 * [new tag]         android-1.5r3 -> android-1.5r3
 * [new tag]         android-1.5r4 -> android-1.5r4
 * [new tag]         android-1.6_r1 -> android-1.6_r1
 * [new tag]         android-1.6_r1.1 -> android-1.6_r1.1
 * [new tag]         android-1.6_r1.2 -> android-1.6_r1.2

This list generally contains some other random stuff and varies by project. The tags seem to be logically named and standardized across projects, but I couldn’t find how to get the repo tool to pull source based on a tag (if someone knows, by all means comment below). Repo takes the -b option to specify a branch however, and the cupcake / donut / eclair branches are universal, so those are what I used to make the source archives linked in this article, e.g.:

repo init -u git://android.git.kernel.org/platform/manifest.git -b cupcake
repo sync

Of course, branches are generally moving targets, so caveat emptor.

Assembling the code as Eclipse expects it

If you follow the above and have a good connection and some patience, you’ll eventually have a directory full of some 2GiB of “stuff,” some of which is the source code you’re looking for. But Eclipse needs just the source, in just the right place. Forster’s post “View Android Source Code in Eclipse” provides a python script for rounding up the source code and creating a nice zip archive out of it, and Burke’s post “Browsing Android Source in Eclipse” describes how to figure out where to put it – in a “sources” directory created underneath the SDK platform directory. Other comments on those posts are helpful for coercing Eclipse to recognize that the source is available.

What you came here for

Without further ado, here’s how you attach source to your platform classes. N.B. all screenshots are from Eclipse 3.5 “Galileo” – other versions may differ significantly.

Download source

Download the zipped source code that I’ve gathered for each platform you are developing for.

Put the source in place

For each platform, create a folder “sources” under that platform (e.g. sdk/platforms/android-1.5/sources) and unzip the source code into it. Then refresh your project (select project and press F5 or right-click and select “Refresh”).

Right click on the project and refresh

Voila, you should see the source!

YES, I SEE the SOURCE!

Getting the debugger on board

I found that even after I’d placed sources in the platform, if I was debugging and ended up deep in the platform (In this case, with an exception), the debugger might not show the code:

Sometimes the debugger still won't show the source

However, it’s fairly straightforward to fix this. Just click on that “Edit Source Lookup Path” button to add a source lookup path. In that dialog leave “Default” selected and click “Add.”

In the following “Add Source” dialog choose “File System Directory” and hit the OK button:

Then choose the source directory where you unzipped the code. The debugger should now show all the code you can debug into.

Source in the debugger... which may or may not help you figure out what went wrong; in this case, a layout error caught at runtime.

A word of caution, though: Eclipse’s debugger seems to think that once you’ve set a source lookup for one project, it’s relevant for all of them. If you’re using different platforms for different projects, you’ll want to change the source it uses. You can do that by right-clicking on the project in the debugger and choosing “Edit Source Lookup” to repeat this process.

Getting back to source lookup in the debugger

Patches welcome

Hopefully this guide makes attaching source easy for you. If the code provided here seems out of sync with the platform when you’re debugging, let me know. If someone knows a better way to pick out the exact code for the different platform versions, comment below. If I’ve slightly (or utterly) misrepresented something, correct me. If you’re just happy to finally see your source, I’d be glad to hear about it!

http://source.android.com/download/

.

Both comments and pings are currently closed.

34 Responses to “Attaching Android platform source in Eclipse”

  1. Andrew Louth says:

    Does anyone know where to get Android 2.2?

  2. Bruce says:

    RE Jason #5 – Not sure what you mean, but I think the middle section above describes the process… once the source repositories have been downloaded, the script from “View Android Source Code in Eclipse” (http://blog.michael-forster.de/2008/12/view-android-source-code-in-eclipse.html) will bundle up the relevant sources into a zip for you; a jar is a zip file, not sure if that answers your question?

  3. [...] יש דרך ארוכה ומפרכת להוציא אותו מהGIT שלהם, אבל אנחנו טובים בreuse ומישהו כבר עשה את זה לפנינו ולכן אני יכול להציג לכם קבצי ZIP מוכנים בחסות: http://android.opensourceror.org/2010/01/18/android-source/. [...]

  4. jianwu says:

    Thanks a lot.

  5. [...] what if you want to go one step further and debug into the code from your applications? Attaching Android platform source in Eclipse provides a great tutorial. There are even some pre-created zip files for Cupcake (1.5), Donut (1.6) [...]

  6. daniel says:

    Thanks for your work, you saved me quite a bunch of time.

  7. Amir Szekely says:

    Extremely useful, thanks! Took me a few hours to do this last time, but with your ZIP file it’s a breeze.

  8. Amy says:

    Awesome job putting this together. I laughed out lout when I saw the first two screenshots… yes I **AM** tired of seeing that! Thanks for the ‘fix’; it’s appreciated.

  9. grism says:

    In my opinion you commit an error. I can prove it. Write to me in PM, we will talk.

  10. blair says:

    Please ignore my last comment. It seems I had the source after all.

  11. blair says:

    Thanks for this tarball. It really helps.

    However, when I receive a runtime exception in android.app.ActivityThread there’s no source. So perhaps for your next release you might include this class too.

    Thanks again :)

  12. JC says:

    Thanks for spending the time to put this together, you saved me and others lots of time, download, unzip, refresh… worked first time … excellent.

  13. jk says:

    There is much win, here. Thankyah.

  14. jb says:

    Thank you very much!

  15. Yuan says:

    Great! This is exactly what I’m looking for. Thank you!

  16. Srujana says:

    Hello. A little addition to the above comment..I can get the debugger to go into the source code in the debug perspective,after edit source lookup.:) :) :)
    I still can’t get the source to show up in the java perspective,though.Would appreciate any advice on that.
    Thanks for the great work!! My eyes popped out when the debugger went right into the source! You’re a gem!

  17. Srujana says:

    Hi.Great work! I have a little problem setting up the debugging though,the source code just doesn’t come up for me.
    I pasted the contents of sources-1.5-cupcake into sources folder of android-1.5 and refreshed eclipse. no change.

    Is there anything else i can try?
    thanks

  18. hottex88 says:

    Could it be possible to make a source zip for 2.0 and 2.0.1 as well?

  19. Jim Blackler says:

    You are an absolute star. Thank you so much.

  20. Andrew Louth says:

    Really excellent post. Just what I needed.

  21. Jian Jiang says:

    Try to change your android build target several times on one of your android project within Eclipse and check then your C:\YourWorkSpace\.metadata\.plugins\org.eclipse.jdt.core\.org.eclipse.jdt.core.external.folders\.project file and you will see the following content:

    .org.eclipse.jdt.core.external.folders

    .link0
    2
    C:/software/android/android-sdk-windows/platforms/android-1.6/sources

    .link1
    2
    C:/software/android/android-sdk-windows/platforms/android-2.1/sources

    .link2
    2
    C:/software/android/android-sdk-windows/platforms/android-1.5/sources

    .link3
    2
    C:/software/android/android-sdk-windows/platforms/android-2.0/sources

    This approves how android expect where the sources folder are.

  22. pambuk says:

    Works like a charm, thanks!

  23. Sharon says:

    Awesome job putting this together. I laughed out lout when I saw the first two screenshots… yes I **AM** tired of seeing that! Thanks for the ‘fix’; it’s appreciated.

  24. bo says:

    Thanks man, much needed and much appreciated!

  25. Jags says:

    Guys, I think I have figured out how to get sources matching a particular tag. After ‘repo init’ with the required branch (-b), if you go to ~/mydroid/.repo/manifests, you will see manifest files for each tag. Do a ‘repo init -u git://android.git.kernel.org/platform/manifest.git -m android-2.0_r1_snapshot.xml’ or something similar. Right now, I see manifest files for tags only in eclair branch.

  26. luke says:

    RE Jason #5 – Not sure what you mean, but I think the middle section above describes the process… once the source repositories have been downloaded, the script from “View Android Source Code in Eclipse” (http://blog.michael-forster.de/2008/12/view-android-source-code-in-eclipse.html) will bundle up the relevant sources into a zip for you; a jar is a zip file, not sure if that answers your question?

  27. Brock says:

    I’ve done this the long way before, via Cygwin and Git (in windows), but it is very nice to have have all of the code bundled up in ZIP files like this. I’d been dreading getting my workspace up to date, but it only took me a few moments. Thank you!

  28. Jason says:

    hi if you dont mind, may you please share how you jar the different platforms? thanks

  29. Huy says:

    Very nice!

  30. lencinhaus says:

    Great job! thanks a lot

  31. Perty says:

    Thanks… Very much!

  32. WANG Chi says:

    Thanks a lot, this solves my problem!

Subscribe to RSS Feed Follow me on Twitter!