pyside6-android-deploy: Qt for Python 的 Android 部署工具

pyside6-android-deploy 是一个易于使用的工具,用于将 PySide6 应用程序部署到不同的 Android 架构,即 arm64-v8a, x86_64, x86 和 armeabi-v7a。该工具的工作方式类似于 pyside6-deploy 工具,并使用相同的配置文件 pysidedeploy.spec 来配置部署过程。通过命令行或 pysidedeploy.spec 中的部署配置选项,pyside6-android-deploy 配置部署并调用 buildozer,这是一个用于将 Python 应用程序打包到 Android 的工具。

最终输出是在项目的源目录中创建的.apk.aab文件。pysidedeploy.specbuildozer键下指定的mode选项决定了是创建.apk还是.aab

警告

目前,用户需要为armeabi-v7ax86 Android平台交叉编译Qt for Python以生成所需的wheels。有关为Android交叉编译Qt for Python的说明可以在这里找到。

注意

pyside6-android-deploy 目前只能在 Unix(Linux 或 macOS)主机上运行。

先决条件

在使用 pyside6-android-deploy 之前,请确保满足以下先决条件:

下载Android NDK和SDK

所需的NDK对应于您使用的Qt版本所需的NDK版本。有关更多信息,请参见Qt for Android

下载 Android NDK 的最简单方法是通过位于 Qt for Python 仓库中的脚本。要运行该脚本,请按照以下步骤操作:

  1. 克隆 Qt for Python 仓库:

git clone https://code.qt.io/pyside/pyside-setup
  1. 运行脚本:

cd pyside-setup
python tools/cross_compile_android/main.py --download-only --skip-update --auto-accept-license

脚本将下载所需的Android NDK和SDK包到您的主目录中,作为一个名为.pyside6-android-deploy的目录。pyside6-android-deploy将自动从这个缓存目录中检测NDK和SDK。

如果你想尝试手动下载NDK和SDK,可以按照以下步骤进行(适用于Qt 6.8):

  1. 按照Android Studio 文档中提供的说明下载 sdkmanager。

  2. 使用sdkmanager下载以下包(适用于Qt 6.8):

    "platform-tools", "platforms;android-34", "build-tools;35.0.0"
    

并使用以下命令安装NDK(适用于Qt 6.8):

"ndk;26.1.10909125"

注意

NDK版本和所需的SDK包对应于您使用的Qt版本的要求。有关更多信息,请参见Qt for Android

下载适用于Python的Qt Android轮子

有两种方法可以下载适用于Python Android的Qt轮子:

  1. Qt for Python 下载页面下载轮子。

  2. 使用 qtpip 通过以下命令下载 wheels:

qtpip download PySide6 --android --arch aarch64

适用于aarch64架构。可用的架构有aarch64x86_64

如何使用它?

就像pyside6-deploy: the deployment tool for Qt for Python一样,有两种不同的方式可以使用pyside6-android-deploy来部署你的PySide6应用程序。唯一的区别是,为了让pyside6-android-deploy工作,主要的Python入口文件应该命名为main.py

要部署应用程序,请运行以下命令:

pyside6-android-deploy --name "MyApp"
    --wheel-pyside=path_to_downloaded_PySide_wheel
    --wheel-shiboken=path_to_downloaded_Shiboken_wheel
    --ndk-path=path_to_ndk
    --sdk-path=path_to_sdk

如果您使用了下载 Android NDK 和 SDK部分提供的脚本来下载 NDK 和 SDK,则--ndk-path--sdk-path选项是可选的。

对于任何后续的部署,您可以使用pysidedeploy.spec文件来控制部署过程的各种参数。使用pysidedeploy.spec文件部署应用程序的命令是:

pyside6-android-deploy --config-file path_to_pysidedeploy.spec

如果从项目目录运行命令,config-file 选项是可选的,其中 pysidedeploy.spec 位于该目录。

pysidedeploy.spec

pyside6-deploy类似,您可以使用pysidedeploy.spec文件来控制部署过程的各种参数。该文件包含多个部分,每个部分包含多个键(被控制的参数)分配给一个值。这种文件的优点在这里提到。使用相同的pysidedeploy.spec文件用于pyside6-deploypyside6-android-deploy的好处是,您可以有一个单一的文件来控制所有平台的部署。

pyside6-android-deploy 的相关参数是:

app
  • title: 应用程序的名称。

  • project_dir: 项目目录。通常假设项目目录是主Python入口点文件的父目录。

  • input_file: 主Python入口文件的路径。对于pyside6-android-deploy,此文件应命名为main.py

  • project_file: 如果存在,这指向Qt Creator Python 项目文件 .pyproject文件的路径。项目目录中的此类文件确保在打包可执行文件时不会考虑不必要的文件。

  • exec_directory: 生成最终可执行文件的目录。

python
  • python_path: Python可执行文件的路径。建议从虚拟环境中运行 pyside6-android-deploy,因为某些Python包将被安装到Python环境中。但是,请注意将创建的虚拟环境 保留在项目目录之外,以便pyside6-android-deploy不会尝试将其打包。

  • android_packages: 安装到Python环境中的Python包,以便部署工作。默认情况下,安装了Python包buildozercpython

qt
  • modules: 应用程序使用的所有Qt模块的逗号分隔列表。就像pysidedeploy.spec中的其他配置选项一样,此选项也是由pyside6-android-deploy自动计算的。但是,如果您想显式包含某些Qt模块,可以将模块名称附加到此列表中,而不需要Qt前缀。例如,使用Network而不是QtNetwork。

  • plugins: 这个字段对于pyside6-android-deploy不相关的,仅特定于 pyside6-deploy。与pyside6-android-deploy相关的插件是通过 android键下的plugins选项指定的。

android
  • wheel_pyside: 指定特定目标架构的PySide6 Android wheel的路径。

  • wheel_pyside: 指定特定目标架构的Shiboken6 Android wheel的路径。

  • plugins: 应用程序使用的所有Qt插件的逗号分隔列表。就像pysidedeploy.spec中的其他配置选项一样,此选项也是由pyside6-android-deploy自动计算的。但是,如果您想显式包含某些Qt插件,可以将插件名称附加到此列表中。要查看与PySide6捆绑的所有插件,请参阅安装PySide6的Python的site-packages中的plugins文件夹。插件名称对应于它们的文件夹名称。此字段可能会与qt键下的plugins选项混淆。将来,它们将合并为一个单一选项。

buildozer
  • mode: 指定两种模式之一 - releasedebug,用于运行 buildozerrelease 模式会生成一个 aab 文件,而 debug 模式会生成一个 apk 文件。默认模式是 debug

  • recipe_dir: 指定包含python-for-android配方的目录路径。 此选项在部署期间由pyside6-android-deploy自动计算。如果没有 –keep-deployment-files选项的pyside6-android-deployrecipe_dir将指向一个临时目录,该目录在最终Android应用程序包创建后被删除。

  • jars_dir: 指定与创建Android应用程序包相关的Qt Android .jar文件的路径。此选项在部署期间由pyside6-android-deploy自动计算。与recipe_dir类似,除非与pyside6-android-deploy–keep-deployment-files选项一起使用,否则此字段也不相关

  • ndk_path: 指定用于打包应用程序的Android NDK的路径。

  • sdk_path: 指定用于打包应用程序的Android SDK的路径。

  • local_libs: 指定与Android目标兼容的非Qt插件或其他库,这些库将在启动时由Android运行时加载。

  • sdk_path: 指定用于打包应用程序的Android SDK的路径。

  • arch: 指定目标架构的指令集。此选项接受以下四个值之一 - aarch64, armv7a, i686, x86_64

命令行选项

以下是pyside6-android-deploy的所有命令行选项:

  • -c/–config-file: 此选项用于显式指定pysidedeploy.spec的路径。

  • –init: 用于仅创建 pysidedeploy.spec 文件。 用法:

    pyside6-android-deploy --init
    
  • -v/–verbose: 以详细模式运行 pyside6-android-deploy

  • –dry-run: 显示生成Android应用程序包时运行的命令。

  • –keep-deployment-files: 当添加此选项时,它会保留由 buildozer 在部署过程中创建的构建文件夹。这包括存储 python-for-android 配方的文件夹、相关的 .jar 文件,甚至是应用程序的 Android Gradle 项目。

  • -f/–force: 当使用此选项时,它会假设对所有提示回答yes并以非交互方式运行 pyside6-android-deploypyside6-android-deploy会提示用户 创建一个Python虚拟环境,如果当前不在一个虚拟环境中。使用此选项时,无论当前Python环境是否为虚拟环境, 都会使用当前的Python环境。

  • –name: 应用程序名称。

  • –wheel-pyside: 特定目标架构的 PySide6 Android wheel 的路径。

  • –wheel-shiboken: 特定目标架构的 Shiboken6 Android 轮子的路径。

  • –ndk-path: 用于打包应用程序的Android NDK的路径。

  • –sdk-path: 用于打包应用程序的Android SDK的路径。

  • –extra-ignore-dirs: 项目目录中以逗号分隔的目录名称。在搜索与项目相关的Python文件时,这些目录将被跳过。

  • –extra-modules: 以逗号分隔的Qt模块列表,这些模块将被添加到应用程序中,以防它们未被自动找到。模块名称可以通过省略Qt的前缀或包含它来指定,例如:Network和QtNetwork都可以使用。

为Android交叉编译Qt for Python轮子

针对特定Android目标架构的Qt for Python轮子的交叉编译,每个Qt版本只需进行一次,无论您部署的应用程序数量如何。目前,Qt for Python轮子的交叉编译仅适用于Linux主机。按照以下步骤进行Qt for Python Android轮子的交叉编译。

  1. Download 并安装您希望为其创建 Qt for Python wheels 的 Qt 版本。

  2. 克隆 Qt for Python 仓库:

    git clone https://code.qt.io/pyside/pyside-setup
    
  3. 检出你想要构建的版本,例如6.7。检出的版本必须与步骤1中下载的Qt版本相对应:

    cd pyside-setup && git checkout 6.7
    
  4. 安装依赖项:

    pip install -r requirements.txt
    pip install -r tools/cross_compile_android/requirements.txt
    
  5. 运行交叉编译的Python脚本:

    python tools/cross_compile_android/main.py --plat-name=aarch64 --qt-install-path=/opt/Qt/6.7.0
    --auto-accept-license --skip-update
    

    –qt-install-path 指的是Qt 6.7.0的安装路径。–auto-accept-license–skip-update 是用于下载和安装Android NDK和SDK的,如果没有通过命令行选项指定或者它们不存在于 pyside6-android-deploy 缓存中,则需要使用这些选项。使用–help查看所有其他可用选项:

    python tools/cross_compile_android/main.py --help