Android: Add documentation for including third-party libs

Since Qt 5.3.1, androiddeployqt will support deploying third-party
libraries in a relatively simple way. This needs to be documented,
though, since it will probably not be entirely intuitive.

Change-Id: I5ea5127b93f69d9d445cb6d29f330c8e8e895164
Reviewed-by: Paul Olav Tvete <paul.tvete@digia.com>

1 files changed, 62 insertions, 0 deletions

diff --git a/doc/src/platforms/android.qdoc b/doc/src/platforms/android.qdoc
index d9126091..36d5269f 100644
--- a/doc/src/platforms/android.qdoc
+++ b/doc/src/platforms/android.qdoc
@@ -57,6 +57,7 @@ The following topics provide more details about how to use Qt for Android:
  \li \l{Getting Started with Qt for Android}{Getting Started}
  \li \l{Porting to Android}{Porting a Qt Application}
  \li \l{Adding OpenSSL Support}
+ \li \l{Third-party Android Libraries}{Including third-party Android libraries in an application}
  \li \l{Qt Creator: Deploying Applications to Android Devices}{Deploying to the Device}
  \li \l{Publishing to Google Play}
  \li \l{Qt for Android Examples}{Examples}
@@ -67,6 +68,67 @@ The following topics provide more details about how to use Qt for Android:
 */
 
 /*!
+  \page android3rdpartylibs.html
+  \title Third-party Android Libraries
+  \brief Provides instructions to include third-party Android libraries in an application.
+
+  This guide describes how to include a Java-based third-party library in your application package.
+  There are many Java libraries which provide APIs that may be useful to your application.
+  One example is the \c{Google Play Services} add-on provided in the Android SDK. We will use this library
+  as an example in this guide, but the same approach may be taken to include other libraries, provided
+  that they have been made to be included as library projects in an Android application.
+
+  \section1 Prerequisites
+
+  This guide assumes that the \l{androiddeployqt} tool is used for constructing the deployment package.
+  When using Qt Creator for building and deploying, androiddeployqt is used behind the scenes, so this also
+  applies to development with Qt Creator. Explaining how to access the Java APIs after they have been
+  included in the application is not in the scope of this guide.
+
+  \section1 Including the Library in the Source
+
+  The very first thing we need to do is to copy the actual library project into the source of our
+  project. We want the contents of the library project to be copied without modifications into the
+  packaging directory, so we need to place it into the \c{Android Package Source Directory}. This
+  can be any directory which is pointed to by the \l{qmake} variable \c{ANDROID_PACKAGE_SOURCE_DIR}.
+
+  If you are using Qt Creator, you can quickly set up the directory structure by clicking on the
+  \gui{Create AndroidManifest.xml} button in the \gui{Deployment} settings of your project. This
+  will create an \c{Android Package Source Directory} and place the \c{AndroidManifest.xml} file
+  inside it. Copy the library project directory into this directory.
+
+  For example, once it has been installed via the \c{Android SDK Maintenance} application,
+  the \c{Google Play Services} library project is located under the path
+  \c{$ANDROID_SDK_ROOT/extras/google/google_play_services/libproject/google-play-services_lib}. If
+  the \c{Android Package Source Directory} of our project is \c{$PROJECT_ROOT/android}, then we
+  can copy the \c{google-play-services_lib} directory in there, creating
+  \c{$PROJECT_ROOT/android/google-play-services_lib}.
+
+  \section1 Adding the Library to the Project Dependencies
+
+  Once the library code has been copied into the project, we need to tell the Android build system
+  about it. This is done in the \c{project.properties} file. Create a file called \c{project.properties}
+  inside the \c{Android Package Source Directory} and add a line to it which assigns the relative
+  path of the library project to the property \c{android.library.reference.1}. If you want to include
+  multiple library projects, increment the counter at the end of the property name for each.
+
+  In our example, we would create \c{$PROJECT_ROOT/android/project.properties} and add the
+  following contents:
+
+  \code
+  android.library.reference.1=google-play-services_lib/
+  \endcode
+
+  \section1 Deployment
+
+  And that's it: Provided that the path referenced in the \c{project.properties} file is located
+  under the \c{Android Package Source Directory}, the deployment tool will copy it into the
+  packaging directory and perform the necessary steps to include it in your \c{APK}. You can
+  now add Java code to your application which accesses the APIs provided by the library project.
+
+*/
+
+/*!
 \page androidgs.html
 \title Getting Started with Qt for Android
 \brief Provides instructions to install and configure your development environment.