Help: Document cross compiling for Android

CMake now supports cross compiling for Android using the NDK or a
standalone toolchain.  Document the associated variables and how how to
write toolchain files for Android.

11 files changed, 131 insertions, 6 deletions

diff --git a/Help/variable/CMAKE_ANDROID_API.rst b/Help/variable/CMAKE_ANDROID_API.rst
index c8264e0..c07a05a 100644
--- a/Help/variable/CMAKE_ANDROID_API.rst
+++ b/Help/variable/CMAKE_ANDROID_API.rst
@@ -1,5 +1,11 @@
 CMAKE_ANDROID_API
 -----------------
 
-Default value for the :prop_tgt:`ANDROID_API` target property.
-See that target property for additional information.
+When :ref:`Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio
+Edition`, this variable may be set to specify the default value for the
+:prop_tgt:`ANDROID_API` target property.  See that target property for
+additional information.
+
+Otherwise, when :ref:`Cross Compiling for Android`, this variable provides
+the Android API version number targeted.  This will be the same value as
+the :variable:`CMAKE_SYSTEM_VERSION` variable for ``Android`` platforms.
diff --git a/Help/variable/CMAKE_ANDROID_ARCH.rst b/Help/variable/CMAKE_ANDROID_ARCH.rst
index 8fbb46d..b91ca57 100644
--- a/Help/variable/CMAKE_ANDROID_ARCH.rst
+++ b/Help/variable/CMAKE_ANDROID_ARCH.rst
@@ -1,5 +1,19 @@
 CMAKE_ANDROID_ARCH
 ------------------
 
-Default value for the :prop_tgt:`ANDROID_ARCH` target property.
-See that target property for additional information.
+When :ref:`Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio
+Edition`, this variable may be set to specify the default value for the
+:prop_tgt:`ANDROID_ARCH` target property.  See that target property for
+additional information.
+
+Otherwise, when :ref:`Cross Compiling for Android`, this variable provides
+the name of the Android architecture corresponding to the value of the
+:variable:`CMAKE_ANDROID_ARCH_ABI` variable.  The architecture name
+may be one of:
+
+* ``arm``
+* ``arm64``
+* ``mips``
+* ``mips64``
+* ``x86``
+* ``x86_64``
diff --git a/Help/variable/CMAKE_ANDROID_ARCH_ABI.rst b/Help/variable/CMAKE_ANDROID_ARCH_ABI.rst
new file mode 100644
index 0000000..0a3ed3c
--- /dev/null
+++ b/Help/variable/CMAKE_ANDROID_ARCH_ABI.rst
@@ -0,0 +1,17 @@
+CMAKE_ANDROID_ARCH_ABI
+----------------------
+
+When :ref:`Cross Compiling for Android`, this variable specifies the
+target architecture and ABI to be used.  Valid values are:
+
+* ``arm64-v8a``
+* ``armeabi-v7a``
+* ``armeabi-v6``
+* ``armeabi``
+* ``mips``
+* ``mips64``
+* ``x86``
+* ``x86_64``
+
+See also the :variable:`CMAKE_ANDROID_ARM_MODE` and
+:variable:`CMAKE_ANDROID_ARM_NEON` variables.
diff --git a/Help/variable/CMAKE_ANDROID_ARM_MODE.rst b/Help/variable/CMAKE_ANDROID_ARM_MODE.rst
new file mode 100644
index 0000000..ad3c37c
--- /dev/null
+++ b/Help/variable/CMAKE_ANDROID_ARM_MODE.rst
@@ -0,0 +1,7 @@
+CMAKE_ANDROID_ARM_MODE
+----------------------
+
+When :ref:`Cross Compiling for Android` and :variable:`CMAKE_ANDROID_ARCH_ABI`
+is set to one of the ``armeabi`` architectures, set ``CMAKE_ANDROID_ARM_MODE``
+to ``ON`` to target 32-bit ARM processors (``-marm``).  Otherwise, the
+default is to target the 16-bit Thumb processors (``-mthumb``).
diff --git a/Help/variable/CMAKE_ANDROID_ARM_NEON.rst b/Help/variable/CMAKE_ANDROID_ARM_NEON.rst
new file mode 100644
index 0000000..4b7ae03
--- /dev/null
+++ b/Help/variable/CMAKE_ANDROID_ARM_NEON.rst
@@ -0,0 +1,6 @@
+CMAKE_ANDROID_ARM_NEON
+----------------------
+
+When :ref:`Cross Compiling for Android` and :variable:`CMAKE_ANDROID_ARCH_ABI`
+is set to ``armeabi-v7a`` set ``CMAKE_ANDROID_ARM_NEON`` to ``ON`` to target
+ARM NEON devices.
diff --git a/Help/variable/CMAKE_ANDROID_NDK.rst b/Help/variable/CMAKE_ANDROID_NDK.rst
new file mode 100644
index 0000000..d241dd0
--- /dev/null
+++ b/Help/variable/CMAKE_ANDROID_NDK.rst
@@ -0,0 +1,7 @@
+CMAKE_ANDROID_NDK
+-----------------
+
+When :ref:`Cross Compiling for Android with the NDK`, this variable holds
+the absolute path to the root directory of the NDK.  The directory must
+contain a ``platforms`` subdirectory holding the ``android-<api>``
+directories.
diff --git a/Help/variable/CMAKE_ANDROID_NDK_TOOLCHAIN_VERSION.rst b/Help/variable/CMAKE_ANDROID_NDK_TOOLCHAIN_VERSION.rst
new file mode 100644
index 0000000..dff7d64
--- /dev/null
+++ b/Help/variable/CMAKE_ANDROID_NDK_TOOLCHAIN_VERSION.rst
@@ -0,0 +1,13 @@
+CMAKE_ANDROID_NDK_TOOLCHAIN_VERSION
+-----------------------------------
+
+When :ref:`Cross Compiling for Android with the NDK`, this variable
+may be set to specify the version of the toolchain to be used
+as the compiler.  The variable must be set to one of these forms:
+
+* ``<major>.<minor>``: GCC of specified version
+* ``clang<major>.<minor>``: Clang of specified version
+* ``clang``: Clang of most recent available version
+
+A toolchain of the requested version will be selected automatically to
+match the ABI named in the :variable:`CMAKE_ANDROID_ARCH_ABI` variable.
diff --git a/Help/variable/CMAKE_ANDROID_STANDALONE_TOOLCHAIN.rst b/Help/variable/CMAKE_ANDROID_STANDALONE_TOOLCHAIN.rst
new file mode 100644
index 0000000..ea62cab
--- /dev/null
+++ b/Help/variable/CMAKE_ANDROID_STANDALONE_TOOLCHAIN.rst
@@ -0,0 +1,6 @@
+CMAKE_ANDROID_STANDALONE_TOOLCHAIN
+----------------------------------
+
+When :ref:`Cross Compiling for Android with a Standalone Toolchain`, this
+variable holds the absolute path to the root directory of the toolchain.
+The specified directory must contain a ``sysroot`` subdirectory.
diff --git a/Help/variable/CMAKE_ANDROID_STL_TYPE.rst b/Help/variable/CMAKE_ANDROID_STL_TYPE.rst
index 766b2c8..cfb76aa 100644
--- a/Help/variable/CMAKE_ANDROID_STL_TYPE.rst
+++ b/Help/variable/CMAKE_ANDROID_STL_TYPE.rst
@@ -1,5 +1,36 @@
 CMAKE_ANDROID_STL_TYPE
 ----------------------
 
-Default value for the :prop_tgt:`ANDROID_STL_TYPE` target property.
-See that target property for additional information.
+When :ref:`Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio
+Edition`, this variable may be set to specify the default value for the
+:prop_tgt:`ANDROID_STL_TYPE` target property.  See that target property
+for additional information.
+
+When :ref:`Cross Compiling for Android with the NDK`, this variable may be
+set to specify the STL variant to be used.  The value may be one of:
+
+``none``
+  No C++ Support
+``system``
+  Minimal C++ without STL
+``gabi++_static``
+  GAbi++ Static
+``gabi++_shared``
+  GAbi++ Shared
+``gnustl_static``
+  GNU libstdc++ Static
+``gnustl_shared``
+  GNU libstdc++ Shared
+``c++_static``
+  LLVM libc++ Static
+``c++_shared``
+  LLVM libc++ Shared
+``stlport_static``
+  STLport Static
+``stlport_shared``
+  STLport Shared
+
+The default value is ``gnustl_static``.  Note that this default differs from
+the native NDK build system because CMake may be used to build projects for
+Android that are not natively implemented for it and use the C++ standard
+library.
diff --git a/Help/variable/CMAKE_LANG_ANDROID_TOOLCHAIN_PREFIX.rst b/Help/variable/CMAKE_LANG_ANDROID_TOOLCHAIN_PREFIX.rst
new file mode 100644
index 0000000..b51422f
--- /dev/null
+++ b/Help/variable/CMAKE_LANG_ANDROID_TOOLCHAIN_PREFIX.rst
@@ -0,0 +1,11 @@
+CMAKE_<LANG>_ANDROID_TOOLCHAIN_PREFIX
+-------------------------------------
+
+When :ref:`Cross Compiling for Android` this variable contains the absolute
+path prefixing the toolchain GNU compiler and its binutils.
+
+See also :variable:`CMAKE_<LANG>_ANDROID_TOOLCHAIN_SUFFIX`.
+
+For example, the path to the linker is::
+
+  ${CMAKE_CXX_ANDROID_TOOLCHAIN_PREFIX}ld${CMAKE_CXX_ANDROID_TOOLCHAIN_SUFFIX}
diff --git a/Help/variable/CMAKE_LANG_ANDROID_TOOLCHAIN_SUFFIX.rst b/Help/variable/CMAKE_LANG_ANDROID_TOOLCHAIN_SUFFIX.rst
new file mode 100644
index 0000000..a4af640
--- /dev/null
+++ b/Help/variable/CMAKE_LANG_ANDROID_TOOLCHAIN_SUFFIX.rst
@@ -0,0 +1,7 @@
+CMAKE_<LANG>_ANDROID_TOOLCHAIN_SUFFIX
+-------------------------------------
+
+When :ref:`Cross Compiling for Android` this variable contains the
+host platform suffix of the toolchain GNU compiler and its binutils.
+
+See also :variable:`CMAKE_<LANG>_ANDROID_TOOLCHAIN_PREFIX`.