Debugging Android native C/C++ applications and libraries

This tutorial describes how to debug the hello-neon application provided with the Android Native Development Kit (NDK). It uses the Android SDK Platform 2.2 and the Android emulator as the target.


It does not describe how to install any of the Android tools. See the Android Developers website for more information.


Before you can debug an Android package containing native C/C++ code you must:

  1. Download and install the Android Software Development Kit (SDK). This enables you to build Java applications together with any native C/C++ code into an Android package with a .apk file extension.

  2. Download and install the Android NDK. This is a companion tool to the Android SDK that enables you to build performance-critical parts of your applications in native code such as C and C++ languages.


    On Windows, you must also download and install cygwin, including the make package so that you can run the scripts inside the Android NDK.

  3. Update the version of gdbserver in the relevant Android NDK toolchain directory by copying the Android version provided with DS-5 arm_directory\gdbserver\...\android. This tutorial uses the ...\toolchains\arm-eabi-4.4.0\prebuilt directory.

  4. Set up the Eclipse plug-in for Android:

    1. Launch Eclipse.

    2. Install the Android Development Tools (ADT) Eclipse plug-ins.

    3. Select Window → Preferences → Android and click on Browse... to set the location of the Android SDK.

    4. Open the Android SDK and AVD Manager dialog box by selecting Window → Android SDK and AVD Manager.

    5. Expand the Available packages group and add SDK platforms as required. For example, Android SDK Platform Android 2.2.

    6. Create a new Android Virtual Device (AVD).

  5. Edit the Android NDK script file, ndk-gdb to debug using DS-5. The Android NDK contains a script file to run gdbserver and the application on the target before launching the debugger. By default, the script file is not set up to debug using DS-5. To change this behavior you must comment out the last line as shown:

    #$GDBCLIENT -x `native_path $GDBSETUP`


To debug the application:

  1. Build the hello-neon source files with debug information using the scripts provided by the Android NDK. This tutorial uses the ...\toolchains\arm-eabi-4.4.0\prebuilt directory. For example:

    ./ndk-build -C samples/hello-neon NDK_TOOLCHAIN=arm-eabi-4.4.0 NDK_DEBUG=1
  2. Launch Eclipse.

  3. Create a new Android project:

    1. Select File → New → Project...

    2. Expand the Android group and select Android Project.

    3. Click Next.

    4. Enter a suitable project name. For example, HelloNeon.

    5. Select Create project from your existing source and locate the hello-neon folder.

    6. Leave the Use default location option selected so that the project is created in the default directory shown. Alternatively, deselect this option and browse to your preferred project directory.

    7. Select the required Build Target. For example, Android 2.2.

    8. Enter a suitable Application name. For example, Hello, Neon.

    9. Enter a suitable Package name. For example, com.example.neon.

    10. Enter a suitable Activity name. For example, HelloNeon.

    11. Click Finish.

  4. Ensure that the application builds with debug information. You can do this by:

    1. Open the AndroidManifest.xml file.

    2. Click on the Application tab.

    3. Select true in the Debuggable field.

    4. Save the changes and close the file.

  5. Clean and rebuild the Android project.

  6. If the application is already installed on the target you must uninstall it. For example:

    path\adb uninstall com.example.neon
  7. Install the application. For example:

    path\adb install samples/hello-neon/bin/HelloNeon.apk
  8. Run the ndk-gdb script to start the application and connect gdbserver. For example:

    ./ndk-gdb --project=samples/hello-neon --verbose --port=5000 --start --force --adb=adb

    See the Android NDK documentation for more information on using the script file and the command-line options.

  9. Connect DS-5 to the application using a gdbserver TCP connection:

    1. Select Debug Configurations... from the Run menu.

    2. Select DS-5 Debugger from the configuration tree and then click on New to create a new configuration. Alternatively you can select an existing DS-5 Debugger configuration and then click on Duplicate from the toolbar.

    3. In the Name field, enter a suitable name for the new configuration.

    4. Click on the Connection tab and configure a DS-5 Debugger target connection as shown in the following figure.

      Figure 15. Typical connection configuration for an Android application

      Typical connection configuration for an Android application

    5. Click on the Files tab and select the app_process binary file and the shared library.

      Figure 16. Typical file selection for an Android application

      Typical file selection for an Android application

    6. Click on the Debugger tab and select Connect only in the Run Control panel.

    7. Select Execute debugger commands and enter sharedlibrary in the associated text box to load debug information from all shared libraries into the debugger.

    8. In the Paths panel, specify the shared library search directory on the host that the debugger uses when it displays source code.

      Figure 17. Typical debugger connection settings for an Android application

      Typical debugger connection settings for an Android application

    9. Click on Debug to connect to the target.

  10. Debugging requires the DS-5 Debug perspective. If the Confirm Perspective Switch dialog box opens, click on Yes to switch perspective.

  11. To debug the application, set breakpoints, run, and step as required.

Show/hideSee also

Copyright © 2010, 2011 ARM. All rights reserved.ARM DUI 0478G