Java offers access to native code via the Java Native Interface (JNI). To make it work, you would typically have to compile everything on your host computer for the target architecture, requiring you to have the entire tool chain on your development machine. Setting up the proper cross-compiler and other tools is not easy.

NDK provides the complete toolchain you need to compile and build your native code so it can run on your target platform. The build system makes it really easy to set up your environment and integrate your native code into your project.

If you had a native library and you wanted it available to your application to load, you’d have to make sure it is part of the library path where the system searches for libraries to load. This is typically LD_LIBRARY_PATH on Linux. On an Android device, only the /system/lib directory is part of this path. This is a problem because the entire /system partition is read-only and thus unavailable to an app developer to install libraries there.

NDK solves this problem by providing for a mechanism to ship your native library as part of your Application Package (APK) file. Basically, when the user installs an APK that contains a native library, the system creates a directory named /data/data/your.package/lib/. If you recall from the section called “File System, Explained”, this partition is private just to your application and thus a safe place to keep your libraries for the user, while not letting other applications load and use your libraries. This packaging mechanism is a dramatic change to the rules for distributing applications on Android devices, and is a big deal because it brings the huge range of legacy and new native code into the game.

The NDK comes with helpful documentation and sample application explaining how to get things done in native code. It also standardizes on certain guaranteed C and C++ headers, such as:

Given this set of standard headers, you may have extrapolated what NDK is well suited for. We’ll examine that in the next section.

FibLib is where we declare our algorithms for computing the Fibonacci sequence. We have a total of four versions of the Fibonacci algorithm:

We’ll write the Java implementation here and do the native ones in C later.

package com.marakana;

public class FibLib {

        // Java implementation - recursive
        public static long fibJ(long n) {  // 
                if (n <= 0)
                        return 0;
                if (n == 1)
                        return 1;
                return fibJ(n - 1) + fibJ(n - 2);
        }

        // Java implementation - iterative
        public static long fibJI(long n) { // 
          long previous = -1;
          long result = 1;
                for (long i = 0; i <= n; i++) {
                  long sum = result + previous;
                        previous = result;
                        result = sum;
                }
                return result;
        }

        // Native implementation
        static {
                System.loadLibrary("fib"); // 
        }

        // Native implementation - recursive
        public static native long fibN(int n); // 

        // Native implementation - iterative
        public static native long fibNI(int n);  // 
}

At this point, our FibLib is complete, but we still need to back the native methods with their C implementations. To do that, first we need to create the appropriate JNI header file.

The next step is to create the C header file based on our FibLib Java file. To do that, we use Java’s standard javah tool. Note that you must have the Java Development Kit (JDK) installed in order to find this tool in the JDK/bin directory.

Now, to create the C header, go to your project’s bin directory and execute:

[Fibonacci/bin]> javah -jni com.marakana.FibLib

javah -jni takes a Java class as the parameter. Since not all the classes are in the Java classpath by default, it is easiest to just change directory to your project’s bin directory. Here, we assume that the current working directory is part of your Java classpath and thus that javah -jni com.marakana.FibLib at this location will work.

The result should be a new file named com_marakana_FibLib.h. This is the C header file that we need to implement next.

Before implementing our native files, let’s organize our project a little bit. Although Eclipse did a lot to setup our Android application directories in a meaningful way thus far, it doesn’t yet offer that level or support and automation for NDK development. We are going to do a couple of steps manually here.

For one, create a directory named jni inside your Eclipse Fibonacci project. This will be the place where you’ll store all your native code and related files. You can create this directory from within Eclipse by selecting the Fibonacci project in Package Explorer, right-clicking on it, and choosing New→Folder.

Next, move this new header file into that folder:

[Fibonacci/bin]> mv com_marakana_FibLib.h ../jni/

You can look into this file:

include::code/Fibonacci/jni/com_marakana_FibLib.h

As you can see, this file is automatically generated and is not to be modified by the programmer directly. You may observe signatures for two of our native functions that we’re yet to implement:

...
JNIEXPORT jlong JNICALL Java_com_marakana_FibLib_fibN
  (JNIEnv *, jclass, jlong);
...
JNIEXPORT jlong JNICALL Java_com_marakana_FibLib_fibNI
  (JNIEnv *, jclass, jlong);
...

These are standard JNI signatures. They are generated by a naming convention indicating that the function contains code defined in Java as part of com.marakana.FibLib class for native methods fibN and fibNI. You can also see that both methods return jlong, a JNI-standardized integer value.

Their input parameters are also interesting: JNIEnv, jclass and jint. The first two are always part of a Java class created to interface with native code: the JNIEnv points back to the virtual machine environment, and the next parameter points back to the class or object where this method is from; the parameter is jclass for a class method or jobject for an instance method. The third parameter, jlong is just our input into the Fibonacci algorithm, our n.

Now that we have this header file, it is time to provide its implementation in C.

We are going to create a C file that will implement our native algorithms. For simplicity sake, we’ll call it fib.c. Like the header file we looked at earlier, this file will reside in the jni folder. To create it, right-click on jni folder and choose New→File. Save it as fib.c.

Next, we provide the implementation of the Fibonacci algorithm in C in this fib.c file. The C versions of our algorithms are almost identical to the Java versions:

#include "com_marakana_FibLib.h" /*  */

/* Recursive Fibonacci Algorithm  */
long fibN(long n) {
  if(n<=0) return 0;
  if(n==1) return 1;
  return fibN(n-1) + fibN(n-2);
}

/* Iterative Fibonacci Algorithm  */
long fibNI(long n) {
  long previous = -1;
  long result = 1;
  long i=0;
  int sum=0;
  for (i = 0; i <= n; i++) {
    sum = result + previous;
    previous = result;
    result = sum;
  }
  return result;
}

/* Signature of the JNI method as generated in header file  */
JNIEXPORT jlong JNICALL Java_com_marakana_FibLib_fibN
  (JNIEnv *env, jclass obj, jlong  n) {
  return fibN(n);
}
/* Signature of the JNI method as generated in header file  */
JNIEXPORT jlong JNICALL Java_com_marakana_FibLib_fibNI
  (JNIEnv *env, jclass obj, jlong  n) {
  return fibNI(n);
}

Now that we have implemented C versions of Fibonacci, we want to build the shared library. To that, we need an appropriate Makefile.

To build the native library, the Android.mk Makefile must describe our pieces. The file looks like this:

LOCAL_PATH := $(call my-dir)

include $(CLEAR_VARS)

LOCAL_MODULE    := fib
LOCAL_SRC_FILES := fib.c

include $(BUILD_SHARED_LIBRARY)

It is a part of the standard Android make system. All we are adding here is our specific input (fib.c) and our specific output (the fib module). The name of the module we specify is important and will determine the name of the library based on operating system convention. For example, on ARM-based systems, the output will be libfib.so file.

Once we have this make file, we’re ready to initiate the build.

Assuming you have the NDK installed properly, you can now build the native shared library by running ndk/ndk-build in your project directory. Here, ndk refers to the directory where your NDK is installed.

At this point, you should have a subdirectory named lib containing your shared library. When you deploy the Fibonacci application in the next section, this library is packaged as part of the APK.

Finally, we need an application to put this library to good use.

The Fibonacci Activity asks the user to input a number. Then it runs the four algorithms to compute Fibonacci value of that number. It also times the results and prints them to the screen. This activity basically uses the FibLib class that in turn uses libfib.so for its native part.

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 Fibonacci extends Activity implements OnClickListener {
        TextView textResult;
        Button buttonGo;
        EditText editInput;

        @Override
        public void onCreate(Bundle savedInstanceState) {
                super.onCreate(savedInstanceState);
                setContentView(R.layout.main);

                // Find UI views
                editInput = (EditText) findViewById(R.id.editInput);
                textResult = (TextView) findViewById(R.id.textResult);
                buttonGo = (Button) findViewById(R.id.buttonGo);
                buttonGo.setOnClickListener(this);
        }

        public void onClick(View view) {

                int input = Integer.parseInt(editInput.getText().toString()); // 

                long start, stop;
                long result;
                String out = "";

                // Dalvik - Recursive
                start = System.currentTimeMillis(); // 
                result = FibLib.fibJ(input);  // 
                stop = System.currentTimeMillis();  // 
                out += String.format("Dalvik recur  sive: %d (%d msec)", result, stop
                                - start);

                // Dalvik - Iterative
                start = System.currentTimeMillis();
                result = FibLib.fibJI(input); // 
                stop = System.currentTimeMillis();
                out += String.format("\nDalvik iterative: %d (%d msec)", result, stop
                                - start);

                // Native - Recursive
                start = System.currentTimeMillis();
                result = FibLib.fibN(input); // 
                stop = System.currentTimeMillis();
                out += String.format("\nNative recursive: %d (%d msec)", result, stop
                                - start);

                // Native - Iterative
                start = System.currentTimeMillis();
                result = FibLib.fibNI(input); // 
                stop = System.currentTimeMillis();
                out += String.format("\nNative iterative: %d (%d msec)", result, stop
                                - start);

                textResult.setText(out); // 
        }
}

At this point, we can fire up the Fibonacci application and run some tests on it. Keep in mind that larger values for n take quite a bit longer to process, especially using the recursive algorithms. One suggestion would be to keep n in the 25-30 range. Also keep in mind that we are doing all this processing on Activity’s main UI thread, and blocking that thread for a long period of time will lead to the Application Not Responding (ANR) error we talked about in Figure 6.9, “Application Not Responding”. As an exercise, you may want to move the actual calculation into an AsyncTask as described in the section called “AsyncTask” to prevent blocking the main thread.

As you run some tests, you may notice that the native version of the algorithm runs about one order of magnitude faster than the Java implementation (Figure 15.1, “Fibonacci of 33”).

Figure 15.1. Fibonacci of 33

These results in themselves should provide enough motivation to consider moving some of your computationally intensive code into native code. NDK makes the job of integrating native code into your app much simpler.