1ECM-TOOLCHAINS(7)             Extra CMake Modules            ECM-TOOLCHAINS(7)
2
3
4

NAME

6       ecm-toolchains - ECM Toolchains Reference
7

INTRODUCTION

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

ALL MODULES

14   AndroidToolchain
15       Enable easy compilation of cmake projects on Android.
16
17       By using this android toolchain, the projects will be set up to compile
18       the specified project targeting an Android platform, depending  on  its
19       input.   Furthermore,  if  desired, an APK can be directly generated by
20       using the androiddeployqt tool.
21
22       CMake upstream has Android support now. This module will still give  us
23       some  useful features offering androiddeployqt integration and adequate
24       executables format for our Android applications.
25
26       Since we are using CMake Android support, any  information  from  CMake
27       documentation                       still                      applies:
28       https://cmake.org/cmake/help/v3.7/manual/cmake-toolchains.7.html#cross-compiling-for-android
29
30       NOTE:
31          This module requires CMake 3.18.
32
33       Since 1.7.0.
34
35   Usage
36       To  use this file, you need to set the CMAKE_TOOLCHAIN_FILE to point to
37       Android.cmake on the command line:
38
39          cmake -DCMAKE_TOOLCHAIN_FILE=/usr/share/ECM/toolchain/Android.cmake
40
41       You will also need to provide the locations of the Android NDK and SDK.
42       This  can  be done on the commandline or with environment variables; in
43       either case the variable names are:
44
45       CMAKE_ANDROID_NDK
46              The NDK root path.
47
48       ANDROID_SDK_ROOT
49              The SDK root path.
50
51       Additional options are specified as cache variables (eg: on the command
52       line):
53
54       ANDROID_ABI
55              The ABI to use. See the sources/cxx-stl/gnu-libstdc++/*/libs di‐
56              rectories in the NDK. Default: armeabi-v7a.
57
58       ANDROID_SDK_COMPILE_API
59              The platform API level to compile against. May be different from
60              the  NDK  target.  Default:  newest  installed version (e.g. an‐
61              droid-30).
62
63       ANDROID_SDK_BUILD_TOOLS_REVISION
64              The build tools version to use.  Default: newest installed  ver‐
65              sion (e.g. 30.0.2).
66
67       ANDROID_EXTRA_LIBS
68              The  “;”-separated  list of full paths to libs to include in re‐
69              sulting APK.
70
71       For integrating other libraries which  are  not  part  of  the  Android
72       toolchain,  like  Qt5,  and  installed to a separate prefix on the host
73       system, the install prefixes of those libraries would be passed as  al‐
74       ternative   roots  as  list  via  ECM_ADDITIONAL_FIND_ROOT_PATH.  Since
75       5.30.0.
76
77       For  example,  for  integrating  a   Qt5   for   Android   present   at
78       ~/Qt/5.14.2/android/  and  some other libraries installed to the prefix
79       /opt/android/foo, you would use:
80
81          cmake \
82            -DCMAKE_TOOLCHAIN_FILE=/usr/share/ECM/toolchain/Android.cmake \
83            -DECM_ADDITIONAL_FIND_ROOT_PATH="~/Qt/5.14.2/android/;/opt/android/foo"
84
85       If your project uses find_package() to locate build tools on  the  host
86       system,    make    sure    to    pass    CMAKE_FIND_ROOT_PATH_BOTH   or
87       NO_CMAKE_FIND_ROOT_PATH as argument in the call. See the find_package()
88       documentation for more details.
89
90   Deploying Qt Applications
91       After  building  the application, you will need to generate an APK that
92       can be deployed to an Android device. This module integrates androidde‐
93       ployqt support to help with this for Qt-based projects. To enable this,
94       set the QTANDROID_EXPORTED_TARGET variable to the targets you  wish  to
95       export as an APK (in a ;-separed list), as well as ANDROID_APK_DIR to a
96       directory containing some basic information. This will  create  a  cre‐
97       ate-apk-<target> target that will generate the APK file.  See the Qt on
98       Android deployment documentation for more information.
99
100       For example, you could do:
101
102          cmake \
103            -DCMAKE_TOOLCHAIN_FILE=/usr/share/ECM/toolchain/Android.cmake \
104            -DQTANDROID_EXPORTED_TARGET=myapp \
105            -DANDROID_APK_DIR=myapp-apk
106          make
107          make create-apk-myapp
108
109       You can specify the APK output directory  by  setting  ANDROID_APK_OUT‐
110       PUT_DIR.   Otherwise  the  APK  can be found in myapp_build_apk/ in the
111       build directory.
112
113       The create-apk-myapp target will be able to take an ARGS parameter with
114       further arguments for androiddeployqt. For example, one can use:
115
116          make create-apk-myapp ARGS="--install"
117
118       To  install  the  apk  to test. To generate a signed apk, one can do it
119       with the following syntax:
120
121          make create-apk-myapp ARGS="--sign ~/my.keystore alias_name"
122
123       In case it’s needed for your application to set the APK directory  from
124       cmake  scripting  you can also set the directory as the ANDROID_APK_DIR
125       property of the create-apk-myapp target.
126
127       See Android documentation on how to create a keystore to use
128
129   Advanced Options
130       The following packaging options are mainly interesting  for  automation
131       or integration with CI/CD pipelines: ANDROID_APK_OUTPUT_DIR
132          Specifies a folder where the generated APK files should be placed.
133
134       ANDROID_FASTLANE_METADATA_OUTPUT_DIR
135              Specifies  a folder where the generated metadata for the F-Droid
136              store should be placed.
137
138       ANDROIDDEPLOYQT_EXTRA_ARGS
139              Allows to pass additional arguments to androiddeployqt. This  is
140              an  alternative  to  the ARGS= argument for make and unlike that
141              works with all CMake generators.
142

SEE ALSO

144       ecm(7)
145
147       KDE Developers
148
149
150
151
1525.82                             May 03, 2021                ECM-TOOLCHAINS(7)
Impressum