@ -7,10 +7,39 @@ Using Android binary package with Eclipse
This tutorial was tested using Ubuntu 10.04 and Windows 7 SP1 operating systems. Nevertheless, it should also work on any other **OS**\ es supported by Android SDK (including 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.
Quick environment setup for Android development
===============================================
If you are making a clean environment installation then you can try **T**\ egra **A**\ ndroid **D**\ evelopment **P**\ ack (*TADP*) released by *NVIDIA*:
It will cover all of the environment set up automatically and you can go to the next step :ref:`Get_the_OpenCV_package_for_Android_development` right after automatic setup.
If you are a beginner in Android development then we recommentd you to start with TADP.
..note::*NVIDIA*\ 's Tegra Android Development Pack includes some special features for |Nvidia_Tegra_Platform|_ but it is not just for *Tegra* devices
+ You need at least *1.6 Gb* free disk space for installation.
+ TADP will download Android SDK platforms and Android NDK from Google's server, so you need an Internet connection for the installation.
+ TADP can ask you to flash your development kit at the end of installation process. Just skip this step if you have no |Tegra_Ventana_Development_Kit|_\ .
+ (``UNIX``) TADP will ask you for a *root* in the middle of installation, so you need to be a member of *sudo* group.
@ -18,7 +47,7 @@ You need the following tools to be installed:
Visit http://www.oracle.com/technetwork/java/javase/downloads/index.html and download installer for your OS.
Here is a detailed JDK installation guide for Ubuntu and Mac OS: http://source.android.com/source/initializing.html#installing-the-jdk (only JDK sections are applicable for OpenCV)
Here is a detailed :abbr:`JDK (Java Development Kit)` installation guide for Ubuntu and Mac OS: http://source.android.com/source/initializing.html#installing-the-jdk (only JDK sections are applicable for OpenCV)
..note:: OpenJDK is not usable for Android development because Android SDK supports only Sun JDK.
If you use Ubuntu, after installation of Sun JDK you should run the following command to set Sun java environment:
@ -27,9 +56,6 @@ You need the following tools to be installed:
sudo update-java-alternatives --set java-6-sun
#. **Android SDK**
Get the latest Android SDK from http://developer.android.com/sdk/index.html
@ -87,24 +113,26 @@ You need the following tools to be installed:
Assuming that you have Eclipse IDE installed, as described above, follow these steps to download and install the ADT plugin:
#. Start Eclipse, then select **Help** > **Install New Software...**
#. Click **Add**, in the top-right corner.
#. In the Add Repository dialog that appears, enter "ADT Plugin" for the Name and the following URL for the Location:
#. Start Eclipse, then select :menuselection:`Help --> Install New Software...`
#. Click :guilabel:`Add` (in the top-right corner).
#. In the :guilabel:`Add Repository` dialog that appears, enter "ADT Plugin" for the Name and the following URL for the Location:
https://dl-ssl.google.com/android/eclipse/
#. Click **OK**
#. Click :guilabel:`OK`
..note:: If you have trouble acquiring the plugin, try using "http" in the Location URL, instead of "https" (https is preferred for security reasons).
#. In the Available Software dialog, select the checkbox next to Developer Tools and click **Next**.
#. In the next window, you'll see a list of the tools to be downloaded. Click **Next**.
#. Read and accept the license agreements, then click **Finish**.
#. In the :guilabel:`Available Software` dialog, select the checkbox next to :guilabel:`Developer Tools` and click :guilabel:`Next`.
#. In the next window, you'll see a list of the tools to be downloaded. Click :guilabel:`Next`.
#. Read and accept the license agreements, then click :guilabel:`Finish`.
..note:: If you get a security warning saying that the authenticity or validity of the software can't be established, click **OK**.
..note:: If you get a security warning saying that the authenticity or validity of the software can't be established, click :guilabel:`OK`.
#. When the installation completes, restart Eclipse.
@ -112,7 +140,7 @@ Get the OpenCV package for Android development
#. Create new folder for Android+OpenCV development.
..note:: Better to use a path without spaces in it. Otherwise you will probably have problems with ndk-build.
..note:: Better to use a path without spaces in it. Otherwise you will probably have problems with :command:`ndk-build`.
#. Unpack the OpenCV package into that dir.
@ -154,30 +182,30 @@ Open OpenCV library and samples in Eclipse
Once you have created a new workspace, you have to point the ADT plugin to the Android SDK directory. This setting is stored in workspace metadata, as result this step is required each time when you are creating new workspace for Android development. See `Configuring the ADT Plugin
<http://developer.android.com/sdk/eclipse-adt.html#configuring>`_ document for the original instructions from *Google*.
* Select **Window > Preferences...** to open the Preferences panel (Mac OS X: **Eclipse > Preferences**):
* Select :menuselection:`Window --> Preferences...` to open the Preferences panel (Mac OS X: :menuselection:`Eclipse --> Preferences`):
..image:: images/eclipse_2_window_preferences.png
:height:400px
:alt:Select Window > Preferences...
:align:center
* Select **Android** from the left panel.
* Select :guilabel:`Android` from the left panel.
You may see a dialog asking whether you want to send usage statistics to *Google*. If so, make your choice and click **Proceed**. You cannot continue with this procedure until you click **Proceed**.
You may see a dialog asking whether you want to send usage statistics to *Google*. If so, make your choice and click :guilabel:`Proceed`. You cannot continue with this procedure until you click :guilabel:`Proceed`.
* For the *Select root directory* in the main panel locate your OpenCV package folder. (If you have created workspace in the package directory, then just click **Browse...** button and instantly close directory choosing dialog with **OK** button!) Eclipse should automatically locate OpenCV library and samples:
* For the :guilabel:`Select root directory` in the main panel locate your OpenCV package folder. (If you have created workspace in the package directory, then just click :guilabel:`Browse...` button and instantly close directory choosing dialog with :guilabel:`OK` button!) Eclipse should automatically locate OpenCV library and samples:
..image:: images/eclipse_7_select_projects.png
:alt:Locate OpenCV library and samples
:align:center
* Click **Finish** button to complete the import operation.
* Click :guilabel:`Finish` button to complete the import operation.
After clicking **Finish** button Eclipse will load all selected projects into workspace. And... will indicate numerous errors:
After clicking :guilabel:`Finish` button Eclipse will load all selected projects into workspace. And... will indicate numerous errors:
..image:: images/eclipse_8_false_alarm.png
:alt:Confusing Eclipse screen with numerous errors
@ -215,7 +243,7 @@ Open OpenCV library and samples in Eclipse
However **all these errors are only false-alarms**!
To help Eclipse to understand that there are no any errors choose OpenCV library in *Package Explorer* (left mouse click) and press **F5** button on your keyboard. Then choose any sample (except first samples in *Tutorial Base* and *Tutorial Advanced*) and also press **F5**.
To help Eclipse to understand that there are no any errors choose OpenCV library in :guilabel:`Package Explorer` (left mouse click) and press :kbd:`F5` button on your keyboard. Then choose any sample (except first samples in *Tutorial Base* and *Tutorial Advanced*) and also press :kbd:`F5`.
After this manipulation Eclipse will rebuild your workspace and error icons will disappear one after another:
@ -229,7 +257,7 @@ Open OpenCV library and samples in Eclipse
:alt:OpenCV package imported into Eclipse
:align:center
..note:: If you are importing only OpenCV library without samples then instead of second refresh command (**F5**) you might need to make **Android Tools** > **Fix Project Properties** from project context menu.
..note:: If you are importing only OpenCV library without samples then instead of second refresh command (:kbd:`F5`) you might need to make :menuselection:`Android Tools --> Fix Project Properties` from project context menu.
Running OpenCV Samples
======================
@ -242,7 +270,7 @@ Also I want to note that only ``Tutorial 1 Basic - 0. Android Camera`` and ``Tut
Well, running samples from Eclipse is very simple:
* Connect your device with ``adb`` tool from Android SDK or create Emulator with camera support.
* Connect your device with :command:`adb` tool from Android SDK or create Emulator with camera support.
* See `Managing Virtual Devices
<http://developer.android.com/guide/developing/devices/index.html>`_ document for help with Android Emulator.
@ -250,7 +278,7 @@ Well, running samples from Eclipse is very simple:
<http://developer.android.com/guide/developing/device.html>`_ for help with real devices (not emulators).
* Select project you want to start in *Package Explorer* and just press **Ctrl + F11** or select option **Run** > **Run** from main menu, or click **Run** button on the toolbar.
* Select project you want to start in :guilabel:`Package Explorer:guilabel:` and just press :kbd:`Ctrl + F11` or select option :menuselection:`Run --> Run` from main menu, or click :guilabel:`Run` button on the toolbar.
..note:: Android Emulator can take several minutes to start. So, please, be patient.
@ -260,7 +288,7 @@ Well, running samples from Eclipse is very simple:
:alt:Run sample as Android Application
:align:center
* Select the *Android Application* option and click **OK** button. Eclipse will install and run the sample.
* Select the :guilabel:`Android Application` option and click :guilabel:`OK` button. Eclipse will install and run the sample.
Here is ``Tutorial 1 Basic - 1. Add OpenCV`` sample detecting edges using Canny algorithm from OpenCV:
@ -281,7 +309,7 @@ If you already have an Android application, you can add a reference to OpenCV an
#. Add a reference to OpenCV project.
Do the right mouse click on your app in Package Explorer, go to **Properties > Android > Library > Add**
Do the right mouse click on your app in Package Explorer, go to :menuselection:`Properties --> Android --> Library --> Add`
@ -75,11 +75,11 @@ Also the root folder should contain the following files
* :file:`AndroidManifest.xml` file presents essential information about application to the Android system
(name of the Application, name of main application's package, components of the application, required permissions, etc)
It can be created using Eclipse wizard or :file:`android` tool from Android SDK
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.
This file is generated by Eclipse or can be created with :file:`android` tool from Android SDK
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.
@ -95,7 +95,7 @@ Here is the standard way to compile C++ part of an Android application:
cd <root folder of the project>/
..note:: Alternatively you can go to the folder :file:`jni` of Android project but samples from OpenCV binary package are configured for building from project root level (because of relative path to OpenCV library).
..note:: Alternatively you can go to the folder :file:`jni` of Android project but samples from OpenCV binary package are configured for building from project root level (because of relative path to the OpenCV library).
#. Run the following command
@ -111,9 +111,9 @@ Here is the standard way to compile C++ part of an Android application:
#. After executing this command the C++ part of the source code is compiled.
After that the Java part of the application can be (re)compiled (using either *Eclipse* or *ant* build tool).
After that the Java part of the application can be (re)compiled (using either *Eclipse* or :command:`ant` build tool).
..note:: Some parameters can be set for the :file:`ndk-build`:
..note:: Some parameters can be set for the :command:`ndk-build`:
**Example 1**: Verbose compilation
@ -140,92 +140,92 @@ There are several possible ways to integrate compilation of C++ code by Android
Below is an adapted version of this guide:
#. Navigate to *Package Explorer* window and expand your project having JNI resources.
#. Navigate to :guilabel:`Package Explorer` window and expand your project having JNI resources.
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 *Package Explorer* window and select *Properties*.
#. Right click on your project in :guilabel:`Package Explorer` window and select :guilabel:`Properties`.
#. In the *Properties* dialog select *Builders* menu and press the *New...* button:
#. In the :guilabel:`Properties` dialog select :guilabel:`Builders` menu and press the :guilabel:`New...` button:
..image:: images/eclipse_builders.png
:alt:Configure builders
:align:center
#. In the resulting dialog select the *Program* type and press the *OK* button:
#. In the resulting dialog select the :guilabel:`Program` type and press :guilabel:`OK` button:
..image:: images/eclipse_builder_types.png
:alt:Choose builder type
:align:center
#. In the *Main* tab fill the following fields:
#. In the :guilabel:`Main` tab fill the following fields:
* *Name* - any name for your builder. ("Tutorial 2.1 Builder" in my case.)
* :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.
* *Location* - path to :file:`ndk-build` tool.
* :guilabel:`Location` - full path to :command:`ndk-build` tool.
+ *UNIX*
Just put full path to :file:`ndk-build` into this filed. Also you can add some options to the *Arguments* fied, for example **-B** option.
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 :file:`ndk-build` tool you need to put full path to *cygwin*:file:`bash.exe` location. E.g: :file:`C:\\cygwin\\bin\\bash.exe`.
- 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 :file:`ndk-build` into the *Arguments* field E.g. :file:`C:\\Android\\android-ndk-r6\\ndk-build`.
- 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 *Environment* tab and define an environment variable:
- Go to the :guilabel:`Environment` tab and define an environment variable:
* **PATH** - full path to the *cygwin* tools. E.g. :file:`C:\\cygwin\\bin`
* :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
* *Working Directory* - put path to your project into this field. Instead of hardcoding full path you can click *Browse Workspace..." button and select your project.
* :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.
#. Finally press *OK* in the builder configuration and project properties dialogs. If you have automatic build turned on then console showing build log should appear:
#. 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:
..image:: images/eclipse_NDK_build_success.png
:alt:Select resources to build
:align:center
Theory: The structure of Android.mk and Application.mk scripts
The script :file:`Android.mk` usually have the following structure:
@ -269,13 +269,13 @@ 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
#. 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"*
#. 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: *Project* > *Clean...*)
#. Clean these projects (in the main Eclipse menu: :menuselection:`Project --> Clean...`)
#. Run Eclipse build command (if option *"Build Automatically"* is not set)
#. Run Eclipse build command (if option :guilabel:`Build Automatically` is not set)
Practice: Create an Android application, which uses OpenCV
@ -287,7 +287,7 @@ To build your own Android application, which uses OpenCV from native part, the f
#. 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.
So, the environment variable **OPENCV_PACKAGE_DIR** should be defined.
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.
@ -305,15 +305,15 @@ To build your own Android application, which uses OpenCV from native part, the f
* *Windows 7 / Windows Vista*
My Computer (Right Click on Icon) > Properties (Link) > Advanced System Settings (Link) > Advanced (Tab) > Environment Variables (Button) > System variables (Section)
:menuselection:`My Computer (Right Click on Icon) --> Properties (Link) --> Advanced System Settings (Link) --> Advanced (Tab) --> Environment Variables (Button) --> System variables (Section)`
* *Windows XP*
My Computer (Right Click on Icon) > Properties (Link) > Advanced (Tab) > Environment Variables (Button) > System variables (Section)
:menuselection:`My Computer (Right Click on Icon) --> Properties (Link) --> Advanced (Tab) --> Environment Variables (Button) --> System variables (Section)`
Create new variable **OPENCV_PACKAGE_DIR** and similarly to *UNIX* relogin or reboot.
Create new variable :envvar:`OPENCV_PACKAGE_DIR` and similarly to *UNIX* relogin or reboot.
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 *Environment* tab of the builder configuration window (we have already added some variables to this tab on *Windows* but skipped it for other platforms).
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).
#. The file :file:`jni/Android.mk` should be written for the current application using the common rules for the file.
@ -353,11 +353,11 @@ To build your own Android application, which uses OpenCV from native part, the f
is recommended for the applications targeting modern ARMs
#. To build the C++ code the Android NDK script :file:`ndk-build` should be run in the root directory of application.
#. 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 :file:`ndk-build` script from the console; instead of this step you can use integration of Android NDK into Eclipse
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` .
@ -366,13 +366,12 @@ Additional C++ support in Eclipse
Note that you can install additional C++ plugins in Eclipse:
#. Open Help / Install New Software. This shows the “Install” dialog.
#. Open :guilabel:`Help / Install New Software`. This shows the :guilabel:`Install` dialog.
#. In the “Work with” drop-down list choose "Helios - http://download.eclipse.org/releases/helios" and wait while the list of
available software is loaded.
#. 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 “Programming Languages” / “C/C++ Development Tools 7.0.1”.
#. From the list of available software select :menuselection:`Programming Languages --> C/C++ Development Tools`.
#. Click "Next", click "Next" again, accept the agreement, and click the button "Finish"
#. Click :guilabel:`Next`, click :guilabel:`Next` again, accept the agreement, and click the :guilabel:`Finish` button.
#. When installation is finished, click "Reload"
#. When installation is finished, click :guilabel:`Reload`
Andrey Kamaev
13 years ago