How to Set Up Android Platform Development and Debugging

By Larry Schiefer  |  Posted 2010-03-23

How to Set Up Android Platform Development and Debugging

The number of mobile devices powered by the Android operating system is growing dramatically, but potential uses extend well beyond the mobile market. Android's simple architecture and extensible framework open the possibility for it to be used to power set-top boxes, kiosks, video displays, data collection terminals or other devices.

There are many reasons to use Android: there are no licensing costs, it is a stable open-source platform, open source allows you to customize the code to fit your needs, and it is backed by Google (which is desirable for some users).

Having access to Android's source code gives you tremendous power to extend it to suit your device's unique needs. The only problem is, similar to many open-source projects, the documentation tends to be the source code and you may need to depend on the community to answer questions or help solve problems.

Most of the Android documentation is targeted toward application developers using the Java-based Android SDK. This is where the real push is right now: to get more applications written for the new devices. Large companies making high-profile devices may receive direct help from Google. If you are not included in this select group, then creating new, native components or bringing up a new platform may require you to figure out critical issues for yourself.

Having the source code will help with technical issues but requires debugging guidance not covered in the current Android documentation. In this article, I will help you set up your development environment and debug lower-level code.

Setting up the platform

Native code development requires the same type of environment as Android applications, with some minor additions. Follow the instructions on the Android developer Website for setting up Eclipse and the Android SDK.

You now have the components needed for Java development on Android. Developing and debugging native code requires the C/C++ Development Tooling (CDT) extensions. Get them through Eclipse on the Software Updates dialog box from the Help menu. Click Available software. Expand the "Ganymede Update Site" and "C and C++ Development" trees and click the top-level "C and C++ Development" checkbox. Additionally, download the Android source code from the Android Open Source project Website and build it.

Native Code Debug Setup}

Native code debug setup

Eclipse needs to be configured to use a remote C/C++ target. For every service or application that uses


Insert DBG_HALT(); in the native code you would like to debug. Currently, there is no way to embed a hard-coded breakpoint in native code.

Native Debugging

Native debugging

Debugging native code on a platform can be done using Eclipse by following these nine steps:

Step No. 1: Start the target. Using Eclipse, start debugging the Java application (or service) containing your native code. Stop the Java-side debugger in the entry point of the Activity or Service.

Step No. 2: Using the Android plug-in in Eclipse (or adb logcat), determine the Linux process ID for the application/service.

Step No. 3: Configure the machine to port forward to the target by executing:

 ~> adb forward tcp:10000 tcp:10000

Run gdbserver on the target, attaching it to the process ID found above (PID below):

~> adb shell /system/bin/gdbserver tcp:10000 --attach PID

Step No. 4: In Eclipse, go back to C/C++ or Java mode, but do not disconnect the Java debugger if you want to debug the Java side as well.

Step No. 5: Select your C/C++ project, right-click and select Debug Configurations.

Step No. 6: Select the Android C/C++ debug configuration you made earlier and click Debug. Eclipse will connect to the emulator and bring up the Debug perspective filled with target information, along with the remote Java debug information. It is normal to see warnings from gdb about dynamic sections. Ignore them. You can switch between the Java and C/C++ debug sessions as needed, though Java debugging will be unavailable while halted in native code.

Step No. 7: Select the C/C++ target in the Debug perspective, and click Suspend to stop the native process to see the current call stack. Examine each thread within the process and find which one is executing the DBG_HALT() in your code.

Step No. 8: Look at the disassembly of the DBG_HALT() code to find the memory location on the stack where it is pulling the value of "i." Change the memory location 1.

Step No. 9: Changing the memory location prevents you from single-stepping. To work around this, set a breakpoint at the next valid C/C++ line of code after the macro and click Resume. The breakpoint will get hit immediately and the ability to single step through the code.

Android platform and native development documentation may be sparse, but source code access and an understanding of how to set up your native code projects for debugging should give you a head start.

Larry Schiefer is a Senior Software Architect at Bsquare Corporation. He is the lead engineer in its Android engineering practice and has worked on Android projects for several Bsquare customers. Most recently, he led the effort to port Adobe Mobile Client (AMC) software to an Android-based handset. Larry also has managed embedded system software development with Linux, Symbian, Windows Mobile and Windows Embedded CE operating systems. His project experience covers 802.11 driver ports/enhancements, WiMax, Gigabit Ethernet, custom application-specific integrated circuit (ASIC) firmware, BSP development and custom GUI applications. Larry has a BS degree in Computer Engineering from Rose-Hulman Institute of Technology in Terre Haute, Indiana. He can be reached at

Rocket Fuel