Termux 包仓库贡献指南：从打包规范到 build.sh 实战

Termux 包仓库贡献指南从打包规范到 build.sh 实战【免费下载链接】termux-packagesA package build system for Termux.项目地址: https://gitcode.com/GitHub_Trending/te/termux-packagesTermux 是一个构建在 Android 之上的开源终端环境其软件包全部由 termux-packages 仓库中的构建脚本与补丁产出。本文以仓库根目录的 CONTRIBUTING.md 为主体系统讲解如何向 Termux 提交新包、维护存量包、遵循打包策略、编写符合规范的build.sh与补丁并给出可对照源码验证的底层实现细节。读完本文你将掌握一条从提出包请求到合入一个合规 PR的完整路径。一、参与 Termux 项目的七条途径Termux 是开源项目但维护工作主要由维护者在业余时间完成因此只处理优先事项。社区贡献并非只有提交代码一种方式报告问题Reporting issues发现缺陷时让社区知晓。请做好问题不会立刻被解决的准备维护者会忽略诸如尽快解决急需方案之类的催促也不要翻旧帖、在早已关闭的 issue 里反复追问——先仔细阅读旧 issue很可能其中已有答案。注意两个边界只报告官方包内出现的问题第三方软件的问题会被忽略不接受针对旧版 TermuxAndroid 5.x/6.x的缺陷报告这些系统版本已被放弃支持。审查现有包的潜在问题包括未声明的依赖、未加前缀的硬编码 FHS 路径、崩溃等。若无法直接提交修复 PR可通过 issue 告知。修复已知 bug仓库 issue 中带bug report或help wanted标签的工单都在等待解决。提交新包大量package request工单尚未落地优先关注带help wanted标签的请求。保持存量包最新包不会自动更新需要有人更新构建脚本与补丁。托管包仓库镜像Termux 流量很大镜像能减轻主服务器压力、提升下载速度并消除单点故障。捐赠参见开发 Wiki 的 Donate 页面。二、如何请求一个新包在官方仓库找不到所需软件时可以提交package request类型的 issue。请求至少要提供包描述、主页以及源码仓库 URL。请注意请求不会立刻被处理且所请求的包必须符合下文打包策略。三、打包策略Packaging Policy仓库中已有上千个包需要持续维护。与主流发行版不同Termux 开发团队规模小、服务器磁盘空间有限。为保证服务质量被接受的包必须满足以下条件活跃且知名的项目主流 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。要点独立的库包主要对开发者有价值除非被其他包作为依赖引用否则默认不打包。这不是硬性规则而是为了保持仓库干净、内容对普通 Termux 用户有用。需要 root 权限、依赖 SELinux permissive 模式或自定义固件的包会被放入独立的 root apt 仓库其构建配方位于 root-packages 目录。请记住 Termux 主要为非 root 场景设计若 root 相关功能干扰非 root 使用或引发构建问题可能被移除。不符合上述策略的包可以提交到 Termux User RepositoryTUR。四、提交 Pull Request 的硬性要求贡献者需为自己的提交负全责。维护者可能帮你修复 PR 或给出建议但不等于替你完成全部工作。提交 PR 的最低要求具备 Linux 发行版使用经验Debian 优先Arch、Fedora 亦可具备从源码编译软件的经验有扎实的 shell 脚本能力已通读开发者 Wiki。如果你从未用过 Linux 发行版、或 Termux 是你接触的第一个 Linux 环境强烈建议不要提交 PR——低质量的工作会被拒绝。提交新包前务必自查打包策略违规的 PR 会被直接关闭不合并。也不要提交破坏性变更如无故回退提交、删除文件、制造垃圾内容这类 PR 的作者可能被禁止继续向 Termux 项目贡献。新包提交清单十个高频雷区1. 版本号格式版本号必须以数字开头除.点、-减号、加号外不应包含特殊字符冒号:仅用于指定 epoch。合法示例1.0、20201001、10a带 epoch 的示例1:2.6.0。2. 使用特定 Git commit 时若打包的是某个具体 commitTERMUX_PKG_VERSION必须包含提交日期格式为YYYY.MM.DD或YYYYMMDD。永远不要使用 Git hash、分支名等会破坏包管理器版本追踪的东西。3. 源码 URL 必须确定源码 URL 必须保证始终指向与TERMUX_PKG_VERSION及TERMUX_PKG_SHA256校验和匹配的内容。不要在 URL 中硬编码版本应通过变量引用Bash 支持切片等字符串操作TERMUX_PKG_VERSION1.0 TERMUX_PKG_SRCURLhttps://example.com/archive/package-${TERMUX_PKG_VERSION}.tar.gzTERMUX_PKG_VERSION5:4.11.3 TERMUX_PKG_SRCURLhttps://example.com/archive/package-${TERMUX_PKG_VERSION:2}.tar.gz第二个例子中${TERMUX_PKG_VERSION:2}会切掉前两个字符5:得到真实版本4.11.3。4. 依赖不要列出通用构建工具autoconf、automake、bison、clang、ndk-sysroot等常见构建工具不应出现在包依赖中。5. 依赖区分构建期与运行期TERMUX_PKG_DEPENDS只应包含运行期需要的依赖仅构建期使用的依赖如静态库应放入TERMUX_PKG_BUILD_DEPENDS。仓库构建系统中这两个变量分别在 termux_step_setup_variables.sh 中被初始化为空串。6. 补丁格式补丁必须是 GNUdiff或 Git 生成的标准 diff 输出不要手工编辑补丁文件除非你完全理解其格式内部结构。补丁通常通过如下命令生成diff -uNr sourcedir sourcedir.mod filename.patch7. 补丁中的硬编码路径引用软件常依赖 FHS 标准路径/bin、/etc、/home、/run、/sbin、/tmp、/usr、/var。这些路径在 Termux 中不存在已被带前缀的等价路径取代。Termux 的安装前缀是/data/data/com.termux/files/usr可视为一个虚拟 rootfs主目录位于前缀之外/data/data/com.termux/files/home不要硬编码 home 与前缀应分别使用快捷方式TERMUX_HOME与TERMUX_PREFIX——补丁文件在应用前会先经过预处理替换。/run与/sbin应分别替换为TERMUX_PREFIX/var/run与TERMUX_PREFIX/bin。8. 构建配置不要随意动编译器标志除非是为了让构建跑通否则不要修改CFLAGS、CXXFLAGS、CPPFLAGS、LDFLAGS变量。参考 packages/hello/build.sh真正的需求通过termux_step_pre_configure()追加例如LDFLAGS -liconv。9. 构建配置Autotools 的旗标由系统代劳build-package.sh已经为 GNU Autotools 项目做了大量配置工作无需再显式指定--prefix、--host、--build、--disable-nls、--disable-rpath等旗标。构建系统会为你注入这些默认值额外传给./configure的选项通过TERMUX_PKG_EXTRA_CONFIGURE_ARGS提供。这一点可在 termux_step_configure_autotools.sh 中看到实现脚本会检查--disable-static、--enable-nls、--disable-shared、--host、--libexecdir等参数并发出警告同时自动拼装交叉编译参数而 termux_step_make.sh 与 termux_step_configure_meson.sh 等会把TERMUX_PKG_EXTRA_CONFIGURE_ARGS原样传给各构建系统。五、与包打交道commit 规范仓库中的所有软件都旨在兼容 Android 并通过 Android NDK 构建这常引入兼容性问题——Android尤其是 Termux不是标准平台不要指望现成的包配方开箱即用。Commit 消息应描述所做变更让维护者无需查看代码改动就能理解改了什么、改的是哪个包或作用域。推荐格式commitType(repo/package): (变更摘要/变更简述) [可选但强烈推荐的详细描述] [Fixes (termux/repo)#issue 编号] [Closes (termux/repo)#pr 编号]其中repo取main、root或x11即包所在的仓库。另一种定义方式是 repo.json 中包目录name属性去掉termux-前缀后的名称该文件实际定义了termux-main、termux-root、termux-x11三个仓库。package是包的实际名称。任何一行 commit 消息不应超过 80 个字符超长时应换一种更凝练的措辞。各 commit 类型addpkg(repo/package)新增包。摘要应包含包的一句话介绍扩展描述可写使用说明和收录理由。bump(repo/package)更新一个或多个包。摘要应写明更新到的新版本/标签扩展描述可列新版本特性、构建脚本与补丁的详细变更。fix(repo/package)修复包的 Termux 专属 bug。摘要应概括旧错误行为扩展描述可深入分析 bug 成因。dwnpkg(repo/package)因构建问题或潜在 bug 降级包。摘要需说明降级理由必要时在扩展描述中给出完整原因。disable(repo/package)禁用包。摘要应包含禁用原因放不下时写进扩展描述。enhance(repo/package)启用此前未开启的功能。强烈推荐在扩展描述中写清新功能的要点与基本用例。chore任何不影响用户的整理性变更。rebuild为链接更新后的共享库而重建包。特殊场景——大批量重建依赖某大包如 openssl的包时可写作rebuild(deps:main/openssl): link against OpenSSL 3.0。scripts(path/to/script)任何影响构建脚本或非配方脚本含工具链配置脚本的变更。ci(action_file_without_extension)影响 GitHub Actions yaml 文件或仅由其使用的脚本的变更。官方给出的优秀示例可在仓库中对应包上验证bump(main/nodejs): v18.2.0dwnpkg(main/htop): v2.2.0 v3.x needs access to /proc/stat which is now restricted by Androidenhance,bump(main/nodejs): v18.2.0 and use shared libuvfix(main/nodejs{,-lts}): test failures for process.report给新手的特殊照顾为鼓励新人参与上述 commit 规范可酌情放宽。需要改写 commit 消息时PR 可被 Squash 合并或在命令行手动合并。手动合并流程用 GitHub CLIgh pr checkout PR 编号拉取分支 →git commit --amend修改消息必要时git rebase origin/master→ 记录分支名 →git switch master git merge 分支名合并。手动合并时务必添加Co-authored-by:行保留原作者署名并附上Closes #PR 编号若 PR 作者允许维护者推送其分支优先 force-push 到作者分支这样 GitHub 界面能自动识别合并。六、build.sh 基础一个包就是一个脚本每个包通过放在./packages/name/目录下的build.sh脚本定义name是包的小写名称。build.sh是一个 Bash 脚本通过环境变量定义依赖、描述、主页等属性有时也用来覆写构建系统的默认打包步骤。仓库根目录还有build-package.sh作为构建入口包的具体定义即遵循如下模板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_BUILD_IN_SRCtrue包仅支持源码树内构建时使用例如使用裸 Makefile 而非 CMake 等构建系统的项目。TERMUX_PKG_PLATFORM_INDEPENDENTtrue包与平台无关可在任何 CPU 架构的设备上运行。构建系统中 termux_step_create_debian_package.sh 会据此把架构设为all。TERMUX_PKG_LICENSE应使用 SPDX 许可证标识符或取值custom/non-free多个许可证用逗号分隔。TERMUX_PKG_SRCURL应只指向官方源码包仅在充分理由下才允许使用 fork。仓库中真实存在的例子 packages/hello/build.sh 展示了完整写法——包括TERMUX_PKG_REVISION1同一版本内的第 1 次重打包和TERMUX_PKG_AUTO_UPDATEtrue允许自动版本检查以及通过覆写termux_step_pre_configure()追加链接标志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 }创建补丁文件很多包需要的改动无法通过配置构建系统完成此时必须直接修改源码并生成机器可读的补丁。仓库采用 Unified Format 补丁由 GNUdiff、git或兼容工具生成。大多数情况下用git diff更简单。用git diff制作补丁克隆包源码仓库可在/tmp下操作以便清理git clone https://github.com/curl/curl检出最新发布版可用git describe查看最新标签输出形如curl-8_12_1-118-gc10fd464e即最后标签-此后提交数-当前提交hashcd curl git describe git checkout curl-8_12_1修改代码vim sourcefile.c生成补丁文件git diff # 先确认改动符合预期 git diff /path/to/package-build/example.patch制作多个补丁时可在保存一个补丁后执行git reset HEAD --hard避免不同补丁间内容重复也可向git diff传入文件/目录列表来限定范围但同一文件的多个独立补丁不适用此法。用 GNUdiff制作补丁适用于项目不用 Git、或对发布 tarball 做了大量增改的情况cd ./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补丁文件名应自描述便于他人理解其作用每个改动最好单独存放为一个补丁文件。七、更新包可通过 Repology 的 Termux 页面查看哪些包已过时。常规更新流程将TERMUX_PKG_VERSION赋值为新版本号。注意不要误删 epoch编号前缀如1:、2:。若存在TERMUX_PKG_REVISION变量则删除它——revision 只在同一版本内的后续构建中使用。下载源码归档并计算 SHA-256 校验和cd ./packages/${YOUR_PACKAGE} (source build.sh 2/dev/null; curl -LO $TERMUX_PKG_SRCURL)将新校验和赋给TERMUX_PKG_SHA256。处理补丁应用失败包的重大升级常使旧补丁与新版本不兼容而修复方式完全取决于新版源码的具体改动没有放之四海皆准的指南。可尝试若补丁修复的是某个已知上游问题去项目 VCS 查是否有修复该问题的 commit——很可能补丁已不再需要。检查失败的补丁并手工把改动应用到源码上仅当你理解源码和补丁引入的改动时然后用例如diff -uNr package-1.0 package-1.0.mod previously-failed-patch-file.patch重新生成补丁。务必关注 CIGitHub Actions状态PR 失败就修复或关闭。小问题维护者可以代为修复但他们不会重写你的整个提交。八、版本不变的重建、降级与 epoch不升版本的重建修改补丁或构建配置会触发包重建。要让包管理器识别为更新需要通过定义TERMUX_PKG_REVISION或在其已有值时递增设置构建号。它应紧跟在TERMUX_PKG_VERSION下方TERMUX_PKG_VERSION1.0 TERMUX_PKG_REVISION4一旦版本号更新就应移除TERMUX_PKG_REVISION。其默认值在 termux_step_setup_variables.sh 中被初始化为0。降级或改变版本方案需要设置或递增 epoch强制包管理器把新版本识别为更新。Epoch 写在与版本相同的变量TERMUX_PKG_VERSION中格式为{EPOCH}:{VERSION}TERMUX_PKG_VERSION1:5.0.0如果你不是 termux 协作者提交降级 PR 时必须在描述中说明理由没有正当理由的降级 PR 会被拒绝。九、常见构建问题速查No files in package. Maybe you need to run autoreconf -fi before configuring?构建系统找不到 Makefile。视项目而定可尝试对仅含 Makefile 的项目设置TERMUX_PKG_BUILD_IN_SRCtrue对使用 Autotools 的项目在termux_step_pre_configure中运行./autogen.sh或autoreconf -fi。No LICENSE file was installed for ...构建系统找不到许可证文件需要通过TERMUX_PKG_LICENSE_FILE手动指定。在 termux_step_install_license.sh 中可以看到该变量支持逗号分隔的多个相对路径指向$TERMUX_PKG_SRCDIR下的 LICENSE 文件安装到$TERMUX_PREFIX/share/$TERMUX_PKG_NAME默认值定义见 termux_step_setup_variables.sh。十、把以上规范落地到仓库实践本文讨论的每一条规范都能在仓库中找到落点新包配方放在 packages主仓库、x11-packagesX11 图形包或 root-packages需 root 的包目录下每个目录一个build.sh无法继续维护的包会被移入 disabled-packages 并在其中保留历史补丁仓库还提供了可直接参考的最小示例 sample含sample-sub.subpackage.sh子包脚本与sample.alternatives备选机制以及 scripts 目录下支撑整个构建链的脚本集如 build-package.sh 入口、各termux_step_*构建步骤、lint-packages.sh 配方检查工具等。遵循本文的版本号、依赖划分、补丁生成与 commit 规范你提交的包才能顺利通过审查、进入 Termux 官方仓库。【免费下载链接】termux-packagesA package build system for Termux.项目地址: https://gitcode.com/GitHub_Trending/te/termux-packages创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考