diff options
Diffstat (limited to 'toolchain')
| -rw-r--r-- | toolchain/Android.cmake | 260 |
1 files changed, 130 insertions, 130 deletions
diff --git a/toolchain/Android.cmake b/toolchain/Android.cmake index db70de50..3f2443c6 100644 --- a/toolchain/Android.cmake +++ b/toolchain/Android.cmake @@ -1,137 +1,137 @@ -#.rst: -# 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 <https://doc.qt.io/qt-5/deployment-android.html>`_ 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 <https://doc.qt.io/qt-5/deployment-android.html>`_ 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. - -# ============================================================================= # SPDX-FileCopyrightText: 2014 Aleix Pol i Gonzalez <aleixpol@kde.org> # # SPDX-License-Identifier: BSD-3-Clause +#[=======================================================================[.rst: +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 <https://doc.qt.io/qt-5/deployment-android.html>`_ 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 <https://doc.qt.io/qt-5/deployment-android.html>`_ 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. +#]=======================================================================] + cmake_minimum_required(VERSION "3.18") macro(set_deprecated_variable actual_variable deprecated_variable default_value) |