Difference between revisions of "Sequoyah/ndk guide"

Revision as of 14:04, 21 January 2011

A step-by-step guide for debugging native code

by Carlos Souto

Pre-requisites

• Sequoyah Native Debug feature must be installed. You can install it from Sequoyah update site:

File:/Sequoyah/ndk guide/01.PNG

It will install CDT's dependencies if needed: File:/Sequoyah/ndk guide/02.PNG

• The platform must be Android 2.2 (android-8) or greater
  

• The ndk version must be r4b or newer
  

• Eclipse CDT 7.0 or newer must be installed
  

• The AndroidManifest.xml must have the property of the application node android:debuggable="true" or the project must have been built with the flag "NDK_DEBUG=1" (for r5):
  

• The build must have been done with the ndk-build (if using the Sequoyah Android components, it will be automatic)

Setting up the debug session

• Create a debug configuration for an Android application (can be done with Eclipse or MOTODEV Studio)

• Create a debug configuration for a C/C++ application

• Set the following properties:

File:/Sequoyah/ndk guide/03.PNG

• The process launcher must be the Standard Process Launcher. This is selected at the bottom of the Main tab:

File:/Sequoyah/ndk guide/04.PNG

• On the "Main" tab: the Field C/C++ Application: $PROJECT_PATH/obj/local/armeabi/app_process

• On the "Debugger" tab:
  • field Debugger: gdbserver

• • On the "Main" subtab:

File:/Sequoyah/ndk guide/05.PNG

• • • GDB debugger: $NDK_PATH/build/prebuilt/$ARCH/arm-eabi-$GCC_VERSION/bin/arm-eabi-gdb
    • GDB command file: $PROJECT_PATH/obj/local/armeabi/gdb2.setup

[Windows users] Uncheck the "Use full file path to set breakpoints" option

• • On the "Connection" subtab:

File:/Sequoyah/ndk guide/06.PNG

• • • Type: TCP
    • Hostname or IP address: localhost
    • Port number: 5039

File:/Sequoyah/ndk guide/07.PNG

• Open the ndk-gdb script that came with the android NDK and comment the last line

(we are not calling the usual gdb client, but we will attach an Eclipse gdb session instead):

1. $GDBCLIENT -x $GDBSETUP -e $APP_PROCESS

• Insert a breakpoint in your Java code, preferably after all System.loadLibrary() calls.

(To make sure that the debugger is correctly attached to the Java process)

• Launch the android debug and wait for it to reach the breakpoint
• From a Terminal session, in the project folder, run the modified ndk-gdb command. It should not attach

to an gdb client, but call the gdbserver on the emulator and open a TCP port for connection.

• In the $PROJECT_PATH/obj/local/armeabi/, modify the gdb.setup file, removing the target remote:5039 statement.

(For some reason, the Eclipse GDB session does not like this statement being done in the commands file) Rename this new file to gdb2.setup. This step need to be run just once, on the first debug session. (I am working on further tweaking the ndk-gdb script to generate the gdb.setup file without the target statement, but for the time being, this workaround will work)

• Launch the C/C++ Application debug and wait for the Eclipse GDB session

to fully connect to the emulator's gdbserver instance

After following these steps, one can continue to debug the application as usual, using the "continue" option to let the execution flow until the next breakpoint is hit or by using the usual "step-in" to execute each statement individually. Setting a breakpoint on a Java statement that calls a native function through JNI and stepping into will place the user at the beginning of the native code.