Please note that before starting this tutorial you should fulfill all the steps, described in the tutorial :ref:`Android_Binary_Package`.
This tutorial was tested using Ubuntu 10.04 and Windows 7 SP1 operating systems.
-Nevertheless, it should also work on Mac OS X. If you encounter errors after following the steps described here, feel free to contact us via *android-opencv* discussion group https://groups.google.com/group/android-opencv/ and we will try to help you.
+Nevertheless, it should also work on Mac OS X. If you encounter errors after following the steps described here, feel free to contact us via
+`android-opencv <https://groups.google.com/group/android-opencv/>`_ discussion group and we will try to help you.
Prerequisites: Setup NDK
========================
-To compile C++ code for Android platform you need Android **N**\ ative **D**\ evelopment **K**\ it (*NDK*).
+To compile C++ code for Android platform you need ``Android Native Development Kit`` (*NDK*).
-You can get the latest version of NDK from the page http://developer.android.com/sdk/ndk/index.html .
+You can get the latest version of NDK from the `download page <http://developer.android.com/sdk/ndk/index.html>`_.
-To install Android NDK just extract the archive to some folder on your computer. (Here is installation instructions on the NDK home page: http://developer.android.com/sdk/ndk/index.html#installing)
+To install Android NDK just extract the archive to some folder on your computer. (Here is `installation instructions <http://developer.android.com/sdk/ndk/index.html#installing>`_ on the NDK home page.)
.. note:: Before start you can read official Android NDK documentation which is in the Android NDK archive, in the folder :file:`docs/`.
- :file:`AndroidManifest.xml`
- - :file:`default.properties`
+ - :file:`project.properties`
- :file:`... other files ...`
It can be created using Eclipse wizard or :command:`android` tool from Android SDK
-* :file:`default.properties` is a text file containing information about target Android platform and other build details.
+* :file:`project.properties` is a text file containing information about target Android platform and other build details.
This file is generated by Eclipse or can be created with :command:`android` tool from Android SDK
-.. note:: Both files (:file:`AndroidManifest.xml` and :file:`default.properties`) are required to compile the C++ part of the application (NDK build system uses information from these files). If any of these files does not exist, compile the Java part of the project before the C++ part.
+.. note:: Both files (:file:`AndroidManifest.xml` and :file:`project.properties`) are required to compile the C++ part of the application (NDK build system uses information from these files). If any of these files does not exist, compile the Java part of the project before the C++ part.
+
+.. _NDK_build_cli:
Theory: How to build Android application having C++ native part (from command line)
<path_where_NDK_is_placed>/ndk-build
- .. note:: If you are working in *cygwin* shell and encounter an error saying that NDK does not find some *cygwin*\ 's path then you might need to define the following environment variable:
-
- .. code-block:: bash
+ .. note:: On Windows we recomend use of ``ndk-build.cmd`` in standard Windows console (``cmd.exe``) rather than the similar ``bash`` script in ``Cygwin`` shell.
- export NDK_USE_CYGPATH=1
+ .. image:: images/ndk_build.png
+ :alt: NDK build
+ :align: center
#. After executing this command the C++ part of the source code is compiled.
Theory: How to build Android application having C++ native part (from *Eclipse*)
================================================================================
-There are several possible ways to integrate compilation of C++ code by Android NDK into Eclipse compilation process. We recommend the approach taken from this site: http://mobilepearls.com/labs/ndk-builder-in-eclipse/
+There are several possible ways to integrate compilation of C++ code by Android NDK into Eclipse compilation process.
+We recommend the approach based on Eclipse :abbr:`CDT(C/C++ Development Tooling)` Builder.
-.. important:: This instructions should be applied for each Android project in *Eclipse* workspace. So if you have 3 projects having C++ part then you need to configure 3 builders.
+.. important:: Make sure your Eclipse IDE has the :abbr:`CDT(C/C++ Development Tooling)` plugin installed. (Menu ``Help`` -> ``About Eclipse SDK`` -> ``Installation Details``)
-Below is an adapted version of this guide:
+.. image:: images/eclipse_inst_details.png
+ :alt: Configure builders
+ :align: center
-#. Navigate to :guilabel:`Package Explorer` window and expand your project having JNI resources.
+To install the `CDT plugin <http://eclipse.org/cdt/>`_ use menu ``Help`` -> ``Install New Software...``,
+then paste the CDT 8.0 repository URL http://download.eclipse.org/tools/cdt/releases/indigo as shown on the picture below and click :guilabel:`Add...`, name it *CDT* and click :guilabel:`OK`.
+
+.. image:: images/eclipse_inst_cdt.png
+ :alt: Configure builders
+ :align: center
- If you can not see :file:`libs` folder under this project then you need to create it manually. (It will be required on step 7, but you need to create it before you open project properties.)
-
-#. Right click on your project in :guilabel:`Package Explorer` window and select :guilabel:`Properties`.
+``CDT Main Features`` should be enough:
+
+.. image:: images/eclipse_inst_cdt_2.png
+ :alt: Configure builders
+ :align: center
+.. important:: This instructions should be applied for each Android project in *Eclipse* workspace having native (JNI) part to build.
-#. In the :guilabel:`Properties` dialog select :guilabel:`Builders` menu and press the :guilabel:`New...` button:
+#. Right click on your project in :guilabel:`Package Explorer` window and select :guilabel:`New` -> :guilabel:`Other`:
- .. image:: images/eclipse_builders.png
- :alt: Configure builders
+ .. image:: images/eclipse_cdt_cfg1.png
+ :alt: Configure CDT
:align: center
-#. In the resulting dialog select the :guilabel:`Program` type and press :guilabel:`OK` button:
+#. Select :guilabel:`C/C++` -> :guilabel:`Convert to C/C++ project`:
- .. image:: images/eclipse_builder_types.png
- :alt: Choose builder type
+ .. image:: images/eclipse_cdt_cfg2.png
+ :alt: Configure CDT
:align: center
-#. In the :guilabel:`Main` tab fill the following fields:
-
- * :guilabel:`Name` - any name for your builder. ("Tutorial 2.1 Builder" in my case.)
-
- .. note:: This name has to be unique for each project in your workspace.
-
- * :guilabel:`Location` - full path to :command:`ndk-build` tool.
-
- + *UNIX*
-
- Just put full path to :command:`ndk-build` into this filed. Also you can add some options to the :guilabel:`Arguments:guilabel:` fied, for example ``-B`` option.
-
- + *Cygwin*
-
- - Instead of path to the :command:`ndk-build` tool you need to put full path to *cygwin*\ 's :program:`bash.exe` location. E.g: :file:`C:\\cygwin\\bin\\bash.exe`.
-
- - Put full path to :command:`ndk-build` into the :guilabel:`Arguments` field E.g. :file:`C:\\Android\\android-ndk-r6\\ndk-build`.
-
- - Go to the :guilabel:`Environment` tab and define an environment variable:
-
- * :envvar:`PATH` - full path to the *cygwin* tools. E.g. :file:`C:\\cygwin\\bin`
-
- .. image:: images/eclipse_windows_environment.png
- :alt: Define environment variables
- :align: center
-
- * :guilabel:`Working Directory` - put path to your project into this field. Instead of hardcoding full path you can click :guilabel:`Browse Workspace...` button and select your project.
-
- .. image:: images/eclipse_edit_configuration_main.png
- :alt: Define environment variables
- :align: center
+#. Select :guilabel:`"C++"`, :guilabel:`"Makefile Project"`, :guilabel:`"Other Toolchain"`:
-#. Go to the :guilabel:`Refresh` tab and select both :guilabel:`Refresh resources upon completion` and :guilabel:`Recursively include sub-folders`.
-
- Next set the :guilabel:`Specific resources` option and click :guilabel:`Specify resources...` button:
-
- .. image:: images/eclipse_edit_configuration_refresh.png
- :alt: Define environment variables
- :align: center
-
-#. Select :file:`libs` folder under your project and click :guilabel:`Finish`:
-
- .. image:: images/eclipse_edit_configuration_specify_resources.png
- :alt: Select resources folder to refresh automatically
- :align: center
+ .. image:: images/eclipse_cdt_cfg3.png
+ :alt: Configure CDT
+ :align: center
-#. Go to the last tab :guilabel:`Build options`. Make sure that all checkboxes are set as shown on the next screen:
+#. Right click on your project in :guilabel:`Package Explorer` window and select :guilabel:`Properties`, then :guilabel:`C/C++ Build` in the left pane.
+ Unckeck :guilabel:`Use default build command` and put ndk-build invocation in the :guilabel:`Build command` edit box and click :guilabel:`Apply` :
- .. image:: images/eclipse_edit_configuration_build_options.png
- :alt: Configure build options
- :align: center
+ .. image:: images/eclipse_cdt_cfg4.png
+ :alt: Configure CDT
+ :align: center
-#. Next, click the :guilabel:`Specify resources...` button.
+#. Select :guilabel:`Builders` in the left pane, select :guilabel:`"CDT Builder"`, press :guilabel:`Edit` button on the righ and set check-boxes as on the picture below for automatic rebuild of JNI part:
-#. Select :file:`jni` folder of your project and click the :guilabel:`Finish` button:
+ .. image:: images/eclipse_cdt_cfg5.png
+ :alt: Configure CDT
+ :align: center
- .. image:: images/eclipse_edit_configuration_build_resources.png
- :alt: Select resources to build
- :align: center
-#. Finally press :guilabel:`OK` in the builder configuration and project properties dialogs. If you have automatic build turned on then console showing build log should appear:
+#. Use menu :guilabel:`Project` -> :guilabel:`Clean...` to make sure that NDK build is invoked on the project build:
- .. image:: images/eclipse_NDK_build_success.png
- :alt: Select resources to build
- :align: center
+ .. image:: images/eclipse_ndk_build.png
+ :alt: Select resources folder to refresh automatically
+ :align: center
Theory: The structure of :file:`Android.mk` and :file:`Application.mk` scripts
==============================================================================
Practice: Build samples from OpenCV binary package
==================================================
-OpenCV binary package includes two samples having JNI resources:
+OpenCV binary package includes 3 samples having JNI resources:
-* *Tutorial 2 Advanced - 1. Add Native OpenCV*
+* *Tutorial 3 (Advanced) - Add Native OpenCV*
- This sample illustrate how you can use OpenCV in C++ but without OpenCV Java API.
+ This sample illustrates how you can use OpenCV in C++ but without OpenCV Java API.
-* *Tutorial 2 Advanced - 2. Mix Java+Native OpenCV*
+* *Tutorial 4 (Advanced) - Mix Java+Native OpenCV*
This sample shows how you can mix OpenCV Java API and native C++ code.
-To build these samples you need to:
-
-#. Fulfill all the steps, described in the tutorial :ref:`Android_Binary_Package`.
-
-#. Setup one builder for *"Tutorial 2 Advanced - 1. Add Native OpenCV"* project (as described in :ref:`Android_NDK_integration_with_Eclipse`)
-
-#. Setup second builder for *"Tutorial 2 Advanced - 2. Mix Java+Native OpenCV"* project (repeat the steps from :ref:`Android_NDK_integration_with_Eclipse`)
-
-#. Clean these projects (in the main Eclipse menu: :menuselection:`Project --> Clean...`)
-
-#. Run Eclipse build command (if option :guilabel:`Build Automatically` is not set)
+* *Sample - face-detection*
+ This sample illustrates usage of both simple OpenCV face detector via Java API and advanced detection based face tracker via JNI and C++.
+
+Before OpenCV 2.4.2 for Android these projects are not configured to use CDT for building their native part , so you can do it yourself.
Practice: Create an Android application, which uses OpenCV
==========================================================
To build your own Android application, which uses OpenCV from native part, the following steps should be done:
-#. The archive with OpenCV binary package should be downloaded and extracted to some folder (as example, into the home folder)
-
-#. We recommend to use an environment variable to specify the location of OpenCV package. Full or relative path hardcoded in :file:`jni/Android.mk` will also work.
+#. The archive with OpenCV binary package should be downloaded and extracted to some folder (e.g. ``C:\Work\android-opencv\OpenCV-2.4.0``)
- So, the environment variable :envvar:`OPENCV_PACKAGE_DIR` should be defined.
- The value of the variable should points to the folder, where the OpenCV package has been extracted.
+#. You can use an environment variable to specify the location of OpenCV package or just hardcode full or relative path in the :file:`jni/Android.mk` of your projects.
+#. The file :file:`jni/Android.mk` should be written for the current application using the common rules for the file.
- As an example, on *UNIX* you can add add the following line into the hidden file :file:`.bashrc` placed in your home folder:
-
- .. code-block:: bash
-
- export OPENCV_PACKAGE_DIR = <path to the extracted OpenCV package>
-
- Then relogin (or better reboot your computer).
-
- .. attention:: without rebooting (or logout) this change might not work.
+ For detailed information see the Android NDK documentation from the Android NDK archive, in the file
+ :file:`<path_where_NDK_is_placed>/docs/ANDROID-MK.html`
- If you are a *Windows* user, then navigate to:
+#. The line
- * *Windows 7 / Windows Vista*
+ .. code-block:: make
- :menuselection:`My Computer (Right Click on Icon) --> Properties (Link) --> Advanced System Settings (Link) --> Advanced (Tab) --> Environment Variables (Button) --> System variables (Section)`
+ include C:\Work\android-opencv\OpenCV-2.4.0\share\OpenCV\OpenCV.mk
- * *Windows XP*
+ should be inserted into the :file:`jni/Android.mk` file right after the line
- :menuselection:`My Computer (Right Click on Icon) --> Properties (Link) --> Advanced (Tab) --> Environment Variables (Button) --> System variables (Section)`
+ .. code-block:: make
- Create new variable :envvar:`OPENCV_PACKAGE_DIR` and similarly to *UNIX* relogin or reboot.
+ include $(CLEAR_VARS)
- If you are setting NDK builder as described above in :ref:`Android_NDK_integration_with_Eclipse`, then you can define this variable in builder settings. It can be done on third :guilabel:`Environment` tab of the builder configuration window (we have already added some variables to this tab on *Windows* but skipped it for other platforms).
+ Several variables can be used to customize OpenCV stuff, they should be set **before** the ``"include ...\OpenCV.mk"`` line:
-#. The file :file:`jni/Android.mk` should be written for the current application using the common rules for the file.
+ .. code-block:: make
- For detailed information see the Android NDK documentation from the Android NDK archive, in the file
- :file:`<path_where_NDK_is_placed>/docs/ANDROID-MK.html`
+ OPENCV_INSTALL_MODULES:=on
-#. The line
+ Copies necessary OpenCV dynamic libs to the project ``libs`` folder in order to include them into the APK.
.. code-block:: make
- include $(OPENCV_PACKAGE_DIR)/share/OpenCV/OpenCV.mk
+ OPENCV_CAMERA_MODULES:=off
- should be inserted into the :file:`jni/Android.mk` file right after the line
+ Skip native OpenCV camera related libs copying to the project ``libs`` folder.
.. code-block:: make
- include $(CLEAR_VARS)
-
- .. note:: If your application utilize both native (C++) OpenCV and its Java API you need to put the following line before including :file:`OpenCV.mk` to avoid conflict between C++ and Java builders:
-
- .. code-block:: make
+ OPENCV_LIB_TYPE:=STATIC
- OPENCV_CAMERA_MODULES:=off
+ Perform static link with OpenCV. By default dynamic link is used and the project JNI lib depends on ``libopencv_java.so``.
#. The file :file:`Application.mk` should exist and should contain lines
is recommended for the applications targeting modern ARMs
-#. To build the C++ code the Android NDK script :command:`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.
-
- Note that this step requires calling the :command:`ndk-build` script from the console. Instead of this step you can use integration of Android NDK into Eclipse
- as stated above in the section :ref:`Android_NDK_integration_with_Eclipse` .
-
-
-Additional C++ support in Eclipse
-==================================
-
-Note that you can install additional C++ plugins in Eclipse:
-
-#. Open :guilabel:`Help / Install New Software`. This shows the :guilabel:`Install` dialog.
-
-#. In the :guilabel:`Work with` drop-down list choose :guilabel:`Helios - http://download.eclipse.org/releases/helios` (or :guilabel:`Indigo - http://download.eclipse.org/releases/indigo` depending on your Eclipse version) and wait while the list of available software is loaded.
-
-#. From the list of available software select :menuselection:`Programming Languages --> C/C++ Development Tools`.
-
-#. Click :guilabel:`Next`, click :guilabel:`Next` again, accept the agreement, and click the :guilabel:`Finish` button.
-
-#. When installation is finished, click :guilabel:`Reload`
+#. Either use :ref:`manual <NDK_build_cli>` ``ndk-build`` invocation or :ref:`setup Eclipse CDT Builder <Android_NDK_integration_with_Eclipse>` to build native JNI lib before Java part [re]build and APK creation.