The need for quality professional tools for cross platform development when battling obscure software bugs and performance issues cannot be understated. With the ARM® Development Studio 5 (DS-5™) Community Edition (CE) we deliver some of the professional development capabilities of the DS-5 toolkit to the Android developer community. In this blog we’ll explore a few of the debug features of DS-5 CE and look at how it enables application development on Android.
Is DS-5 Community Edition for me?
The purpose of DS-5 CE is to bring the power of DS-5 tools to small development firms (with 10 or fewer employees) and individuals who publish applications for Android. This edition of DS-5 tools supports debug of native C/C++ libraries included in Android applications, on real devices and emulators. DS-5 CE also includes a basic version of the ARM Streamline™ performance analysis tool and is supported via the ARM forums. More details on its functionality can be found here.
DS-5 CE is designed to work with AVDs, development boards and devices that run Android 2.2 and API 8 or higher. It complements the fully featured DS-5 toolkit, which is targeted at enterprise users who want to reap all the benefits of the ARM Architecture from their software stack. The fully featured version of DS-5 includes the best-in-class ARM Compiler, powerful OS-aware debugger that supports a range of debug operations from bare-metal debug to Linux kernel debug and SMP debug, system-wide performance analyzer, and real-time system simulator. It is supported by ARM through specialist support engineers and a host of technical training courses.
Setting up DS-5 Community Edition on your development host
DS-5 CE is designed to work in the Eclipse development environment (Eclipse 3.7 and higher), which is arguably the Integrated Development Environment (IDE) of choice for Android application development. Also, it is intended to complement Android SDK and NDK, not to replace them. It is aimed at supporting and optimizing the workflows that users are accustomed to with their Eclipse/Android SDK/Android NDK development environments. The setup instructions below assume that you have Eclipse, JRE (Java runtime environment), Android SDK, ADT and Android NDK installed. DS-5 CE supports only the 32 bit version of the Eclipse IDE and 32 bit version of JRE/JDK 6 or above. Help on installing Android SDK, ADT and NDK is available on the Android developer site.
Step by step instructions for setting up DS-5 CE is given below:
1. Start Eclipse and select Help > Install New Software from the menu.
2. Select Add and add http://tools.arm.com/eclipse to the list of update sites using the Add Repository dialog that appears.
3. Select ARM DS-5 Community edition from the list that appears and click through the dialogs that includes the Eclipse Foundation Software User Agreement and the DS-5 Community Edition end user license agreement to install the DS-5 Community Edition plugins into your Eclipse environment. Installation may take a few minutes depending on your network speed.
4. You will be prompted to restart Eclipse once the installation completes. Restart Eclipse at this point by selecting Restart Now from the dialog that appears. Upon restart, you shall be prompted to install the included permanent license for DS-5 Community Edition as below:
5. Select Continue on the above dialog and it automatically installs a free license. You can ensure that the license has been installed correctly by going to Help > ARM License Manager which brings up the below dialog:
This completes the setup for DS-5 Community Edition on your host computer.
Debugging your first application
Now that we have installed DS-5 CE, let us put it to test. For writing this blog, I wanted to pick an application that has a sizeable native codebase to it as the value in DS-5 CE is around debug and performance analysis of native C/C++ code. Gaming applications are perfect candidates as many of the games rely on direct control of the UI and optimized performance which is arguably best done using native code. I was pleased to stumble upon my colleague Simon Tatham’s SGT Puzzles on the web, which has been ported to Android and is available under an open source license. So let’s debug the puzzles!
1. As the first step, download and extract the application zip file alongside other samples, into the NDK folder. (e.g. C:\AndroidNDK\android-ndk-r6b\samples\sgtpuzzles)
2. Open the makefile for the native library (libpuzzles) from the jni folder ( Android.mk ) and modify the LOCAL_CFLAGS variable to add –g. This option flags the compiler to produce debug information which is used by the debugger for resolving symbols.
3. Build the shared library using the ndk-build script. In my case, I am using ndkr6b and a Windows XP box, so I do this by going to the Cygwin shell.
Note: NDK 7.0 includes a DOS version of the ndk-build script, so you do not need Cygwin if you are using NDK 7.0 to build the shared library.
Once the shared library is built, you can see that it goes under libs\armeabi folder under the project directory.
SharedLibrary : libpuzzles.so
Install : libpuzzles.so => libs\armeabi\libpuzzles.so
4. DS-5 CE comes with a pre built gdbserver for Android that has been validated against the DS-5 debugger, you can find it under your installation by going to Help > ARM Extras (under arm\gdbserver\android in the folder that opens up). Two versions are supplied with DS-5 CE: one statically linked against libc and a dynamically linked one. Rename the statically linked one (gdbserver-stat-7.1) as gdbserver and replace the one alongside libpuzzles.so under libs/armebai with the one that comes with DS-5 CE. You can instead replace the gdbserver under <ndk-folder>\toolchains\arm-linux-androideabi-4.4.3\prebuilt with the one that comes with DS-5, so that each time you rebuild the shared library for debug, the gdbserver is copied automatically under the right project folder.
5. At this point, you need to import the shared library built using NDK into an Android SDK project, so that you could build a package (.apk) for installing on the Android device. There are different ways to do this in Eclipse but since SGT Puzzles comes with a pre defined Eclipse project, I simply had to import the project into the workspace by selecting File > Import > Existing projects into workspace. Now build the application by selecting Project > Build Project. (Note: You may need to do a clean to force a rebuild). Also note that libpuzzles.so is built outside the SDK environment in this case.
6. Once you build the application, export it into a package for installation and debug on the target device.
You can find more information on application signing and publishing on the Android developer portal.
The next step is to install and debug the application on an Android target. I used a HTC Desire phone running Android 2.2 for this blog. Connect the device to your host computer using a USB cable. You may need to install the USB driver for particular device to make the adb connection to the device, if not installed already. Make sure Device Debugging is enabled on the target device. Normally, you would find this under Settings > Applications > Development > USB Debugging.
Note: At this point, please ensure adb is in your path and restart Eclipse if necessary. If not, DS-5 complains when you try to create a debug configuration. See below.
7. Select Window > Open perspective > Other > DS-5 Debug and select Run > Debug Configurations.
8. Now create a new DS-5 Debug Configuration and configure the different tabs as shown in the images below. Note that the Connection tab lists the adb connection to the HTC Desire phone in the drop down list. You need to point the debugger at the location of the native library object file containing the debug symbols and the corresponding source location, this will be used by the debugger for resolving symbolic information required for populating various debug views like variables view, source listing view etc.
9. At this point you are ready to go. Save the configuration by assigning a name to it if needed and simply select Apply and Debug buttons on the configuration panel. You will notice that the debugger now connects to the phone and sends down the apk file to the phone, installs on the phone and brings it up ready for debugging! Select the throbbing Run/Continue button to start debugging. Once you select Run, you can see that the application starts on the phone.
10. Now I want to debug the cubes application and in order to do this I set a breakpoint in cube.c so that I can debug the source code of the application. Select OK on the dialog on the target so that the game selection screen comes up. At this point, select the Interrupt button from the Debug Control view so that you can stop the target and set a breakpoint in the source code.
11. Open the source file from the location where it was built so that we could set a breakpoint in the source code. ( Select File > Open > C:\AndroidNDK\android-ndk-r6b\samples\sgtpuzzles\cube.c and double click on line 878 which is the entry point into the game (function static game_state *new_game). This sets a breakpoint at the line, you can see from the Commands view of the debugger that the action is echoed in the view. Select F8 and start the game from the above list on the phone, you can see that the debugger hits the breakpoint ( in source listing and disassembly ) and the current program counter is highlighted both in source and assembly views. You can explore the various debugger views at this point (Variables, Expressions, Registers, Memory view) and step through code and debug the app.
We have seen how Android application developers can debug the native libraries in their apps using DS-5 debugger, which is delivered via an Eclipse update site. The DS-5 Community Edition brings together the convenience and productivity of professional tools to the Android application development scene by integrating with Eclipse, Android SDK, ADT and NDK, which are popular tools for application development in the Android community, thus making the learning curve simpler for Android developers. We have yet to explore ARM Streamline, another important part of DS-5 Community Edition, in this blog so watch this space!
Vinod Krishnamoni, Engineering Manager – DS-5 Applications and Validation, ARM. Vinod leads ARM's DS-5 Applications engineering team which creates product examples, demos and supporting documentation. The team also supports technical marketing and FAEs with product demos and workshops and acts as voice of the customer to other DS-5 engineering teams. Before joining ARM, Vinod worked for several years with companies in the mobile communication industry, including Motorola and Symbian Ltd, in various software roles.