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:
132
133       ANDROID_APK_OUTPUT_DIR
134              Specifies  a  folder  where  the  generated  APK files should be
135              placed.
136
137       ANDROID_FASTLANE_METADATA_OUTPUT_DIR
138              Specifies a folder where the generated metadata for the  F-Droid
139              store should be placed.
140
141       ANDROIDDEPLOYQT_EXTRA_ARGS
142              Allows  to pass additional arguments to androiddeployqt. This is
143              an alternative to the ARGS= argument for make  and  unlike  that
144              works with all CMake generators.
145

SEE ALSO

147       ecm(7)
148
150       KDE Developers
151
152
153
154
1555.111                            Oct 14, 2023                ECM-TOOLCHAINS(7)
Impressum