Doc: update information about deploying to Android

Change-Id: I276aa36bcf3401f2020338e8eb38f5fd25c50342
Reviewed-by: Daniel Teske <daniel.teske@digia.com>
Reviewed-by: Eskil Abrahamsen Blomfeldt <eskil.abrahamsen-blomfeldt@digia.com>

3 files changed, 224 insertions, 112 deletions

diff --git a/doc/src/android/androiddev.qdoc b/doc/src/android/androiddev.qdoc
index bf5134c5cb..ddacabf3dc 100644
--- a/doc/src/android/androiddev.qdoc
+++ b/doc/src/android/androiddev.qdoc
@@ -47,17 +47,22 @@
 
     \list
 
-        \li OpenJDK Java Development Kit
+        \li Java Development Kit (JDK)
 
-            To check whether you have OpenJDK installed, enter the following
+            To check whether you have JDK installed, enter the following
             command:
 
             \c {java -version}
 
-            To install OpenJDK, enter the following command:
+            On Linux and Mac OS X, you can use OpenJDK. To install it on Linux,
+            enter the following command:
 
             \c {sudo apt-get install openjdk-6-jdk}
 
+            On Windows, you must download and install JDK from
+            \l{http://www.oracle.com/technetwork/java/javase/downloads/index.html}
+            {Java SE Downloads} on the Oracle site.
+
         \li \l{http://ant.apache.org/bindownload.cgi}{Apache Ant} 1.8.0, or
             later
 
@@ -125,10 +130,10 @@
 
     You must download and install the latest Android NDK and SDK, and update the
     SDK to get the API and tools packages needed for development. In addition,
-    you must install Qt for Android from the Qt 5.1 packages.
+    you must install Qt for Android as part of Qt 5.2, or later.
 
     For more information, see
-    \l{http://qt-project.org/doc/qt-5.1/qtdoc/android-support.html}{Android}.
+    \l{http://qt-project.org/doc/qt-5/android-support.html}{Qt for Android}.
 
     To configure connections between \QC and Android devices:
 
@@ -148,20 +153,13 @@
             follow the instructions of the wizard. For more information, see
             \l{Creating Qt Quick Projects}.
 
-        \li To specify information for the Android manifest file, select
-            \gui Projects > \gui Run for the \gui Android kit.
-
-        \li Select \gui Details to view the
-            \gui {Package configurations}. For more information about the
-            options you have, see
-            \l{Specifying Settings for Application Packages}.
-
         \li To specify settings for deploying applications to Android, select
+            \gui Projects > \gui Run for the \gui Android kit, and then select
             \gui Details to view the \gui {Deploy configurations}. For more
             information about the options you have, see
             \l{Deploying Applications to Android Devices}.
 
-        \li Enable debugging on your Android device and connect it to the PC.
+        \li Enable debugging on your Android device.
 
             Debugging is enabled in different ways on different Android devices.
             Look for \gui {USB Debugging} under \gui {Developer Options}. On
@@ -169,8 +167,41 @@
             when you tap the \gui {Build number} field in \gui Settings >
             \gui About several times.
 
+        \li Connect the Android device to the development PC with a USB cable.
+            You might be asked to select a device in the
+            \gui {Select Android Devices} dialog.
     \endlist
 
+    \section1 Selecting Android Devices
+
+    When you deploy an application to an Android device with Android
+    version 4.2 or later, the \gui {Select Android Devices} dialog opens. It
+    lists the devices that are connected to the development PC. and their
+    status. You can select devices from the \gui {Compatible Devices} list for
+    deployment.
+
+    If \QC determines that a device is not ready for deployment, it places the
+    device in the \gui {Incompatible Devices} list, with information about the
+    issue. For example, you might need to authorize the connection on the
+    device. After you authorize the connection on the device, select
+    \gui {Refresh Device List}. The device is moved to the
+    \gui {Compatible Devices} list and you can select it for deployment.
+
+    Other reasons for placing a device on the \gui {Incompatible Devices} are
+    that the Android version on the device is too old or that the tool chain
+    used for building does not match the Android architecture on the device
+    (for example, you cannot deploy an ARM build on an x86 device).
+
+    \image qtcreator-android-select-devices.png "Select Android Devices dialog"
+
+    Android Virtual Devices (AVD) are also listed. To create new AVDs, select
+    \gui {Create Android Virtual Device}.
+
+    To set a device as the default device for a particular Android architecture,
+    select the \gui {Always use this device for architecture} check box. The
+    \gui {Select Android Devices} dialog will not appear until you switch to
+    another project or restart \QC.
+
     \section1 Using the Android Emulator
 
     To run your application on the Android Emulator, you must create Android
diff --git a/doc/src/android/creator-projects-settings-run-android.qdocinc b/doc/src/android/creator-projects-settings-run-android.qdocinc
index a42ec97a25..56fb176130 100644
--- a/doc/src/android/creator-projects-settings-run-android.qdocinc
+++ b/doc/src/android/creator-projects-settings-run-android.qdocinc
@@ -1,29 +1,25 @@
     To configure Android packages, select \gui Projects >
-    \gui Run > \gui {Package configurations}. The Android system uses the
-    information from the file to start application components.
+    \gui Run > \gui {Package configurations} > \gui Details. The Android system
+    uses the information from the file to start application components.
 
     \image qtcreator-android-manifest.png "Package configuration"
 
     \section2 Selecting API Level
 
     In the \gui {Android target SDK} field, you can select the API level to use
-    for the Android target SDK.
+    for building the application. Usually, you should select the newest API
+    level available.
 
+    This field does not specify the minimum supported API level nor the target
+    API level, which you can specify in the Android manifest file.
     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?}.
 
-    The minimum API level is android-4 for Necessitas and android-9 for Qt 5.
-    \QC does not allow you to select an API level that the Qt version specified
-    for the kit does not support.
-
-    \note The android-4 API level does not support multitouch. If your
-    application needs multitouch, select a higher API level.
-
     \section2 Selecting Qt Libraries
 
     In the \gui Libraries group, specify which Qt libraries the application uses.
-    To automatically determine this, select \gui {Read Infomation from
+    To automatically determine this, select \gui {Read Information 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
@@ -41,34 +37,3 @@
     a private key from the keystore. To create new keys, select \gui Create.
 
     \image qtcreator-android-sign-package.png "Sign Package"
-
-    \section1 Editing Manifest Files
-
-    To specify information for the Android manifest file, open it in \QC.
-
-    \image qtcreator-android-manifest-editor.png "Android Manifest Editor"
-
-    Select the \gui {XML Source} tab to edit the file in XML format.
-
-    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}.
-
-    You can specify an internal version number for the package in the
-    \gui {Version code} field. It is used to determine whether one version of
-    the application is more recent than another. In the \gui {Version name}
-    field, specify the version number that is shown to users.
-
-    In the \gui Application group, you can give the application a name and
-    select an icon for it. The three icon fields can contain different versions
-    of the icon with low, medium, and high DPI values, from left to right.
-
-    In the \gui Permissions field, 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.
-
-    To add permissions, select \gui Add and select permissions from the list.
diff --git a/doc/src/android/deploying-android.qdoc b/doc/src/android/deploying-android.qdoc
index 1c761f71c3..758687f86c 100644
--- a/doc/src/android/deploying-android.qdoc
+++ b/doc/src/android/deploying-android.qdoc
@@ -25,35 +25,9 @@
 
     \title Deploying Applications to Android Devices
 
-    When you select a \gui {Qt for Android Kit} for a project, \QC creates and
-    maintains a set of files that are required to make your application run on
-    Android devices.
-
-    \QC adds the following files to your project:
-
-    \list
-
-        \li Java files, which serve as the entry point into your application and
-            that automatically load Qt and execute the native code in your
-            application.
-
-        \li AndroidManifest.xml, which provides meta-information about your
-            application.
-
-        \li Other XML files, which specify the dependencies of your application.
-
-        \li Resource files.
-
-        \li Libraries and QML files, which can be included in the project
-            depending on the deployment method that you select.
-
-    \endlist
-
-    \QC adds the files to the project to a subdirectory called \c android. The
-    contents of the \c android folder are used to create a distributable
-    application package.
-
-    \QC supports the following methods of deployment for Android applications:
+    On Android, applications are distributed in specially structured type of ZIP
+    packages called APK. \QC supports the following methods of deployment for
+    Android applications:
 
      \list
 
@@ -73,29 +47,16 @@
 
     The default option depends on whether you are developing with Qt 4 or Qt 5.
     The Necessitas SDK does not support bundling Qt libraries with applications,
-    so you must use Ministro when developing with Qt 4.
-
-    \section1 Specifying Settings for Application Packages
-
-    On Android, applications are distributed in packages called APK. \QC creates
-    the APK for you. If you want to do this manually, you must first make sure
-    that the appropriate packaging and build files are in place. \QC places the
-    files in the \c android subfolder of the project.
-
-    \include android/creator-projects-settings-run-android.qdocinc
-
-    \section1 Deploying Application Packages
+    so you must use Ministro when developing with Qt 4. To specify the
+    deployment method, select \gui Projects > \gui Run >
+    \gui {Deploy configurations} > \gui Details
 
-    To specify settings for deploying applications to Android devices, select
-    \gui Projects > \gui Run > \gui {Deploy configurations} > \gui Details.
-
-    \image qtcreator-deploy-android.png "Deploy configurations"
+    \section1 Creating Distributable APK Packages
 
     To copy Qt libraries and files to the project directory and to bundle them
     as part of the APK, select the \gui {Bundle Qt libraries in APK} option.
-    This is the default option
-    when developing with Qt 5.
-    It is not supported when developing with Qt 4.
+    This is the default option when developing with Qt 5. It is not supported
+    when developing with Qt 4.
 
     \section1 Using Ministro to Install Qt Libraries
 
@@ -128,17 +89,120 @@
     turn-around time, and is therefore convenient for testing the application
     during development.
 
-    Select \gui Projects > \gui Run > \gui {Deploy configurations} >
-    \gui Details, and then select the
-    \gui {Deploy local Qt libraries to temporary directory} option to deploy
-    Qt libraries to
-    the \c{/data/local/tmp/qt} folder on the device and to run the application
-    against them.
+    Select the \gui {Deploy local Qt libraries to temporary directory} option to
+    deploy Qt libraries to the \c{/data/local/tmp/qt} folder on the device and
+    to run the application against them.
 
     To deploy new Qt libraries to the device, select
     \gui {Clean Temporary Libraries Directory on Device}. The next time you
     deploy the application, Qt libraries are copied to the device again.
 
+    \section1 Packaging Qt 4 Applications
+
+    When you select a \gui {Qt for Android Kit} that specifies Qt 4 for a
+    project, \QC creates and maintains a set of files that are required to make
+    your application run on Android devices.
+
+    \QC adds the following files to your project:
+
+    \list
+
+        \li Java files, which serve as the entry point into your application and
+            that automatically load Qt and execute the native code in your
+            application.
+
+        \li AndroidManifest.xml, which provides meta-information about your
+            application.
+
+        \li Other XML files, which specify the dependencies of your application.
+
+        \li Resource files.
+
+        \li Libraries and QML files, which can be included in the project
+            depending on the deployment method that you select.
+
+    \endlist
+
+    \QC adds the files to the project to a subdirectory called \c android. The
+    contents of the \c android folder are used to create a distributable
+    application package.
+
+    To view the packages that \QC created, select the
+    \gui {Open package location after is complete} check box.
+
+    To specify information for the Android manifest file, open it in \QC. For
+    more information, see \l{Editing Manifest Files}.
+
+    \section2 Specifying Settings for Qt 4 Packages
+
+    \include creator-projects-settings-run-android.qdocinc
+
+    \section1 Packaging Qt 5 Applications
+
+    Because bundling applications as APK packages is not
+    trivial, Qt 5 provides a deployment tool called \c androiddeployqt.
+    When you deploy an application using a \gui {Qt for Android Kit}, \QC uses
+    the \c androiddeployqt tool to create the necessary files and to bundle them
+    into an APK.
+
+    To view the packages that the \c androiddeployqt tool created, select the
+    \gui {Open package location after build} check box.
+
+    The packages are deployed on the connected Android devices. To switch the
+    device used as a default device for the selected kit, select
+    \gui {Reset Default Devices}. The setting applies until you restart \QC.
+    For more information, see \l{Selecting Android Devices}.
+
+    For more information about the \c androiddeployqt tool, see
+    \l{http://qt-project.org/doc/qt-5/deployment-android.html}
+    {Deploying an Application on Android}.
+
+    \section2 Specifying Settings for Qt 5 Packages
+
+    You can specify settings for the \c androiddeployqt tool in \QC and in the
+    project .pro file. To specify settings in \QC, select
+    \gui Projects > \gui Run > \gui {Deploy configurations} > \gui Details.
+
+    \image qtcreator-android-deploy-configurations.png "Deploy configurations"
+
+    The anddroiddeployqt tool uses the information in the project .pro file to
+    create APKs. For more information about the qmake variables
+    that you can set in the .pro file to tailor the APK, see
+     \l{http://qt-project.org/doc/qt-5/deployment-android.html#qmake-variables}
+    {qmake Variables}.
+
+    You can view information about what the anddroiddeployqt tool is doing in
+    the \gui {Compile Output} pane. To view additional information, select the
+    \gui {Verbose output} check box.
+
+    \section3 Selecting API Level
+
+    In the \gui {Android target SDK} field, you can select the API level to use
+    for building the application. Usually, you should select the newest API
+    level available.
+
+    This field does not specify the minimum supported API level nor the target
+    API level, which you can specify in the Android manifest file.
+    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?}.
+
+    \section3 Signing Android Packages
+
+    In the \gui {Sign Package} group you can sign the Android package by using
+    a private key from the keystore. To create new keys, select \gui Create.
+
+    \section2 Adding External Libraries
+
+    \QC automatically detects which Qt libraries the application uses and adds
+    them as dependencies. If the application needs external libraries, specify
+    them in the \gui {Additional Libraries} field. The libraries are copied into
+    your application's library folder and loaded on startup.
+
+    For example, to enable OpenSSL in your application, add the paths to the
+    required \c libssl.so and \c libcrypto.so libraries to the
+    \gui {Additional Libraries} field.
+
     \section1 Installing Ministro
 
     The easiest way to install Ministro is to do it on the device via Google
@@ -149,13 +213,65 @@
     from the Google Market or from the
     \l{http://necessitas.kde.org/necessitas/ministro.php}{Ministro} home page.
 
-    Then select \gui {Install Ministro from APK} in \gui Projects > \gui Run >
-    \gui {Deploy configurations} > \gui Details.
+    Then select \gui {Install Ministro from APK}.
 
     You can use this option also to install any Android package (.apk).
 
     You can use this option to install applications on an Android Virtual
     Device (AVD).
 
+    \section1 Editing Manifest Files
+
+    When you develop with Qt 4, \QC creates the Android manifest file for you,
+    and you can open it for editing in the Android Manifest Editor.
+
+    When you develop with Qt 5, you can use the qmake variables to specify all
+    the settings you need for the \c androiddeployqt tool and you do not need an
+    Android manifest file until you want to publish the package in an
+    application store. To specify additional settings for APK packages, you can
+    create an Android manifest file and edit it in \QC. Select
+    \gui {Create AndroidManifest.xml} to create the file and to open it in the
+    Android Manifest Editor.
+
+    \image qtcreator-android-manifest-editor.png "Android Manifest Editor"
+
+    Select the \gui {XML Source} tab to edit the file in XML format.
+
+    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}.
+
+    You can specify an internal version number for the package in the
+    \gui {Version code} field. It is used to determine whether one version of
+    the application is more recent than another. In the \gui {Version name}
+    field, specify the version number that is shown to users.
+
+    In the \gui {Minimum required SDK} field, select the minimum API level
+    required to run the application. The minimum API level is android-4 for
+    Necessitas and android-9 for Qt 5. \QC does not allow you to select an API
+    level that the Qt version specified for the kit does not support.
+
+    \note The android-4 API level does not support multitouch. If your
+    application needs multitouch, select a higher API level.
+
+    In the \gui {Target SDK} field, select the targeted API level of the
+    application. This affects the activation of some compatibility features in
+    the OS. The value used by the \c androiddeployqt tool by default is 14, which
+    means that the overflow button in the system navigation bar will not be
+    enabled by default.
+
+    In the \gui Application group, you can give the application a name and
+    select an icon for it. The three icon fields can contain different versions
+    of the icon with low, medium, and high DPI values, from left to right.
+
+    In the \gui Permissions field, 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.
+
+    To add permissions, select \gui Add and select permissions from the list.
 */