Doc: Android target

Change-Id: I03bb68dac3a6a2af7424ee31ca14ef66236101e7
(cherry picked from commit 64c5d45b0f6f7a2e3aa6eb1929d56fa52fa8252c)
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@nokia.com>

doc/src/android/androiddev.qdoc

@@ -0,0 +1,130 @@
+/****************************************************************************
+**
+** This file is part of Qt Creator
+**
+** Copyright (c) 2012 Nokia Corporation and/or its subsidiary(-ies).
+**
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+**
+** GNU Free Documentation License
+**
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of this
+** file.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+****************************************************************************/
+
+    /*!
+
+    \contentspage index.html
+    \previouspage creator-developing-qnx.html
+    \page creator-developing-android.html
+    \nextpage creator-build-process-customizing.html
+
+    \title Connecting Android Devices
+
+    You can connect Android devices to the development PC to build, run, debug,
+    and analyze applications on them from \QC.
+
+    If you have a tool chain for building applications for Android devices
+    installed on the development PC, you can add it to \QC. You can then select
+    the \gui {Android} target to run applications on Android devices.
+
+    \section1 Requirements
+
+    To use \QC to develop Qt applications for Android, you need the following:
+
+    \list
+
+        \o  OpenJDK Java Development Kit
+
+            To check whether you have OpenJDK installed, enter the following
+            command:
+
+            \c {java -version}
+
+            To install OpenJDK, enter the following command:
+
+            \c {sudo apt-get install openjdk-6-jdk}
+
+        \o  \l{http://ant.apache.org/bindownload.cgi}{Apache Ant} 1.8.0, or
+            later
+
+            To check the Ant version, enter the following command on the command
+            line:
+
+            \c {ant -version}
+
+        \o  \l{http://necessitas.kde.org/necessitas/necessitas_sdk_installer.php}
+            {Necessitas SDK}
+
+    \endlist
+
+    \section1 Configuring Connections
+
+    The Qt for Android SDK automatically sets the paths to the required software
+    in \QC.
+
+    To configure connections between \QC and Android devices:
+
+    \list 1
+
+        \o  Select \gui Tools > \gui Options > \gui {Build & Run} >
+            \gui {Qt Versions} > \gui Add to add Qt for Android.
+
+        \o  In the \gui {qmake location} field, add the \c qmake path from the
+            Qt for Android SDK
+            (\c {/opt/necessitas/Android/<qtversion>/bin/qmake} by default).
+
+        \o  Select \gui Tools > \gui Options > \gui Android to view and edit
+            paths to the required software.
+
+            \image qtcreator-options-android.png "Android options"
+
+        \o  Select \gui Tools > \gui Options > \gui {Build & Run} >
+            \gui {Qt Versions} and build the GDB Helper to make the debugging
+            output for Qt specific constructs clean and easy to read.
+
+        \o  To build the GDB Helper, select Qt for Android, select \gui Details
+            in the \gui Helpers section, and then select \gui Build in the
+            \gui {GDB Helper} field.
+
+        \o  Select \gui {Start Android AVD Manager} to create Android virtual
+            devices (AVD) that enable you emulate device hardware and software
+            on the Android Emulator.
+
+        \o  To specify information for the Android manifest file, select
+            \gui Projects > \gui Run, and then select \gui Details to view the
+            \gui {Package configurations}. For more information about the
+            options you have, see
+            \l{Specifying Run Settings for Android Devices}.
+
+        \o  To specify settings for deploying applications to Android, select
+            \gui Details to view the \gui {Deploy configurations}. For more
+            information about the options you have, see
+            \l{Deploying Applications to Android Devices}.
+
+    \endlist
+
+    \section1 Debugging on Android Devices
+
+    Android devices support debugging multi-thread applications in version
+    2.2.1 and later. If you use AVD, select Android 2.3, or later. For more
+    information, see the Android documentation.
+
+    In addition, debugging is supported at android-10 API level, or higher. In
+    the run settings for the project, in the \gui {Android target SDK} field,
+    select android-10, or higher. For more information about Android API levels,
+    see \l{http://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels}
+    {What is API Level?}.
+
+    \note Select a \l{glossary-build-config}{debug build configuration} to build
+    the application for debugging.
+
+*/
+

doc/src/android/creator-projects-settings-run-android.qdocinc

@@ -0,0 +1,71 @@
+    \section2 Specifying Run Settings for Android Devices
+
+    In \gui {Package configurations}, you can specify information for the
+    Android manifest file. The Android system uses the information from the file
+    to start application components.
+
+    \section3 Specifying Package Data
+
+    In the \gui Manifest tab, you can select the API level to use for the
+    Android target SDK and the name and version number for the application
+    package.
+
+    \image qtcreator-android-manifest.png "Manifest tab"
+
+    For more information about Android API levels, see
+    \l{http://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels}
+    {What is API Level?}.
+
+    \note The android-4 API level does not support multitouch. If your
+    application needs multitouch, select a higher API level.
+
+    In the \gui {Package name} field, enter a package name for the application.
+    The application is launched by an automatically generated Java launcher that
+    is packaged with the application into an Android package (.apk). For more
+    information, see
+    \l{http://developer.android.com/guide/components/fundamentals.html}
+    {Android Application Fundamentals}.
+
+    \section3 Specifying Application Data
+
+    In the \gui Application tab, you can select an icon for the application and
+    give the application a name.
+
+    \image qtcreator-android-application.png "Application tab"
+
+    \section3 Setting Permissions
+
+    In the \gui Permissions tab, you can specify the permissions that your
+    application needs. Users are asked to grant the permissions when they
+    install the application. Android OS then grants the application access to
+    the appropriate data and features.
+
+    \image qtcreator-android-permissions.png "Permissions tab"
+
+    Select from existing Android permissions or add new ones to deploy the
+    application to a particular Android OS.
+
+    \section3 Selecting Qt Libraries
+
+    In the \gui Libraries tab, specify which Qt libraries the application uses.
+    To automatically determine this, select \gui {Read Infomation from
+    Application (Must Be Compiled)}. Alternatively, you can manually select the
+    Qt libraries and the external libraries you think your application needs.
+    Make sure to arrange the libraries so that depended libraries appear before
+    the ones that depend on them.
+
+    \image qtcreator-android-libraries.png "Libraries tab"
+
+    These entries are used by the Ministro tool to determine which Qt libraries
+    to download.
+
+    In addition, the Java Loader uses this list to determine which Qt Libraries
+    and other prebundled libraries to load with your application.
+
+    \section3 Signing Android Packages
+
+    In the \gui {Sign Package} tab, you can sign the Android package by using
+    a private key from the keystore. To create new keys, select \gui Create.
+
+    \image qtcreator-android-sign-package.png "Sign Package tab"
+

doc/src/android/deploying-android.qdoc

@@ -0,0 +1,64 @@
+/****************************************************************************
+**
+** This file is part of Qt Creator
+**
+** Copyright (c) 2012 Nokia Corporation and/or its subsidiary(-ies).
+**
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+**
+** GNU Free Documentation License
+**
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of this
+** file.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+****************************************************************************/
+
+    /*!
+
+    \contentspage index.html
+    \previouspage creator-deployment-qnx.html
+    \page creator-deploying-android.html
+    \nextpage creator-connecting-mobile.html
+
+    \title Deploying Applications to Android Devices
+
+    To specify settings for deploying applications to Android devices, select
+    \gui Projects > \gui Run.
+
+    \image qtcreator-deploy-android.png "Deploy configurations"
+
+    Select the \gui {Use device's Qt libs} option to use Qt libraries installed
+    on the device. If you do not select the \gui {Use local Qt libs} option,
+    the application needs the Ministro package to run. However, if you select
+    the \gui {Use local Qt libs} option, \QC passes special parameters to the
+    application, forcing it to use Qt libraries from the \c{/data/local/qt}
+    folder on the device
+
+    Select the \gui {Deploy local Qt libs} option to deploy Qt libraries from
+    the specified Qt for Android SDK (for exmple, android-lighthouse-4.8.0).
+    This option enables you to develop on the Qt framework to test it.
+
+    The \gui {Deploy local Qt libs} option automatically selects the
+    \gui {Use local Qt libs} option. It is deselected automatically after \QC
+    pushes the Qt libs to the device. Select the option again to push your local
+    Qt modifications to devices. This option takes the same effect as the
+    \c{push_qt_libs.sh} script thas is located in the root folder of the
+    Qt for Android SDK. You can also use the \gui {Use local Qt libs}
+    independently of the \gui {Deploy local Qt libs} option.
+
+    \section1 Installing Ministro
+
+    To install Ministro, select the \gui {Install Ministro system} option. You
+    can also use it to install any Android package (.apk). You can use this
+    option to install applications on an Android Virtual Device (AVD). Download
+    the Ministro .apk from the Google Market or from the
+    \l{http://necessitas.kde.org/necessitas/ministro.php}{Ministro} home page.
+
+*/
+

doc/src/overview/creator-deployment-overview.qdoc

@@ -58,6 +58,11 @@
             When you deploy the application on the \gui{QNX} target, \QC generates
             a BAR package in the build directory and deploys it to the connected
             device. You can test and debug the application on the device.
+        \o  \l{Deploying Applications to Android Devices}
+
+            When you deploy the application on the Android target, \QC copies
+            the application files to the device. In addition, you can determine
+            the Qt libraries to use.
     \endlist
 
     \section1 Related Topics

doc/src/overview/creator-getting-started.qdoc

@@ -25,7 +25,7 @@
 
 /*!
     \contentspage index.html
-    \previouspage index.html
+    \previouspage creator-glossary.html
     \page creator-getting-started.html
     \nextpage creator-overview.html
 

doc/src/overview/creator-mobile-targets.qdoc

@@ -25,7 +25,7 @@
 
 /*!
     \contentspage index.html
-    \previouspage creator-deployment-qnx.html
+    \previouspage creator-deploying-android.html
     \page creator-connecting-mobile.html
     \nextpage creator-developing-meego.html
 
@@ -81,6 +81,15 @@
             supported for BlackBerry Playbook, and requires the BlackBerry NDK
             to be installed on the development PC.
 
+        \o  \l{Connecting Android Devices}
+
+            Qt applications for Android are compiled as \c {shared objects} that
+            are loaded by a Java launcher generated by the Qt for Android SDK.
+            This is totally transparent to users. As Qt is composed of libraries
+            referencing each other, Qt applications are only supported on
+            Android version 1.6, or later. You must install the Qt for Android
+            SDK to develop for Android devices.
+
     \endlist
 
 */

doc/src/overview/creator-target-platforms.qdocinc

@@ -18,6 +18,8 @@
 
         \o  QNX
 
+        \o  Android
+
     \endlist
 
     The following table summarizes operating system support for developing
@@ -25,8 +27,8 @@
 
     \table
         \header
-            \o  {1,7} Operating system
+            \o  {1,8} Operating system
-            \o  {7,1} Platform
+            \o  {8,1} Platform
         \header
             \o  Desktop
             \o  \QS
@@ -35,6 +37,7 @@
             \o  Generic Remote Linux
             \o  Symbian
             \o  QNX
+            \o  Android
 
         \row
             \o  Windows
@@ -45,6 +48,8 @@
             \o  Yes
             \o  Yes
             \o  Yes (see \l{Running on QNX Devices} for limitations)
+            \o  Yes
+
         \row
             \o  Linux
             \o  Yes
@@ -54,6 +59,7 @@
             \o  Yes
             \o  Yes (by using Remote Compiler for building)
             \o  Yes
+            \o  Yes
         \row
             \o  Mac OS X
             \o  Yes
@@ -63,4 +69,5 @@
             \o  Yes
             \o  Yes (by using Remote Compiler for building)
             \o  Yes
+            \o  Yes
     \endtable

doc/src/projects/creator-projects-builds-customizing.qdoc

@@ -25,7 +25,7 @@
 
 /*!
     \contentspage index.html
-    \previouspage creator-developing-qnx.html
+    \previouspage creator-developing-android.html
     \page creator-build-process-customizing.html
     \nextpage creator-maemo-emulator.html
 

doc/src/projects/creator-projects-settings-run.qdoc

@@ -53,6 +53,7 @@
     \input symbian/creator-projects-settings-run-symbian.qdocinc
     \input linux-mobile/creator-projects-settings-run-linux.qdocinc
     \input qnx/creator-projects-settings-run-qnx.qdocinc
+    \input android/creator-projects-settings-run-android.qdocinc
     \endif
 
     \section1 Specifying a Custom Executable to Run

doc/src/qnx/creator-deployment-qnx.qdoc

@@ -28,7 +28,7 @@
     \contentspage index.html
     \previouspage creator-deployment-maemo.html
     \page creator-deployment-qnx.html
-    \nextpage creator-connecting-mobile.html
+    \nextpage creator-deploying-android.html
 
     \title Deploying Applications to QNX Devices
 

doc/src/qnx/creator-developing-qnx.qdoc

@@ -22,7 +22,7 @@
     \contentspage index.html
     \previouspage creator-developing-symbian.html
     \page creator-developing-qnx.html
-    \nextpage creator-build-process-customizing.html
+    \nextpage creator-developing-android.html
 
     \title Connecting QNX Devices
 

doc/src/qtcreator.qdoc

@@ -239,6 +239,7 @@
                 \o  \l{Deploying Applications to Symbian Devices}
                 \o  \l{Deploying Applications to Linux-Based Devices}
                 \o  \l{Deploying Applications to QNX Devices}
+                \o  \l{Deploying Applications to Android Devices}
             \endlist
             \o  \l{Connecting Mobile Targets}
             \list
@@ -247,6 +248,7 @@
                 \o  \l{Connecting Maemo Devices}
                 \o  \l{Connecting Symbian Devices}
                 \o  \l{Connecting QNX Devices}
+                \o  \l{Connecting Android Devices}
             \endlist
             \o  \l{Customizing the Build Process}
             \o  \l{Using Maemo or MeeGo Harmattan Emulator}