Add Android toolchain module to the documentation.

6 files changed, 121 insertions, 55 deletions

diff --git a/README.rst b/README.rst
index ccc692b7..01c844d2 100644
--- a/README.rst
+++ b/README.rst
@@ -5,8 +5,9 @@ Introduction
 ============
 
 The Extra CMake Modules package, or ECM, adds to the modules provided by CMake,
-including both ones used by ``find_package()`` to find common software and ones
-that can be used directly in ``CMakeLists.txt`` files to perform common tasks.
+including ones used by ``find_package()`` to find common software, ones that
+can be used directly in ``CMakeLists.txt`` files to perform common tasks and
+toolchain files that must be specified on the commandline by the user.
 
 In addition, it provides common build settings used in software produced by the
 KDE community.
@@ -54,7 +55,7 @@ some of the settings.  Some of the functionality of
 Organization
 ------------
 
-ECM provides three different types of modules.
+ECM provides four different types of modules.
 
 * Core modules provide helpful macros for use in project CMake scripts.
   See :manual:`ecm-modules(7)` for more information.
@@ -63,6 +64,8 @@ ECM provides three different types of modules.
 * KDE modules provide common settings for software produced by KDE; much of this
   may also be useful to other projects.  See :manual:`ecm-kde-modules(7)` for
   more information.
+* Toolchain files change the build tools and targets used by CMake. See
+  :manual:`ecm-toolchains(7)` for more information.
 
 The ``${ECM_MODULE_DIR}``, ``${ECM_FIND_MODULE_DIR}`` and
 ``${ECM_KDE_MODULE_DIR}`` variables may be used instead of
diff --git a/docs/manual/ecm-modules.7.rst b/docs/manual/ecm-modules.7.rst
index 16fd8612..ee0e4638 100644
--- a/docs/manual/ecm-modules.7.rst
+++ b/docs/manual/ecm-modules.7.rst
@@ -11,12 +11,12 @@ Introduction
 ============
 
 Extra CMake Modules (ECM) provides various modules that provide useful functions
-for CMake scripts. ECM actually provides three types of modules: those that
-extend the functionality of the ``find_package`` command are documented in
-:manual:`ecm-find-modules(7)`; those that provide standard settings for software
-produced by the KDE community are documented in :manual:`ecm-kde-modules(7)`.
-The rest provide macros and functions for general use by CMake scripts and are
-documented here.
+for CMake scripts. ECM actually provides three types of modules that can be
+used from CMake scripts: those that extend the functionality of the
+``find_package`` command are documented in :manual:`ecm-find-modules(7)`; those
+that provide standard settings for software produced by the KDE community are
+documented in :manual:`ecm-kde-modules(7)`.  The rest provide macros and
+functions for general use by CMake scripts and are documented here.
 
 To use these modules, you need to tell CMake to find the ECM package, and
 then add either ``${ECM_MODULE_PATH}`` or ``${ECM_MODULE_DIR}`` to the
@@ -30,6 +30,10 @@ then add either ``${ECM_MODULE_PATH}`` or ``${ECM_MODULE_DIR}`` to the
 Using ``${ECM_MODULE_PATH}`` will also make the find modules and KDE modules
 available.
 
+Note that there are also toolchain modules, documented in
+:manual:`ecm-toolchains(7)`, but these are used by users building the software
+rather than developers writing CMake scripts.
+
 
 All Modules
 ===========
diff --git a/docs/manual/ecm-toolchains.7.rst b/docs/manual/ecm-toolchains.7.rst
new file mode 100644
index 00000000..66f685e2
--- /dev/null
+++ b/docs/manual/ecm-toolchains.7.rst
@@ -0,0 +1,33 @@
+.. ecm-manual-description: ECM Toolchains Reference
+
+ecm-toolchains(7)
+*****************
+
+.. only:: html or latex
+
+   .. contents::
+
+Introduction
+============
+
+Extra CMake Modules (ECM) provides some toolchain modules. Unlike normal
+modules, these are not included directly in projects, but specified with
+the ``CMAKE_TOOLCHAIN_FILE`` cache variable on the commandline.
+
+
+All Modules
+===========
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   /toolchain/*
+
+.. only:: man
+
+  See Also
+  ========
+
+  :manual:`ecm(7)`
+
diff --git a/docs/sphinx/ecm.py b/docs/sphinx/ecm.py
index 3eb75248..ed966bfb 100644
--- a/docs/sphinx/ecm.py
+++ b/docs/sphinx/ecm.py
@@ -154,6 +154,7 @@ _ecm_index_objs = {
     'module':      _ecm_index_entry('module'),
     'find-module': _ecm_index_entry('find-module'),
     'kde-module':  _ecm_index_entry('kde-module'),
+    'toolchain':   _ecm_index_entry('toolchain'),
     }
 
 def _ecm_object_inventory(env, document, line, objtype, targetid):
@@ -264,6 +265,7 @@ class ECMDomain(Domain):
         'kde-module':  ObjType('kde-module',  'kde-module'),
         'find-module': ObjType('find-module', 'find-module'),
         'manual':      ObjType('manual',      'manual'),
+        'toolchain':   ObjType('toolchain',   'toolchain'),
     }
     directives = {}
     roles = {
@@ -271,6 +273,7 @@ class ECMDomain(Domain):
         'kde-module':  XRefRole(),
         'find-module': XRefRole(),
         'manual':      XRefRole(),
+        'toolchain':   XRefRole(),
     }
     initial_data = {
         'objects': {},  # fullname -> docname, objtype
diff --git a/docs/toolchain/Android.rst b/docs/toolchain/Android.rst
new file mode 100644
index 00000000..9103e622
--- /dev/null
+++ b/docs/toolchain/Android.rst
@@ -0,0 +1 @@
+.. ecm-module:: ../../toolchain/Android.cmake
diff --git a/toolchain/Android.cmake b/toolchain/Android.cmake
index 8272ef9d..55d2ca81 100644
--- a/toolchain/Android.cmake
+++ b/toolchain/Android.cmake
@@ -1,57 +1,79 @@
 #.rst:
 # AndroidToolchain
-# -------------------
+# ----------------
 #
-# Enable easy compilation of cmake projects on Android
+# Enable easy compilation of cmake projects on Android.
 #
 # By using this android toolchain, the projects will be set up to compile the
 # specified project targeting an Android platform, depending on its input.
 # Furthermore, if desired, an APK can be directly generated by using the
-# androiddeployqt tool.
-#
-# Note: Requires CMake 3.1
-#
-# How to use it?
-# --------------
-# First of all, to make use of this toolchain file it's required to specify the
-# CMAKE_TOOLCHAIN_FILE variable pointing to AndroidToolchain.cmake.
-#
-# Then, there's many settings that we may want to specify under what circumstances
-# the project will be built. This will be done through environment variables:
-# - ANDROID_NDK: points to the NDK root path
-# - ANDROID_SDK_ROOT: points to the SDK root path
-#
-# Also there's some cache variables we can pass as well to narrow down the
-# preferred settings:
-# - ANDROID_NDK: Points to the NDK root, defaults to the environment variable
-# with the same name.
-# - ANDROID_SDK_ROOT: Points to the Android SDK root, defaults to the environment
-# variable with the same name.
-# - ANDROID_ARCHITECTURE: Specifies the used architecture, "arm" by default. See
-# arch-* directory.
-# - ANDROID_TOOLCHAIN: Specifies the toolchain to be used. Defaults to
-# "arm-linux-androideabi". See <ndk>/toolchains/ directory.
-# - ANDROID_ABI: Specifies the ABI to be used. Defaults to "armeabi-v7a". See
-# <ndk>/sources/cxx-stl/gnu-libstdc++/*/libs/ directories.
-# - ANDROID_GCC_VERSION: Specifies the GCC version. Defaults to "4.9".
-# - ANDROID_API_LEVEL: Specifies the API level to require. Defaults to "14". See
-# http://developer.android.com/guide/topics/manifest/uses-sdk-element.html
-# - ANDROID_SDK_BUILD_TOOLS_REVISION: Specifies the build tools version to be used.
-# Defaults to "21.1.1".
-#
-# Once we have the application built, we will want to generate an APK that we
-# can run on an Android device. To this end we've integrated androiddeployqt so
-# this can be done easily. This won't work with non-qt projects.
-# To make use of the APK generation, we'll define QTANDROID_EXPORTED_TARGET with
-# the target we want to have exported.
-# Additionally, we'll need to specify a ANDROID_APK_DIR with the base information
-# to set the project up. For more information see:
-# https://qt-project.org/doc/qt-5-snapshot/deployment-android.html
-#
-# Once set up, after building, make create-apk-<target_name> will process this
-# input and generate an apk that can be found inside the build directory:
-# ${CMAKE_BINARY_DIR}/<target_name>_build_apk/bin/QtApp-*.apk.
+# `androiddeployqt <http://doc.qt.io/qt-5/deployment-android.html>`_ tool.
 #
+# .. note::
+#
+#   This module requires CMake 3.1.
+#
+# Since 1.7.0.
+#
+# Usage
+# =====
+#
+# To use this file, you need to set the ``CMAKE_TOOLCHAIN_FILE`` to point to
+# ``AndroidToolchain.cmake`` on the command line::
+#
+#   cmake -DCMAKE_TOOLCHAIN_FILE=/usr/share/ECM/toolchain/AndroidToolchain.cmake
+#
+# You will also need to provide the locations of the Android NDK and SDK. This
+# can be done on the commandline or with environment variables; in either case
+# the variable names are:
+#
+# ``ANDROID_NDK``
+#     The NSK root path.
+# ``ANDROID_SDK_ROOT``
+#     The SSK root path.
+#
+# Additional options are specified as cache variables (eg: on the command line):
+#
+# ``ANDROID_ARCHITECTURE``
+#     The architecture to compile for. Default: ``arm``.
+# ``ANDROID_TOOLCHAIN``
+#     The toolchain to use. See the ``toolchains`` directory of the NDK.
+#     Default: ``arm-linux-androideabi``.
+# ``ANDROID_ABI``
+#     The ABI to use. See the ``sources/cxx-stl/gnu-libstdc++/*/libs``
+#     directories in the NDK. Default: ``armeabi-v7a``.
+# ``ANDROID_GCC_VERSION``
+#     The GCC version to use. Default: ``4.9``.
+# ``ANDROID_API_LEVEL``
+#     The `API level
+#     <http://developer.android.com/guide/topics/manifest/uses-sdk-element.html>`_
+#     to require. Default: ``14``.
+# ``ANDROID_SDK_BUILD_TOOLS_REVISION``
+#     The build tools version to use. Default: ``21.1.1``.
+#
+# Deploying Qt Applications
+# =========================
+#
+# After building the application, you will need to generate an APK that can be
+# deployed to an Android device. This module integrates androiddeployqt support
+# to help with this for Qt-based projects. To enable this, set the
+# ``QTANDROID_EXPORTED_TARGET`` variable to the target you wish to export as an
+# APK, as well as ``ANDROID_APK_DIR`` to a directory containing some basic
+# information. This will create a ``create-apk-<target>`` target that will
+# generate the APK file.  See the `Qt on Android deployment documentation
+# <http://doc.qt.io/qt-5/deployment-android.html>`_ for more information.
+#
+# For example, you could do::
+#
+#   cmake \
+#     -DCMAKE_TOOLCHAIN_FILE=/usr/share/ECM/toolchain/AndroidToolchain.cmake \
+#     -DQTANDROID_EXPORTED_TARGET=myapp \
+#     -DANDROID_APK_DIR=myapp-apk
+#   make
+#   make create-apk-myapp
+#
+# The APK would then be found in ``myapp_build_apk/bin`` in the build directory.
+
 # =============================================================================
 # Copyright 2014 Aleix Pol i Gonzalez <aleixpol@kde.org>
 #