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.

Help/manual/cmake-toolchains.7.rst

@@ -290,12 +290,206 @@ Windows Store may look like this:
   set(CMAKE_SYSTEM_NAME WindowsStore)
   set(CMAKE_SYSTEM_VERSION 8.1)
 
-Cross Compiling using NVIDIA Nsight Tegra
+.. _`Cross Compiling for Android`:
------------------------------------------
 
-A toolchain file to configure a Visual Studio generator to
+Cross Compiling for Android
-build using NVIDIA Nsight Tegra targeting Android may look
+---------------------------
-like this:
+
+A toolchain file may configure cross-compiling for Android by setting the
+:variable:`CMAKE_SYSTEM_NAME` variable to ``Android``.  Further configuration
+is specific to the Android development environment to be used.
+
+For :ref:`Visual Studio Generators`, CMake expects :ref:`NVIDIA Nsight Tegra
+Visual Studio Edition <Cross Compiling for Android with NVIDIA Nsight Tegra
+Visual Studio Edition>` to be installed.  See that section for further
+configuration details.
+
+For :ref:`Makefile Generators` and the :generator:`Ninja` generator,
+CMake expects one of these environments:
+
+* :ref:`NDK <Cross Compiling for Android with the NDK>`
+* :ref:`Standalone Toolchain <Cross Compiling for Android with a Standalone Toolchain>`
+
+CMake uses the following steps to select one of the environments:
+
+* If the :variable:`CMAKE_ANDROID_NDK` variable is set, the NDK at the
+  specified location will be used.
+
+* Else, if the :variable:`CMAKE_ANDROID_STANDALONE_TOOLCHAIN` variable
+  is set, the Standalone Toolchain at the specified location will be used.
+
+* Else, if the :variable:`CMAKE_SYSROOT` variable is set to a directory
+  of the form ``<ndk>/platforms/android-<api>/arch-<arch>``, the ``<ndk>``
+  part will be used as the value of :variable:`CMAKE_ANDROID_NDK` and the
+  NDK will be used.
+
+* Else, if the :variable:`CMAKE_SYSROOT` variable is set to a directory of the
+  form ``<standalone-toolchain>/sysroot``, the ``<standalone-toolchain>`` part
+  will be used as the value of :variable:`CMAKE_ANDROID_STANDALONE_TOOLCHAIN`
+  and the Standalone Toolchain will be used.
+
+* Else, if a cmake variable ``ANDROID_NDK`` is set it will be used
+  as the value of :variable:`CMAKE_ANDROID_NDK`, and the NDK will be used.
+
+* Else, if a cmake variable ``ANDROID_STANDALONE_TOOLCHAIN`` is set, it will be
+  used as the value of :variable:`CMAKE_ANDROID_STANDALONE_TOOLCHAIN`, and the
+  Standalone Toolchain will be used.
+
+* Else, if an environment variable ``ANDROID_NDK_ROOT`` or
+  ``ANDROID_NDK`` is set, it will be used as the value of
+  :variable:`CMAKE_ANDROID_NDK`, and the NDK will be used.
+
+* Else, if an environment variable ``ANDROID_STANDALONE_TOOLCHAIN`` is
+  set then it will be used as the value of
+  :variable:`CMAKE_ANDROID_STANDALONE_TOOLCHAIN`, and the Standalone
+  Toolchain will be used.
+
+* Else, an error diagnostic will be issued that neither the NDK or
+  Standalone Toolchain can be found.
+
+.. _`Cross Compiling for Android with the NDK`:
+
+Cross Compiling for Android with the NDK
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A toolchain file may configure :ref:`Makefile Generators` or the
+:generator:`Ninja` generator to target Android for cross-compiling.
+
+Configure use of an Android NDK with the following variables:
+
+:variable:`CMAKE_SYSTEM_NAME`
+  Set to ``Android``.  Must be specified to enable cross compiling
+  for Android.
+
+:variable:`CMAKE_SYSTEM_VERSION`
+  Set to the Android API level.  If not specified, the value is
+  determined as follows:
+
+  * If the :variable:`CMAKE_ANDROID_API` variable is set, its value
+    is used as the API level.
+  * If the :variable:`CMAKE_SYSROOT` variable is set, the API level is
+    detected from the NDK directory structure containing the sysroot.
+  * Otherwise, the latest API level available in the NDK is used.
+
+:variable:`CMAKE_ANDROID_ARCH_ABI`
+  Set to the Android ABI (architecture).  If not specified, this
+  variable will default to ``armeabi``.
+  The :variable:`CMAKE_ANDROID_ARCH` variable will be computed
+  from ``CMAKE_ANDROID_ARCH_ABI`` automatically.
+  Also see the :variable:`CMAKE_ANDROID_ARM_MODE` and
+  :variable:`CMAKE_ANDROID_ARM_NEON` variables.
+
+:variable:`CMAKE_ANDROID_NDK`
+  Set to the absolute path to the Android NDK root directory.
+  A ``${CMAKE_ANDROID_NDK}/platforms`` directory must exist.
+  If not specified, a default for this variable will be chosen
+  as specified :ref:`above <Cross Compiling for Android>`.
+
+:variable:`CMAKE_ANDROID_NDK_TOOLCHAIN_VERSION`
+  Set to the version of the NDK toolchain to be selected as the compiler.
+  If not specified, the latest available GCC toolchain will be used.
+
+:variable:`CMAKE_ANDROID_STL_TYPE`
+  Set to specify which C++ standard library to use.  If not specified,
+  a default will be selected as described in the variable documentation.
+
+The following variables will be computed and provided automatically:
+
+:variable:`CMAKE_<LANG>_ANDROID_TOOLCHAIN_PREFIX`
+  The absolute path prefix to the binutils in the NDK toolchain.
+
+:variable:`CMAKE_<LANG>_ANDROID_TOOLCHAIN_SUFFIX`
+  The host platform suffix of the binutils in the NDK toolchain.
+
+
+For example, a toolchain file might contain:
+
+.. code-block:: cmake
+
+  set(CMAKE_SYSTEM_NAME Android)
+  set(CMAKE_SYSTEM_VERSION 21) # API level
+  set(CMAKE_ANDROID_ARCH_ABI arm64-v8a)
+  set(CMAKE_ANDROID_NDK /path/to/android-ndk)
+  set(CMAKE_ANDROID_STL_TYPE gnustl_static)
+
+Alternatively one may specify the values without a toolchain file:
+
+.. code-block:: console
+
+  $ cmake ../src \
+    -DCMAKE_SYSTEM_NAME=Android \
+    -DCMAKE_SYSTEM_VERSION=21 \
+    -DCMAKE_ANDROID_ARCH_ABI=arm64-v8a \
+    -DCMAKE_ANDROID_NDK=/path/to/android-ndk \
+    -DCMAKE_ANDROID_STL_TYPE=gnustl_static
+
+.. _`Cross Compiling for Android with a Standalone Toolchain`:
+
+Cross Compiling for Android with a Standalone Toolchain
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A toolchain file may configure :ref:`Makefile Generators` or the
+:generator:`Ninja` generator to target Android for cross-compiling
+using a standalone toolchain.
+
+Configure use of an Android standalone toolchain with the following variables:
+
+:variable:`CMAKE_SYSTEM_NAME`
+  Set to ``Android``.  Must be specified to enable cross compiling
+  for Android.
+
+:variable:`CMAKE_ANDROID_STANDALONE_TOOLCHAIN`
+  Set to the absolute path to the standalone toolchain root directory.
+  A ``${CMAKE_ANDROID_STANDALONE_TOOLCHAIN}/sysroot`` directory
+  must exist.
+  If not specified, a default for this variable will be chosen
+  as specified :ref:`above <Cross Compiling for Android>`.
+
+:variable:`CMAKE_ANDROID_ARM_MODE`
+  When the standalone toolchain targets ARM, optionally set this to ``ON``
+  to target 32-bit ARM instead of 16-bit Thumb.
+  See variable documentation for details.
+
+:variable:`CMAKE_ANDROID_ARM_NEON`
+  When the standalone toolchain targets ARM v7, optionally set thisto ``ON``
+  to target ARM NEON devices.  See variable documentation for details.
+
+The following variables will be computed and provided automatically:
+
+:variable:`CMAKE_SYSTEM_VERSION`
+  The Android API level detected from the standalone toolchain.
+
+:variable:`CMAKE_ANDROID_ARCH_ABI`
+  The Android ABI detected from the standalone toolchain.
+
+:variable:`CMAKE_<LANG>_ANDROID_TOOLCHAIN_PREFIX`
+  The absolute path prefix to the binutils in the standalone toolchain.
+
+:variable:`CMAKE_<LANG>_ANDROID_TOOLCHAIN_SUFFIX`
+  The host platform suffix of the binutils in the standalone toolchain.
+
+For example, a toolchain file might contain:
+
+.. code-block:: cmake
+
+  set(CMAKE_SYSTEM_NAME Android)
+  set(CMAKE_ANDROID_STANDALONE_TOOLCHAIN /path/to/android-toolchain)
+
+Alternatively one may specify the values without a toolchain file:
+
+.. code-block:: console
+
+  $ cmake ../src \
+    -DCMAKE_SYSTEM_NAME=Android \
+    -DCMAKE_ANDROID_STANDALONE_TOOLCHAIN=/path/to/android-toolchain
+
+.. _`Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio Edition`:
+
+Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio Edition
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A toolchain file to configure one of the :ref:`Visual Studio Generators`
+to build using NVIDIA Nsight Tegra targeting Android may look like this:
 
 .. code-block:: cmake
 

Help/manual/cmake-variables.7.rst

@@ -225,6 +225,9 @@ Variables that Control the Build
    /variable/CMAKE_ANDROID_API
    /variable/CMAKE_ANDROID_API_MIN
    /variable/CMAKE_ANDROID_ARCH
+   /variable/CMAKE_ANDROID_ARCH_ABI
+   /variable/CMAKE_ANDROID_ARM_MODE
+   /variable/CMAKE_ANDROID_ARM_NEON
    /variable/CMAKE_ANDROID_ASSETS_DIRECTORIES
    /variable/CMAKE_ANDROID_GUI
    /variable/CMAKE_ANDROID_JAR_DEPENDENCIES
@@ -232,11 +235,14 @@ Variables that Control the Build
    /variable/CMAKE_ANDROID_JAVA_SOURCE_DIR
    /variable/CMAKE_ANDROID_NATIVE_LIB_DEPENDENCIES
    /variable/CMAKE_ANDROID_NATIVE_LIB_DIRECTORIES
+   /variable/CMAKE_ANDROID_NDK
+   /variable/CMAKE_ANDROID_NDK_TOOLCHAIN_VERSION
    /variable/CMAKE_ANDROID_PROCESS_MAX
    /variable/CMAKE_ANDROID_PROGUARD
    /variable/CMAKE_ANDROID_PROGUARD_CONFIG_PATH
    /variable/CMAKE_ANDROID_SECURE_PROPS_PATH
    /variable/CMAKE_ANDROID_SKIP_ANT_STEP
+   /variable/CMAKE_ANDROID_STANDALONE_TOOLCHAIN
    /variable/CMAKE_ANDROID_STL_TYPE
    /variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY
    /variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY_CONFIG
@@ -337,6 +343,8 @@ Variables for Languages
    /variable/CMAKE_Fortran_MODDIR_FLAG
    /variable/CMAKE_Fortran_MODOUT_FLAG
    /variable/CMAKE_INTERNAL_PLATFORM_ABI
+   /variable/CMAKE_LANG_ANDROID_TOOLCHAIN_PREFIX
+   /variable/CMAKE_LANG_ANDROID_TOOLCHAIN_SUFFIX
    /variable/CMAKE_LANG_ARCHIVE_APPEND
    /variable/CMAKE_LANG_ARCHIVE_CREATE
    /variable/CMAKE_LANG_ARCHIVE_FINISH

Help/prop_tgt/ANDROID_API.rst

@@ -1,7 +1,8 @@
 ANDROID_API
 -----------
 
-Set the Android Target API version (e.g. ``15``).  The version number
+When :ref:`Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio
-must be a positive decimal integer.  This property is initialized by
+Edition`, this property sets the Android target API version (e.g. ``15``).
-the value of the :variable:`CMAKE_ANDROID_API` variable if it is set
+The version number must be a positive decimal integer.  This property is
-when a target is created.
+initialized by the value of the :variable:`CMAKE_ANDROID_API` variable if
+it is set when a target is created.

Help/prop_tgt/ANDROID_ARCH.rst

@@ -1,7 +1,8 @@
 ANDROID_ARCH
 ------------
 
-Set the Android target architecture.
+When :ref:`Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio
+Edition`, this property sets the Android target architecture.
 
 This is a string property that could be set to the one of
 the following values:

Help/prop_tgt/ANDROID_GUI.rst

@@ -1,7 +1,9 @@
 ANDROID_GUI
 -----------
 
-Build an executable as an application package on Android.
+When :ref:`Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio
+Edition`, this property specifies whether to build an executable as an
+application package on Android.
 
 When this property is set to true the executable when built for Android
 will be created as an application package.  This property is initialized

Help/prop_tgt/ANDROID_STL_TYPE.rst

@@ -1,15 +1,27 @@
 ANDROID_STL_TYPE
 ----------------
 
-Set the Android property that defines the type of STL support for the project.
+When :ref:`Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio
+Edition`, this property specifies the type of STL support for the project.
 This is a string property that could set to the one of the following values:
-``none``           e.g. "No C++ Support"
+
-``system``         e.g. "Minimal C++ without STL"
+``none``
-``gabi++_static``  e.g. "GAbi++ Static"
+  No C++ Support
-``gabi++_shared``  e.g. "GAbi++ Shared"
+``system``
-``gnustl_static``  e.g. "GNU libstdc++ Static"
+  Minimal C++ without STL
-``gnustl_shared``  e.g. "GNU libstdc++ Shared"
+``gabi++_static``
-``stlport_static`` e.g. "STLport Static"
+  GAbi++ Static
-``stlport_shared`` e.g. "STLport Shared"
+``gabi++_shared``
+  GAbi++ Shared
+``gnustl_static``
+  GNU libstdc++ Static
+``gnustl_shared``
+  GNU libstdc++ Shared
+``stlport_static``
+  STLport Static
+``stlport_shared``
+  STLport Shared
+
 This property is initialized by the value of the
-variable:`CMAKE_ANDROID_STL_TYPE` variable if it is set when a target is created.
+:variable:`CMAKE_ANDROID_STL_TYPE` variable if it is set when a target is
+created.

Help/release/dev/android-platform-modules.rst

@@ -0,0 +1,5 @@
+android-platform-modules
+------------------------
+
+* CMake now supports :ref:`Cross Compiling for Android` with simple
+  toolchain files.

Help/variable/CMAKE_ANDROID_API.rst

@@ -1,5 +1,11 @@
 CMAKE_ANDROID_API
 -----------------
 
-Default value for the :prop_tgt:`ANDROID_API` target property.
+When :ref:`Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio
-See that target property for additional information.
+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.

Help/variable/CMAKE_ANDROID_ARCH.rst

@@ -1,5 +1,19 @@
 CMAKE_ANDROID_ARCH
 ------------------
 
-Default value for the :prop_tgt:`ANDROID_ARCH` target property.
+When :ref:`Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio
-See that target property for additional information.
+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``

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.

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``).

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.

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.

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.

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.

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.
+When :ref:`Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio
-See that target property for additional information.
+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.

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}

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`.