Running native codes (C codes) in Android using JNI and NDK

May 7, 2012 by Munir 6 Comments

Although Android applications are mainly written by Java, developers sometimes may still want to leverage many good ready-made C/C++ libraries. Android applications run in the Dalvik virtual machine. The NDK allows you to implement parts of your applications using native-code languages such as C and C++. This can provide benefits to certain classes of applications, in the form of reuse of existing code and in some cases increased speed.

JNI

JNI or Java Native Interface is the interface between the Java code running in a JVM and the native code running outside the JVM. It works both ways, that is you can use JNI to call native code from your Java programs and to call Java code from your native code. The native code normally resides within a library (.so file) and is typically written in C/C++.

Reasons to use JNI:

ü  Wrapping lower level functionality and make an abstraction level i,e, Camera, Sensors, audio devices etc.

ü  Suppose you have an existing C/C++ code library or a full game you’d like to port to Android, but you don’t want to translate them into Java. One solution is to keep as much code as possible in C/C++ and then use the Android NDK and the Java Native Interface to communicate between the two languages.

ü  Bypass performance bottlenecks.

Android NDK

Android NDK is a set of tools that embed native language (c\c++) in an android application. It’s easy to setup and use. Android applications run in the Dalvik virtual machine. The NDK allows you to implement parts of your applications using native-code languages such as C and C++. This can provide benefits to certain classes of applications, in the form of reuse of existing code and in some cases increased speed.

To build a shared library, you can use the ndk-build shell script included with the Android NDK. It needs to run in a Unix-like environment so, if you’re on Windows, you will require Cygwin.

You always have to compile your native code against a specific architecture. The Android NDK includes a cross-compiler (compilers and linkers etc) that will generate binaries for the ARM architecture. Since ARM is by far the most common architecture on the Android devices today it should work on most devices

NDK supports following instruction sets –

ü  ARMv5TE

ü  ARMv7-A

ARMv5TE runs on every ARM based Android devices. ARMv7-A will run only on devices such as the Verizon Droid or Google Nexus One that have a compatible CPU.

ARMv5TE is the default, but switching to ARMv7-A is as easy as adding a single line to the application’s Application.mk file, without needing to change anything else in the file.

NDK provides headers and libraries that allow you to build activities, handle user input, use hardware sensors, access application resources, and more, when programming in C or C++.  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.

 

List of NDK Development tools –

The NDK includes a set of cross-toolchains (compilers, linkers, etc..) that can generate native ARM binaries on Linux, OS X, and Windows (with Cygwin) platforms.

It provides a set of system headers for stable native APIs that are guaranteed to be supported in all later releases of the platform:

• libc (C library) headers
• libm (math library) headers
• JNI interface headers
• libz (Zlib compression) headers
• liblog (Android logging) header
• OpenGL ES 1.1 and OpenGL ES 2.0 (3D graphics libraries) headers
• libjnigraphics (Pixel buffer access) header (for Android 2.2 and above).
• A Minimal set of headers for C++ support
• OpenSL ES native audio libraries
• Android native application APIS

The NDK also provides a build system that lets you work efficiently with your sources, without having to handle the toolchain/platform/CPU/ABI details. You create very short build files to describe which sources to compile and which Android application will use them — the build system compiles the sources and places the shared libraries directly in your application project.

Ways to write native codes in Android

• Write your application using the Android framework and use JNI to access the APIs provided by the Android NDK. This technique allows you to take advantage of the convenience of the Android framework, but still allows you to write native code when necessary. You can install applications that use native code through the JNI on devices that run Android 1.5 or later.
• Write a native activity, which allows you to implement the lifecycle callbacks in native code. The Android SDK provides the NativeActivityclass, which is a convenience class that notifies your native code of any activity lifecycle callbacks (onCreate(), onPause(), onResume(), etc). You can implement the callbacks in your native code to handle these events when they occur. Applications that use native activities must be run on Android 2.3 (API Level 9) or later.

You cannot access features such as Services and Content Providers natively, so if you want to use them or any other framework API, you can still write JNI code to do so.

Basic procedures to run native code

1)  A folder named ‘jni’ (lowercase) must be created by you in the Eclipse project’s root directory. This would place a folder at the same level as the Eclipse/Java ‘bin’, ‘src’, and ‘res’ folders. It would also be at the same level as the ‘AndroidManifest.xml’ file. Inside this folder is where the source c or c++ documents need to be placed.

 

 

 

2)  Create Android mk file, before the NDK build tools will compile your code they need a ‘Makefile’ file. Android.mk file describes your sources to the build-system.Information on writing the ‘Android.mk’ file can be found in the ‘docs’ folder inside the ‘android-ndk-***‘ folder.

The file syntax is designed to allow you to group your sources into ‘modules’. A module is one of the following: – a static library – a shared library. Only shared libraries will be installed/copied to your application package. Static libraries can be used to generate shared libraries though. You can define one or more modules in each Android.mk file, and you can use the same source file in several modules.

We can consider an example –

  LOCAL_PATH := $(call my-dir)

   include $(CLEAR_VARS)

   LOCAL_MODULE    := hellojni

   LOCAL_SRC_FILES := NativeSource.c

   include $(BUILD_SHARED_LIBRARY)

Let us explain these lines:

LOCAL_PATH := $(call my-dir)

An Android.mk file must begin with the definition of the LOCAL_PATH variable. It is used to locate source files in the development tree. In this example, the macro function ‘my-dir’, provided by the build system, is used to return the path of the current directory (i.e. the directory containing the Android.mk file itself).

include $(CLEAR_VARS)

The CLEAR_VARS variable is provided by the build system and points to a special GNU Makefile that will clear many LOCAL_XXX variables for you (e.g. LOCAL_MODULE, LOCAL_SRC_FILES, LOCAL_STATIC_LIBRARIES, etc…), with the exception of LOCAL_PATH. This is needed because all build control files are parsed in a single GNU Make execution context where all variables are global.

LOCAL_MODULE    := hellojni

The LOCAL_MODULE variable must be defined to identify each module you describe in your Android.mk. The name must be *unique* and not contain any spaces. Note that the build system will automatically add proper prefix and suffix to the corresponding generated file. In other words, a shared library module named ‘hellojni’ will generate ‘libhellojni.so’.  [If you name your module ‘libhellojni’, the build system will not add another ‘lib’ prefix and will generate libhellojni.so as well. This is to support Android.mk files that originate from the Android platform sources, would you need to use these.]

LOCAL_SRC_FILES := NativeSource.c

The LOCAL_SRC_FILES variables must contain a list of C and/or C++ source files that will be built and assembled into a module. Note that you should not list header and included files here, because the build system will compute dependencies automatically for you; just list the source files that will be passed directly to a compiler

include $(BUILD_SHARED_LIBRARY)

The BUILD_SHARED_LIBRARY is a variable provided by the build system that points to a GNU Makefile script that is in charge of collecting all the information you defined in LOCAL_XXX variables since the latest ‘include $(CLEAR_VARS)’ and determine what to build, and how to do it exactly. There is also BUILD_STATIC_LIBRARY to generate a static library.

3)  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.

package com.ndkadd.munir;

public class UseNDK {

static

{

System.loadLibrary("hellojni"); // we will load all the modules described in the Android.mk file

}

public native int AddNumbers(int value1 , int value2);

}

                 A C header file named  com_ndkadd_munir_UseNDK.h will be created    on the defined path.Next, copy the JNI header from NDKAddDemo/bin/class    to   NDKAddDemo/jni

4) Create the Native code header file, to do this , run Cygwin, go to the bin directory of the project in Cygwin. Enter one more step farther into classes folder. In my case, I entered /cygdrive/c/workspace/NDKAddDemo/bin/classes in Cygwin terminal. Run javah tool in this location to create jni header file

m.hoque@S-11627522 /cygdrive/c/workspace/NDKAddDemo/bin/classes $ javah -jni com.ndkadd.munir.UseNDK

A C header file named  com_ndkadd_munir_UseNDK.h will be created    on the defined path.Next, copy the JNI header from NDKAddDemo/bin/class    to   NDKAddDemo/jni

 

5)  Writing C/C++ code is little tricky here. In the JNI framework, native functions are implemented in separate .c or .cpp files. When the JVM invokes the function, it passes a JNIEnv pointer, a jobject pointer, and any Java arguments declared by the Java method. You must have to implement the methods in the header file here. You can consider an example here –

#include<com_ndkadd_munir_UseNDK.h>
#include<string.h>
JNIEXPORT jint JNICALL Java_com_ndkadd_munir_UseNDK_AddNumbers
(JNIEnv *env, jobject obj, jint v1, jint v2)
{
return(v1+v2);
}

The env pointer is a structure that contains the interface to the JVM. It includes all of the functions necessary to interact with the JVM and to work with Java objects. Example JNI functions are converting native arrays to/from Java arrays, converting native strings to/from Java strings, instantiating objects, throwing exceptions, etc. Basically, anything that Java code can do can be done using JNIEnv.




 6) Compile everything and build you Shared Library, We will use the Android NDK ToolChain here. Go to Project root, the project root is the base folder for the Eclipse Android project.

m.hoque@S-11627522 /cygdrive/c/workspace/NDKAddDemo

$ /cygdrive/c/workspace/android-ndk-r7b/ndk-build

The NDK build tools will compile the code, and then if there are no errors it will name the object code ‘libndkadd.so’ and place it in the Android project in a new folder that it creates especially for this purpose. The name of the folder is ‘libs/armeabi/‘. The build tools also manage the creation of some other files that are necessary.

Use your native code inside Android activity,  here is my main.xml file –

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="fill_parent"
    android:layout_height="fill_parent"
    android:orientation="vertical" >
    <TextView
        android:id="@+id/textgreetings"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text=""
        android:textAppearance="?android:attr/textAppearanceMedium" />

    <EditText
        android:id="@+id/editV1"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:inputType="number" >

        <requestFocus />
    </EditText>

    <EditText
        android:id="@+id/editV2"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:inputType="number" />

    <Button
        android:id="@+id/btnAdd"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="Add" />

    <TextView
        android:id="@+id/textResult"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text=""
        android:textAppearance="?android:attr/textAppearanceLarge" />

    <LinearLayout>

And, here is the Activity –

package com.ndkadd.munir;

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

public class NDKAddDemoActivity extends Activity implements OnClickListener {
	UseNDK ntv = new UseNDK();
	private Button btnCalculate;
	private EditText editResult;
	private EditText editV1;
	private EditText editV2;
	private TextView result;

    /** Called when the activity is first created. */
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.main);
        btnCalculate = (Button)findViewById(R.id.btnAdd);
        // editResult = (EditText)findViewById(R.id.textResult);
         editV1 = (EditText)findViewById(R.id.editV1);
         editV2 = (EditText)findViewById(R.id.editV2);
         result = (TextView)findViewById(R.id.textResult);
         btnCalculate.setOnClickListener(this);

     }

 	@Override
 	public void onClick(View v) {
 		// TODO Auto-generated method stub
 		if(v.getId() == R.id.btnAdd)
 		{
 		int v1, v2, res = 0;
         v1 = Integer.parseInt(editV1.getText().toString());
         v2 = Integer.parseInt(editV2.getText().toString());
         res = ntv.AddNumbers(v1, v2);
         Log.d("Result", "dsdfsf");
         result.setText(new Integer(res).toString());
 		}

 	}
    }

I had a wish to write more about JNI and NDK by someday. Enough for today. 🙂 🙂 😀