Unlucky-Launcher/TERMUX-ADAPTATION.md

Termux 适配：方案、改动清单与合并指南

分支：termux-glibc（基于 origin/dev，14 个提交，HEAD 38d3024） 目的：让主线快速了解这组代码改了什么、为什么、怎么验证、如何合并。

TL;DR

• 构建：为 Termux 编出 aarch64-unknown-linux-gnu（glibc）二进制，在 termux-x11 里跑 GUI。 Android 原生 target 走不通（winit 的 android 后端需要 NativeActivity），所以不用它。
• 已跑通：GUI（CPU 与 GPU 两条渲染路径）、中文、横屏自适应、JDK 发现与系统包安装、 MC 1.20.4（glibc JRE + arm64 natives + softpipe GL，真机进游戏）。
• 未收口：MC 启动参数支持（由主线后续补）、MC 硬件 GL（zink 卡 DRI3）、剪贴板/IME。
• 对主线的影响：所有行为都由 运行时 Termux 识别 / cfg(target_os = "linux") / 文件存在 三选一 gate 住，Windows / macOS / 普通 Linux 的默认路径不变。

方案

1. 平台识别

crates/core/src/platform/termux.rs：用 TERMUX_VERSION 或默认 PREFIX （/data/data/com.termux/files/usr）识别 Termux，推导 $PREFIX 与 $PREFIX/lib/jvm。 不把路径写死到调用方，也不改 OsFamily（Android 上仍按 Linux 家族处理）。

2. JDK：发现 + 安装

• 发现：game/java/discover.rs 的 Unix 扫描根追加 $PREFIX/lib/jvm， 环境可注入（standard_roots_in）。补上「Termux 装了 openjdk 但没设 JAVA_HOME/PATH」的盲点。
• 安装：新增 game/java/termux.rs。Termux 的 openjdk 是 .deb（bionic）， 与 Temurin 的 zip/tar.gz 不是同一形态，所以委托包管理器：
  • 内置 SAU / TUNA / USTC / 官方四个 termux-main 镜像，按顺序 apt-get update && install；
  • lists/cache 隔离在 $PREFIX/tmp/ull-java-termux/，不污染用户 apt 配置；装完清理；
  • 装完从 $PREFIX/lib/jvm 定位，幂等（已装则不走网络）。
• vendor 接线：JdkVendor::Termux（17/21/25）。Termux 上缺省安装先试系统包， 失败再走归档链；--vendor termux 只走系统包。设置白名单与契约测试同步。

3. 字体

crates/app-iced/src/fonts.rs：Termux 上把 /system/fonts/NotoSansCJK-Regular.ttc 注册进 cosmic-text（fontdb 不扫 Android 字体目录），中文不再显示方框。

4. 窗口（横屏优先）

app/boot/termux_window.rs：Termux 上默认窗口按当前 X 屏幕等比自适应 （日志 size_source=termux-screen），横屏铺满、竖屏不溢出； ULL_WINDOW_SIZE 覆盖与 1180×760 验收基准不变。

5. GPU（启动器）

• 驱动是自编的 Mesa 26.2.6 + KGSL，装在 $PREFIX/glibc/{lib,share/vulkan/icd.d}； 构建/安装步骤见 packaging/docs/termux-glibc-build.md §5。
• app/boot/termux_gpu.rs：glibc 构建 + Termux + ICD 文件存在时，在探测前设 VK_ICD_FILENAMES / VK_DRIVER_FILES；用户显式设置不覆盖。
• 实测 wgpu 选中 Adreno 840（turnip Mesa 26.2.6）；无驱动自动降级 tiny-skia。

6. Minecraft 运行链

• natives：1.19+ 的清单把 natives 作为独立库条目（org.lwjgl:...:natives-linux）， Linux/aarch64 上改写成 natives-linux-arm64（Library::linux_arm64_native_name， install 与 launch 共用）；Mojang 的 libraries.minecraft.net 对 arm64 一律 404， 下载兜底到阿里云 Maven（install/libraries.rs）。
• JVM：用 glibc 的 Temurin JRE（patchelf 后直接执行），bionic 的 Termux JVM 加载不了 glibc natives。
• GL：glibc Mesa 的 zink 在 termux-x11 下卡 DRI3 not available， 子进程默认带 MESA_LOADER_DRIVER_OVERRIDE=swrast + LIBGL_ALWAYS_SOFTWARE=1 （launch/defaults.rs，用户自定义环境变量可覆盖）。

改动清单

文件	改动	平台隔离
core/platform/termux.rs（新）	Termux 识别、$PREFIX/JVM 根	纯函数，按环境判断
core/platform/mod.rs	导出新模块	—
core/game/java/discover.rs	$PREFIX/lib/jvm 扫描	Unix + Termux 判断
core/game/java/termux.rs（新）	镜像/隔离 apt 安装、installed_home	仅 Termux 可执行
core/game/java/vendor.rs / source.rs / install.rs	JdkVendor::Termux 与安装分派	Termux 上才启用
core/setting/keys.rs + 契约测试	白名单加 termux	跨平台可选，非 Termux 明确报错
cli/commands/java_vendors.rs、cli/cli/help.rs、presenter/host/java.rs	展示与帮助文案	展示层
core/game/library.rs	linux_arm64_native_name / 分类器改写	仅 linux+arm64
core/game/install/libraries.rs	现代 natives 条目改写 + Maven 兜底	仅 linux+arm64
core/launch/defaults.rs	Termux softpipe 环境默认值	cfg(linux) + Termux
presenter/host/launch.rs、cli/commands/snapshot.rs	classpath 用改写后的 arm64 坐标	仅 linux+arm64
app-iced/fonts.rs	Android CJK 字体注册	仅 Termux
app-iced/boot/termux_window.rs（新）	横屏自适应	仅 Termux
app-iced/boot/termux_gpu.rs（新）	自动启用自编 ICD	仅 glibc+Termux+文件存在
app-iced/Cargo.toml	新增 unlucky-core 依赖	复用平台识别
README.termux.md（新）、packaging/docs/termux-glibc-build.md（新）	分支说明与构建配方	文档
README.md / README.zh-CN.md / 支持矩阵两处	Termux 行同步	文档

行为变化与兼容性

• 新增 JdkVendor::Termux 会改变 VENDOR_IDS / JDK_VENDORS 的允许值集合 （契约测试已同步）。非 Termux 上显式选它会在安装时明确报「只在 Termux 里可用」， 默认回退序不含 termux，PC 行为不变。
• Linux/aarch64 的 LWJGL3 natives 会被改写；x86_64、Windows、macOS 不受影响。
• app-iced 直接依赖 unlucky-core（此前通过 cli/presenter 间接依赖）。
• 所有 Termux 专属路径都需要运行时识别或文件存在才会生效；普通 Linux 桌面不会触发。

合并指南

1. git fetch origin && git rebase origin/dev（分支基于 7d8b3b9 之后的 dev； dev 若前进，先 rebase 再推）。
2. PR base：dev。CI 门禁：fmt / clippy --workspace --all-targets -D warnings / test --workspace --all-targets / cargo deny（本机没装 deny，PC 上补跑）。
3. 本机已知、不影响 PC CI 的三条失败：
   • unlucky-core --test launch：/proc/<pid>/task/<pid>/children（Android 内核没有）
   • 同测试：长路径被脱敏成 <opaque>
   • presenter settings_bridge：mtime 热重载偶发（flaky，单跑 3 次 2 过 1 挂）
4. 不要提交：dist/、.gnu/、任何 ULL_MSA_CLIENT_ID 值（仓库 Secret）。
5. 合并后建议真机再跑一次：--software-renderer 截图 + ull java install 17 + MC 启动。

验证矩阵（本机）

项	结果
GUI 截图（横屏 1657×1067）	✅ 中文正常，client_id=configured source=build
GPU 渲染	✅ wgpu 选中 Adreno 840（turnip Mesa 26.2.6）；降级路径也验证过
ull java install 17	✅ SAU 镜像约 20 s，装完清理，java list 可见
MC 1.20.4	✅ 真机安装（740 MB）→ 主菜单 → 建世界 → 进游戏
fmt / clippy / 核心测试	✅ 475 条核心测试通过，clippy 零告警

后续路线

1. MC 启动参数（主线功能，另行排期）：当前 ull launch 不接受自定义 JVM/游戏参数。
2. MC 硬件 GL：修 glibc GLX 的 DRI3（让 zink 生效），或改用 VulkanMod。
3. 剪贴板 / IME 在 termux-x11 下的行为验证。
4. narrator/flite 与音频设备（当前缺失但不阻断）。
5. GPU 驱动分发：目前每次都要按文档自编 Mesa；可考虑脚本化/预编译产物。

回滚策略

全部改动按提交分组（platform → fonts → docs → java → gpu → natives → mc）， 可按组 revert；Termux 专属逻辑都有运行时/文件存在 gate，回滚不会波及 PC 路径。