Tutorial about how to debug C/C++ code for Android in

Eclipse on Windows XP

Version 1.0 April 2011

By Tjeerd Schouten

Preface This tutorial will guide you through the setup required to be able to debug C/C++ code for Android in Eclipse on Windows XP. There are a few tutorials out there which explain how to debug C/C++ code for Android but they are either incomplete or do not work on Windows. Please follow each instruction in this tutorial carefully and do it in the correct order. Note that all hard coded paths in this tutorial need to be replaced by the appropriate path on your system. This tutorial contains a sample project which you can use as a reference and confirm everything is set up correctly. The project is mixed Java/C++. You can write a pure C++ application but this is not recommended because it can create issues between the user interface and Android. Make sure you use the latest version of all software and plugins at the time of writing, otherwise it won't work. Also make sure you don't use any spaces in the paths. This is important. This tutorial is only for Android 2.2 or later. Some components cannot be installed when offline.

Installing prerequisites Install the Java JDK

The Java Development Kit is used to develop Java applications. http://www.oracle.com/technetwork/java/javase/downloads/index.html

You will need to add the JDK directory to the windows PATH variable. To do this, in Windows, go to Start->Control Panel->System->Advanced(tab)->Environment Variables->System Variables. Click on the entry "Path" and then click Edit. At the end of the string, add the directory where you installed the JDK\bin (don't forget the semicolon (;) after the last entry in the path string). While you are here, add the path to the android-sdk platform-tools directory too. The Android SDK will be installed later but we can add the path now. Path to be added: ;F:\JDK\bin;F:\android-sdk\platform-tools

Install Eclipse Eclipse is an open source software development environment. Use "Eclipse IDE for Java Developers". http://www.eclipse.org/downloads/ Note that this package does not include an installer. It needs to be unzipped and moved to the appropriate directory manually.

Install the Android SDK http://developer.android.com/sdk/index.html Note that there is a bug in the android SDK windows installer. It will be unable to detect that the JDK is installed but there is a simple workaround for this. On the screen "Java SE Development kit (JDK) not found." click Back. It will then display "Java SE Development Kit (JDK) version ... has been found.". Then click Next and you will be able to continue the Android SDK installation. When finished, tick the box "Start SDK Manager" and click Finish. It will take some time for the SDK Manager to initialize. It may appear to freeze at times when initializing but if you move the mouse over the window, the progress updates. You can start the Android SDK Manager manually by executing " SDK Manager.exe", located in the android-sdk folder. Using the SDK Manager, install at least these packages (to install or skip, select the package and then press Accept or Reject on the right): -Android SDK Platform-tools -Documentation for Android SDK -SDK Platform Android ... API ... (select the android version you want to develop for) -Google USB Driver package(optinial, but may come in handy) -Android Compatibility package Then click Install. This again will take some time.

Install the Android NDK The Android Native Development Kit is used to develop applications for Android written in C/C++. http://developer.android.com/sdk/ndk/index.html Note that this package does not include an installer. It needs to be unzipped and moved to the appropriate directory manually. Make sure Eclipse works

Start Eclipse. After Eclipse starts, select a workspace. As always, do not use a path which contains any spaces. If eclipse fails to start by displaying the splash screen shortly and then shutting down without displaying any error message, then the "eclipse.ini" file needs to be modified. It is located in the Eclipse folder. After this entry: --launcher.XXMaxPermSize 256m Add this: -vm

F:\JDK\bin\javaw.exe

Install the ADT Plugin for Eclipse The Android Development Tools are used to write Android applications in Eclipse. In Eclipse, click Help->Install new software->Add Name: ADT Plugin Location: https://dl-ssl.google.com/android/eclipse/ Press OK. Wait for the tree to load. Click "Select All", then Next, then Next again. Accept the licenses and click Finish. Wait for the plugin to download and install. When the plugin is finished installing, restart Eclipse.

Install the CDT Plugin for Eclipse The C/C++ Development Toolkit is used to write C/C++ applications in Eclipse. Click Help->Install new software Select Helios from the "Work with" drop down menu. (replace helios with the current release name). Wait for the tree to load. Expand the "Programming Languages tree and select "C/C++ Development Tools". Click Next, then Next again. Accept the license and select Finish. Wait for the plugin to download and install. When the plugin is finished installing, restart Eclipse.

Install the Sequoyah Plugin for Eclipse Sequoyah allows us to debug C/C++ code in Eclipse. Click Help->Install new software->Add Name: Sequoyah Plugin Location: http://download.eclipse.org/sequoyah/updates/2.0 (replace 2.0 with the latest release). Press OK. Un-check "group items by category", otherwise you cannot see the packages. Click Next, then Next again. Accept the licenses and click Finish. Wait for the plugin to download and install. When the plugin is finished installing, restart Eclipse.

Install Cygwin Cygwin is an environment which allows you to run Linux programs on Windows. http://cygwin.com/setup.exe

Be sure to install Cygwin with all the developer packages. Run Cygwin setup.exe->next->Install from internet->Select root directory->Select local package directory (can be re-used if you want to install Cygwin on another machine)->Direct connection (or proxy)->Select mirror->Select packages->Click on Devel tree->Default, and change to Install. Downloading and installing Cygwin will take a long time. When finished, make sure it installed correctly by starting up a Cygwin terminal and typing: make -v

It should not give any error. If it does, you didn't install Cygwin with the developer packages. Note: to increase the Cygwin window size, click the Cygwin icon on the top left ->Properties->Layout(tab)->Screen buffer size and window buffer size change for example width to 100.

Set up the paths

Set the path to the Android NDK

In Eclipse go to Window->Preferences->Android (on the left window)->Native Development->NDK Location Fill in the path to your android NDK. In my case: F:\android-ndk

Set the path to the Android SDK

In Eclipse go to Window->Preferences->Android (on the left window)->SDK Location Fill in the path to your android SDK. In my case: F:\android-sdk

Create the project files Create an Eclipse project

In Eclipse, click File->New->Project...->Android->Android project->Next Select the Build Target (Android version) and fill in these variables:

Project name: android-ndk-program Application name: android-ndk-program Package name: com.example.packagename Create Activity: activityname Click Finish.

Create the make file Right click your project in the Eclipse project explorer window on the left, and select New->Folder->Folder name and call it "jni". When the folder is created, right click it an select New->File->File name, and call it Android.mk Then click Finish. The new file should open. Copy and paste this code into that file: LOCAL_PATH := $(call my-dir)

include $(CLEAR_VARS)

# Here we give our module name and source file(s)

LOCAL_MODULE := ndkfoo

LOCAL_SRC_FILES := ndkfoo.c

include $(BUILD_SHARED_LIBRARY)

Create the C source file

Right click the jni folder and select New->File->File name, and call it "ndkfoo.c". Then copy this code into that file: #include <string.h>

#include <jni.h>

jstring Java_com_example_packagename_activityname_invokeNativeFunction (JNIEnv* env, jobject

javaThis) {

return (*env)->NewStringUTF(env, "Hello from native code!");

}

Note: if you change program related names such as the program name, package name, and activity name, make sure the function above matches the name change. The function name is made out of 4 different parts:

Java_ :always the same. com_example_packagename_ :the package name. activityname_ :the activity name. invokeNativeFunction :the function name which will be called from Java.

Edit the Java source file Expand your project tree, and navigate to src->com.example.packagename and open the file "activityname.java". Replace the entire code by this: package com.example.packagename;

import android.app.Activity;

import android.app.AlertDialog;

import android.os.Bundle;

public class activityname extends Activity {

// load the library - name matches jni/Android.mk

static {

System.loadLibrary("ndkfoo");

}

// declare the native code function - must match ndkfoo.c

private native String invokeNativeFunction();

@Override

public void onCreate(Bundle savedInstanceState) {

super.onCreate(savedInstanceState);

setContentView(R.layout.main);

// this is where we call the native code

String hello = invokeNativeFunction();

new AlertDialog.Builder(this).setMessage(hello).show();

}

}

Add native support to the project

Right click your program in the Project Explorer, and click Android Tools->Add Native Support...

Enable debugging Expand your project in the Project Explorer. Double click on "AndroidManifest.xml" to open it. On the bottom tab, click Application. Change the Debuggable field to "true". Save the file.

Change the project settings

Set the path to the app_process file and configure the process launcher

Select your project in the Project Explorer. Then go to Run->Debug Configurations. In the window on the left, right click "C/C++ application" and select New. Your program is automatically added. On the Main tab, change the "C/C++ Application" field to F:\eclipse\workspace\android-ndk-program\obj\local\armeabi\app_process

This file is not created yet. We will do this later. Change "Build Configuration" to "use active" Select "Disable Auto Build" At the bottom, click "Select other" next to "Using GDB (DSF) Create Process Launcher". In the dialog popup, select "Use configuration specific settings", then select "Standard Create Process Launcher". Click Apply, then Close.

Set the path to the debugger and configure Select your project in the Project Explorer. Then go to Run->Debug Configurations. In the window on the left, expand "C/C++ application" and click on your project. Select the Debugger tab. Change "Debugger" to "gdbserver". Select "Stop on startup at" and change the field to: Java_com_example_packagename_activityname_invokeNativeFunction

Note that only " Java_com_example_" is shown in the screenshot. Select the Main tab. Change the "GDB Debugger" field to: F:\android-ndk\toolchains\arm-eabi-4.4.0\prebuilt\windows\bin\arm-eabi-gdb.exe

Change the "GDB command file" filed to: F:\eclipse\workspace\android-ndk-program\obj\local\armeabi\gdb2.setup

This file is not created yet. We will do this later. Change "GDB command set" to "standard" Uncheck the "Use full file path to set breakpoints" option Click Apply. Select the Connection tab. Change Type to: TCP

Host name or IP address: localhost Port number: 5039 Click Apply, then Close.

Set the path to Cygwin

Right click project->Properties->C/C++ Build (on the left)->Environment->PATH->Edit Add the line ;F:\cygwin\bin

If you don't do this, you will get this error when debugging: Cannot run program "bash": Launching failed

Set the path to the ndk-build file

Right click your project ->Build Path --> Configure Build Path Click C/C++ Build (not a sub tree). Uncheck "use default build command" Change the "Build command" to: bash /cygdrive/f/android-ndk/ndk-build

Press OK and wait for the building to finish. Note that the path to your files in Cygwin is preceded with "/cygdrive" and then your drive letter, which is the F drive in my case.

Modify the ndk-gdb file In Windows, go to the android-ndk root folder. Open the ndk-gdb file with Notepad, as Wordpad changes the formatting and will break the build process. Change the last line in ndk-gdb from $GDBCLIENT -x `native_path $GDBSETUP`

to #$GDBCLIENT -x `native_path $GDBSETUP`

This is to disable the line (comment it).

If you issue the ndk-gdb command in Cygwin, and it creates errors like: Line 17: $'\r' : command not found Line 27: /cygdrive...build/core/ndk : No such file or directory Then the ndk-gdb file format is corrupted by the text editor. Replace it with the original and try again with a different text editor like Notepad.

Debugging the application Set up phone or emulator for debugging

Put your phone in USB debugging mode and connect it to the computer, or set up the Android Emulator (AVD, Android Virtual Device). To set up the emulator, in Eclipse go to: Window->Android SDK and AVD manager->New Select a Name, and Target. Then click Create AVD and close the manager. Note that the AVD is very slow to start up. It is recommended that you use your phone for debugging as it is much faster. If your phone is connected, the debugger will detect it and use the phone for debugging instead of the AVD. Set the breakpoints Set a breakpoint just after each System.loadLibrary() call. Do not set it before it or on it. This will not work. Also, set a breakpoint somewhere in your C++ code. Start the Java debugger

Select your project on the window on the left in Eclipse. Then Select Run->Debug as->Android application. Wait for the debugger to load and break at the breakpoint. Do not close the debugger. Start gdbserver The Java debugger is loaded but we need to start the gdbserver so the C/C++ debugger can connect to it. Afer the Java debugger (debug as android application) is at the breakpoint, open a Cygwin terminal and type: cd /cygdrive/f/eclipse/workspace/android-ndk-program

enter /cygdrive/f/android-ndk/ndk-gdb

enter This will start gdbserver. Wait for the command to finish. This command will also create the .so, and the gdb.setup and app_process files. Modify the gdb.setup file

Go to obj\local\armeabi of your eclipse project and open the gdb.setup file. Remove the line: target remote :5039

Close the file and rename it to "gdb2.setup". Every time the gdbserver is started, it will create a new gdb.setup file but since we renamed it, it will not be overwritten so this step only needs to be done once. This is a workaround for a bug. Save and close the file. Start the C/C++ debugger

The debugger in Eclipse is already running but this is only for the Java part. We need to start the C++ debugger in parallel. This will work fine. Click Run->Debug configurations->C/C++ Application (on the left)->your-program->Debug Continue debugging

After the C++ debugger loads, click Resume(F8) and the debugger will break at the breakpoint in your C++ code. Note that in Eclipse you can switch between debug view and android native code view by pressing the arrow button next to the Android Native/Debug button on the top right of the screen.

References http://developer.android.com/sdk/installing.html http://developer.android.com/sdk/eclipse-adt.html http://mhandroid.wordpress.com/2011/01/23/using-eclipse-for-android-cc-debugging/ http://wiki.eclipse.org/Sequoyah/ndk_guide http://mindtherobot.com/blog/452/android-beginners-ndk-setup-step-by-step/ http://developer.android.com/resources/tutorials/hello-world.html Hopefully Google will make it easier in the future.