• OpenCVAndroidBinariesBuild

How to build Android NDK application with prebuilt OpenCV

This page is under construction

This page describes a simple way to build Android application which uses OpenCV from native (C++) level. This way does not require building OpenCV from source code. Instead, you will use prebuilt OpenCV binary distribution. Note that this page does not describe how to create an Android application which uses OpenCV Java API (coming soon).

Prerequisites

1. Install the latest version of Android NDK (download it as an archive and extract somewhere).
2. Eclipse
3. ant

Android NDK Documentation

Before start you can read official Android NDK documentation which is in the Android NDK archive, in the folder docs/. The main article about using Android NDK build sustem is in ANDROID-MK.html file. Also some additional information is in APPLICATION-MK.html, NDK-BUILD.html, CPU-ARM-NEON.html, CPLUSPLUS-SUPPORT.html, and PREBUILTS.html files.

Android application' source code structure

Usually source code of an Android application has the following structure:

• root folder of the project/
  • jni/
  • res/
  • src/

  • AndroidManifest.xml

  • default.properties
  • ... other files ...

where

• the folder "src" contains the Java code of the application,

  the folder "res" contains resources of the application (images, xml files describing the application layout, etc),

  and the folder "jni" contains C/C++ application source code and simple scripts Android.mk and Application.mk. These scripts control the C++ build process (they are written in Makefile language).

Also the root folder should contain the following files:

• the file AndroidManifest.xml presents essential information about the application to the Android system (name of the Application, name of the main application's Java package, components of the application, etc) --- it can be created using Eclipse wizard, android tool from SDK, or manually

• the text file default.properties contains information about Android target platform and some other details. The file is generated by Eclipse or console ant application.

ATTENTION: Both files (AndroidManifest.xml and default.properties) are required to compile the C++ part of the application source code (the Android build system uses information from these files). If the files don't exist, compile the Java part of the project before the C++ part of the project.

How to build Android application which have C++ part

Here is the standard way to compile C++ part of an Android application:

1. go to the folder jni of the application project
2. run the following command

    <path_where_NDK_is_placed>/ndk-build

   After executing this command the C++ part of the source code is compiled

After that the Java part of the application can be recompiled (using either Eclipse, or ant build tool, or scripts calling ant commands, etc), and then the built application can be installed on a device.

Note that some parameters can be set for the script ndk-build.

Example 1: Verbose compilation

<path_where_NDK_is_placed>/ndk-build V=1

Example 2: Rebuild all

<path_where_NDK_is_placed>/ndk-build -B''' '''

The structure of Android.mk and Application.mk scripts

The script Android.mk usually have the following structure:

LOCAL_PATH := $(call my-dir)
include $(CLEAR_VARS)
LOCAL_MODULE    := <module_name>
LOCAL_SRC_FILES := <list of .c and .cpp project files>
<some variable name> := <some variable value>
...
<some variable name> := <some variable value>
include $(BUILD_SHARED_LIBRARY)

This is the minimal file Android.mk, which builds a C++ source code of an Android application. Note that the first two lines and the last line are mandatory for any Android.mk.

Usually the file Application.mk is optional, but sometimes, when STL or exceptions are used in C++, it also should be written. Example of the file Application.mk:

APP_STL := gnustl_static
APP_CPPFLAGS := -frtti -fexceptions
APP_ABI := armeabi-v7a

How to build an Android application, which uses OpenCV

To build an application, which uses OpenCV, the following changes should be done:

1. The archive OpenCV_Package.tar.bz2 should be downloaded and extracted to some folder (as example, into the home folder)

2. The environment variable OPENCV_PACKAGE_DIR should be defined. The value of the variable should points to the folder, where the OpenCV package has been extracted. As an example, you can add add the following line into the hidden file .bashrc placed in your home folder: export OPENCV_PACKAGE_DIR = <path to the extracted OpenCV package>. Then and reboot your computer. ATTENTION: without rebooting (or logout) this change won't work.

3. The file jni/Android.mk should be written for the current application using the common rules for the file.

   • For detailed information see the Android NDK documentation from the Android NDK archive, in the file

   • <path_where_NDK_is_placed>/docs/ANDROID-MK.html

4. The line include OpenCV.Android.mk.inc should be inserted into the jni/Android.mk file right after the include $(CLEAR_VARS) line.

5. Also the line

   • LOCAL_ARM_NEON := true

   • is recommended to be added to the jni/Android.mk file, if the application should be run on Android devices with ARM NEON support.
6. The file Application.mk should exist and should contain lines
   • APP_STL := gnustl_static APP_CPPFLAGS := -frtti -fexceptions
   • Also the line
     • APP_ABI := armeabi-v7a
     is recommended to run the application on modern ARMs
7. To build the C++ code the script ndk-build should be run in the root directory of application.

Then the C++ source code using OpenCV will be built by Android NDK build system. After that the Java part of the application can be rebuild and the application can be installed on an Android device.