Android NDK and OpenCV Development With Android Studio

---------------- If you do NOT know Chinese, you can just skip this part ----------------

一直打算將原來的XFace進行改進，最近終於有了些時間能夠動手了，改進計劃以下：開發上使用Android Studio做爲新的開發環境，配上新的構建系統Gradle；應用上將修改原來的UI設計，內部代碼也將有很大的變化，可能會用上ContentProvider和Service等略高級內容；算法上打算讓應用擴展性加強以適應不一樣的算法，並結合強大的Android Studio和Gradle讓這個項目變得更加豐富。說了一堆廢話，言歸正傳，本文的重點是介紹如何在Android Studio中進行NDK開發(目前它還不徹底支持NDK開發)，難點是NDK中還包含OpenCV的動態庫。最後的最後，本文剩下部分將使用英文，由於它要成爲我在StackOverflow上的處女答，麼麼噠 ~O(∩_∩)O~

---------------------------- Here is the right stuff you may need --------------------------------

This post shows how to develop an Android NDK application with OpenCV included using Android Studio and Gradle. If you're working on migrating your original Eclipse Project to Android Studio, you may find this post is what exactly you want!

OK，Let's start!

Section 1: Three things you must know

1.Firstly, if you are not familiar with Android Studio and Gradle, you may find these links useful. (if you already know these well, skip this part)

①Creating a new Project with Android Studio

②Building Your Project with Gradle

③Gradle Plugin User Guide or you may want to read a Chinese commented version in my blog here.

2.Secondly, if your android ndk project is not that complicated(for example, having no opencv included), you may wanna see ph0b 's introduction here, it's quite a nice job with a video recorded! (you can also follow Section 2 in this post to get a simple Android NDK demo application)

ph0b's post: ANDROID STUDIO, GRADLE AND NDK INTEGRATION

3.Thirdly, if those above two do not meet your needs, then I think you may want to customize the Android.mk with Gradle in Android Studio. Thanks to Gaku Ueda , he had made a great job explaining how to achieve that goal. Actually I have found another nicer solution without adding that many codes and also achieve that goal. :-) Find it out in the next sections.

Gaku Ueda's post: Using custom Android.mk with Gradle/Android Studio

OK, I will cover all above and give another nice solution in the end, have fun!

Section 2: A simple Android NDK demo application

This section shows creating a simple Android NDK demo application, if you already know, you can directly go the section 3.

1.Create a new Android project named NDKDemo with a blank Activity in AS(=Android Studio).

2.Give an id to the TextView in activity_my.xml such as android:id="@+id/textview", then add these codes in MyActivity.java.

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_my);

    TextView textView = (TextView) findViewById(R.id.textview);
    textView.setText(hello());
}

static {
    System.loadLibrary("hello");
}

public native String hello();

3.Create a new directory jni in folder app/src/main, then you have java, jni and res in this folder.

4.This step is very important! You can add a external tool to run the javah command without typing that much code!

Open AS's Preferences, then find External Tools in IDE Settings, click + to add one tool with the following configurations. (Make sure you have add JDK tools in your system path, if you don't know how, click here)

With the help of this tool, each time we right click on a class file, then choose Android Tools -> javah to run this tool, it will automatically generate a C head file for us in the target folder $ModuleFileDir$/src/main/jni , in this case, it is app/src/main/jni. Try this on MyActivity.java file now! The console will print out a log like:

/usr/bin/javah -v -jni -d /Users/hujiawei/AndroidStudioProjects/NDKDemo/app/src/main/jni com.android.hacks.ndkdemo.MyActivity [Creating file RegularFileObject[/Users/hujiawei/AndroidStudioProjects/NDKDemo/app/src/main/jni/ com_android_hacks_ndkdemo_MyActivity.h]]

Then you get a com_android_hacks_ndkdemo_MyActivity.h file in jni folder with the following content.

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

#ifndef _Included_com_android_hacks_ndkdemo_MyActivity
#define _Included_com_android_hacks_ndkdemo_MyActivity
#ifdef __cplusplus
extern "C" {
#endif
/*
 * Class:     com_android_hacks_ndkdemo_MyActivity
 * Method:    hello
 * Signature: ()Ljava/lang/String;
 */
JNIEXPORT jstring JNICALL Java_com_android_hacks_ndkdemo_MyActivity_hello
  (JNIEnv *, jobject);

#ifdef __cplusplus
}
#endif
#endif

5.Write a simple C implementation file named main.c in jni folder

#include <jni.h>
#include "com_android_hacks_ndkdemo_MyActivity.h"

JNIEXPORT jstring JNICALL Java_com_android_hacks_ndkdemo_MyActivity_hello
  (JNIEnv * env, jobject obj){
    return (*env)->NewStringUTF(env, "Hello from JNI");
  }

6.In the build.gradle file under app module, add the following codes to configure ndk in defaultConfig element, here we just give the uni module a name hello, you can find other configurations in Gradle Plugin User Guide.

defaultConfig {
    applicationId "com.android.hacks.ndkdemo"
    minSdkVersion 16
    targetSdkVersion 20
    versionCode 1
    versionName "1.0"

    ndk{
        moduleName "hello"
    }
}

7.In order to let Gradle run ndk-build command (in some task, maybe NdkCompile task), we should configure the ndk.dir in local.properties file in Project root.

sdk.dir=/Volumes/hujiawei/Users/hujiawei/Android/android_sdk
ndk.dir=/Volumes/hujiawei/Users/hujiawei/Android/android_ndk

8.OK, everything is ready, click Run to give it a try, you will see the result like

All right, so what's happening inside?

Since you have a jni folder, Gradle will consider it as a default native code folder. When Gradle builds the app, it will run ndk-build command(since you have configured ndk.dir, Gradle knows where to find it) with a generated Android.mk file(locates in app/build/intermediates/ndk/debug/Android.mk), after compiling the native codes, it will generate the libs and obj folder into folder app/build/intermediates/ndk/debug/. Gradle will then package the libs into final apk file in folder app/build/outputs/apk/app-debug.apk(you can unarchive this file to check whether libs is contained)

app/build/intermediates/ndk/debug (lib and obj folders)

app/build/outputs/apk/app-debug.apk (and files within it)

Secontion 3: Using OpenCV

If your project do not use OpenCV, then the section 2 is just enough. But what if you wanna use OpenCV to do other stuff? Of course, we want to use OpenCV for Android instead of JavaCV here, and Of course, we need to package OpenCV library for Android into our application's APK file (then users who use this app does not have to install OpenCV Manager). So, how can we achieve these goals?

The simplest way has been posted by TGMCians on Stack Overflow here, that is, let the main app include the OpenCV library as a dependency, and copy all <abi>/*.so files in OpenCV for Android SDK to jniLibs folder under app/src/main/, Gradle will automatically package these <abi>/*.so files into libs folder within the final APK file. Of course, this method will work, but it has a few backwards: (1) Unless you only copy the needed *.so files, you will always have a large APK due to this reason; (2) How about the building of the jni files? How to run ndk-build if these files contain opencv related codes?

So, here comes to our Using custom Android.mk with Gradle and Android Studio part. For testing, we first creat an Android.mk and an Application.mk file under jni folder.

Android.mk

LOCAL_PATH := $(call my-dir)

include $(CLEAR_VARS)

LOCAL_SRC_FILES := main.c
LOCAL_LDLIBS += -llog
LOCAL_MODULE := hello

include $(BUILD_SHARED_LIBRARY)

Application.mk

APP_ABI := armeabi
APP_PLATFORM := android-16

Thanks to Gaku Ueda, he had made a great job explaining how to achieve that goal with this post. The core idea of his method is to run ndk-build command in some task, then zip the <abi>/*.so files under the output app/build/libs/ folder into a jar file which is finally put in app/build/libs/ folder, then add a compile dependency to this jar file. The key code for his method listed below

Notice 1: When using custom Android.mk, we should first disable Gradle to build the jni folder as before, and sourceSets.main.jni.srcDirs = [] just does this job!

Notice 2: The code is not exactly the same with Gaku Ueda's code: tasks.withType(Compile) to tasks.withType(JavaCompile), because Compile is deprecated.

Notice 3: You can get $ndkDir variable with project.plugins.findPlugin('com.android.application').getNdkFolder() or you can define it in grade.properties file under Project root, so you need to add ndkDir=path/to/your/ndk in that file, if the file is not created, simply create a new one.

android{
    ...
    sourceSets.main.jni.srcDirs = []

    task ndkBuild(type: Exec, description: 'Compile JNI source via NDK') {
        ndkDir = project.plugins.findPlugin('com.android.application').getNdkFolder()
        commandLine "$ndkDir/ndk-build",
                'NDK_PROJECT_PATH=build',
                'APP_BUILD_SCRIPT=src/main/jni/Android.mk',
                'NDK_APPLICATION_MK=src/main/jni/Application.mk'
    }

    task ndkLibsToJar(type: Zip, dependsOn: 'ndkBuild', description: 'Create a JAR of the native libs') {
        destinationDir new File(buildDir, 'libs')
        baseName 'ndk-libs'
        extension 'jar'
        from(new File(buildDir, 'libs')) { include '**/*.so' }
        into 'lib/'
    }

    tasks.withType(JavaCompile) {
        compileTask -> compileTask.dependsOn ndkLibsToJar
    }
    ...
}

dependencies {
    compile fileTree(dir: 'libs', include: ['*.jar'])
    // add begin
    compile fileTree(dir: new File(buildDir, 'libs'), include: '*.jar')
    // add end
}

But we can still do a little improvements here. We have already know that Gradle will take jniLibs folder as its default native libraries folder, so we can simply output the libs/<abi>/*.so files generated by ndk-build command into jniLibs folder, so there's no need to zip these *.so files into a jar file.

The final build.gradle file under app module

apply plugin: 'com.android.application'

android {
    compileSdkVersion 20
    buildToolsVersion "20.0.0"

    defaultConfig {
        applicationId "com.android.hacks.ndkdemo"
        minSdkVersion 16
        targetSdkVersion 20
        versionCode 1
        versionName "1.0"
    }

    // add begin
    sourceSets.main.jni.srcDirs = []

    task ndkBuild(type: Exec, description: 'Compile JNI source via NDK') {
        ndkDir = project.plugins.findPlugin('com.android.application').getNdkFolder()
        commandLine "$ndkDir/ndk-build",
                'NDK_PROJECT_PATH=build/intermediates/ndk',
                'NDK_LIBS_OUT=src/main/jniLibs',
                'APP_BUILD_SCRIPT=src/main/jni/Android.mk',
                'NDK_APPLICATION_MK=src/main/jni/Application.mk'
    }

    tasks.withType(JavaCompile) {
        compileTask -> compileTask.dependsOn ndkBuild
    }
    // add end

    buildTypes {
        release {
            runProguard false
            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
        }
    }
}

dependencies {
    compile fileTree(dir: 'libs', include: ['*.jar'])
}

So simple, right? 'NDK_LIBS_OUT=src/main/jniLibs' helps us do the right job!

For testing, you can also add some lines relating with OpenCV in your Android.mk file and some line in your main.c to check whether everything is readlly working. For example, add #include <opencv2/core/core.hpp> in main.c file, and change Android.mk to

LOCAL_PATH := $(call my-dir)

include $(CLEAR_VARS)

#opencv
OPENCVROOT:= /Volumes/hujiawei/Users/hujiawei/Android/opencv_sdk
OPENCV_CAMERA_MODULES:=on
OPENCV_INSTALL_MODULES:=on
OPENCV_LIB_TYPE:=SHARED
include ${OPENCVROOT}/sdk/native/jni/OpenCV.mk

LOCAL_SRC_FILES := main.c
LOCAL_LDLIBS += -llog
LOCAL_MODULE := hello

include $(BUILD_SHARED_LIBRARY)

In Gradle Console window, you can see these similar lines

*.so files relating with OpenCV has been packaged into the final APK

One More Thing

Of course, maybe you don't want to change your build.grale file with that much code, and Of course, you also don't want to run ndk-build outside the IDE, then copy the <abi>/*.so files into jniLibs folder each time you want to rebuild the native codes!

At last, I came out another nicer solution, if you like, that is to create a ndk-build external tool in Android Studio, and every time you want to rebuild the native codes, simply run the external tool, then it automatically generates the libs/<abi>/*.so files into jniLibs folder, so everything is ready to run this app, :-)

The configuration is simple

Parameters: NDK_PROJECT_PATH=$ModuleFileDir$/build/intermediates/ndk NDK_LIBS_OUT=$ModuleFileDir$/src/main/jniLibs NDK_APPLICATION_MK=$ModuleFileDir$/src/main/jni/Application.mk APP_BUILD_SCRIPT=$ModuleFileDir$/src/main/jni/Android.mk V=1

OK, I hope it is helpful. Let me know if it is really helpful, or tell me what's your problem. :-)