python-for-android Bootstraps 完全指南：从零创建自定义 Android 构建后端

• 开发工具
• 构建工具
• 移动开发

python-for-android（简称 p4a）的Bootstrap机制是连接 Python 模块与完整 Android 工程之间的桥梁：它定义了如何将若干 recipe 编译产物、Android 原生源码和各种构建文件组装成一个可构建、可打包的 Android 项目。本文以官方文档 doc/source/bootstraps.rst 为主线，结合仓库内全部 Bootstrap 实现与基类源码，系统讲解 Bootstrap 的职责、核心组件、自动选择逻辑，并给出从零编写自有 Bootstrap 的完整方法，帮助你掌握"把 Python 应用变成 Android APK"的最后一块拼图。

一、Bootstrap 是什么：与 Recipe 的分工

在 p4a 中，构建一个 APK 至少涉及两类"零件"：

• Recipe（配方）：描述如何为某个具体 Python 模块（如numpy、sdl2、openssl）交叉编译出.so库，即"单个模块怎么编"。
• Bootstrap（引导后端）：描述如何把多个 recipe 的产物与 Android 源码、Gradle/构建脚本、Java 代码、模板文件等组合成一个完整的 Android 工程，即"整个项目怎么拼"。

官方文档给出的定义非常直白：Bootstrap 与 recipe 扮演相似角色，但 recipe 说明"如何编译某个特定模块"，而 bootstrap 说明"如何把单个 recipe 与其他组件（Android 源码、各类构建文件）组合成一个完整的 Android 项目"。它是构建产物的最终装配层，位于 pythonforandroid/bootstraps/ 目录之下。

二、仓库内置的 Bootstrap 一览

当前仓库的pythonforandroid/bootstraps/目录下共包含以下 bootstrap 实现，每个子目录既是 Python 模块（提供bootstrap实例），也包含各自的build/工程模板目录：

除各后端目录外，bootstraps/下还有两份全局 Gradle 配置：gradle.properties 与 settings.gradle，以及_sdl_common/目录，存放 SDL2/SDL3 共用的SDLGradleBootstrap基类。

2.1 各后端的源码级差异

从源码可以清楚看到后端的定制点。SDL 系列后端复用了_sdl_common中的 Gradle 装配逻辑，仅通过recipe_depends注入对应的 SDL 库（见 sdl2/init.py 与 sdl3/init.py）：

class SDL2GradleBootstrap(SDLGradleBootstrap): name = "sdl2" recipe_depends = list( set(SDLGradleBootstrap.recipe_depends).union({"sdl2"}) ) bootstrap = SDL2GradleBootstrap()

empty后端则直接声明can_be_chosen_automatically = False，并在assemble_distribution中打印提示后退出，明确它只是一个"占位/测试"后端（见 empty/init.py）：

class EmptyBootstrap(Bootstrap): name = 'empty' recipe_depends = [] can_be_chosen_automatically = False def assemble_distribution(self): print('empty bootstrap has no distribute') exit(1)

qt后端是目前最"重"的定制实现之一：它重写了整个assemble_distribution，并且只允许单一架构构建（len(self.ctx.archs) > 1时直接抛出ValueError），其recipe_depends直接声明['python3', 'genericndkbuild', 'PySide6', 'shiboken6']（见 qt/init.py）。

三、一个 Bootstrap 的核心组件

官方文档指出：一个 bootstrap 类只由几个基本组件组成，但其中有一个组件必须承担绝大部分工作。以文档给出的 SDL2 为例：

from pythonforandroid.toolchain import Bootstrap, shprint, current_directory, info, warning, ArchAndroid, logger, info_main, which from os.path import join, exists from os import walk import glob import sh class SDL2Bootstrap(Bootstrap): name = 'sdl2' recipe_depends = ['sdl2'] def run_distribute(self): # much work is done here...

三个核心组件的职责：

1. name：bootstrap 的标识符，同时决定其在bootstraps/下的目录名。基类的name属性实际上是从模块名推导的——self.__class__.__module__.split(".", 2)[-1]（见 bootstrap.py），子类显式声明只是让逻辑更清晰。
2. recipe_depends：该 bootstrap 需要的 recipe 依赖列表。注意基类默认值是['python3', 'android']，即所有 bootstrap 都必须以某种方式包含 Python（见 bootstrap.py）；列表中还允许使用(tuple, list)形式的"多选一"备选依赖，配合check_recipe_choices()决定最终构建目录名（见 bootstrap.py）。
3. run_distribute（或assemble_distribution）：装配主逻辑。官方文档强调该方法必须完成"创建构建目录、把 recipes 等拷贝进去、按需增删额外组件"的全部工作。

需要说明：当前仓库的基类中，文档示例所提的run_distribute已演进为prepare_build_dir+assemble_distribution+_assemble_distribution_for_arch的分阶段方法体系（见下文第四节），这体现了该机制随版本迭代的演进，读者以仓库实际 API 为准。

四、深入基类：Bootstrap 到底做了什么

基类定义在 pythonforandroid/bootstrap.py，其类注释写道："一个 Android 项目模板，包含用于编译的 recipe 内容和用于 APK 信息的模板字段"。整个生命周期可拆为四个阶段：

4.1 目录规划：get_bootstrap_dirs与get_build_dir

get_bootstrap_dirs()沿类的 MRO 链收集所有父类名称（去掉Bootstrap与object），再加上固定的common，得到一组"由基类到子类"的模板目录列表（见 bootstrap.py）。例如 SDL2 后端会依次处理common、_sdl_common、sdl2三个模板目录——这一设计让公共工程文件只需维护一份。

4.2 构建目录准备：prepare_build_dir

对上述每个模板目录，prepare_build_dir()将其下的build/内容累积拷贝进ctx.build_dir/bootstrap_builds/<name>-<choices>/，随后写入project.properties（内容为target=android-<api>）（见 bootstrap.py）。累积拷贝由模块级函数copy_files()实现，支持symlink模式（对应--symlink-bootstrap-files选项）（见 bootstrap.py）。

4.3 分发装配：assemble_distribution与_assemble_distribution_for_arch

assemble_distribution()是默认装配入口（见 bootstrap.py），主要步骤包括：

1. 删除旧的dist_dir，将build_dir递归拷贝为最终分发目录；
2. 写入local.properties（sdk.dir=<sdk_dir>）；
3. 调用distribute_javaclasses()拷贝 Java 类到src/main/java；
4. 对每个架构调用_assemble_distribution_for_arch(arch)：拷贝.so库、解包 AAR、创建 Python bundle（_python_bundle__<arch>_python_bundle）、按需 strip 调试符号（strip_libraries）、"煎熟"egg（fry_eggs）；
5. 若未启用sqlite3recipe，则向blacklist.txt追加排除规则；
6. 调用_copy_in_final_files()（SDL 系列会从 SDL recipe 的 JNI 构建目录拷贝官方org.libsdl.appJava 源码）并保存分发元信息。

_assemble_distribution_for_arch默认实现适用于绝大多数后端；需要按架构定制时只需重写该方法，_sdl_common中的SDLGradleBootstrap就是范例——它跳过distribute_aars()，因为 SDL 的 AAR 以不同方式处理（见 _sdl_common/init.py）。

4.4 注册与获取：get_bootstrap

get_bootstrap(name, ctx)是访问 bootstrap 类的唯一入口：它通过importlib动态导入pythonforandroid.bootstraps.<name>模块，读取模块级变量bootstrap，并为其设置bootstrap_dir与ctx（见 bootstrap.py）。这也解释了为什么每个后端模块末尾都有一行bootstrap = XxxBootstrap()。

五、Bootstrap 如何被自动选择

当用户没有显式指定--bootstrap时，p4a 会根据所选 recipes 自动挑选合适的后端，逻辑集中在get_bootstrap_from_recipes()（见 bootstrap.py）：

1. 候选过滤：get_usable_bootstraps_for_recipes()先排除can_be_chosen_automatically = False的后端，再检查 bootstrap 依赖与用户 recipes 之间是否存在conflicts冲突（见 bootstrap.py）。
2. 特殊规则优先：依赖中含sdl2则选sdl2；含sdl3则选sdl3；含已知 Web 包（如flask，见known_web_packages）则优先选webview。
3. 默认优先级兜底：若以上规则都不命中，按default_recipe_priorities = ["webview", "sdl2", "sdl3", "service_only"]排序取最高优先级，其中service_only是"没有图形库/Web 库"时的最合理猜测（见 bootstrap.py）。排序由_cmp_bootstraps_by_priority()实现，同级时按名称字母序保证确定性。

六、如何创建自己的 Bootstrap

官方文档给出的建议路径非常明确："最好的资源是查看 p4a 源码中现有的实现"。结合前三节的分析，一个完整的自定义 bootstrap 需要做四件事：

6.1 建目录、写模块

在 pythonforandroid/bootstraps/ 下新建目录<yourname>/，其中必须包含__init__.py，内容如下骨架：

from pythonforandroid.toolchain import Bootstrap, shprint, current_directory, info, info_main, which from os.path import join, exists import sh class MyBootstrap(Bootstrap): name = 'yourname' # 与目录名一致 recipe_depends = ['python3'] # 至少要含 python3 / android # can_be_chosen_automatically = True # 默认即可被自动选择 def assemble_distribution(self): info_main("# Creating Android project using yourname bootstrap") # 1. 清空并拷贝 build 模板到 dist_dir # 2. 拷贝 recipes 产物（.so / aar / javaclasses） # 3. 生成 _python_bundle，strip / fry_eggs # 4. 写入 local.properties / project.properties bootstrap = MyBootstrap() # 模块级实例，供 get_bootstrap 读取

6.2 准备build/模板目录

在pythonforandroid/bootstraps/<yourname>/build/下放置 Gradle 工程模板（build.gradle、src/main/java、jni/Android.mk等）。公共文件优先放在common/build/（该目录现有gradlew、gradle/wrapper、templates/等通用资产，见 common/build），你的后端只放差异化内容，prepare_build_dir会按"公共 → 父类 → 自身"顺序累积合并。

6.3 复用基类分发方法

装配阶段优先复用基类提供的distribute_libs()、distribute_aars()、distribute_javaclasses()、strip_libraries()、fry_eggs()等现成方法（见 bootstrap.py），仅在确有差异时重写_assemble_distribution_for_arch或整个assemble_distribution——qt后端是整体重写、_sdl_common是按架构重写的两个参考范例。

6.4 测试与联系维护者

仓库的测试套件中，tests/test_bootstrap.py 与 tests/test_bootstrap_build.py 覆盖了 bootstrap 选择与构建相关逻辑，可作为新后端的回归参考。若在实现中遇到问题，可参考官方文档 doc/source/troubleshooting.rst 中的联系方式求助开发者。

七、与相关文档的衔接

• 已有 bootstrap 的构建选项：本文聚焦"如何写新 bootstrap"；对 SDL2、Webview 等现有后端的构建参数（如--window、--orientation等），请查阅 doc/source/buildoptions.rst。
• Kivy 3 应用契约：若你的 bootstrap 要运行 Kivy 3 应用，还必须满足 doc/source/kivy_bootstrap.rst 描述的 Kivy bootstrap 契约（如python_launcher相关的约定）。
• 构建选项详解：完整的命令行与buildozer.spec对应关系可继续阅读 doc/source/buildoptions.rst。

结语

Bootstrap 是 python-for-android 最具扩展性的设计之一：它把"Android 工程装配"抽象为"一个类 + 一套模板目录 + 若干分发方法"。理解name、recipe_depends与装配方法三者的分工，再对照sdl2、webview、qt等现有实现，即可按 pythonforandroid/bootstraps/ 目录下的既有模式快速搭建属于自己的 Android 构建后端，让任意 Python 项目类型都能被 p4a 打成一个可运行的 APK。

• 开发工具
• 构建工具
• 移动开发