doc: Platform notes for Android

Try to document some more low-level details about Qt for Android.

Change-Id: I8dd12a20958683fce26746e80ff9e4f4a24d31a2
Reviewed-by: Jerome Pasion <jerome.pasion@digia.com>

3 files changed, 152 insertions, 1 deletions

diff --git a/doc/src/platforms/android.qdoc b/doc/src/platforms/android.qdoc
index 281045263..350defc1e 100644
--- a/doc/src/platforms/android.qdoc
+++ b/doc/src/platforms/android.qdoc
@@ -42,6 +42,16 @@ supported items:
      \l{Qt Creator Manual}{Qt Creator}
 \endlist
 
+\section1 Requirements
+
+In order to use Qt for Android, you will need the following external tools:
+
+\list
+\li The Android SDK
+\li The Android NDK
+\li The Ant build tool
+\endlist
+
 \section1 Getting Started
 
 The following step-by-step instructions guide you to set up the environment
@@ -159,7 +169,7 @@ AVDs found.
 
 \section1 Related Information
 \list
- \li Platform Notes
+ \li \l{Platform and Compiler Notes - Android}{Platform Notes}
  \li \l{Qt Creator: Deploying Applications to Android Devices}
 \endlist
 */
diff --git a/doc/src/platforms/platform-notes-android.qdoc b/doc/src/platforms/platform-notes-android.qdoc
new file mode 100644
index 000000000..67e2c4fa9
--- /dev/null
+++ b/doc/src/platforms/platform-notes-android.qdoc
@@ -0,0 +1,139 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.  For licensing terms and
+** conditions see http://qt.digia.com/licensing.  For further information
+** use the contact form at http://qt.digia.com/contact-us.
+**
+** GNU Free Documentation License Usage
+** 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.  Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+
+/*!
+    \page platform-notes-android.html
+    \title Platform and Compiler Notes - Android
+    \contentspage Platform and Compiler Notes
+
+    This page contains information particular to building Qt applications for and running
+    them on the Android platform. Qt supports Android versions 2.3.3 (API level 10) or
+    later.
+
+    \tableofcontents
+
+    \section1 Android Development in Qt Creator
+
+    The easiest way to develop with Qt for Android is to use
+    \l{http://qt-project.org/doc/qtcreator/creator-developing-android.html}{Qt Creator}. When you apply
+    a \b{Qt for Android Kit} to a Qt Creator project, it will create and maintain a set of files which
+    are required to make your app run on Android.
+
+    The files added to your project are:
+    \list
+    \li Java files which serve as the entry point into your app and which will automatically load Qt
+        and execute the native code in your app
+    \li AndroidManifest.xml which provides meta-information about your app
+    \li Other XML files detailing the dependencies of your app
+    \li Resource files
+    \li Depending on the deployment method selected in Qt Creator, additional files like libraries
+    and QML files can be included in the project.
+    \endlist
+
+    Qt Creator adds these files in a subdirectory of your project called \b android. The contents of
+    the \b android folder is used as basis for your app's distributable application package.
+
+    \section1 Application Package
+
+    On Android, apps are distributed in packages called APK. Qt Creator will manage building the
+    APK for you, but if you for some reason want to do this manually, you must first make sure
+    that the appropriate packaging and build files are in place. As mentioned, Qt Creator will
+    place these files in the \b android subfolder in your project.
+
+    \section1 Deployment
+
+    Qt Creator currently supports three methods of deployment for Android apps: the default
+    deployment method is suitable for distribution of the APK file. With this deployment method,
+    the necessary Qt libraries and files will be copied into your project directory, and bundled
+    as part of the APK, so that you get a stand-alone, distributable application package.
+
+    \section2 Deployment with Ministro
+    The second method is suitable if you want to minimize the size of your APK, and can be selected by
+    opening the \b Run settings of your project, expanding \b{Deploy Configurations} and removing the
+    tick from the \b{Use local Qt libraries} check box. In this case, your application will have an
+    external dependency called \b{Ministro}. If a user downloads your application, and it is the first
+    application on their device to depend on Ministro, they will be asked to install it before they can
+    run your application. Ministro downloads Qt libraries from a repository of your choice. The
+    repository URL can be set by editing the file \e{android/res/values/libs.xml} which is created by Qt
+    Creator when configuring your project. Ministro will then serve as a central repository for Qt
+    libraries, and several apps can share the libraries to limit the amount of duplication. Note that
+    using this deployment method requires a repository for the libraries you want to distribute.
+
+    \section2 Deployment for Debugging
+    The third method is more convenient when you are simply testing your application on a device
+    physically connected to your development machine (or an emulator). It will copy the Qt libraries
+    into a temporary directory on your device and run the application against these instead. An APK
+    built in this way is not distributable, since it relies on the device being prepared to contain
+    the Qt libraries in the correct location. However, since the Qt libraries are only copied into
+    the device once, it benefits from a faster turn-around time, so it's more suited for testing
+    changes to your application during development. This deployment method can be selected by
+    opening the \b Run settings of your project, expanding \b{Deploy Configurations} and choosing
+    \b{Deploy local Qt libraries}. Make sure the \b{Use local Qt libraries} check box is also ticked.
+
+    \section1 OpenGL Special Considerations
+
+    Qt for Android provides two separate platform plugins: One which is suited for traditional
+    \l{Qt Widget}{widget-based} apps that do not require OpenGL support, and one which will be used
+    when OpenGL is required. When building and deploying your app, Qt Creator will detect whether the
+    OpenGL-enabled plugin is required by checking if your app depends on either the \l{Qt OpenGL}
+    module or the \l{Qt Quick} module.
+
+    There are some special considerations to be made when the OpenGL-enabled platform plugin is in
+    use. The plugin only supports full screen top-level windows. This means that even dialogs and popups
+    will be shown as full screen. There may also be drawing errors if you try to stack windows that
+    have animations or otherwise require updating their UI while they are obscured by another window.
+
+    It is recommended that you try to avoid multiple top-level windows in the case of Android apps, as
+    there is no traditional window system on this platform.
+
+    \note Embedding a QGLWidget inside a widget hierarchy is not supported. When QGLWidget is in use,
+    it must be the top-level widget.
+
+    \section1 Assets File System
+
+    Qt for Android provides a special, virtual file system which is based on the \e assets mechanism
+    in Android. Files that are put under \e assets in the \e android folder created by Qt Creator, will
+    be packaged as part of your application package. These can be accessed in Qt by prefixing the paths
+    with \c{assets:/}. For instance, to access the image \e logo.png in the folder \e{assets/images},
+    you can use \c QPixmap("assets:/images/logo.png").
+
+    If using the assets mechanism is not required for your app, the recommended way of distributing
+    resources with your Qt app is to use \l{the Qt Resource System}, which is a cross-platform mechanism
+    for distributing resources with your app.
+
+    \section1 Supported Architectures
+
+    Qt for Android currently has binaries for ARMv5, ARMv7, and x86. Make sure you select the
+    correct architecture for the device or emulator you are targeting, otherwise your application
+    will crash. The MIPS archictecture is currently not supported by Qt.
+
+    If you want to support several different architectures in your application, the recommendation is
+    to build separate APKs for each architecture, so that each APK only contains the binaries required
+    for the targeted architecture. For more information about this, see the Android documentation
+    about \l{http://developer.android.com/google/play/publishing/multiple-apks.html}{Multiple APK Support}.
+*/
diff --git a/doc/src/platforms/platform-notes.qdoc b/doc/src/platforms/platform-notes.qdoc
index c3ec6371a..acd40de4e 100644
--- a/doc/src/platforms/platform-notes.qdoc
+++ b/doc/src/platforms/platform-notes.qdoc
@@ -49,6 +49,8 @@
     \tableofcontents{1 Platform and Compiler Notes - QNX}
     \li \l{Platform and Compiler Notes - VxWorks}
     \tableofcontents{1 Platform and Compiler Notes - VxWorks}
+    \li \l{Platform and Compiler Notes - Android}
+    \tableofcontents{1 Platform and Compiler Notes - Android}
     \endlist
 
     \section1 General Compiler Notes