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
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/com.marakana/NativeLib.java
Create C Header File
In your project bin directory (in my case,
Next, create a jni directory in your project directory (in my case,
Next, copy the JNI header from
Here's my command line:
Write the C Code
In your
<EclipseWorkspace>/NDKDemo/jni/com_marakana_NativeLib.h
And the corresponding implementation looks like this:
<EclipseWorkspace>/NDKDemo/jni/ndk_demo.c
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
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/Application
Next, create a symbolic link
If you are on Windows, or another OS that doesn't support symbolic links, you may have to copy entire Eclipse project into
You can now to to your <NDKHOME> and run
The output should look lie this:
You can now refresh your Eclipse project and you should
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
/src/com.marakana/NDKDemo.java
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
Output
Source Code
http://marakana.com/static/tutorials/NDKDemo.zip
http://marakana.com/static/tutorials/NDKHOME.zip
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
No comments:
Post a Comment