python-for-android 命令行完全指南：toolchain.py 全部命令与参数详解

开发工具构建工具移动开发【免费下载链接】python-for-androidTurn your Python application into an Android APK项目地址https://gitcode.com/gh_mirrors/py/python-for-android点击查看免费下载本篇指南以 python-for-androidp4a官方文档 doc/source/commands.rst 为骨架系统讲解所有可以传递给toolchain.py的命令与选项。你将掌握p4a 的通用参数SDK/NDK/API 定位与 Distribution 参数名称、依赖、架构、Bootstrap如何共同决定一次 Android 构建以及create、apk、aab、recipes、clean等全部子命令的语义与典型用法。文中所有细节均与当前仓库源码一一对应可直接用于日常打包与排障。一、命令体系总览ToolchainCL 与命令行入口python-for-android 的核心 CLI 定义在 pythonforandroid/toolchain.py 中ToolchainCL类负责解析参数并分发命令。按官方文档的说法本页记录了所有可以传递给toolchain.py的命令与选项。可用命令即ToolchainCL类的方法下文逐一说明。每个命令可能拥有自己的专属选项也可以随时向任何命令传递通用参数general arguments或Distribution 参数distribution arguments——即使某些参数对该命令无意义也只是不起作用而已不会被拒绝。入口方式命令行入口p4a等价于执行python -m pythonforandroid.toolchain。入口逻辑在 pythonforandroid/entrypoints.py 的main()中先调用check_python_version()当前仓库要求 Python ≥ 3.10见 recommendations.py随后实例化ToolchainCL()。-v/--version打印 p4a 版本号来自pythonforandroid.__version__。不传任何子命令直接打印帮助信息并以状态码 1 退出见 toolchain.py。.p4a配置文件ToolchainCL初始化时会读取当前目录下的.p4a文件把其中每一行按 shell 规则切分后追加到命令行参数中#开头的行视为注释被忽略见_read_configurationtoolchain.py。这意味着你可以把常用的--sdk-dir、--arch等参数固化到.p4a里。完整命令列表从 toolchain.py 的子命令注册可见当前仓库支持以下命令括号内为别名命令别名作用recommendations—列出 p4a 推荐的依赖版本SDK/NDK/APIrecipes—列出可用 recipe 及依赖关系bootstraps—列出可用 bootstrapcreate—将一组 requirements 编译为一个 distapk/aar/aab—打包生成 APK / AAR / AABexport_distexport-dist把已构建的 dist 复制或软链到指定目录archs—列出可构建的目标架构distributionsdists列出当前已编译完成的 distdelete_distdelete-dist删除一个已编译的 distclean_allclean-all删除所有构建产物、dist 与缓存clean_distsclean-dists删除所有 distclean_buildsclean-builds删除所有 recipe 构建缓存clean_bootstrap_buildsclean-bootstrap-builds删除所有 bootstrap 构建clean—按组件批量清理all/builds/dists/…clean_recipe_buildclean-recipe-build删除指定 recipe 的构建产物clean_download_cacheclean-download-cache删除下载缓存sdk_toolssdk-tools调用 SDK tools 目录下的二进制工具adb—调用 SDK 中的 adblogcat—调用adb logcatbuild_statusbuild-status打印当前已构建组件的调试信息注意子命令通过args.subparser_name.replace(-, _)映射到同名方法toolchain.py因此带连字符的别名如clean-all与下划线写法如clean_all完全等价。二、通用参数General arguments官方文档指出通用参数可以传给任何命令以修改其行为但并非所有命令都会用到。以下先介绍文档列出的四个核心参数再补充源码中注册的其他通用参数。--debug打印构建过程的额外调试信息包括全部编译输出。在源码中--debug是一个store_true开关默认False一旦启用就把日志级别设置为logging.DEBUGtoolchain.py 与 toolchain.py。构建失败需要查看完整编译日志时这是最常用的排障开关。--sdk_dirAndroid SDK 的安装路径。文档强调可以用多种其他方式设置源码中的实际查找顺序如下见 build.py 的prepare_build_environment--sdk-dir/--sdk_dir命令行参数两者均被注册见 toolchain.py环境变量ANDROIDSDK旧式 p4a 专用变量环境变量ANDROID_HOME更通用的惯例回退扫描~/.buildozer/android/platform/android-sdk-*仅为调试便利官方建议自己维护 SDK 下载均未找到则抛出BuildInterruptingException(Android SDK dir was not specified, exiting.)。--android_api要构建的 Android API level。p4a 会检查该 level 的 platform tools 是否已安装。源码中该参数类型为int默认值为 0实际默认取 recommendations.py 中定义的RECOMMENDED_TARGET_API 33。查找顺序为--android-api命令行参数 → 环境变量ANDROIDAPI→ 默认 33见 build.py。随后会调用get_available_apis(sdk_dir)核对 SDK 中是否安装了对应平台若未安装会提示用 SDK 的 android 工具安装build.py。需要注意两个边界约束来自 recommendations.pyMIN_TARGET_API 30低于 30 的目标 API 已不受 Google Play 支持p4a 会给出警告目标 API 可以高于设备系统版本且通常应尽量取高。ARMEABI_MAX_TARGET_API 21构建armeabiARMv5时目标 API 不得超过 21否则直接报错并建议改用--archarmeabi-v7a。--ndk_dirAndroid NDK 的安装路径同样支持多种设置方式。查找顺序build.py--ndk-dir/--ndk_dir命令行参数环境变量ANDROIDNDK旧式 p4a 专用变量环境变量NDK_HOME最常见的惯例环境变量ANDROID_NDK_HOMEMaven 相关惯例回退扫描~/.buildozer/android/platform/android-ndk-r*均未找到则抛出BuildInterruptingException(Android NDK dir was not specified)。找到 NDK 目录后还会调用check_ndk_version()校验版本recommendations.py当前仓库要求 NDK 主版本 ≥ 25推荐版本为28c常量RECOMMENDED_NDK_VERSION 28c高于MAX_NDK_VERSION 25会警告新版 NDK 可能未被完整支持。--ndk_versionNDK 的版本号。文档特别强调内部构建工具的文件路径依赖此版本因此很重要。但也可以不手动设置——只要 NDK 目录中存在RELEASE.TXT现代 NDK 是source.properties包含版本信息p4a 会自动读取。在源码中该参数已被标记为DEPRECATEDtoolchain.py传入的值会被忽略并打印弃用警告warn_on_deprecated_argstoolchain.py。版本现在完全自动从 NDK 目录的source.properties中读取Pkg.Revision字段解析得到见read_ndk_versionrecommendations.py。其他通用参数源码补充除文档列出的四个外generic_parser还注册了以下常用通用参数均可传给任何命令参数说明依据 toolchain.py--color {always,never,auto}控制彩色输出默认在 tty 上启用--ndk-api编译目标的最小 APIminimal supported API通常不等于--android-api默认取min(ANDROID_API, 24)RECOMMENDED_NDK_API 24也可用环境变量NDKAPI设置它必须低于目标 Android API且不得低于 21见 build.py--storage-dir下载与构建的主存储目录默认user_data_dir(python-for-android)若路径含空格则退回~/.python-for-android--symlink-bootstrap-files对 bootstrap 文件使用符号链接仅供开发调试可能引发奇怪问题--arch构建架构可多次指定见下文 Distribution 参数--extra-index-url额外的 wheel 包索引可多次指定用于寻找预编译的 Android wheel--skip-prebuilt一律从源码构建不使用预编译 wheel--use-prebuilt-version-for对这些包忽略锁定的版本、优先使用额外索引中的最新预编译版本仅对有 recipe 的包生效--save-wheel-dirPyProjectRecipe 构建出的 wheel 的保存目录--local-recipes/--local_recipes本地 recipe 查找目录默认./p4a-recipes--activity-class-name主 Activity 的完整 Java 类名默认org.kivy.android.PythonActivity--service-class-namePythonService 类的完整包名默认org.kivy.android.PythonService--java-build-tool {auto,ant,gradle}打包 APK 时使用的 Java 构建工具默认auto自动选择--copy-libs复制库文件而非使用 biglinkAndroid 4.3 场景--hook指向一个包含 p4a 钩子的模块文件before_apk_build、after_apk_build、before_apk_assemble、after_apk_assemble等钩子点见 toolchain.py--use-setup-py处理项目中存在的setup.py实验性未来将成为默认--ignore-setup-py忽略项目中存在的setup.py当前默认行为当项目含 setup.py 且两个开关都未显式给出时会打印未来行为变更警告见 toolchain.py三、Distribution 参数指定你要构建的 Android 发行版p4a 提供若干参数用于指定使用哪个已编译的 Android distributiondist。文档原文强调你可以向任何命令传递这些参数一旦某个命令需要 dist这些参数就会用于加载、编译或下载它。这些选项都不是必须的原则上你只需要提供自己需要的那几个。dist 的装载/创建逻辑集中在 pythonforandroid/distribution.py 的Distribution.get_distribution()由dist_from_args调用见 toolchain.py其入参正好对应以下参数。--name NAMEDistribution 的名称。同一名称只能存在一个 dist同名时依据--allow-replace-dist决定是否自动替换。命令行中实际注册的是--dist-name/--dist_name默认空字符串见 toolchain.py文档中的--name即指此参数。--requirements LIST,OF,REQUIREMENTS你的 dist 必须包含的 recipe以逗号分隔的列表形式给出。列表项可以是recipe 名称仓库内置 recipe 见 pythonforandroid/recipes/ 目录如python3、kivy、numpy、sqlalchemyPython 模块的 PyPI 名称纯 Python 包会被自动支持。源码解析细节toolchain.py使用split_argument_list按空格或逗号切分re.split(r[ ,], arg_list)toolchain.py支持名称版本的版本钉扎语法例如--requirements python33.11.0,kivyp4a 会把版本写入环境变量VERSION_recipe如VERSION_python3recipe 构建时据此选择版本若项目根目录存在setup.py且启用了--use-setup-pyp4a 会解析其依赖把其中与内置 recipe 名称匹配的依赖自动追加到 requirements 中这一分析可能耗时较长。--force-build BOOL是否必须从零编译该 dist。在源码中通过add_boolean_option注册为一对开关--force-build默认False与--no-force-buildtoolchain.py。开启后即使存在满足条件的 dist 也会强制重建。--arch要构建的架构可以同时多次指定。例如p4a ... --arch arm64-v8a --arch armeabi-v7a ...会同时为arm64-v8a与armeabi-v7a两个架构构建。源码中--arch使用actionappendtoolchain.py收集后通过ctx.set_archs(self._archs)注入构建上下文toolchain.py。可用架构由 pythonforandroid/archs.py 定义运行p4a archs可实时查看架构对应类三元组前缀典型 cflagsarmeabi-v7aArchARMv7_aarm-linux-androideabitarget 为armv7a-...-marcharmv7-a -mfloat-abisoftfp -mfpuvfp -mthumb -fPICarm64-v8aArchAarch_64aarch64-linux-android-marcharmv8-a -fPICx86Archx86i686-linux-android-marchi686 -mssse3 -mfpmathsse -m32 -fPICx86_64Archx86_64x86_64-linux-android-marchx86-64 -msse4.2 -mpopcnt -m64 -fPIC另有ArchARM基类对应的armeabi但受限于最大目标 API 21实践中应优先使用armeabi-v7a。--bootstrap BOOTSTRAP应用使用的 Java bootstrap。文档明确说明大多数情况下你无需关心、也不必手动设置它因为 p4a 会根据你的--requirements自动选择合适的一个。当前可选值是sdl2用于 Kivy 及大多数应用、webview或qt。bootstrap 的自动选择逻辑在 pythonforandroid/bootstrap.py 的Bootstrap.get_bootstrap_from_recipes()与 pythonforandroid/graph.py 的get_recipe_order_and_bootstrap()中完成。除文档提到的三种外从 pythonforandroid/bootstraps/ 目录看仓库还内置了sdl3、service_only、service_library、empty等 bootstrap如p4a bootstraps命令所列。典型对应关系Kivy/SDL 应用用sdl2或sdl3WebView Python 后端用webviewQt/PySide6 应用用qt。与 dist 装载相关的其他参数源码补充--require-perfect-match默认False要求 dist 的 recipe 与请求完全一致才复用否则视为不匹配--allow-replace-dist默认True允许自动替换同名已有 dist--recipe-blacklist/--blacklist-requirements将一个内部 recipe 加入黑名单可用于禁用 Python 3 核心模块以减小体积构建时黑名单在build_dist_from_args中按逗号切分并传入toolchain.py。四、命令详解以下按 toolchain.py 中每个方法的文档字符串与实现逐一说明。p4a recommendations列出 p4a 推荐的依赖版本。实现即print_recommendations()recommendations.py输出形式为简单的键值对Min supported NDK version: 25 Recommended NDK version: 28c Min target API: 30 Recommended target API: 33 Min NDK API: 21 Recommended NDK API: 24首次配置环境前运行此命令可以快速确认自己的 SDK/NDK/API 组合是否落在推荐区间。p4a recipes打印所有可用 recipe 的基本信息例如方法 docstring 中的示例python3 3.7.1 depends: [hostpython3, sqlite3, openssl, libffi] conflicts: [] optional depends: [sqlite3, libffi, openssl]实现遍历Recipe.list_recipes()逐一对每个 recipe 输出名称、版本、depends依赖、conflicts冲突红色、optional depends可选依赖黄色toolchain.py。可选参数--compact输出仅包含 recipe 名称的空格分隔列表适合脚本消费例如p4a recipes --compact | tr \n。p4a bootstraps列出所有可用的 bootstrap并显示每个 bootstrap 的dependsrecipe 依赖实现见 toolchain.py。p4a create若 distribution 目录尚不存在则创建之必要时运行各 recipe并构建 apk。源码中该方法体为pass——所有工作由require_prebuilt_dist装饰器完成toolchain.py。装饰器的逻辑toolchain.py是设置架构并准备构建环境SDK/NDK/API 定位由 Distribution 参数得到 dist 对象若dist.needs_build为真则调用build_dist_from_args()完成构建解析 bootstrap → 通过get_recipe_order_and_bootstrap计算 recipe 构建顺序与 pip 模块列表 →build_recipes()编译 →ctx.bootstrap.assemble_distribution()组装 disttoolchain.py。典型用法仓库自带示例应用可参考 testapps/on_device_unit_tests/buildozer.spec 与 testapps/testapp_sqlite_openssl/main.pyp4a create --requirements python3,kivy \ --arch arm64-v8a --arch armeabi-v7a \ --bootstrap sdl2p4a apk/p4a aar/p4a aab构建 APK / AAR / AAB 包。三者共享一组打包参数parser_packagingtoolchain.py内部都走_build_package()_finish_package()--private DIR应用源码目录包含main.py入口点会被传递给内部 bootstrap 的 build.py--add-asset PATH[:DEST]把文件放入 APK 的 assets 目录--asset透传--add-resource PATH[:DEST]把文件放入 APK 的 res 目录--resource透传--release构建发布版默认是debug会禁用 gdb 调试等AAB 仅支持 releasedebug 模式下构建 aab 会直接报错toolchain.py--with-debug-symbols保留.so文件中的调试符号--keystore/--signkey/--keystorepw/--signkeypwrelease 构建的 JAR 签名密钥、别名与口令经_prepare_release_env映射为P4A_RELEASE_KEYSTORE、P4A_RELEASE_KEYALIAS、P4A_RELEASE_KEYSTORE_PASSWD、P4A_RELEASE_KEYALIAS_PASSWD环境变量见 toolchain.py。底层构建流程toolchain.py在 dist 目录中加载并解析build.py把未知参数透传过去检测 SDKbuild-tools要求最高可用版本 ≥ 25.0通过./gradlew clean Gradle 任务完成构建debug 模式为assembleDebugrelease 的 apk/aar 为assembleReleaserelease 的 aab 为bundleRelease从 Gradle 输出中解析包文件路径重命名为原名-版本号.{apk,aar,aab}并复制到当前目录_finish_packagetoolchain.py。示例Kivy 应用打包可参考仓库 pythonforandroid/bootstraps/sdl2/init.py 对应 bootstrap 的使用p4a apk --private ./myapp \ --requirements python3,kivy \ --arch arm64-v8a \ --bootstrap sdl2p4a export_dist OUTPUT_DIR把已构建的 dist 复制或符号链接到指定输出目录便于直接进入 dist 目录检查产物或手动调用 build.pytoolchain.py。可选参数--symlink以软链代替复制。注意若没有匹配的 dist 会直接报错需要先用create构建。p4a archs列出可构建的目标架构见上文架构表实现见 toolchain.py。p4a distributions别名dists列出当前已编译完成的全部 dist通过Distribution.get_distributions(ctx)获取并以pretty_log_dists打印若无 dist 则提示当前没有任何已构建的 disttoolchain.py。p4a delete_dist按当前 Distribution 参数删除匹配的 dist若不存在匹配项则提示并退出toolchain.py。p4a clean与清理家族清理命令家族对应方法与实现位置如下p4a clean_allclean-all依次清理 dists、builds 与下载缓存即全部清空toolchain.pyp4a clean_distsclean-dists删除内部 dist 目录中的所有已编译发行版toolchain.pyp4a clean_buildsclean-builds删除各 recipe 的构建缓存、python-install、Java 代码与已收集的编译库不删除下载缓存与最终 disttoolchain.pyp4a clean_bootstrap_buildsclean-bootstrap-builds删除build_dir/bootstrap_buildstoolchain.pyp4a clean COMPONENT...按组件批量清理合法组件为all、builds、dists、distributions、bootstrap_builds、downloads可一次传多个非法组件名会抛出BuildInterruptingExceptiontoolchain.pyp4a clean_recipe_build RECIPE [--no-clean-dists]删除指定 recipe 的构建文件供调试使用默认同时删除 dists传--no-clean-dists可保留toolchain.py。注意部分 recipe 的构建可能产生意外状态变更若清理后异常可继续清理其他 recipe 或直接clean_buildsp4a clean_download_cache [RECIPES...]删除指定 recipe 的下载缓存不传参数则清空全部缓存例如p4a clean_download_cache kivy,pyjnius按空格分隔传多个 recipe 名即可。不删除构建缓存与最终 disttoolchain.py。p4a sdk_tools TOOL从检测到的 SDK 目录运行指定二进制工具如avdmanager、android并把其余参数原样透传适合 SDK 工具不在$PATH时的便捷调用toolchain.py。p4a adb/p4a logcatp4a adb ...从 SDK 的platform-tools调用adbWindows 下为adb.exe参数原样透传toolchain.pyp4a logcat ...等价于p4a adb logcat ...用于查看设备日志toolchain.py。p4a build_status打印当前构建组件的状态哪些 bootstrap 的核心组件可能已构建来自build_dir/bootstrap_builds哪些 recipe 可能已构建来自build_dir/other_builds按名称-依赖1-依赖2的目录命名解析见 toolchain.py。五、从源码理解一次构建的完整链路把前三节的参数串起来一次典型 p4a 构建的生命周期是入口与参数装载entrypoints.main()校验 Python 版本 →ToolchainCL.__init__读取.p4a配置、注册所有子命令、解析通用参数与 Distribution 参数toolchain.py。环境准备ctx.prepare_build_environment()按上文顺序解析 SDK/NDK/API并检查 NDK 版本、目标 API 与 NDK API 的合法性build.py。dist 解析dist_from_args()把--dist-name、--requirements、--arch、--ndk-api、--force-build、--require-perfect-match、--allow-replace-dist组装成Distribution.get_distribution()调用toolchain.py。按需构建 distrequire_prebuilt_dist装饰器判断dist.needs_build需要时触发build_dist_from_args()选择/自动推导 bootstrap →get_recipe_order_and_bootstrap计算构建顺序 →build_recipes()编译 recipe 与 pip 模块 →assemble_distribution()toolchain.py。打包apk/aar/aab命令进入 dist 目录调用 Gradle产物带版本号复制回当前目录。六、实用组合示例查看推荐环境版本p4a recommendations查看可用 recipe 与架构p4a recipes --compact p4a archs完整构建并打包一个 Kivy 应用debug 版p4a apk \ --private ./myapp \ --requirements python33.11.0,kivy \ --arch arm64-v8a \ --bootstrap sdl2 \ --debugrelease 签名打包p4a apk --release \ --private ./myapp \ --requirements python3,kivy \ --arch arm64-v8a \ --bootstrap sdl2 \ --keystore ./my-release.keystore --signkey myalias \ --keystorepw ******** --signkeypw ********清理与调试p4a clean_dists # 只清 dist p4a clean builds dists # 批量清理构建缓存与 dist p4a clean_recipe_build kivy --no-clean-dists # 单独重编 kivy recipe p4a clean_download_cache python3 openssl # 只清指定下载缓存 p4a logcat # 查看设备日志七、总结python-for-android 的命令行体系可以概括为一句话通用参数决定用什么环境编译SDK/NDK/APIDistribution 参数决定编译成什么名称、依赖、架构、bootstrap具体命令决定做什么create/apk/aab/clean/…。官方文档 doc/source/commands.rst 是这一体系的权威索引而 pythonforandroid/toolchain.py 则是其唯一实现来源——任何参数的默认值、查找顺序与边界约束都可以在该文件及其引用的 build.py、recommendations.py、archs.py、distribution.py 中直接验证。掌握这些命令与参数你就拥有了对 p4a 构建过程从环境定位到产物输出的完整控制力。赞分享开发工具构建工具移动开发【免费下载链接】python-for-androidTurn your Python application into an Android APK项目地址https://gitcode.com/gh_mirrors/py/python-for-android点击查看免费下载相关推荐Trippy 命令行完全指南trip 命令参考与实战参数详解Trippy 命令行完全指南trip 命令参考与实战参数详解 Trippy命令名 trip 是一款用 Rust 编写的网络诊断工具以现代 tracero网络CLI运维kimi 命令完全指南Kimi Code CLI 全部参数、子命令与运行模式详解kimi 命令完全指南Kimi Code CLI 全部参数、子命令与运行模式详解 kimi 是 Kimi Code CLI 的入口命令用于启动交互式会话或执人工智能AI Agent代码智能体交互助手CLI工具调用Seclogon服务滥用NanoDump中的本地和远程句柄泄露技术Seclogon服务滥用NanoDump中的本地和远程句柄泄露技术 NanoDump作为一款功能强大的LSASS转储工具提供了多种创新技术来获取Window上一篇Manba项目常见问题解决方案下一篇开源项目 gliderlabs/ssh 常见问题解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考