diff --git a/doc/tutorials/introduction/android_binary_package/O4A_SDK.rst b/doc/tutorials/introduction/android_binary_package/O4A_SDK.rst index b426c5c1e..7aed35121 100644 --- a/doc/tutorials/introduction/android_binary_package/O4A_SDK.rst +++ b/doc/tutorials/introduction/android_binary_package/O4A_SDK.rst @@ -159,8 +159,8 @@ Get the OpenCV4Android SDK unzip ~/Downloads/OpenCV-2.4.3-android-sdk.zip -.. |opencv_android_bin_pack| replace:: OpenCV-2.4.3-android-sdk.zip -.. _opencv_android_bin_pack_url: http://sourceforge.net/projects/opencvlibrary/files/opencv-android/2.4.3/OpenCV-2.4.3-android-sdk.zip/download +.. |opencv_android_bin_pack| replace:: OpenCV-2.4.3.2-android-sdk.zip +.. _opencv_android_bin_pack_url: http://sourceforge.net/projects/opencvlibrary/files/opencv-android/2.4.3/OpenCV-2.4.3.2-android-sdk.zip/download .. |opencv_android_bin_pack_url| replace:: |opencv_android_bin_pack| .. |seven_zip| replace:: 7-Zip .. _seven_zip: http://www.7-zip.org/ @@ -186,6 +186,8 @@ Import OpenCV library and samples to the Eclipse Each sample included into the |opencv_android_bin_pack| is a regular Android project that already references OpenCV library.Follow the steps below to import OpenCV and samples into the workspace: + .. note:: OpenCV samples are indeed **dependent** on OpenCV library project so don't forget to import it to your workspace as well. + * Right click on the :guilabel:`Package Explorer` window and choose :guilabel:`Import...` option from the context menu: @@ -213,13 +215,21 @@ Import OpenCV library and samples to the Eclipse and you have to wait some time while it is building OpenCV samples. Just give a minute to Eclipse to complete initialization. - .. note :: After the initial import, on a non-Windows (Linux and Mac OS) operating system Eclipse + .. warning :: After the initial import, on a non-Windows (Linux and Mac OS) operating system Eclipse will still show build errors for applications with native C++ code. To resolve the issues, please do the following: Open :guilabel:`Project Properties -> C/C++ Build`, and replace "Build command" text to ``"${NDKROOT}/ndk-build"`` (remove .cmd at the end). + .. note :: In some cases the build errors don't disappear, then try the following actions: + + * right click on ``OpenCV Library`` project -> :guilabel:`Android Tools -> Fix Project Properties`, + then menu :guilabel:`Project -> Clean... -> Clean all` + * right click on the project with errors -> :guilabel:`Properties -> Android`, make sure the + ``Target`` is selected and is ``Android 3.0`` or higher + * check the build errors in the :guilabel:`Problems` view window and try to resolve them by yourselves + .. image:: images/eclipse_cdt_cfg4.png :alt: Configure CDT :align: center @@ -235,14 +245,14 @@ Import OpenCV library and samples to the Eclipse Running OpenCV Samples ---------------------- -At this point you should be able to build and run the samples. Keep in mind, that ``face-detection``, -``Tutorial 3`` and ``Tutorial 4`` include some native code and require Android NDK and CDT plugin -for Eclipse to build working applications. If you haven't installed these tools see the corresponding -section of :ref:`Android_Dev_Intro`. +At this point you should be able to build and run the samples. Keep in mind, that +``face-detection``, ``Tutorial 3` and ``Tutorial 4`` include some native code and +require Android NDK and CDT plugin for Eclipse to build working applications. If you haven't +installed these tools, see the corresponding section of :ref:`Android_Dev_Intro`. -Also, please consider that ``Tutorial 0`` and ``Tutorial 1`` samples use Java Camera API that -definitelly accessible on emulator from the Android SDK. -Other samples use OpenCV Native Camera which may not work with emulator. +.. warning:: Please consider that some samples use Android Java Camera API, which is accessible + with an AVD. But most of samples use OpenCV Native Camera which **may not work** with + an emulator. .. note:: Recent *Android SDK tools, revision 19+* can run ARM v7a OS images but they available not for all Android versions. @@ -282,6 +292,40 @@ Well, running samples from Eclipse is very simple: If you have no access to the *Market*, which is often the case with emulators - you will need to install the packages from OpenCV4Android SDK folder manually. See :ref:`manager_selection` for details. + .. code-block:: sh + :linenos: + + /platform-tools/adb install /apk/OpenCV_2.4.3_Manager_armv7a-neon.apk + + .. note:: ``armeabi``, ``armv7a-neon``, ``arm7a-neon-android8``, ``mips`` and ``x86`` stand for + platform targets: + + * ``armeabi`` is for ARM v5 and ARM v6 architectures with Android API 8+, + + * ``armv7a-neon`` is for NEON-optimized ARM v7 with Android API 9+, + + * ``arm7a-neon-android8`` is for NEON-optimized ARM v7 with Android API 8, + + * ``mips`` is for MIPS architecture with Android API 9+, + + * ``x86`` is for Intel x86 CPUs with Android API 9+. + + If using hardware device for testing/debugging, run the following command to learn + its CPU architecture: + + .. code-block:: sh + + adb shell getprop ro.product.cpu.abi + + If you're using an AVD emulator, go :menuselection:`Window > AVD Manager` to see the + list of availible devices. Click :menuselection:`Edit` in the context menu of the + selected device. In the window, which then pop-ups, find the CPU field. + + You may also see section :ref:`manager_selection` for details. + + + When done, you will be able to run OpenCV samples on your device/emulator seamlessly. + * Here is ``Tutorial 2 - Use OpenCV Camera`` sample, running on top of stock camera-preview of the emulator. .. image:: images/emulator_canny.png @@ -289,6 +333,7 @@ Well, running samples from Eclipse is very simple: :alt: Tutorial 1 Basic - 1. Add OpenCV - running Canny :align: center + What's next =========== diff --git a/doc/tutorials/introduction/android_binary_package/android_dev_intro.rst b/doc/tutorials/introduction/android_binary_package/android_dev_intro.rst index 8855c5bd9..a735bc8a7 100644 --- a/doc/tutorials/introduction/android_binary_package/android_dev_intro.rst +++ b/doc/tutorials/introduction/android_binary_package/android_dev_intro.rst @@ -78,7 +78,7 @@ Development in Java You need the following software to be installed in order to develop for Android in Java: -#. **Sun JDK 6** +#. **Sun JDK 6** (Sun JDK 7 is also possible) Visit `Java SE Downloads page `_ and download an installer for your OS. @@ -103,9 +103,10 @@ You need the following software to be installed in order to develop for Android Here is Google's `install guide `_ for the SDK. - .. note:: If you choose SDK packed into a Windows installer, then you should have 32-bit JRE - installed. It is not a prerequisite for Android development, but installer is a x86 - application and requires 32-bit Java runtime. + .. note:: You can choose downloading ``ADT Bundle package`` that in addition to Android SDK Tools includes + Eclipse + ADT + CDT plugins, Android Platform-tools, the latest Android platform and the latest + Android system image for the emulator - this is the best choice for those who is setting up Android + development environment the first time! .. note:: If you are running x64 version of Ubuntu Linux, then you need ia32 shared libraries for use on amd64 and ia64 systems to be installed. You can install them with the @@ -215,45 +216,11 @@ You need the following software to be installed in order to develop for Android #. **CDT plugin for Eclipse** + If you selected for installation the ``NDK plugins`` component of Eclipse ADT plugin (see the picture above) your Eclipse IDE + should already have ``CDT plugin`` (that means ``C/C++ Development Tooling``). 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. - Make sure your Eclipse IDE has the :abbr:`CDT(C/C++ Development Tooling)` plugin - installed. Menu :guilabel:`Help -> About Eclipse SDK -> Installation Details`. - - .. image:: images/eclipse_about_cdt_0.png - :alt: CDT in Eclipse About - :align: center - - .. - - .. image:: images/eclipse_about_cdt_1.png - :alt: CDT in Eclipse About - :align: center - - .. note:: If you're using the latest ADT plugin for Eclipse (version 20 and above), most likely - you already have the CDT plugin and don't need to install it. - - .. image:: images/eclipse_about_cdt_1.png - :alt: CDT in Eclipse About - :align: center - - To install the `CDT plugin `_ use menu - :guilabel:`Help -> Install New Software...`, then paste the CDT 8.0 repository URL - http://download.eclipse.org/tools/cdt/releases/indigo as shown in 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 - - ``CDT Main Features`` should be enough: - - .. image:: images/eclipse_inst_cdt_2.png - :alt: Configure builders - :align: center - - That's it. Compilation of C++ code is fully integrated into Eclipse building process now. Android application structure @@ -336,9 +303,9 @@ and exceptions are used in C++, it also should be created. Example of the file : APP_CPPFLAGS := -frtti -fexceptions APP_ABI := all -.. note:: We recommend setting ``APP_ABI := all`` for all targets. If you want to specify the - target explicitly, use ``armeabi`` for ARMv5/ARMv6, ``armeabi-v7a`` for ARMv7, ``x86`` - for Intel Atom or ``mips`` for MIPS. +.. note:: We recommend setting ``APP_ABI := all`` for all targets. If you want to specify the + target explicitly, use ``armeabi`` for ARMv5/ARMv6, ``armeabi-v7a`` for ARMv7, ``x86`` + for Intel Atom or ``mips`` for MIPS. .. _NDK_build_cli: @@ -348,6 +315,11 @@ Building application native part from command line Here is the standard way to compile C++ part of an Android application: +.. warning:: We strongly reccomend using ``cmd.exe`` (standard Windows console) instead of Cygwin on + **Windows**. Use the latter if only you're absolutely sure about, what you're doing. Cygwin + is not really supported and we are unlikely to help you in case you encounter some + problems with it. So, use it only if you're capable of handling the consequences yourself. + #. Open console and go to the root folder of an Android application .. code-block:: bash @@ -361,7 +333,7 @@ Here is the standard way to compile C++ part of an Android application: /ndk-build .. note:: On Windows we recommend to use ``ndk-build.cmd`` in standard Windows console (``cmd.exe``) - rather than the similar ``bash`` script in ``Cygwin`` shell. + rather than the similar ``bash`` script in ``Cygwin`` shell. .. image:: images/ndk_build.png :alt: NDK build @@ -401,12 +373,19 @@ Eclipse build process. We recommend the approach based on Eclipse (e.g. ``"X:\\Apps\\android-ndk-r8"`` or ``"/opt/android-ndk-r8"``). **On Windows** an environment variable can be set via - :guilabel:`My Computer -> Properties -> Advanced -> Environment variables` and restarting Eclipse. + :guilabel:`My Computer -> Properties -> Advanced -> Environment variables`. On Windows 7 it's also possible to use `setx `_ command in a console session. **On Linux** and **MacOS** an environment variable can be set via appending a ``"export VAR_NAME=VAR_VALUE"`` line to the :file:`"~/.bashrc"` file and logging off and then on. + .. note:: It's also possible to define the ``NDKROOT`` environment variable within Eclipse IDE, + but it should be done for every new workspace you create. If you prefer this option better than setting system + environment variable, open Eclipse menu :guilabel:`Window -> Preferences -> C/C++ -> Build -> Environment`, + press the :guilabel:`Add...` button and set variable name to ``NDKROOT`` and value to local Android NDK path. + +#. After that you need to **restart Eclipse** to apply the changes. + #. Open Eclipse and load the Android app project to configure. #. Add C/C++ Nature to the project via Eclipse menu :guilabel:`New -> Other -> C/C++ -> Convert to a C/C++ Project`. @@ -463,11 +442,20 @@ Eclipse build process. We recommend the approach based on Eclipse :: + # for NDK r8 and prior: ${NDKROOT}/platforms/android-9/arch-arm/usr/include ${NDKROOT}/sources/cxx-stl/gnu-libstdc++/include ${NDKROOT}/sources/cxx-stl/gnu-libstdc++/libs/armeabi-v7a/include ${ProjDirPath}/../../sdk/native/jni/include + :: + + # for NDK r8b and later: + ${NDKROOT}/platforms/android-9/arch-arm/usr/include + ${NDKROOT}/sources/cxx-stl/gnu-libstdc++/4.6/include + ${NDKROOT}/sources/cxx-stl/gnu-libstdc++/4.6/libs/armeabi-v7a/include + ${ProjDirPath}/../../sdk/native/jni/include + The last path should be changed to the correct absolute or relative path to OpenCV4Android SDK location. This should clear the syntax error notifications in Eclipse C++ editor. @@ -476,16 +464,6 @@ Eclipse build process. We recommend the approach based on Eclipse :alt: Configure CDT :align: center - .. note:: The latest Android NDK **r8b** uses different STL headers path. So if you use this NDK - release add the following **Include** paths list instead: - - :: - - ${NDKROOT}/platforms/android-9/arch-arm/usr/include - ${NDKROOT}/sources/cxx-stl/gnu-libstdc++/4.6/include - ${NDKROOT}/sources/cxx-stl/gnu-libstdc++/4.6/libs/armeabi-v7a/include - ${ProjDirPath}/../../sdk/native/jni/include - Debugging and Testing ===================== @@ -666,8 +644,8 @@ execute :command:`adb devices` command. You will see the list of attached device :alt: List of attached devices :align: center -MacOS host computer -^^^^^^^^^^^^^^^^^^^ +Mac OS host computer +^^^^^^^^^^^^^^^^^^^^ No actions are required, just connect your device via USB and run ``adb devices`` to check connection. What's next diff --git a/doc/tutorials/introduction/android_binary_package/images/eclipse_about_cdt_0.png b/doc/tutorials/introduction/android_binary_package/images/eclipse_about_cdt_0.png deleted file mode 100644 index 79e43690b..000000000 Binary files a/doc/tutorials/introduction/android_binary_package/images/eclipse_about_cdt_0.png and /dev/null differ diff --git a/doc/tutorials/introduction/android_binary_package/images/eclipse_about_cdt_1.png b/doc/tutorials/introduction/android_binary_package/images/eclipse_about_cdt_1.png deleted file mode 100644 index 9b2c9b136..000000000 Binary files a/doc/tutorials/introduction/android_binary_package/images/eclipse_about_cdt_1.png and /dev/null differ diff --git a/doc/tutorials/introduction/android_binary_package/images/eclipse_about_cdt_2.png b/doc/tutorials/introduction/android_binary_package/images/eclipse_about_cdt_2.png deleted file mode 100644 index c061a2074..000000000 Binary files a/doc/tutorials/introduction/android_binary_package/images/eclipse_about_cdt_2.png and /dev/null differ