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.

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