ecm-toolchains(7) - Man pages

ECM-TOOLCHAINS(7) Extra CMake Modules ECM-TOOLCHAINS(7)

NAME
ecm-toolchains - ECM Toolchains Reference

INTRODUCTION
Extra CMake Modules (ECM) provides some toolchain modules. Unlike nor-
mal modules, these are not included directly in projects, but specified
with the CMAKE_TOOLCHAIN_FILE cache variable on the commandline.

ALL MODULES
AndroidToolchain
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.

CMake upstream has Android support now. This module will still give us
some useful features offering androiddeployqt integration and adequate
executables format for our Android applications.

Since we are using CMake Android support, any information from CMake
documentation still applies:
https://cmake.org/cmake/help/v3.7/manual/cmake-toolchains.7.html#cross-compiling-for-android

NOTE:
This module requires CMake 3.18.

Since 1.7.0.

Usage
To use this file, you need to set the CMAKE_TOOLCHAIN_FILE to point to
Android.cmake on the command line:

cmake -DCMAKE_TOOLCHAIN_FILE=/usr/share/ECM/toolchain/Android.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:

CMAKE_ANDROID_NDK
The NDK root path.

ANDROID_SDK_ROOT
The SDK root path.

Additional options are specified as cache variables (eg: on the command
line):

ANDROID_ABI
The ABI to use. See the sources/cxx-stl/gnu-libstdc++/*/libs di-
rectories in the NDK. Default: armeabi-v7a.

ANDROID_SDK_COMPILE_API
The platform API level to compile against. May be different from
the NDK target. Default: newest installed version (e.g. an-
droid-30).

ANDROID_SDK_BUILD_TOOLS_REVISION
The build tools version to use. Default: newest installed ver-
sion (e.g. 30.0.2).

ANDROID_EXTRA_LIBS
The “;”-separated list of full paths to libs to include in re-
sulting APK.

For integrating other libraries which are not part of the Android
toolchain, like Qt5, and installed to a separate prefix on the host
system, the install prefixes of those libraries would be passed as al-
ternative roots as list via ECM_ADDITIONAL_FIND_ROOT_PATH. Since
5.30.0.

For example, for integrating a Qt5 for Android present at
~/Qt/5.14.2/android/ and some other libraries installed to the prefix
/opt/android/foo, you would use:

cmake \
-DCMAKE_TOOLCHAIN_FILE=/usr/share/ECM/toolchain/Android.cmake \
-DECM_ADDITIONAL_FIND_ROOT_PATH="~/Qt/5.14.2/android/;/opt/android/foo"

If your project uses find_package() to locate build tools on the host
system, make sure to pass CMAKE_FIND_ROOT_PATH_BOTH or
NO_CMAKE_FIND_ROOT_PATH as argument in the call. See the find_package()
documentation for more details.

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 androidde-
ployqt support to help with this for Qt-based projects. To enable this,
set the QTANDROID_EXPORTED_TARGET variable to the targets you wish to
export as an APK (in a ;-separed list), as well as ANDROID_APK_DIR to a
directory containing some basic information. This will create a cre-
ate-apk-<target> target that will generate the APK file. See the Qt on
Android deployment documentation for more information.

For example, you could do:

cmake \
-DCMAKE_TOOLCHAIN_FILE=/usr/share/ECM/toolchain/Android.cmake \
-DQTANDROID_EXPORTED_TARGET=myapp \
-DANDROID_APK_DIR=myapp-apk
make
make create-apk-myapp

You can specify the APK output directory by setting ANDROID_APK_OUT-
PUT_DIR. Otherwise the APK can be found in myapp_build_apk/ in the
build directory.

The create-apk-myapp target will be able to take an ARGS parameter with
further arguments for androiddeployqt. For example, one can use:

make create-apk-myapp ARGS="--install"

To install the apk to test. To generate a signed apk, one can do it
with the following syntax:

make create-apk-myapp ARGS="--sign ~/my.keystore alias_name"

In case it’s needed for your application to set the APK directory from
cmake scripting you can also set the directory as the ANDROID_APK_DIR
property of the create-apk-myapp target.

See Android documentation on how to create a keystore to use

Advanced Options
The following packaging options are mainly interesting for automation
or integration with CI/CD pipelines:

ANDROID_APK_OUTPUT_DIR
Specifies a folder where the generated APK files should be
placed.

ANDROID_FASTLANE_METADATA_OUTPUT_DIR
Specifies a folder where the generated metadata for the F-Droid
store should be placed.

ANDROIDDEPLOYQT_EXTRA_ARGS
Allows to pass additional arguments to androiddeployqt. This is
an alternative to the ARGS= argument for make and unlike that
works with all CMake generators.