Feed on
Posts
Comments

Android Source Code

I was involved into related activities lately, so there are a couple of things I would like to share.

I’m not going to tell the whole store here, as it is covered rather precisely in the official papers on the point:

  • http://source.android.com/source/downloading.html
  • http://source.android.com/source/initializing.html
  • http://source.android.com/source/building.html
  • http://source.android.com/source/using-eclipse.html

The purpose of the post is to make some notes on the setup process and to go a bit further. Major point on this way is to understand that at least basic literacy in Android development is required to pass through the process smoothly. You should not start platform investigation with building Android core from the source code. Android SDK itself provides the environment covering the entire life cycle of native application development. So make sure that you really need it, before you go.

Phase 1. Downloading the source code and building it.

Major point to consider is that xCode 3.x is required to build the whole source code. Build process fails, when building with xCode 4.x installed.

Phase 2. Preparing modified version of the stock application.

Let’s assume that disk image with Android source code lives at ANDROID_SOURCE directory. We are now ready to proceed to the most interesting part.

  1. Clone the source code of the application you are interested in (or start a new project) and put it in ANDROID_SOURCE/packages/apps/YOUR_APP.
  2. Change application label (see application:label tag in manifest file). Sometimes it is not enough to change application name on Home screen. Make sure that the activity with LAUNCHER category set does not contain label property itself. Note that application:name property corresponds to application class name not to home screen name.
  3. Change application package name. This is the most important step. In the world of native Android applications package name means a lot. ADT plugin provides a helper to change package name in regular Android project. In case of stock app most of the steps will be performed manually (mostly by means of text replace tool). You have to change package name in application manifest file (see manifest:package and original-package:name tags).
  4. In addition to that you will have to modify Android.mk file (see LOCAL_PACKAGE_NAME variable). This file exists in each directory with stock application source code and is used when building the app. Note that you will have to build the application with make tool. There is no easy way to tune Eclipse for this purpose.
  5. And even that is not enough. You will have to update the source code. I strongly recommend to change package name of each source file so it corresponds to the package specified in the manifest. It is not critical requirement and it is possible to do it only partially, but this leads conflicts and confusion. When changing package name along the source code, make sure that you change references to sub-packages and to auto-generated R class in the code.
  6. Next place to update is resource files. Sometimes XML layout definitions refer to concrete classes from the source code. You should update these references as well. As you can see most of these changes might be automated with text replace tool.
  7. Make sure that you also update package name in string constants in the source code. It is application specific point. So you should be careful about that.
  8. Add SDK version information to manifest file. By default the source is built to be run on the version, which corresponds to the source code revision. Most stock applications depend on the most recent features in the OS, but sometimes it is possible to specify minimal SDK version to lower level than current SDK source.

Note that tests project comes with all applications. It is located in /YOUR_APP/tests/ directory. You will have to perform all the steps above for that project as well to be able to build it. Note that it is not necessary to maintain that project. You can just remove tests directory for simplicity.

Phase 3.  Building and running modified version of the stock application.

Once all preparations are done, you will have to build the application with the help of the following command:

$ mmm packages/apps/YOUR_APP/

The command builds the source code and installs apk file into the emulator image, which was created when building Android source code. In order to install the application on emulator provided with the SDK, use the following command:

$ adb install -r /Volumes/Android/source/out/target/product/generic/system/app/YOUR_APP.apk

Note that the binary used above is already signed with debug signature. In order to distribute it, you need unsigned and unaligned version, which is located at

ANDROID_SOURCE/out/target/product/generic/obj/APPS/YOUR_APP/

Other tips

As it is mentioned above and in the original documentation, it is hard (impossible?) to configure Eclipse to build stock apps. However, it is possible to edit source code using Eclipse. Official documentation proposes to add YOUR_APP/src directory to Eclipse project (containing the entire Android source tree). In this case you will be able to make sure that you code compiles correctly before building it from command line. This approach does not allow you to edit other project related resources. So you can just create new Android project from source and specify YOUR_APP directory as project home. In this case you will most likely get lots of compilation errors but along with that you will get access to the entire project tree.

Eclipse is also helpful, when you are ready to run your app on emulator. Keeping Eclipse connected to emulator instance, you get a chance to view run logs in LogCat tab. It is really helpful as exception stack traces provide complete information on error.

Have a fun!