Termux Packages 构建系统完全指南：从包配方到多仓库发布机制

Termux Packages 构建系统完全指南从包配方到多仓库发布机制【免费下载链接】termux-packagesA package build system for Termux.项目地址: https://gitcode.com/GitHub_Trending/te/termux-packages本篇技术指南以 README.md 为核心脉络系统讲解 Termux 官方软件包构建系统 termux-packages 的整体架构、仓库布局、包配方package recipe编写规范与多仓库发布机制。你将掌握如何阅读build.sh配方、理解 packages / x11-packages / root-packages 三类仓库的划分逻辑、按打包政策提交新包以及版本更新、补丁制作、重建与降级等完整实操流程。项目定位为 Termux 构建 Android 软件包termux-packages是一个为 Termux Android 应用构建软件包的脚本与补丁集合。正如 README.md 所述它不直接提供软件本体而是提供一整套“把开源软件编译成可在 Termux 环境运行的.deb包”的自动化工程——包括每个包的构建配方、针对 Android 环境的补丁、NDK 补丁以及 Docker 构建环境。值得强调的是Termux 并非标准 Linux 平台所有软件均由 Android NDK 编译且 Android尤其是 Termux存在大量与传统 FHSFilesystem Hierarchy Standard不同的路径约定因此仓库中的包配方不能简单照搬主流发行版的打包方式详见 CONTRIBUTING.md 中 “Working with packages” 一节。仓库结构四大包目录与支撑目录从仓库根目录可以清楚看到构建系统的组织方式目录用途packages/主仓库termux-main的包配方面向普通非 root 用户数量超过 1000 个x11-packages/图形界面X11 / Wayland相关包的配方对应 termux-x11 仓库root-packages/需要 root 权限或依赖 SELinux permissive 模式、自定义固件的包对应 termux-root 仓库disabled-packages/因构建失败、上游废弃等原因被禁用的包配方存档ndk-patches/对 Android NDK 头文件与库的修正补丁如langinfo.h、libintl.hscripts/构建系统核心脚本、Docker 环境与各类辅助工具sample/新包配方的骨架模板repo.json定义各软件源仓库的元数据名称、发行版、组件、URLrepo.json三个软件源的元数据定义repo.json 是理解“多仓库机制”的关键配置文件它声明了三个独立的 APT 软件源{ pkg_format: debian, packages: { name: termux-main, distribution: stable, component: main, url: https://packages-cf.termux.dev/apt/termux-main }, root-packages: { name: termux-root, distribution: root, component: stable, url: https://packages-cf.termux.dev/apt/termux-root }, x11-packages: { name: termux-x11, distribution: x11, component: main, url: https://packages-cf.termux.dev/apt/termux-x11 } }三个仓库分别对应packages/、root-packages/、x11-packages/三个目录包格式统一为 Debian.deb通过 APT 系列工具apt/pkg安装管理。这种划分使得“普通终端工具”“需要 root 的软件”“图形界面软件”三类内容互不干扰也与 CONTRIBUTING.md 中“Termux 主要面向非 root 使用”的设计原则一致。一个真实配方示例hello每个包通过./packages/name/build.sh定义文件名即包名。以 packages/hello/build.sh 为例TERMUX_PKG_HOMEPAGEhttps://www.gnu.org/software/hello/ TERMUX_PKG_DESCRIPTIONPrints a friendly greeting TERMUX_PKG_LICENSEGPL-3.0 TERMUX_PKG_MAINTAINERtermux TERMUX_PKG_VERSION2.12.3 TERMUX_PKG_REVISION1 TERMUX_PKG_SRCURLhttps://mirrors.kernel.org/gnu/hello/hello-${TERMUX_PKG_VERSION}.tar.gz TERMUX_PKG_SHA2560d5f60154382fee10b114a1c34e785d8b1f492073ae2d3a6f7b147687b366aa0 TERMUX_PKG_DEPENDSlibiconv TERMUX_PKG_AUTO_UPDATEtrue TERMUX_PKG_BUILD_IN_SRCtrue termux_step_pre_configure() { LDFLAGS -liconv }该配方展示了核心变量版本、源码 URL、SHA-256 校验和、运行时依赖以及termux_step_pre_configure()函数对默认构建步骤的覆写——这里在链接阶段追加-liconv。构建脚本 build-package.sh 会按预定义步骤执行下载、校验、打补丁、配置、编译、打包全流程。包配方 build.sh 核心变量速查CONTRIBUTING.md 的 “Basics” 一节给出了最小配方模板TERMUX_PKG_HOMEPAGEhttps://example.com TERMUX_PKG_DESCRIPTIONTermux package TERMUX_PKG_LICENSEGPL-3.0 TERMUX_PKG_MAINTAINERgithub TERMUX_PKG_VERSION1.0 TERMUX_PKG_SRCURLhttps://example.com/sources-${TERMUX_PKG_VERSION}.tar.gz TERMUX_PKG_SHA2560000000000000000000000000000000000000000000000000000000000000000 TERMUX_PKG_DEPENDSlibiconv, ncurses各变量含义与约束如下TERMUX_PKG_VERSION版本号必须以数字开头只能包含.、-、仅在指定 epoch 时允许冒号如1:2.6.0。若使用特定 Git 提交则必须用YYYY.MM.DD或YYYYMMDD格式的提交日期作为版本严禁用 Git hash 或分支名。TERMUX_PKG_SRCURL只能指向官方源码包且必须保证与TERMUX_PKG_VERSION、TERMUX_PKG_SHA256严格对应。不要硬编码版本号应通过${TERMUX_PKG_VERSION}变量引用Bash 的切片语法可用于处理带 epoch 的版本例如${TERMUX_PKG_VERSION:2}。TERMUX_PKG_SHA256源码包的 SHA-256 校验和构建系统会下载后校验防止内容与版本不匹配。TERMUX_PKG_DEPENDS仅包含运行时依赖。所有仅构建期需要的依赖如静态库应放入TERMUX_PKG_BUILD_DEPENDS。常见构建工具autoconf、automake、bison、clang、ndk-sysroot等无需也不能写进依赖。TERMUX_PKG_LICENSE使用 SPDX 标识符或以逗号分隔多个许可证特殊值custom、non-free可用。TERMUX_PKG_BUILD_IN_SRCtrue仅支持源码树内构建的项目如纯 Makefile 项目启用。TERMUX_PKG_PLATFORM_INDEPENDENTtrue标记平台无关包可在任意 CPU 架构设备上运行。TERMUX_PKG_REVISION版本不变时的重建序号详见下文“重建”一节。TERMUX_PKG_MAINTAINER维护者标识惯例为用户名格式。子包拆分sample 模板大型包可拆分为多个子包。sample/sample-sub.subpackage.sh 提供了子包配方的骨架只需重命名并填写TERMUX_SUBPKG_DESCRIPTION TERMUX_SUBPKG_INCLUDE其中TERMUX_SUBPKG_INCLUDE指定子包应包含的文件列表用于把文档、开发头文件、独立二进制等拆到不同子包缩小主包体积。Termux 路径约定与补丁中的占位符Android 上不存在标准 FHS 路径Termux 使用带前缀的虚拟 rootfs。补丁中凡涉及以下路径都必须使用占位符补丁在应用前会做预处理替换原路径替换为前缀/usr等TERMUX_PREFIX即/data/data/com.termux/files/usr家目录/homeTERMUX_HOME即/data/data/com.termux/files/home/runTERMUX_PREFIX/var/run/sbinTERMUX_PREFIX/bin源码常硬编码的/bin、/etc、/home、/run、/sbin、/tmp、/usr、/var这些路径在 Termux 中均不存在必须通过补丁替换为上述带前缀的等价路径。补丁制作规范使用 git diff 生成补丁推荐按 CONTRIBUTING.md 的指引大多数情况下用git diff生成补丁更简单# 1. 克隆上游源码仓库 git clone https://github.com/curl/curl # 2. 检出最新发布标签可用 git describe 查看最近标签 cd curl git describe git checkout curl-8_12_1 # 3. 修改源码 vim sourcefile.c # 4. 生成补丁文件 git diff /path/to/package-build/example.patch若一次制作多个补丁建议保存一个补丁后执行git reset HEAD --hard或将文件/目录名作为参数传给git diff以限制范围避免不同补丁内容重叠。使用 GNU diff 生成补丁对于不使用 Git 或对发布包有额外改动的项目可退回到diff -uNrcd ./packages/your-package (source build.sh 2/dev/null; curl -LO $TERMUX_PKG_SRCURL) tar xf package-1.0.tar.gz cp -a package-1.0 package-1.0.mod cd package-1.0.mod vim sourcefile.c cd .. diff -uNr package-1.0 package-1.0.mod very-nice-improvement.patch补丁文件命名应自描述让人一眼看出修了什么且每项修改建议单独存放一个补丁文件。整个仓库中遍布的*.patch文件如 packages/htop/ 等目录下即为这套规范的实际产物。包版本更新流程常规更新大多数情况下更新包只需改几个变量并提交为TERMUX_PKG_VERSION赋新版本号注意不要误删 epoch 前缀如1:、2:。若存在TERMUX_PKG_REVISION变量则删除它revision 只在同一版本内多次构建时使用。下载源码并计算 SHA-256cd ./packages/${YOUR_PACKAGE} (source build.sh 2/dev/null; curl -LO $TERMUX_PKG_SRCURL)将新校验和写入TERMUX_PKG_SHA256。重建revision bump仅修改补丁或构建选项、版本号不变时需要定义或递增TERMUX_PKG_REVISION使包管理器识别为更新TERMUX_PKG_VERSION1.0 TERMUX_PKG_REVISION4TERMUX_PKG_REVISION应紧跟在TERMUX_PKG_VERSION下方。若版本号已更新则须删除该变量。例如 packages/hello/build.sh 中TERMUX_PKG_VERSION2.12.3配合TERMUX_PKG_REVISION1就是版本不变时重建的实例。降级与修改版本方案epoch需要降级包或改变版本方案时须设置或递增 epoch强制包管理器把新版本视为更新TERMUX_PKG_VERSION1:5.0.0若提交者不是 termux 协作成员提交降级 PR 必须附上理由说明无正当理由的降级会被拒绝。处理补丁失败上游大版本改动常导致旧补丁失效。可尝试若补丁修的是已知上游问题先检查上游 VCS 是否已修复——若已修复则该补丁可移除。检查失败补丁并手动应用修改仅在理解源码与补丁改动时进行再用diff -uNr package-1.0 package-1.0.mod 补丁文件.patch重新生成。常见构建错误No files in package. Maybe you need to run autoreconf -fi before configuring?构建系统找不到 Makefile。可尝试设置TERMUX_PKG_BUILD_IN_SRCtrue纯 Makefile 项目或在termux_step_pre_configure中运行./autogen.sh或autoreconf -fiAutotools 项目。No LICENSE file was installed for ...构建系统找不到许可证文件需通过TERMUX_PKG_LICENSE_FILE手动指定。打包政策新包入仓的准入标准CONTRIBUTING.md 明确列出了新包必须满足的条件任何提交 PR 前都应核对活跃且知名的项目主流 Linux 发行版中存在的软件更易被收录不接受过时、死亡或社区不活跃的项目。广泛认可的开放源码许可证Apache、BSD、GPL、MIT 等闭源、含二进制组件或 EULA 分发的软件不接收。不通过语言级包管理器安装能用cargo、cpan、dotnet tool、gem、npm、pip安装的模块不应打包Node.js、Perl、Ruby 模块的交叉编译尤为困难。体积限制成品包应小于 100 MiB。因为要同时为 aarch64、arm、i686、x86_64 四种 CPU 架构编译实际磁盘占用是单个.deb的 4 倍特殊例外需个别申请。功能不重复不接收与现有包功能重复的提交以免稀释有限的维护资源。拒绝破坏性功能不接受纯粹用于渗透测试、钓鱼、暴力破解、短信/电话轰炸、DDoS、OSINT 等破坏或侵犯隐私用途的包。补充规则独立的库包主要对开发者有价值除非作为其他包的依赖否则一般不打包需要 root、依赖 SELinux permissive 模式或自定义固件的包放入 root-packages/ 对应的 termux-root 仓库如arp-scan、bubblewrap、containerd等因为 Termux 主要面向非 root 使用若 root 功能干扰非 root 场景或引发构建问题维护者可能移除相关功能。不符合政策但有需求的包可提交到独立的用户仓库TUR。提交规范commit 消息格式与类型CONTRIBUTING.md 要求提交消息描述清楚改动对象与范围推荐格式commitType(repo/package): (改动摘要) [可选但强烈建议的详细说明] [Fixes (termux/repo)#issue number] [Closes (termux/repo)#pr number]其中repo为main、root或x11对应repo.json中三个仓库也可按去掉termux-前缀的包目录名确定。任何行不应超过 80 字符。常用的 commitType 包括类型含义addpkg(repo/package)新增包bump(repo/package)更新一个或多个包摘要应包含新版本号fix(repo/package)修复 Termux 特定 bugdwnpkg(repo/package)降级包需说明理由disable(repo/package)禁用包摘要应说明原因enhance(repo/package)启用此前未启用的功能chore不影响用户的家务性改动rebuild为链接新版共享库而重建如rebuild(deps:main/openssl): link against OpenSSL 3.0scripts(path/to/script)修改构建脚本等非配方内容ci(action_file_without_extension)修改 GitHub Actions 相关文件典型示例bump(main/nodejs): v18.2.0 dwnpkg(main/htop): v2.2.0 v3.x needs access to /proc/stat which is now restricted by Android enhance,bump(main/nodejs): v18.2.0 and use shared libuv构建系统支撑与脚本工具构建脚本体系构建的核心由 scripts/ 目录下的脚本驱动包括 Docker 构建环境Dockerfile、环境初始化setup-termux.sh、setup-ubuntu.sh、setup-archlinux.sh等、包列表工具与维护脚本list-packages.sh遍历packages/*逐个 source 各包build.sh输出包名(版本): 主页与描述——直接展示了“配方即数据”的读取方式。check-versions.sh、check-built-packages.py、lint-packages.sh版本检查、已构建包校验与配方静态检查。buildorder.py计算依赖构建顺序。run-docker.sh / run-docker.ps1在 Docker 中启动统一构建环境保证构建可复现。新包配方骨架提交新包时可参考 sample/ 中的模板sample-sub.subpackage.sh与sample.alternatives以及仓库内现有配方的写法build.sh中还可覆写termux_step_*系列步骤函数如 hello 配方中的termux_step_pre_configure以适配特殊构建流程。结语termux-packages 是一套完整、严谨的 Android 软件包构建工程通过build.sh配方声明元数据与构建行为借助统一的TERMUX_PKG_*变量体系和termux_step_*步骤钩子在 Docker 环境中将开源软件编译为 Debian 格式的.deb包并经由repo.json定义的 termux-main、termux-root、termux-x11 三个软件源向数百万用户分发。无论你是想了解 Termux 软件从源码到安装包的完整链路还是准备提交自己的第一个包配方都可以从 README.md 出发结合 CONTRIBUTING.md 的规范、repo.json 的仓库定义与 packages/ 中的真实配方逐步上手。【免费下载链接】termux-packagesA package build system for Termux.项目地址: https://gitcode.com/GitHub_Trending/te/termux-packages创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考