Using NDK to Call C code from Android Apps Part-2

Updated for NDK 1.6

While Android SDK is great for application development, every once in a while you may need access to native code. This code is usually done in C. While you were able to access native code via Java Native Interface (JNI) all along, the process was rather hard. You would've typically had to compile everything on your host computer for the target architecture, requiring you to have the entire toolchain on your development machine.

Android NDK (Native Development Kit) simplifies working with native code. It includes the entire toolchain needed to build for your target platform (ARM). It is designed to help you create that shared library.




Note that native code accessible via JNI still runs inside the Dalvik VM, and as such is subject to the same life-cycle rules that any Android application lives by. The advantage of writing parts of your app code in native language is presumably speed in certain cases.

Note: I'm using <NDKHOME> to refer to the root directory in which you installed your NDK. For me that's /Users/marko/WorkArea/android-ndk-1.6_r1. I'm assuming all other directories and files are relative to your Eclipse project root, in my case /Users/marko/Workspace/Android/NDKDemo.

Overview




We are roughly going to do this:

1. Create the Java class representing the native code
2. Create the native code header file
3. Implement the native code by writing your C code
4. Compile everything and build you Shared Library
5. Use your native code inside Android activity


Create Native Library

This is just a Java file that lives in standard src directory in your Eclipse project. It serves as the glue to the native code that we'll write later.

/src/com.marakana/NativeLib.java

Code:

package com.marakana;

public class NativeLib {

  static {
    System.loadLibrary("ndk_demo");
  }
  
  /** 
   * Adds two integers, returning their sum
   */
  public native int add( int v1, int v2 );
  
  /**
   * Returns Hello World string
   */
  public native String hello();
}

Create C Header File
In your project bin directory (in my case, <EclipseWorkspace>/NDKDemo/bin), run javah tool to create the JNI header file.

Next, create a jni directory in your project directory (in my case, <EclipseWorkspace>/NDKDemo/jni).

Next, copy the JNI header from <EclipseWorkspace>/NDKDemo/bin to <EclipseWorkspace>/NDKDemo/jni

Here's my command line:

Code:

NDKDemo/bin$ javah -jni com.marakana.NativeLib
NDKDemo/bin$ mv com_marakana_NativeLib.h ../jni/

Write the C Code

In your <EclipseWorkspace>/NDKDemo/jni/ folder, create ndk_demo.c file. This is where we'll implement the native code. To start, copy the function signatures from the header file, and provide the implementation for those functions. In this example, the header file looks like this:

<EclipseWorkspace>/NDKDemo/jni/com_marakana_NativeLib.h

Code:

/* DO NOT EDIT THIS FILE - it is machine generated */
#include <jni.h>
/* Header for class com_marakana_NativeLib */

#ifndef _Included_com_marakana_NativeLib
#define _Included_com_marakana_NativeLib
#ifdef __cplusplus
extern "C" {
#endif
/*
 * Class:     com_marakana_NativeLib
 * Method:    add
 * Signature: (II)I
 */
JNIEXPORT jint JNICALL Java_com_marakana_NativeLib_add
  (JNIEnv *, jobject, jint, jint);

/*
 * Class:     com_marakana_NativeLib
 * Method:    hello
 * Signature: ()Ljava/lang/String;
 */
JNIEXPORT jstring JNICALL Java_com_marakana_NativeLib_hello
  (JNIEnv *, jobject);

#ifdef __cplusplus
}
#endif
#endif

And the corresponding implementation looks like this:

<EclipseWorkspace>/NDKDemo/jni/ndk_demo.c

Code:

#include "com_marakana_NativeLib.h"

JNIEXPORT jstring JNICALL Java_com_marakana_NativeLib_hello
  (JNIEnv * env, jobject obj) {
  return (*env)->NewStringUTF(env, "Hello World!");
}

JNIEXPORT jint JNICALL Java_com_marakana_NativeLib_add
  (JNIEnv * env, jobject obj, jint value1, jint value2) {
  return (value1 + value2);
}

Build The Library

To build the library, first we need to create a makefile for how to compile the C code:

<EclipseWorkspace>/NDKDemo/jni/Android.mk

Code:

LOCAL_PATH := $(call my-dir)

include $(CLEAR_VARS)

LOCAL_MODULE    := ndk_demo
LOCAL_SRC_FILES := ndk_demo.c

include $(BUILD_SHARED_LIBRARY)

Next, we need to tell NDK how to build the shared library and put it in the correct place inside the Eclipse project. To do this, create a folder <NDKHOME>/apps/ndk_demo/ and inside this folder create the Application file:

<NDKHOME>/apps/ndk_demo/Application

Code:

APP_PROJECT_PATH := $(call my-dir)/project
APP_MODULES      := ndk_demo

Next, create a symbolic link <NDKHOME>/apps/ndk_demo/project to your Eclipse project:

ln -s ~/Workspace/Android/NDKDemo <NDKHOME>/apps/ndk_demo/project

If you are on Windows, or another OS that doesn't support symbolic links, you may have to copy entire Eclipse project into <NDKHOME>/apps/ndk_demo/project directory, then copy back to Eclipse. I'm running all this on Mac OS X 10.6 and I assume Linux-type shell.

You can now to to your <NDKHOME> and run make APP=ndk_demo

The output should look lie this:

Code:

android-ndk-1.5_r1$ make APP=ndk_demo
Android NDK: Building for application 'ndk_demo'    
Compile thumb  : ndk_demo <= sources/ndk_demo/ndk_demo.c
SharedLibrary  : libndk_demo.so
Install        : libndk_demo.so => apps/ndk_demo/project/libs/armeabi

You can now refresh your Eclipse project and you should /lib/ directory containing your libndk_demo.so file.

Calling Native Code from Java

So now that we have the native C library implemented, compiled, and placed in the right place, let's see how we can call it from our Activity. It's actually rather simple - you just have to instantiate the instance of your NativeLib class and from there on, it's just a regular Java object.

/src/com.marakana/NDKDemo.java

Code:

package com.marakana;

import android.app.Activity;
import android.os.Bundle;
import android.view.View;
import android.view.View.OnClickListener;
import android.widget.Button;
import android.widget.EditText;
import android.widget.TextView;

public class NDKDemo extends Activity {
  NativeLib nativeLib;

  /** Called when the activity is first created. */
  @Override
  public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.main);

    nativeLib = new NativeLib();
    String helloText = nativeLib.hello();

    // Update the UI
    TextView outText = (TextView) findViewById(R.id.textOut);
    outText.setText(helloText);

    // Setup the UI
    Button buttonCalc = (Button) findViewById(R.id.buttonCalc);

    buttonCalc.setOnClickListener(new OnClickListener() {
      TextView result = (TextView) findViewById(R.id.result);
      EditText value1 = (EditText) findViewById(R.id.value1);
      EditText value2 = (EditText) findViewById(R.id.value2);

      public void onClick(View v) {
        int v1, v2, res = -1;
        v1 = Integer.parseInt(value1.getText().toString());
        v2 = Integer.parseInt(value2.getText().toString());

        res = nativeLib.add(v1, v2);
        result.setText(new Integer(res).toString());
      }
    });
  }
}

The UI for this example is not that significant, but I'm going to include it here for the sake of completeness.

/res/layout/main.xml

Code:

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
  android:orientation="vertical" android:layout_width="fill_parent"
  android:layout_height="fill_parent">
  <TextView android:layout_width="fill_parent"
    android:layout_height="wrap_content" android:text="NDK Demo"
    android:textSize="22sp" />
  <TextView android:layout_width="wrap_content"
    android:layout_height="wrap_content" android:id="@+id/textOut"
    android:text="output"></TextView>
  <EditText android:layout_width="wrap_content"
    android:layout_height="wrap_content" android:id="@+id/value1"
    android:hint="Value 1"></EditText>
  <TextView android:id="@+id/TextView01" android:layout_width="wrap_content"
    android:layout_height="wrap_content" android:text="+"
    android:textSize="36sp"></TextView>
  <EditText android:layout_width="wrap_content"
    android:layout_height="wrap_content" android:id="@+id/value2"
    android:hint="Value 2"></EditText>
  <Button android:layout_width="wrap_content"
    android:layout_height="wrap_content" android:id="@+id/buttonCalc"
    android:text="="></Button>
  <TextView android:layout_width="wrap_content"
    android:layout_height="wrap_content" android:text="result"
    android:textSize="36sp" android:id="@+id/result"></TextView>
</LinearLayout>

Output


Source Code
http://marakana.com/static/tutorials/NDKDemo.zip
http://marakana.com/static/tutorials/NDKHOME.zip