Android部署工具

构建 Android 打包包涉及多个步骤,因此 Qt 伴随一个工具可为您处理这些步骤。由 androiddeployqt 工具处理的步骤在 在 Android 上部署应用程序 一节中进行描述。

运行 androiddeployqt 之前的需求

在手动运行工具之前,您需要使用 CMakeqmake 配置您的项目以生成 Makefiles 和一个包含重要设置(例如 android-<target_name>-deployment-settings.json)的 JSON 文件,这些设置由 androiddeployqt 使用。

注意: 不建议修改 androiddeployqt JSON 文件。

为了为 androiddeployqt 准备环境,请在与源目录不同的单独目录中配置您的项目。有关配置项目的更多信息,请参阅 从命令行构建 Android 项目 Qt

命令行参数

运行工具时,仅需要的命令行参数是 --input--output。其他命令行参数是可选的,但非常有用。以下列表可通过传递 --help 参数到 androiddeployqt 获取。

Syntax: androiddeployqt --output <destination> [options]

Creates an Android package in the build directory <destination> and
builds it into an .apk file.

Optional arguments:
    --input <inputfile>: Reads <inputfile> for options generated by
       qmake. A default file name based on the current working
       directory will be used if nothing else is specified.

    --deployment <mechanism>: Supported deployment mechanisms:
       bundled (default): Includes Qt files in stand-alone package.
       unbundled: Assumes native libraries are present on the device
       and does not include them in the APK.

    --aab: Build an Android App Bundle.

    --no-build: Do not build the package, it is useful to just install
       a package previously built.

    --install: Installs apk to device/emulator. By default this step is
       not taken. If the application has previously been installed on
       the device, it will be uninstalled first.

    --reinstall: Installs apk to device/emulator. By default this step
       is not taken. If the application has previously been installed on
       the device, it will be overwritten, but its data will be left
       intact.

    --device [device ID]: Use specified device for deployment. Default
       is the device selected by default by adb.

    --android-platform <platform>: Builds against the given android
       platform. By default, the highest available version will be
       used.

    --release: Builds a package ready for release. By default, the
       package will be signed with a debug key.

    --sign <url/to/keystore> <alias>: Signs the package with the
       specified keystore, alias and store password.
       Optional arguments for use with signing:
         --storepass <password>: Keystore password.
         --storetype <type>: Keystore type.
         --keypass <password>: Password for private key (if different
           from keystore password.)
         --sigfile <file>: Name of .SF/.DSA file.
         --digestalg <name>: Name of digest algorithm. Default is
           "SHA-256".
         --sigalg <name>: Name of signature algorithm. Default is
           "SHA256withRSA".
         --tsa <url>: Location of the Time Stamping Authority.
         --tsacert <alias>: Public key certificate for TSA.
         --internalsf: Include the .SF file inside the signature block.
         --sectionsonly: Don't compute hash of entire manifest.
         --protected: Keystore has protected authentication path.
         --jarsigner: Deprecated, ignored.

       NOTE: To conceal the keystore information, the environment variables
         QT_ANDROID_KEYSTORE_PATH, and QT_ANDROID_KEYSTORE_ALIAS are used to
         set the values keysotore and alias respectively.
         Also the environment variables QT_ANDROID_KEYSTORE_STORE_PASS,
         and QT_ANDROID_KEYSTORE_KEY_PASS are used to set the store and key
         passwords respectively. This option needs only the --sign parameter.

    --jdk <path/to/jdk>: Used to find the jarsigner tool when used
       in combination with the --release argument. By default,
       an attempt is made to detect the tool using the JAVA_HOME and
       PATH environment variables, in that order.

    --qml-import-paths: Specify additional search paths for QML
       imports.

    --verbose: Prints out information during processing.

    --no-generated-assets-cache: Do not pregenerate the entry list for
       the assets file engine.

    --aux-mode: Operate in auxiliary mode. This will only copy the
       dependencies into the build directory and update the XML templates.
       The project will not be built or installed.

    --apk <path/where/to/copy/the/apk>: Path where to copy the built apk.

    --qml-importscanner-binary <path/to/qmlimportscanner>: Override the
       default qmlimportscanner binary path. By default the
       qmlimportscanner binary is located using the Qt directory
       specified in the input file.

    --depfile <path/to/depfile>: Output a dependency file.

    --builddir <path/to/build/directory>: build directory. Necessary when
       generating a depfile because ninja requires relative paths.

    --no-rcc-bundle-cleanup: skip cleaning rcc bundle directory after
       running androiddeployqt. This option simplifies debugging of
       the resource bundle content, but it should not be used when deploying
       a project, since it litters the 'assets' directory.

    --copy-dependencies-only: resolve application dependencies and stop
       deploying process after all libraries and resources that the
       application depends on have been copied.

    --help: Displays this information.

使用 project_name,在不部署到设备的情况下使用 androiddeployqt 构建应用程序包,请运行以下命令

androiddeployqt --input <build_dir>/android-project_name-deployment-settings.json \
                --output <build_dir>/android-build

构建并部署包装到设备

androiddeployqt --input <build_dir>/android-project_name-deployment-settings.json \
                --output <build_dir>/android-build --install --device <device_serial_id>

依赖检测

Qt 随带了一些插件,在运行时按需加载。这些插件可以从连接 SQL 数据库到加载特定的图像格式。由于插件在运行时加载,因此检测插件依赖项是不可能的,但 androiddeployqt 尝试根据您的应用程序的 Qt 依赖项猜测这些依赖项。如果插件有任何不是应用程序依赖项的 Qt 依赖项,则它不会默认包含。例如,为了确保 SVG 图像格式插件包含在内,您需要将 Qt SVG 模块添加到您的项目中,以便它成为应用程序的依赖项

find_package(Qt6 REQUIRED COMPONENTS Svg)
...
target_link_libraries(target_name PRIVATE Qt6::Svg)

如果您想知道为什么某个特定插件未自动包含,您可以在运行 androiddeployqt 时使用 --verbose 选项以获取每个排除插件的缺少依赖项列表。您也可以在 Qt Creator 中通过在 项目 > 构建步骤 > 构建 Android APK > 高级操作 中选中 详细输出 复选框来实现。

还可以手动指定应用程序的依赖项。有关更多信息,请参阅 QT_ANDROID_DEPLOYMENT_DEPENDENCIES CMake 变量。

注意:androiddeployqt 会扫描项目中的 QML 文件以收集 QML 导入。但是,如果您在运行时从 C++ 中作为 QString 加载 QML 代码,这可能不会正常工作,因为 androiddeployqt 在部署时可能不知道这一点。为了纠正这个问题,您可以添加一个虚拟的 QML 文件,该文件导入在运行时引用的此类 QML 模块。

Qt Creator 中的部署

Qt Creator 在底层使用 androiddeployqt,并提供了简单直观的用户界面来指定各种选项。有关更多信息,请参阅 Qt Creator:将应用程序部署到 Android 设备

有关自定义和部署 Qt for Android 应用程序的更多信息,请参阅 在 Android 上部署应用程序

© 2024 The Qt Company Ltd。此处包含的文档贡献归其各自所有者所有。此处提供的文档受 GNU 自由文档许可证版本 1.3 的条款约束,由自由软件基金会发布。Qt 及其相应标志是 The Qt Company Ltd. 在芬兰和其他国家的商标。所有其他商标均为其各自所有者的财产。