Android Multi-ABI builds for user projects are back

In Qt 6.3, we have restored support for multi-ABI builds for user applications that use CMake. The build procedure for Qt 6 has undergone significant changes, especially with regards to Qt for Android. Let's have a look at how to work with the multi-ABI builds in Qt 6.

First of all, it's recommended to use the recent CMake version to support latest features. As you probably noticed, Qt for Android uses DEFER calls, so multi-ABI builds rely on this feature as well. If you are stuck on CMake versions older than 3.19, check out the note at the end of this post.

To configure your project, you need to run the bin/qt-cmake script from any of the available Qt for Android directories and use one of the ways to enable the multi-ABI build described below. The ABI of this primary Qt for Android will be used to set up and build the secondary ABIs and generate the final Android package. The build routine uses CMake ExternalProject for each secondary ABI under the hood.

Set QT_ANDROID_BUILD_ALL_ABIS to detect them all

The easiest way to enable multi-ABI build is to set the CMake option QT_ANDROID_BUILD_ALL_ABIS to 'ON' at the project configuring stage. This option automatically detects available Qt for Android ABIs and uses them to build the Android package.

For successful autodetection, each secondary ABI requires the presence of the related Qt for Android directory at the same directory level as the primary ABI, assuming the use of the default directory structure supplied by the Qt installer:

/home/user/Qt/6.3.0
    android_armv7
    android_arm64_v8a
    android_x86
    android_x86_64
    ...

QT_ANDROID_ABIS to be a little more precise

The most common way to build packages with multiple ABIs is to use the QT_ANDROID_ABIS CMake cache variable. This variable gives you the ability to build Android packages with a specific set of ABIs.

Note that in Qt 6.3.0, the primary ABI is added to the list of used ABIs unconditionally, without the ability to exclude it from the build.

QT_ANDROID_ABIS can take one of the following values supported by Qt 6: armeabi-v7a, arm64-v8a, x86, x86_64.

The command below will configure the project to build packages using armeabi-v7a, arm64-v8a and x86_64(see the note) ABIs:

/home/user/Qt/Qt6.3.0/android_x86_64/bin/qt-cmake \
    -DQT_ANDROID_ABIS="armeabi-v7a;arm64-v8a" \
    -S <source_directory> -B <build_directory>

The /home/user/Qt/Qt6.3.0/android_armv7 and /home/user/Qt/Qt6.3.0/android_arm64_v8a directories are supossed to contain Qt for Android for respective secondary ABIs.

Using the CMake cache variables QT_PATH_ANDROID_ABI_<ABI>, you can specify the absolute path to custom Qt for Android for each secondary ABIs. For instance:

/home/user/Qt/Qt6.3.0/android_x86_64/bin/qt-cmake \
    -DQT_ANDROID_ABIS="armeabi-v7a;arm64-v8a" \
    -DQT_PATH_ANDROID_ABI_armeabi-v7a="<Qt/for/armeabi-v7a>" \
    -DQT_PATH_ANDROID_ABI_arm64-v8a="<Qt/for/arm64-v8a>" \
    -S <source_directory> -B <build_directory>

These variables can be used with the QT_ANDROID_BUILD_ALL_ABIS flag too:

/home/user/Qt/Qt6.3.0/android_x86_64/bin/qt-cmake \
    -DQT_ANDROID_BUILD_ALL_ABIS=ON \
    -DQT_PATH_ANDROID_ABI_armeabi-v7a="<Qt/for/armeabi-v7a>" \
    -DQT_PATH_ANDROID_ABI_arm64-v8a="<Qt/for/arm64-v8a>" \
    -S <source_directory> -B <build_directory>

Specify ABIs for a single target

Yet another way to build a single package with multiple ABIs is to set the ANDROID_ABIS property for the executable target. The property has the highest priority among all the described methods. This way has very limited use, but it can still be applied for some projects.

# Build for arm64-v8a
set_property(TARGET androidapp PROPERTY ANDROID_ABIS "arm64-v8a")
if(BUILD_FOR_X86_TOO)
    set_property(TARGET androidapp APPEND PROPERTY ANDROID_ABIS "x86")
endif()

The primary ABI will be included regardless of entry into the ABIs list.

For users of older CMake versions

If you use the CMake version older than 3.19, you need to finalize executable targets manually to make the multi-ABI magic work:

qt_add_executable(androidapp MANUAL_FINALIZATION main.cpp)
# Build for arm64-v8a, x86 only
set_target_properties(androidapp PROPERTIES ANDROID_ABIS "arm64-v8a;x86")
# ...
qt_finalize_target(androidapp)

Enable multi-ABI builds in QtCreator

The described methods for building multi-ABI packages can be used with QtCreator. The QT_ANDROID_BUILD_ALL_ABIS, QT_ANDROID_ABIS, and QT_PATH_ANDROID_ABI_<ABI> variables can be found in corresponding to the project Build Settings menu:
android_enable_multi_abi_wtih_arrow


We keep improving Android experience in Qt 6.


Blog Topics:

Comments