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:

• View Android Source Code in Eclipse by Dr. Michael Forster of Google
• Browsing Android Source in Eclipse by Eric Burke
• Get source from the Android Open Source Project

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.

• Cupcake (1.5)
• Donut (1.6)
• Eclair (2.1)

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!

Sometimes you just want to ask questions and get answers. Here are 7 ways to do that.

1. d.android.com – especially the “Resources” tab

This is the canonical source for all things related to Android development and an obvious starting point. The site gets changed around occasionally – there used to be a “Community” tab with links to get support, but as of this writing the “Resources” tab is the place to start if you’re looking for answers to questions. Some of the following items are listed there, but this would be a short post if it were a complete guide! Anyway, check back there for further developments.

Of course, the site also has a pretty good search box to find help among the tutorials, blog posts, and documentation there.

2. IRC – #android-dev on freenode; developer office hours

As detailed in that “Resources” tab, anyone can join an ongoing chat on the freenode network – see the link for more information on how. For application development, the most relevant channel seems to be #android-dev; there are frequently several fairly knowledgeable developers (including ones that work at Google) lurking in that channel, and many are pretty helpful, even with “dumb” questions, as long as they are asked sincerely and follow netiquette. There are a few other channels for folks to talk about Android in general, about Android’s OS development, about root and ROM hacks, and so forth, but you’ll know when you need those.

Recently, Google developers have offered “office hours” on this IRC channel. It remains to be seen if they’ll keep doing this and how useful it will be, but give it a try. Questions may be asked (and later, answered) via the Moderator sessions that are set up for each session of office hours.

Update: Office hours are now once a week and questions should be asked at StackOverflow.

3. Twitter – #androiddev

The “Resources” tab notes that you can follow AndroidDev on Twitter. I haven’t found much benefit from it yet, and it’s been pretty quiet lately, but perhaps it will pick up.

Of more interest are other developers who are tweeting. Many are beginning to use the #androiddev hashtag when tweeting about application development (#android is pretty much dominated by speculation about hardware, OS, and app releases). Follow them, ask questions, and contribute to the conversation.

4. Google groups

Google groups are like mailing lists with better-than-usual web interfaces. A number of these are listed on the “Resources” tab, and you would do well to read the guidelines there. Probably the most immediately relevant are android-beginners and android-developers.

5. Stack Overflow

The Google groups are pretty great for conversations, but when you’re asking questions involving code and looking for detailed answers, a general conversational tool may not be optimal. Recently Google officially recognized that the Stack Overflow website was becoming popular for Android programming questions, promised to work with the site, and encouraged asking beginner questions there.

6. Books

Do books answer questions? Well, not directly, and furthermore you may be overwhelmed by the sheer number of Android books on Amazon. However, books have authors, and these days authors are often answering questions about the books on the book website. Of the very limited sample of books I’ve encountered, I’ve found Hello, Android to be helpful and relatively current. The book’s website has a link for discussions, and the author (by the way) runs the Planet Android blog aggregator. No, I wasn’t paid anything for that mention!

7. Local meetups

If you’re lucky enough to live in an area where there is already an Android meetup (or even a mobile development meetup) then you can join and try your questions in person. If no one has created one near you yet, create your own! You don’t need to be particularly experienced with Android to do it – create the event and people will come. I started one for the NC Triangle – if you’re in the area, come on by.

8. Bonus: the blogosphere!

There are a lot of blogs related to Android development; the best place to find them is on the blogroll for Planet Android. Some of these blogs will fill you in on information you can’t find anywhere else; for instance, I know of no one except Diego Torres Milano that’s talking about testing Android applications and TDD. Go to the relevant blogs and ask questions in the comments if you can. And if you can’t find anyone talking about what you want to know, become part of the solution and start your own blog! Discuss what you’re trying and the problems you’re having, and link to other blogs with pieces of the puzzle.

I hope this helps. Feel free to respond to this post with your feedback and ideas!

As with so many things, Eclipse is your friend if you just know how to set it up. As it turns out, Artem Russakovskii of Beer Planet recently wrote an excellent post with instructions for configuring Eclipse to auto-format your XML pleasingly so it will look more like this:

I can do no better than to refer you to the post. In case he moves it or something, the short-and-sweet version is:

1. Window -> Preferences -> XML -> XML Files -> Editor
2. Source -> Cleanup Document

Making your XML readable means it’s also a lot more writeable. The ADT GUIs for working with resources are very handy, and you might not think you want to write XML by hand, but Eclipse is your friend here, too: it will suggest and auto-complete tags and attributes for you.

Eclipse can suggest and auto-complete allowed tags, attributes, and values for attributes based on the XML schemas supplied by the SDK. If Eclipse isn’t automatically suggesting (or like me, you’ve turned off auto-suggestions because they’re annoying), you can just press Ctrl-Space with your cursor placed where you’d like a suggestion in the document, use the arrow keys to choose a suggestion, and hit Enter to accept one. As you can see above, the suggestions come with at least minimal descriptions to jog your memory. This makes writing XML “by hand” almost completely painless.

The emulator takes forever to come up

Yes, yes it does, especially the first time you start it. It’s emulating booting up a complete OS running on a different architecture (ARM processor) than your development machine – so yeah, it’s a little slow. If you have an Android device you know that even running natively it’s not exactly an instant startup, so expect some delays in the emulator too.

Just go ahead and start the emulator when you start Eclipse and it’ll be there when you need it. Keep it running, there’s no need to stop and start it all the time.

Why does deploying a package to the emulator keep failing?

Often this is because you’re trying to deploy before the emulator has finished booting (because you waited until you were ready to try out your app before starting the emulator). The Home process needs to be running before a deploy will work. It’s a common n00b mistake to try the “run” button on Eclipse, watch it start an emulator and fail to deploy, kill the emulator, and try it again – it will never succeed until the emulator finishes booting.

Deploy may also fail for basically the same reason when the device bridge server has failed (see below) and Eclipse DDMS starts a new emulator (or tries to).

Of course, the other reason deploying may fail is if there’s something wrong with your package. Perhaps the API you’re developing against isn’t available on the emulator, or you’ve messed up something in the application manifest. But those problems should be fairly easy to diagnose from the error messages on the console.

I keep ending up with emulators that can’t be attached to

I’m not sure why this happens – something to do with networking (esp. during suspend/hibernate), or non-Sun Java JDK, or updating components while an emulator is running. But sometimes you’ll be running an emulator and it won’t show up in the list of emulators (either the command line adb devices or in the Eclipse DDMS perspective – or I’ve seen it show up in the perspective but without any processes).

Of course the simple remedy is to kill the emulator and start a new one, but as noted previously, that takes forever. The emulator is  running – why can’t you connect to it?

Try using the “Reset adb” option from the DDMS Devices view menu, or restarting the server at the command line:

adb kill-server
adb start-server

Otherwise I don’t know what you can do. I have a question in about this and I’m waiting for an answer, too.

My emulator keeps offering to “force close” odd things, especially at startup

This is pretty common for me at least; you may never have seen it if you have better hardware. Just choose the “wait” option, everything will work out. I have a theory about this – perhaps someone who knows better will enlighten me if I’m wrong. Android has a policy of offering to force close non-responsive elements, where “non-responsive” means it hasn’t handled an event five seconds after it was notified of the event. As noted above, you’re running an emulator here, and it tends to run a bit slowly – but the clock is still ticking in realtime. I believe it’s simply a matter of certain parts of the operating system taking too long to respond, especially at boot time. Just ignore it and wait for them to finish.

(As of SDK 2.0.1)

The API levels 1.0 through 2.0.1 are versions of the framework with which you develop Android applications (see http://developer.android.com/guide/appendix/api-levels.html for more). They’re fairly backward compatible but not completely. These are also referred to by integer API numbers and sometimes names:

• 1 = version 1.0
• 2 = version 1.1
• 3 = version 1.5 (Cupcake)
• 4 = version 1.6 (Donut)
• 5 = version 2.0 (Eclair)
• 6 = version 2.0.1

The devices out there may be one of several different versions. At the time of writing, my stock T-Mobile G1 is at 1.6 (and may never get 2.0 as evidently the memory requirements are prohibitive). The Droid runs 2.0. I seem to recall hearing of another phone that was still stuck on 1.5 (the Cliq?). If you want to know the relative percentages of what’s out there, check the Platform Versions Dashboard.

When you develop an application, you have to specify what API level you’re developing for. Then the device will know whether it can support your application. For the widest support you’ll want the earliest feasible API (probably 1.5 for now), but then you’re missing out on the features of later APIs.

When you’re selecting the “target” for creating an emulator or developing an app, you also have a choice of developing against the Google APIs or not. These add more libraries for your application to use – currently, this is basically just if you want to integrate Google Maps into your application; later versions of the API may have other useful libraries. The language of “Google API” is a bit confusing when added to SDK/Android API versioning. It’s added functionality on top of the standard Android platform – each “Google APIs” target also includes the API platform with the number given.
]]> http://android.opensourceror.org/2009/12/22/whats-with-the-various-api-levels-and-types-in-the-sdk/feed/ 0 http://android.opensourceror.org/2009/12/14/the-eclipse-adt-plugin-for-creating-projects-says-i-need-to-choose-a-target-but-theres-nowhere-to-choose-a-target/ http://android.opensourceror.org/2009/12/14/the-eclipse-adt-plugin-for-creating-projects-says-i-need-to-choose-a-target-but-theres-nowhere-to-choose-a-target/#comments Mon, 14 Dec 2009 15:03:48 +0000 luke http://android.opensourceror.org/?p=26 This was a particularly frustrating one, but it’s really simple to resolve.

Creating a project - how do I specify the build target when none is listed???

This is a simple problem of screen real estate. When the dialog is not long enough vertically, the part that is shrunk (down to nothing!) to fit is the Build Target selection box. The only way to get it to show up is to expand the dialog vertically – you may have to increase your screen resolution to fit it all in (I found this out while working on an Eee PC – a screen height of 600 pixels won’t cut it!).

Each version of the android platform comes with several default skins which you can find located in the directories under <android-sdk-base-directory>/platforms/android-X.X/skins. An android skin consists of a single  layout file referencing a number of image files.

One particular skin that caught my eye was the platform-1.5/HVGA skin which looked most similar to the android-based phones I was looking at. However, not content with the drab maroon/red color scheme I decided to load up the main device background image in “The Gimp” image editing tool to add some zip. The results are shown below – a basic “leather” phone and “camo” style for military enthusiasts.

Sample Skins created for Android Emulator with The Gimp

I’ve made these two skins freely available for download in a zip file at the bottom of this post. Also included in the zip file is a gimp format file (device.xcf) if you’re familiar with the tool and would like to try overlaying your own textures using the “mask” layer. To use these skins, simply unzip the file into the skins directory of the platform(s) you are targeting.

The next step is to open the Android SDK and AVD manager, delete your existing Android Virtual Device, and add a new device for the platform and skin you wish to use:

Here is one other site I found with skins more closely matching real phones if you’d like to try them as well. Enjoy!

Android Skins (downloadable .zip file)

Illustrations of emulator usage in books and on the web have emulator skins that look like devices, but if your SDK is at all recent, the emulator doesn’t look like that – the screen is bare. This is a seemingly insignificant thing, but strangely no one seems to talk about it. I didn’t find any documentation explaining this – I had to ask like a n00b on the IRC channel. Well, to save you the embarrassment – it’s pretty simple. For the API 1.5 and before, the emulator looks like a device. For 1.6 and after, it doesn’t. If you really want your emulator to look like that, you need to use an emulator targeted at 1.5 or before – as far as I can tell, there’s no setting you can use to configure 1.6 or 2.0 to show the device skin from 1.5.

Emulators for versions 1.5 and 1.6

]]> http://android.opensourceror.org/2009/12/08/my-emulator-looks-different-than-in-the-examples/feed/ 7 http://android.opensourceror.org/2009/12/07/missing-dependencies-for-the-eclipse-adt-plugin/ http://android.opensourceror.org/2009/12/07/missing-dependencies-for-the-eclipse-adt-plugin/#comments Mon, 07 Dec 2009 13:26:43 +0000 luke http://android.opensourceror.org/?p=3 When installing the plugin, depending on your setup, Eclipse may fail with a message that dependencies are missing.

com.android.ide.eclipse.adt.feature.group requires 'org.eclipse.wst.xml.ui 0.0.0' but it could not be found

Unless your Eclipse is too old (the plugin requires 3.4 or above) this is not really a problem with Eclipse, the SDK, or ADT, but rather how various operating systems package Eclipse. The appropriate components need to be installed or Eclipse needs to be configured with the appropriate software update site for its version so that it can resolve dependencies for you.

For eclipse 3.5 (galileo) the appropriate update site is http://download.eclipse.org/releases/galileo – if it is missing, you add it in the same place you add the plugin:

Adding the Galileo (Eclipse 3.5) update site

OS-specific experiences

Under Windows, using the Java Developers version of Eclipse, I had no problems.

In Ubuntu 9.10 the default Eclipse install from the Ubuntu Software Center is almost useless. You need to use Synaptic to add to Eclipse after the default install is done; add the eclipse-jdt package. You also need to add the update site as above – it comes with none configured.

In Fedora, after installing elipse-platform and eclipse-jdt, I needed to go to Eclipse’s Software Sites dialog and enable the base site that was already there but disabled.

I haven’t tried it on Mac OS X; it probably just works, but comment here if that’s not so.