NAME

       ecm-toolchains - ECM Toolchains Reference

INTRODUCTION

       Extra  CMake  Modules  (ECM) provides some toolchain modules. Unlike normal 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  directories  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. android-30).

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

       ANDROID_EXTRA_LIBS
              The “;”-separated list of full paths to libs to include  in  resulting  APK  (Qt  5
              only).

       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  alternative  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 5 Applications
       After  building  the application, you will need to generate an APK that can be deployed to
       an Android device. This module integrates androiddeployqt 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 create-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_OUTPUT_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.

SEE ALSO

       ecm(7)

COPYRIGHT

       KDE Developers