Practical Open Source

Android is an open-source project, which has a bunch of cultural and economic consequences. I’m going to ignore those today, and describe how I use the source code to get work done.

Getting the Source · Before you can do anything with the source code, you have to go get it. This could be a daunting task if you’re not familiar with what a “case-sensitive filesystem” is, or how to use the git distributed version control system.

Fortunately, over at source.android.com there are step-by-step instructions that’ll let you get by even if you’re only lightly acquainted with all that stuff.

I’d advise you, if you’re doing anything substantial with Android, to go grab that source code. It takes less than 10G of disk space, and if you haven’t done this kind of thing before, you might find that it feels empowering.

Learning By Example · The Android SDK documentation is, by the standards of commercial APIs, pretty good. By the standards of open-source projects, it’s excellent. But it’s not complete. It’s very hard to combine reference rigor (describing exactly what some method does, with tutorial hand-holding (teaching why and how you’d go about using that method).

In a lot of cases, no documentation can substitute for the experience of looking at how someone who knows what they’re doing has used the piece of the framework that’s puzzling you. That’s what the Android source is good for.

Unfortunately, it can be a little tricky. I just checked a (behind-the-firewall) snapshot of the recent source code, and discovered that it contained 20,989 “.java” files and 6,992 “.xml” files. So, finding what you’re looking for can take some work.

Basic Tools · There are a variety of tools around for doing this, but if you’re working on a Mac or a Linux box, the built-in command-line shell has what you need. Suppose, for example, that I wanted to figure out the use of CallLog.Calls, which exists to help you work with entries from the phone log. I have a little shell script around called “jgrep”, so I hop over to the top of the source-code directory and say:

jgrep CallLog.Calls

Here’s what’s inside that “jgrep” script:

#!/bin/sh
find . -name '*.java' -print | xargs grep "$@"

[Update:] Hah, Jim Ancona in the comments below points out that the Android source tree comes with a pre-built version of “jgrep”, which is called... “jgrep”.

If I run it against my current source-code snapshot, I get 40 results, of which one is the Compatibility Test Suite, 5 are in the android.providers package, and the rest are in the Google-provided apps.

There’s plenty of information in there to help you to figure out how other people have used this class, if you should, and if so, how.

Getting Fancy · There are lots of times I don’t use “jgrep”, because I want to do something a little fancy, like exclude test-suite files, or look at XML files, or in one step edit all the files that match what I’m looking for.

If you want to do this, you’re just going to have to get comfortable with the programs that are used to build jgrep: find, xargs, and grep. They all have very complete online reference documentation, and the Web is full of examples. I suspect that anyone who’s spent any time as a developer on a Unix-derived platform (Mac, Linux, Solaris, *BSD) will have some feel for find and grep, but quite a few people have never been near xargs. It’s used mostly like this, with find; it takes the potentially thousands of filenames that find prints out and passes them as arguments to whatever other command you’ve provided, in this case grep; it calls grep as many times as necessary and as few as possible to get through all the filenames. The trick is, it knows how many filenames you can pass to a command without anything breaking.

Other Alternatives · I suppose if you loaded the whole Android Open-Source Project into some IDE like Eclipse or NetBeans or IntelliJ, you could get its “Find Usages” tool to find what you want. Has anyone done that?

This find/grep pattern is common enough that there’s a combo tool called “ack” which may already be installed on your computer. You can say:

ack --java CallLog.Calls

My problem with ack is that it’s much slower than just using the built-in tools from the command line. Like 1:40 as opposed to 0:38 for that command on my Mac.

find on my Mac is supposed to have an -exec grep pattern {} + argument which has the same effect, but it seems to Just Not Work for some reason I can’t figure out.

The Next Step · After you’ve found Android code that does something along the lines that you were planning to do, the next step is to... steal it! That’s what it’s there for. Well, since the license invoked at the top of every source file makes it clear that you can copy and re-use the source, it isn’t stealing. But it is what makes open source great.

---

---

Contributions