Kivy/Python-for-Android 项目中的 distutils/setuptools 集成指南

Kivy/Python-for-Android 项目中的 distutils/setuptools 集成指南

python-for-android Turn your Python application into an Android APK 项目地址: https://gitcode.com/gh_mirrors/py/python-for-android

概述

在 Kivy/Python-for-Android 项目中，开发者可以通过两种主要方式利用 Python 的标准打包工具 distutils/setuptools 来构建 Android 应用。本文将详细介绍这两种集成方式及其适用场景，帮助开发者选择最适合自己项目的构建方案。

方式一：在 p4a apk 命令中运行 setup.py

基本概念

这种方式允许 p4a apk 命令在执行时自动运行项目的 setup.py 文件，从而替代传统的 --requirements 参数指定依赖的方式。

启用方法

使用 --use-setup-py 参数启用此功能，或使用 --ignore-setup-py 显式禁用。

核心优势

1. 标准化依赖管理：使用 Python 标准的 setup.py 文件管理依赖，而非项目特定的 --requirements 参数
2. 跨平台一致性：如果项目已经为其他平台使用 setup.py，可以保持构建方式统一
3. 解决导入问题：当应用需要以 site-packages 方式导入自身模块时特别有用

重要限制

1. 文件包含限制：只有 main.py 会从 --private 数据自动复制到 APK，其他所有文件必须通过 setup.py 安装到 site-packages
2. 版本约束严格：依赖项必须指定精确版本号，其他约束可能导致构建失败
3. 构建速度影响：依赖分析阶段可能显著增加构建时间

适用场景建议

推荐使用：

• 已有完善的 setup.py 配置
• 需要与其他平台保持一致的依赖管理方式
• 应用模块需要以标准 Python 包方式导入

不推荐使用：

• 项目简单，直接使用 --requirements 更便捷
• setup.py 包含 Android 不兼容的依赖项
• 需要包含未通过 setup.py 安装的数据文件

方式二：在 setup.py 中调用 p4a

基本概念

这种方式反转了控制流程，允许开发者通过标准的 setup.py 文件来调用 p4a 工具，实现更符合 Python 生态的构建流程。

基本用法

python setup.py apk

自动配置项

1. 文件包含：通过 package_data 参数指定要包含的文件
2. 应用信息：自动从 setup.py 读取 name 和 version
3. 包名规则：默认使用 org.test.lowercaseappname 格式
4. 架构目标：默认为 armeabi

配置示例

from distutils.core import setup
from setuptools import find_packages

setup(
    name='testapp_setup',
    version='1.1',
    packages=find_packages(),
    package_data={'testapp': ['*.py', '*.png']}
)

高级配置

可以在 setup.py 中预定义 p4a 参数：

options = {
    'apk': {
        'debug': None,  # 无值参数使用 None
        'requirements': 'sdl2,pyjnius,kivy,python3',
        'android-api': 19,
        'ndk-dir': '/path/to/ndk'
    }
}

setup(
    ...,
    options=options
)

配置文件方式

也可以通过 setup.cfg 配置 p4a 参数：

[apk]
requirements=sdl2,kivy
android-api=19

两种方式的对比与选择

| 特性 | p4a 运行 setup.py | setup.py 调用 p4a | |---------------------|---------------------------|---------------------------| | 控制流程 | p4a 主导 | setup.py 主导 | | 依赖管理 | 替代 --requirements | 仍可使用 --requirements | | 文件包含机制 | 严格依赖 site-packages | 通过 package_data 灵活控制 | | 适合场景 | 已有成熟 setup.py 的项目 | 希望标准化构建流程的项目 |

最佳实践建议

1. 新项目：建议从 setup.py 调用 p4a 的方式开始，更符合 Python 标准实践
2. 已有项目：根据现有构建方式选择最接近的集成方案
3. 复杂项目：考虑将 Android 特定配置分离到 setup.cfg 中
4. 性能敏感：如果构建速度是关键因素，可能需要权衡是否使用 setup.py 集成

通过合理选择和使用这些集成方式，开发者可以更高效地将 Python 项目打包为 Android 应用，同时保持与 Python 生态系统的良好兼容性。

python-for-android Turn your Python application into an Android APK 项目地址: https://gitcode.com/gh_mirrors/py/python-for-android