Building, running, and debugging Android source

There is a lot of confusion surrounding the work flow in the Android source tree, so allow me to simplify:

1. Follow the initial instructions for downloading the source at:
   
   http://source.android.com/download
   
   
2. Set up your environment to build the engineering build for the generic device and generic product. This is similar to the SDK, but with a few pieces missing.
   
$ source build/envsetup.sh
$ lunch 1


3. To build for the first time:

$ make

   If you have a multi-core system, you can build with make -jN where N is twice the number of cores on your machine. This should speed up the first build considerably.
   
   
4. To launch the emulator from your build:

$ ./out/host/<your-machine-type>/bin/emulator

   On my system <your-machine-type> is linux-x86.
   
   NOTE: The emulator knows where to find system and data images as a result of running lunch 1 above. This sets the environment variable ANDROID_PRODUCT_OUT to point to the target directory. For this example, it should be out/target/product/generic/.
   
   
5. If you wish to make changes to the source code, there are handy utilities that have been exposed to your environment by source build/envsetup.sh above. For example, if you modify the Email app and just want to rebuild it:
   
   $ mmm packages/apps/Email
   
   
6. To see your changes in the emulator you can run:
   
   $ adb remount
$ adb sync
   
   Which will copy the regenerated Email.apk file into the emulator's /system/app folder, triggering the PackageManager to automatically reinstall it.
   
   
7. Or if you change framework resources in frameworks/base/core/res/res/ you could regenerate framework-res.apk with:
   
   $ mmm frameworks/base/core/res
   
   Or if you modified even the framework itself you could run:
   
   $ mmm frameworks/base
   
   To sync these changes you must restart the running framework and sync, as with this handy sequence:
   
   $ adb remount
$ adb shell stop
$ adb sync
$ adb shell start


8. Finally, to debug your changes you can use the DDMS tool to select a process for debug and then attach Eclipse to it. If you have the Eclipse Android Development plugin installed, there is a special DDMS perspective which you can use to choose the process for debug. To attach Eclipse to it, see these instructions:
   
   http://source.android.com/using-eclipse
   
   This document also describes how to use Eclipse for development. Any IDE should work with the proper finagling though. Just note that the IDE won't really be an integrated environment: the final output of APKs, system.img, and even the generation of R.java files will have to be done by make!
   
   A note about the processes in Android:
   
   
   • system_process houses all things under frameworks/base/services. This includes the PackageManagerService, StatusBarService, etc. It has many, many threads (one for each service, and then one main UI thread), so be wary when debugging.
   • com.android.acore hosts Launcher (home), Contacts, etc. You can determine the apps/providers that run here by looking for android:process="android.process.acore" in the various AndroidManifest.xml files in packages/.
     
   
   Also remember that the "framework" (under frameworks/base/core/java) is not hosted by any one process. It is a library used by most processes, so to debug code there you can usually use a simple demo app that takes advantage of whatever you changed and debug that app's process. A useful trick for setting up your debug connection is to call Debug.waitForDebugger() during some startup part of an application or system service.
   

UPDATE 2009-07-24: The original ONE_SHOT_MAKEFILE line I gave for rebuilding the framework has been deprecated. mmm frameworks/base is now the recommended way to rebuild the framework code.