Merge pull request #247 from wswld:2.4

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| 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-android-sdk.zip/download
+.. _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``,
+At this point you should be able to build and run the samples. Keep in mind, that
-``Tutorial 3`` and ``Tutorial 4`` include some native code and require Android NDK and CDT plugin
+``face-detection``, ``Tutorial 3` and ``Tutorial 4`` include some native code and
-for Eclipse to build working applications. If you haven't installed these tools see the corresponding
+require Android NDK and CDT plugin for Eclipse to build working applications. If you haven't
-section of :ref:`Android_Dev_Intro`.
+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
+.. warning:: Please consider that some samples use Android Java Camera API, which is accessible
-definitelly accessible on emulator from the Android SDK.
+             with an AVD. But most of samples use OpenCV Native Camera which **may not work** with
-Other samples use OpenCV Native Camera which may not work with emulator.
+             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:
+
+    <Android SDK path>/platform-tools/adb install <OpenCV4Android SDK path>/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
 ===========
 

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 <http://www.oracle.com/technetwork/java/javase/downloads/>`_
    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 <http://developer.android.com/sdk/installing.html>`_ for the SDK.
 
-   .. note:: If you choose SDK packed into a Windows installer, then you should have 32-bit JRE
+   .. note:: You can choose downloading ``ADT Bundle package`` that in addition to Android SDK Tools includes
-             installed. It is not a prerequisite for Android development, but installer is a x86
+             Eclipse + ADT + CDT plugins, Android Platform-tools, the latest Android platform and the latest
-             application and requires 32-bit Java runtime.
+             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 <http://eclipse.org/cdt/>`_ 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
@@ -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
@@ -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 <http://ss64.com/nt/setx.html>`_ 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
 =====================
@@ -667,7 +645,7 @@ execute :command:`adb devices` command. You will see the list of attached device
    :align: center
 
 Mac OS host computer
-^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^
 No actions are required, just connect your device via USB and run ``adb devices`` to check connection.
 
 What's next