Wednesday, September 19, 2012

Android debugging using the framework source

When writing Android apps, it is helpful to be able to read the implementation of the framework to clarify a point.  This might be when the documentation is incomplete, or if you want to learn from canonical classes like ListView.

Nexus devices contain this framework code unmodified. This allows you to trace your application flow down to the framework level, either to learn how the platform works or to find a bug. Today, the cheapest Nexus device is $199, so having an additional Nexus device is an excellent tool for Android developers, even if you do most of your development for non-Nexus devices.

It is easy to get the source code from the Android Open Source Project (AOSP). You need the following:
  1. A good Internet connection. The full AOSP tree is well over 8 gigabytes of data. If you have more than one Android developer, you could download the tree for a single developer, and then mirror it locally.
  2. A fast computer. AOSP is a lot of code and Eclipse chews a lot of CPU and RAM with large projects. A computer with two CPUs and about 4GB of RAM should do perfectly, you might get away with lesser RAM.
  3. Disk space. If you choose to build the code, you're look at 30 gigabytes of disk space.
  4. Eclipse, some recent version and Sun's Java 1.6.
  5. Linux or Mac. The instructions work for Ubuntu 10.04/11.10/12.04 and some Mac version.

Here are all the steps:
  1. Set up your computer: This can be done on all developer computers simultaneously. This will install all the development tools. At the end of this, you have all the tools but no AOSP code.
  2. Download all the AOSP source: This uses your internet connection to download all the source. The AOSP source has everything going back to the earliest releases of Android. You get all source history, the framework, the open source applications, the kernel, all open drivers, everything. There are instructions on that page to set up a local mirror. Follow those steps to download the source once and then share it over your local network. This conserves bandwidth, and saves time. You might want to start this download over a weekend, depending on your network connection and other users' needs. I will assume that you are putting the source in /usr/local/aosp.
  3. Build the source. Here, you have two options. You could follow the AOSP instructions. However, if you just want to include the source in an eclipse project, those instructions are overkill. You can get a much smaller project if you follow these alternate instructions. If you have trouble with java versions, read the bottom of this post.
    $ cd /usr/local/aosp
    $ source build/envsetup.sh
    $ lunch full-eng
    $ # The following step takes time. -j<num jobs> increases parallelism.
    $ make -k -j2 sdk
    
  4. Create the Eclipse classpath. By default, we can create a project with all the Android source code. This is beneficial if you want to have access to all the AOSP code for reference. If you want just the framework, you can reduce the size of the project significantly. To do this, first create a file in the directory containing the following:
    $ cd /usr/local/aosp
    $ cat excluded-paths 
    ^external/.*
    ^packages/.*
    ^cts/.*
    ^dalvik/.*
    ^development/.*
    ^prebuilts/.*
    ^out/.*
    ^tools/.*
    ^sdk/.*
    ^libcore/.*
    ^gdk/.*
    ^hardware/.*
    ^device/.*
    
    This file allows you to reduce the size of the Eclipse project, which improves Eclipse's performance significantly. Now, we can generate the Eclipse classpath as follows:
    $ cd /usr/local/aosp
    $ ./development/tools/idegen/idegen.sh 
    Read excludes: 3ms
    Traversed tree: 781ms
    $ ls -l .classpath
    -rw-rw-r-- 1 user group 16938 Sep 18 21:50 .classpath
    
  5. Create the project in Eclipse. First you need to start Eclipse with increased heap size and virtual memory:
    $ eclipse -vmargs -Xms128m -Xmx512m -XX:MaxPermSize=256m
    
    Now, create a new Eclipse project (File -> New Java Project -> Next). In the dialog, under the "Libraries" tab, click the "Add Library" button -> Add System Library -> Add JRE system library. This will help resolve the references to core libraries like Integer and String. Adding the system library is not required, but it reduces the number of syntax error Eclipse finds with the framework. Click "Finish" when done.
  6. Done! Try your setup by searching (Ctrl-Shift-T) for FragmentManager. You should be able to see its source code, and navigate through its code. Some handy commands are: Ctrl-Shift-G to look for references of a class, and F3 to look for a method's implementation.

JDK version pain: You might encounter a problem with JDK versions. You need Sun Java 1.6 to compile the AOSP source code, while your Eclipse setup might require a different version (OpenJDK?). One solution is to use sun-java only to compile the AOSP, and switch back to the previous version after the compilation has finished. On Ubuntu, this is done with the commands shown below. Select the number that corresponds to sun-java before the compilation, and run these commands after running idegen.sh to switch back to your previous version of jdk.
$ sudo update-alternatives --config javac
There are 2 choices for the alternative javac (providing /usr/bin/javac).

  Selection    Path                                         Priority   Status
------------------------------------------------------------
  0            /usr/lib/jvm/java-6-openjdk-amd64/bin/javac   1061      auto mode
  1            /usr/lib/jvm/java-6-openjdk-amd64/bin/javac   1061      manual mode
* 2            /usr/local/sun-java-1.6/jdk/bin/javac         1         manual mode

Press enter to keep the current choice[*], or type selection number: 1
update-alternatives: using /usr/lib/jvm/java-6-openjdk-amd64/bin/javac to provide /usr/bin/javac (javac) in manual mode.
$ sudo update-alternatives --config java
There are 2 choices for the alternative java (providing /usr/bin/java).

  Selection    Path                                            Priority   Status
------------------------------------------------------------
  0            /usr/lib/jvm/java-6-openjdk-amd64/jre/bin/java   1061      auto mode
  1            /usr/lib/jvm/java-6-openjdk-amd64/jre/bin/java   1061      manual mode
* 2            /usr/local/sun-java-1.6/jdk/bin/java             1         manual mode

Press enter to keep the current choice[*], or type selection number: 2