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 5fb02c001e..91948afbc2 100644 --- a/doc/tutorials/introduction/android_binary_package/android_dev_intro.rst +++ b/doc/tutorials/introduction/android_binary_package/android_dev_intro.rst @@ -11,77 +11,6 @@ This guide was written with Windows 7 in mind, though it works with Linux (Ubunt If you encounter any error after thoroughly following these steps, feel free to contact us via `OpenCV4Android `_ discussion group or OpenCV `Q&A forum `_. We'll do our best to help you out. -Android application structure -============================= - -Usually source code of an Android application has the following structure: - -+ :file:`root folder of the project/` - - - :file:`jni/` - - - :file:`libs/` - - - :file:`res/` - - - :file:`src/` - - - :file:`AndroidManifest.xml` - - - :file:`project.properties` - - - :file:`... other files ...` - -where: - -* the :file:`src` folder contains Java code of the application, - -* the :file:`res` folder contains resources of the application (images, xml files describing UI layout , etc), - -* the :file:`libs` folder will contain native libraries after a successful build, - -* and the :file:`jni` folder contains C/C++ application source code and NDK's build scripts :file:`Android.mk` and :file:`Application.mk` - producing the native libraries, - -* :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 :command:`android` tool from Android SDK. - -* :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 included in Android SDK. - -.. note:: Both files (:file:`AndroidManifest.xml` and :file:`project.properties`) are required to compile the C++ part of the application, - since Android NDK build system relies on them. If any of these files does not exist, compile the Java part of the project before the C++ part. - -:file:`Android.mk` and :file:`Application.mk` scripts -================================================================== - -The script :file:`Android.mk` usually has the following structure: - -.. code-block:: make - - LOCAL_PATH := $(call my-dir) - - include $(CLEAR_VARS) - LOCAL_MODULE := - LOCAL_SRC_FILES := - := - ... - := - - include $(BUILD_SHARED_LIBRARY) - -This is the minimal file :file:`Android.mk`, which builds C++ source code of an Android application. Note that the first two lines and the last line are mandatory for any :file:`Android.mk`. - -Usually the file :file:`Application.mk` is optional, but in case of project using OpenCV, when STL and exceptions are used in C++, it also should be created. Example of the file :file:`Application.mk`: - -.. code-block:: make - - APP_STL := gnustl_static - APP_CPPFLAGS := -frtti -fexceptions - APP_ABI := armeabi-v7a - Quick environment setup for Android development =============================================== @@ -251,6 +180,77 @@ You need the following software to be installed in order to develop for Android That's it. Compilation of C++ code is fully integrated into Eclipse building process now. +Android application structure +============================= + +Usually source code of an Android application has the following structure: + ++ :file:`root folder of the project/` + + - :file:`jni/` + + - :file:`libs/` + + - :file:`res/` + + - :file:`src/` + + - :file:`AndroidManifest.xml` + + - :file:`project.properties` + + - :file:`... other files ...` + +where: + +* the :file:`src` folder contains Java code of the application, + +* the :file:`res` folder contains resources of the application (images, xml files describing UI layout , etc), + +* the :file:`libs` folder will contain native libraries after a successful build, + +* and the :file:`jni` folder contains C/C++ application source code and NDK's build scripts :file:`Android.mk` and :file:`Application.mk` + producing the native libraries, + +* :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 :command:`android` tool from Android SDK. + +* :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 included in Android SDK. + +.. note:: Both files (:file:`AndroidManifest.xml` and :file:`project.properties`) are required to compile the C++ part of the application, + since Android NDK build system relies on them. If any of these files does not exist, compile the Java part of the project before the C++ part. + +:file:`Android.mk` and :file:`Application.mk` scripts +================================================================== + +The script :file:`Android.mk` usually has the following structure: + +.. code-block:: make + + LOCAL_PATH := $(call my-dir) + + include $(CLEAR_VARS) + LOCAL_MODULE := + LOCAL_SRC_FILES := + := + ... + := + + include $(BUILD_SHARED_LIBRARY) + +This is the minimal file :file:`Android.mk`, which builds C++ source code of an Android application. Note that the first two lines and the last line are mandatory for any :file:`Android.mk`. + +Usually the file :file:`Application.mk` is optional, but in case of project using OpenCV, when STL and exceptions are used in C++, it also should be created. Example of the file :file:`Application.mk`: + +.. code-block:: make + + APP_STL := gnustl_static + APP_CPPFLAGS := -frtti -fexceptions + APP_ABI := armeabi-v7a + Debugging and Testing ===================== In this section we will give you some easy-to-follow instructions on how to set up an emulator or hardware device for testing and debugging an Android project. @@ -263,9 +263,9 @@ AVD (*Android Virtual Device*) is not probably the most convenient way to test a **TBD:** how to start AVD Manager without Eclipse... #. Press the :guilabel:`New` button in :guilabel:`AVD Manager` window. #. :guilabel:`Create new Android Virtual Device` window will let you select some properties for your new device, like target API level, size of SD-card and other. - .. image:: images/AVD_create.png - :alt: Configure builders - :align: center + .. image:: images/AVD_create.png + :alt: Configure builders + :align: center #. When you click the :guilabel:`Create AVD` button, your new AVD will be availible in :guilabel:`AVD Manager`. #. Press :guilabel:`Start` to launch the device. Be aware that any AVD (aka Emulator) is usually much slower than a hardware Android device, so it may take up to several minutes to start. #. Go :guilabel:`Run -> Run/Debug` in Eclipse IDE to run your application in regular or debugging mode. :guilabel:`Device Chooser` will let you choose among the running devices or to start a new one. @@ -274,41 +274,65 @@ Hardware Device --------------- If you have an Android device, you can use it to test and debug your applications. This way is more authentic, though a little bit harder to set up. +Windows host computer +^^^^^^^^^^^^^^^^^^^^^ + +#. Enable USB debugging on the Android device (settings menu). #. Attach the Android device to your PC with a USB cable. #. Go to :guilabel:`Start Menu` and **right-click** on :guilabel:`Computer`. Select :guilabel:`Manage` in the context menu. You may be asked for Administrative permittions. #. Select :guilabel:`Device Manager` in the left pane and find an unknown device in the list. You may try unplugging it and then plugging back in order to check whether it's your exact equipment appearing in the list. -#. Right-click on your device to get to :guilabel:`Properties` and select the :guilabel:`Details` tab. Select :guilabel:`Device ID` and save both numbers (*e.g in a text file*). - .. image:: images/device_details.png - :alt: Details - :align: center -#. Now open file :file:`/extras/google/usb_driver/android_winusb.inf`. You will see some default records there, perhaps looking similar to this: - .. code-block:: ini - - ;Google Nexus One - %SingleAdbInterface% = USB_Install, USB\VID_18D1&PID_0D02 - %CompositeAdbInterface% = USB_Install, USB\VID_18D1&PID_0D02&MI_01 - -#. There should be a record like this for your device and since it hasn't appeared automatically you are free to add one manually. All you should do is to add another record similar to the above, but using the numbers you saved earlier. Second number goes to the first line and the first one goes to the second line. Notice, that the record should be inserted under *[Google.NTx86]* or *[Google.NTamd64]* tag, depending on what system you're currently running. For example, in my case it was Nvidia Tegra device and the record looked like this: - .. code-block:: ini - - ;NVIDIA Tegra - %SingleAdbInterface% = USB_Install, USB\VID_0955&PID_7100&MI_01 - %CompositeAdbInterface% = USB_Install, USB\VID_0955&PID_7100&REV_9999&MI_01 - -#. Assuming you have your SDK installed to :file:`C:/android-sdk/`, you may try the following command in Windows console to acertain that your device was recognised and attached: - .. code-block:: ini - - C:\android-sdk\platform-tools\adb devices - - .. image:: images/cmd_adb_devices.png - :alt: Console - :align: center + .. image:: images/usb_device_connect_01.png + :alt: Unknown device + :align: center +#. Right-click on the unknoen device, select :guilabel:`Properties` then select the :guilabel:`Details` tab. Select :guilabel:`Hardware Ids` and copy the line like ``USB\VID_XXXX&PID_XXXX&MI_XX``. + .. image:: images/usb_device_connect_02.png + :alt: Device properties details + :align: center +#. Now open file :file:`/extras/google/usb_driver/android_winusb.inf`. Select either ``Google.NTx86`` or ``Google.NTamd64`` section depending on your host system architecture. + .. image:: images/usb_device_connect_03.png + :alt: Device properties details + :align: center +#. There should be a record like existing ones for your device and you need to add one manually. + .. image:: images/usb_device_connect_04.png + :alt: Device properties details + :align: center +#. TBD. + .. image:: images/usb_device_connect_05.png + :alt: Device properties details + :align: center +#. TBD. + .. image:: images/usb_device_connect_06.png + :alt: Device properties details + :align: center +#. TBD. + .. image:: images/usb_device_connect_07.png + :alt: Device properties details + :align: center +#. TBD. + .. image:: images/usb_device_connect_08.png + :alt: Device properties details + :align: center +#. TBD. + .. image:: images/usb_device_connect_09.png + :alt: Device properties details + :align: center +#. TBD. + .. image:: images/usb_device_connect_10.png + :alt: Device properties details + :align: center +#. TBD. + .. image:: images/usb_device_connect_11.png + :alt: Device properties details + :align: center #. Now, in Eclipse go :guilabel:`Run -> Run/Debug` to run your application in regular or debugging mode. :guilabel:`Device Chooser` will let you choose among the devices. Consult the official `Android Developers site `_ for more information on configuring hardware devices to work with other operating systems. -**TODO:** Describe device setup on Linux & OSX. + +Linux & MacOS host computer +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +**TODO:** Describe device setup. What's next =========== diff --git a/doc/tutorials/introduction/android_binary_package/images/usb_device_connect_01.png b/doc/tutorials/introduction/android_binary_package/images/usb_device_connect_01.png new file mode 100644 index 0000000000..62f8768a4a Binary files /dev/null and b/doc/tutorials/introduction/android_binary_package/images/usb_device_connect_01.png differ diff --git a/doc/tutorials/introduction/android_binary_package/images/usb_device_connect_02.png b/doc/tutorials/introduction/android_binary_package/images/usb_device_connect_02.png new file mode 100644 index 0000000000..9caf777001 Binary files /dev/null and b/doc/tutorials/introduction/android_binary_package/images/usb_device_connect_02.png differ diff --git a/doc/tutorials/introduction/android_binary_package/images/usb_device_connect_03.png b/doc/tutorials/introduction/android_binary_package/images/usb_device_connect_03.png new file mode 100644 index 0000000000..5f75f84d32 Binary files /dev/null and b/doc/tutorials/introduction/android_binary_package/images/usb_device_connect_03.png differ diff --git a/doc/tutorials/introduction/android_binary_package/images/usb_device_connect_04.png b/doc/tutorials/introduction/android_binary_package/images/usb_device_connect_04.png new file mode 100644 index 0000000000..d686d6d960 Binary files /dev/null and b/doc/tutorials/introduction/android_binary_package/images/usb_device_connect_04.png differ diff --git a/doc/tutorials/introduction/android_binary_package/images/usb_device_connect_05.png b/doc/tutorials/introduction/android_binary_package/images/usb_device_connect_05.png new file mode 100644 index 0000000000..1e5a37a313 Binary files /dev/null and b/doc/tutorials/introduction/android_binary_package/images/usb_device_connect_05.png differ diff --git a/doc/tutorials/introduction/android_binary_package/images/usb_device_connect_06.png b/doc/tutorials/introduction/android_binary_package/images/usb_device_connect_06.png new file mode 100644 index 0000000000..c6d275d8c6 Binary files /dev/null and b/doc/tutorials/introduction/android_binary_package/images/usb_device_connect_06.png differ diff --git a/doc/tutorials/introduction/android_binary_package/images/usb_device_connect_07.png b/doc/tutorials/introduction/android_binary_package/images/usb_device_connect_07.png new file mode 100644 index 0000000000..06ac71e486 Binary files /dev/null and b/doc/tutorials/introduction/android_binary_package/images/usb_device_connect_07.png differ diff --git a/doc/tutorials/introduction/android_binary_package/images/usb_device_connect_08.png b/doc/tutorials/introduction/android_binary_package/images/usb_device_connect_08.png new file mode 100644 index 0000000000..168d3ea232 Binary files /dev/null and b/doc/tutorials/introduction/android_binary_package/images/usb_device_connect_08.png differ diff --git a/doc/tutorials/introduction/android_binary_package/images/usb_device_connect_09.png b/doc/tutorials/introduction/android_binary_package/images/usb_device_connect_09.png new file mode 100644 index 0000000000..c8d30a0def Binary files /dev/null and b/doc/tutorials/introduction/android_binary_package/images/usb_device_connect_09.png differ diff --git a/doc/tutorials/introduction/android_binary_package/images/usb_device_connect_10.png b/doc/tutorials/introduction/android_binary_package/images/usb_device_connect_10.png new file mode 100644 index 0000000000..85b9a75b2a Binary files /dev/null and b/doc/tutorials/introduction/android_binary_package/images/usb_device_connect_10.png differ diff --git a/doc/tutorials/introduction/android_binary_package/images/usb_device_connect_11.png b/doc/tutorials/introduction/android_binary_package/images/usb_device_connect_11.png new file mode 100644 index 0000000000..87f05728f5 Binary files /dev/null and b/doc/tutorials/introduction/android_binary_package/images/usb_device_connect_11.png differ