在 Android 部署應用程序

本文描述把 Qt 應用程序部署到 Android 設備所需的技術步驟。

注意： The androiddeployqt Tool automates this process.

Android 應用程序綁定

Android 上的應用程序有 2 種打包方式：APK (應用程序包) 或 AAB (Android 應用綁定)。兩者是遵循預定義目錄結構的 ZIP 文件。兩者的區彆是 APK 文件可以在設備上部署和執行，而 AAB 旨在由 Google Play 商店解釋，並被用於為不同設備體係結構生成 APK 文件。

對於本地測試應用程序，APK 格式最閤適，因為可以直接將其上傳到設備並運行。為分發到 Google Play 商店，推薦使用有相似布局的 AAB 代替。AAB 的附加便利是可以把所有目標 ABI 包括在同一捆綁中，而不增加用戶實際下載包大小。當使用 AAB 時，Google Play 商店會為發齣下載請求的設備生成優化的 APK 包，並采用發布者密鑰自動對其進行簽名。

有關 AAB 格式的更多信息，見 Android 應用捆綁 .

在任何情況下，應用程序捆綁都是從特定目錄結構生成的，包含 .so 代碼文件，及應用程序所需的所有 Qt 依賴。此外，任何 .jar 文件、Java 代碼、資産、資源及 .xml 文件也包括在內。

生成應用程序捆綁

It is recommended to use Qt Creator or the Makefile created by qmake or CMake to create the application bundle.

All the steps described here are automatically handled by the build script and the androiddeployqt 部署工具 , which are run by Qt Creator by default.

注意： If you prefer building Android packages from the command line, see 構建 Android 應用程序 .

Android 包模闆

The default templates used by Qt are found in $Qt_install_dir/src/android/templates . The first step of making a custom package is to copy these files into an empty directory, for example android , under your project. Then, you need to define that path in your project's .pro file, using the variable ANDROID_PACKAGE_SOURCE_DIR :

android {
    ANDROID_PACKAGE_SOURCE_DIR = $$PWD/android
    DISTFILES += \
        android/AndroidManifest.xml \
        android/build.gradle \
        android/res/values/libs.xml
}

Qt Creator copies the package templates to your Android build directory ( $ANDROID_BUILD_DIR=$BUILD_DIR/android-build ) into your project build directory ( $BUILD_DIR ). If you want to build from the command line, use the following after running qmake or CMake :

make -j$(nproc) apk_install_target

The previous command copies the application's binaries and resources into the $ANDROID_BUILD_DIR. The build directory acts now as the packaging directory, which the application bundle is created from. The main parts of the package templates are described in the following sections.

AndroidManifest.xml

The AndroidManifest.xml file gives detailed meta-information about your application. This information is used to customize your application bundle and by the target device to decide which features to enable, the default orientation of the application, and so on. In addition, it's used by the Google Play Store for information on the version code, device support, package name, and lots more. The Android Manifest is also used to define Android 服務 , and custom Android Activities .

更多信息有關 AndroidManifest.xml ，見 Android Manifest file documentation .

Java 代碼

Under $Qt_install_dir/src/android/java/src/org/qtproject/qt/android/bindings/ are the files comprising the Java code of the Android application. This Java code is compiled under $ANDROID_BUILD_DIR and added to the application bundle. The regular Android application launcher is a Java process, so Qt applications have a Java-based entry point. The code in here will load the required Qt libraries, based on the meta-information given in Manifest file.

After loading the libraries, the Java code will call into the application's native main() function on a new thread and the application will launch. At this point, the Java code in the templates is used to delegate events from Android into Qt.

One thing to note about the files in this directory is that they can contain code specific to certain Android versions. Based on the minimum required Android API level of your application it might be necessary to remove some of this code. This is done automatically by androiddeployqt and Qt Creator during packaging.

If your minimum Android API level is 20 or lower, the code below is removed before building, since it's not a supported API on Android API level 20. However, if your minimum API level is 21 or higher, it is left in:

//@ANDROID-21
    @Override
    public void onActivityReenter(int resultCode, Intent data)
    {
        // Do something
        return super.onActivityReenter(resultCode, data);
    }
//@ANDROID-21

資源

Under the $Qt_instal_dir/src/android/templates/res/ folder are Android resources that can be accessed from the AndroidManifest.xml and Java code used by all Qt applications.

libs.xml

This file can be found at $Qt_instal_dir/src/android/templates/res/values/libs.xml . One of the files containing meta information about the deployment of the application is libs.xml . It consists of the following values:

bundled_libs : Libraries in the package's library folder which should be loaded on start-up. Library names should be specified without the lib prefix and .so suffix.
qt_libs : Qt libraries which should be loaded on start-up. When bundled deployment is used, these are expected to be found inside the APK 's library folder.

注意： Ministro is no longer maintained.

strings.xml

This file can be found at $Qt_instal_dir/src/android/java/res/values/strings.xml 。 strings.xml file contains strings used by the AndroidManifest.xml and by the deployment mechanisms.

In particular, the application name and the name of the application binary can be specified here. There are also strings that contain additional libraries that should be loaded and JAR files which should be included in the class path.

Gradle Files

The main Gradle build file can be found at $Qt_instal_dir/src/android/templates/build.gradle . This file is required by the Gradle build system used by Android to generate the application's APK. For more information, see Android Build Configuration Files .

定製包模闆

資源

Put any resources used by your application under $ANDROID_PACKAGE_SOURCE_DIR/res/ . A typical example of resources customization which should be placed here are the icons used by the application launcher to show your application.

自定義 Java 代碼

Place any Java code under the path $ANDROID_PACKAGE_SOURCE_DIR/src/ . Any code here can be used with your application, for example you can call Java methods from within Qt code. For more information, see Qt Android Notifier Example .

When using Qt Creator, add the Java files to your project using DISTFILES , so they are visible under the project files.

Assets

You can place any assets that are intended to be accessed by Java code under $ANDROID_PACKAGE_SOURCE_DIR/assets/ . For more information on using assets with Qt, see 移植到 Android .

注意： 使用 Qt 資源係統 entails having .qrc files bundled in the .so files which must be unpacked first to be loaded by the linker, while the Android assets are compressed in the .apk and can be directly used in your application. That means using the Android assets can take up less space, but it's not a cross-platform solution with Qt.

Android 庫

Under $ANDROID_PACKAGE_SOURCE_DIR/libs in your custom package directory, it's possible to place libraries that should be included in the application bundle. JAR libraries should be placed directly under $ANDROID_PACKAGE_SOURCE_DIR/libs/ , while shared libraries should be put in a subdirectory named after the target ABI of the libraries. The supported ABIs are: armeabi-v7a, arm64-v8a, x86, x86_64.

For more information, see also 第 3 方 Android 庫 .

構建 Android 應用程序

You may use the "aab" or "apk" build targets from the Makefile directly to build the application bundle. Use the following command to generate an AAB:

make -j$(nproc) aab

Or to generate the APK:

make -j$(nproc) apk

Under the hood, your Qt code is built and copied to the $ANDROID_BUILD_DIR, then Gradle is used to build the Java code and package the application. If an APK intended for release is built, then it should be signed with jarsigner and aligned with zipalign . For more information on signing the package with Qt Creator, see Signing Android packages .