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.
This commit is contained in:
Brad King 2016-06-20 15:48:12 -04:00
parent d7d4083025
commit 6b84df8da9
18 changed files with 375 additions and 27 deletions

View File

@ -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
build using NVIDIA Nsight Tegra targeting Android may look
like this:
Cross Compiling for Android
---------------------------
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

View File

@ -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

View File

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

View File

@ -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:

View File

@ -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

View File

@ -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"
``gabi++_static`` e.g. "GAbi++ Static"
``gabi++_shared`` e.g. "GAbi++ Shared"
``gnustl_static`` e.g. "GNU libstdc++ Static"
``gnustl_shared`` e.g. "GNU libstdc++ Shared"
``stlport_static`` e.g. "STLport Static"
``stlport_shared`` e.g. "STLport Shared"
``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
``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.

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

@ -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}

View File

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