ECM-TOOLCHAINS(7)

💅 ECM-TOOLCHAINS(7) — bestie's guide to Extra CMake Modules toolchains

okay so you found the <rainbow>Extra CMake Modules</rainbow> toolchain reference, hi, welcome, you're gonna do great 💖 This is the ecm-toolchains page, and yes it's a whole man page just for toolchains, slay.

---

✨ NAME ✨

ecm-toolchains — the ECM Toolchains Reference, aka the glow-up guide for your cross-compiling era.

---

🌸 INTRODUCTION 🌸

So <pink>Extra CMake Modules</pink> (ECM, ily) ships some toolchain modules. And these ones are different from your regular modules, bestie — you do not include them directly in your project. Nope. Instead you point the CMAKE_TOOLCHAIN_FILE cache variable at them on the commandline. That's the whole vibe check. 🎀

---

👑 ALL MODULES 👑

Only one module in here today and it's the main character: AndroidToolchain. Let's go.

🦋 AndroidToolchain 🦋

It enables easy compilation of cmake projects on Android. Literally that's it, that's the pitch. 💅

By using this android toolchain, your projects get set up to compile the specified project targeting an Android platform, depending on its input. And — here's the fun part — if you want, an APK can be directly generated by using the androiddeployqt tool (docs: <https://doc.qt.io/qt-5/deployment-android.html>). 🎀

Now, CMake upstream has Android support now, so this module isn't out here doing everything alone. It will still give us some useful features offering androiddeployqt integration and adequate executables format for our Android applications. Iconic behaviour, honestly.

And since we are using CMake Android support, any information from the 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. No cap, check your version.

Since 1.7.0.

✨ Usage ✨

To use this file, you need to set 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"

Heads up bestie: 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) — yes they wrote "separed", we love a typo moment — 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. 🔥

---

🌈 SEE ALSO 🌈

• ecm(7) <#manual:ecm(7)> — go read it, iykyk 💖

---

🎀 Copyright 🎀

KDE Developers. iconic of them.

---

✨ that's the whole page bestie ✨ — this was ECM-TOOLCHAINS(7), version 6.31, dated Oct 11, 2026. Go forth and cross-compile, you absolute legend 👑💖